Add implicit project-scope detection and doctor health checks

README.md

@@ -157,10 +157,12 @@ lnk list --all # all scopes
 ```bash
 lnk doctor # audit repo and profile health
 lnk doctor --fix # apply safe automatic fixes
-lnk doctor --fix --prune-empty # also remove empty host scopes
+lnk doctor --fix --prune-empty # also remove empty host scopes and project storage
 lnk doctor --all # check all scopes
 ```
 
+`lnk doctor` checks project scope as well as host/common scope: it reports orphaned project storage, broken project symlinks, and `.lnkinclude` patterns that match no files. Project issues are listed with severity and a suggested fix.
+
 When restoring symlinks, if a real file exists at the target location (not a symlink), it will be renamed to `<path>.lnk-backup` to preserve your data before the symlink is created. Check for `.lnk-backup` files after running `restore`, `update`, or `doctor` if you expect them.
 
 ### Format migration
@@ -207,6 +209,12 @@ lnk project untrack --keep .crush/** # remove a pattern but leave files man
 lnk project remove # stop managing the project, restore all files
 lnk project forget # stop managing the project, keep stored files
 
+# implicit detection in update/restore
+lnk update # also restores any detected project scope
+lnk restore # also restores any detected project scope
+lnk update --no-project # skip automatic project-scope detection
+lnk restore --no-project # skip automatic project-scope detection
+
 # global patterns (apply to every project)
 lnk project add --global AGENTS.md # include AGENTS.md everywhere
 lnk project add '!AGENTS.md' # then exclude it in one project
@@ -215,6 +223,8 @@ lnk project untrack --global AGENTS.md # remove the global pattern
 
 Matched files are stored under `projects/<normalized-origin>/<path>/` in your lnk repo (derived from the project's origin remote) and symlinked back into the project. Existing files at symlink locations are backed up to `<path>.lnk-backup` during restore, just like host/common scope restores.
 
+`lnk update` and `lnk restore` automatically detect project scope when they run inside a git repo that contains a `.lnkinclude` file. The project scope is restored alongside the common and host scopes, and a `(project scope: <id>)` message is printed to stderr. Use the global `--no-project` flag to skip automatic detection.
+
 ### Notes and edge cases
 
 - **Global patterns are hand-managed** (or edited via `--global`): they apply to every project, so negate them per project with a local `!` pattern. Quote the `!` in your shell (`'!AGENTS.md'`) or zsh's history expansion will eat it before lnk sees it.
@@ -248,9 +258,9 @@ man man/lnk-project-push.1 # read a generated page
 | `commit [-m message]` | Stage all changes and commit |
 | `push` | Push existing commits |
 | `pull` | Pull repo changes |
-| `restore [--host H] [--dry-run]` | Restore symlinks without pulling |
-| `update [--host H]` | Pull and restore the effective profile |
-| `doctor [--host H \| --all] [--fix] [--prune-empty]` | Audit and fix repo health |
+| `restore [--host H] [--dry-run] [--no-project]` | Restore symlinks without pulling (auto-detects project scope) |
+| `update [--host H] [--no-project]` | Pull and restore the effective profile (auto-detects project scope) |
+| `doctor [--host H \| --all] [--fix] [--prune-empty]` | Audit and fix repo health, including project scope |
 | `format [--v1 \| --v2]` | Migrate repo format |
 | `bootstrap` | Run bootstrap.sh explicitly |
 | `project init` | Activate project scope in the current git repo |
@@ -271,6 +281,7 @@ Available with all commands:
 | Option | Default | What it does |
 | --- | --- | --- |
 | `--repo <path>` | `~/.config/lnk` | Path to the lnk repository |
+| `--no-project` | `false` | Skip automatic project-scope detection |
 
 ## Acknowledgements
 

VERSION

@@ -1 +1 @@
-v2.0.0
+v2.1.0

cmd/root.go

@@ -37,6 +37,7 @@ func NewRootCommand() *cobra.Command {
 	}
 
 	rootCmd.PersistentFlags().StringVar(&repoPath, "repo", "", "path to the lnk repository")
+	rootCmd.PersistentFlags().Bool("no-project", false, "skip automatic project scope detection")
 
 	rootCmd.AddCommand(newInitCmd(&repoPath))
 	rootCmd.AddCommand(newCloneCmd(&repoPath))
@@ -913,7 +914,8 @@ func newRestoreCmd(repoFlag *string) *cobra.Command {
  Short: "Restore the effective machine profile",
  RunE: func(cmd *cobra.Command, args []string) error {
  app := svc(repoFlag)
- info, err := app.Restore(cmd.Context(), host, dryRun)
+ noProject, _ := cmd.Flags().GetBool("no-project")
+ info, err := app.RestoreWithProject(cmd.Context(), host, noProject, dryRun)
  if err != nil {
  return err
  }
@@ -935,7 +937,8 @@ func newUpdateCmd(repoFlag *string) *cobra.Command {
  Short: "Pull repo changes and restore the effective machine profile",
  RunE: func(cmd *cobra.Command, args []string) error {
  app := svc(repoFlag)
- info, err := app.Update(cmd.Context(), host)
+ noProject, _ := cmd.Flags().GetBool("no-project")
+ info, err := app.UpdateWithProject(cmd.Context(), host, noProject)
  if err != nil {
  return err
  }
@@ -1141,6 +1144,24 @@ func printDoctor(w io.Writer, report service.DoctorReport) error {
  }
  }
 	}
+	if len(report.ProjectIssues) > 0 {
+ if _, err := fmt.Fprintln(w, "Project issues:"); err != nil {
+ return err
+ }
+ for _, issue := range report.ProjectIssues {
+ if _, err := fmt.Fprintf(w, " [%s] %s: %s", issue.Severity, issue.ProjectID, issue.Issue); err != nil {
+ return err
+ }
+ if issue.Suggestion != "" {
+ if _, err := fmt.Fprintf(w, " -> %s", issue.Suggestion); err != nil {
+ return err
+ }
+ }
+ if _, err := fmt.Fprintln(w); err != nil {
+ return err
+ }
+ }
+	}
 	if len(report.PrunedProjects) > 0 {
  if _, err := fmt.Fprintln(w, "Pruned empty project storage:"); err != nil {
  return err

service/doctor.go

@@ -61,14 +61,23 @@ type DoctorReport struct {
 	UnmarkedProjects []string // storage under projects/ without a marker
 	EmptyProjects []string // marked projects with no stored files
 	PrunedProjects []string // empty project storage removed by --fix --prune-empty
+	ProjectIssues []ProjectIssue
+}
+
+// ProjectIssue captures a project-scope health finding for doctor.
+type ProjectIssue struct {
+	ProjectID string
+	Issue string
+	Severity string // "error" or "warning"
+	Suggestion string
 }
 
 // HasIssues reports whether the doctor found actionable issues.
 func (r DoctorReport) HasIssues() bool {
 	if r.MarkerMissing || len(r.Collisions) > 0 || len(r.EmptyScopes) > 0 {
  return true
 	}
-	if len(r.UnmarkedProjects) > 0 || len(r.EmptyProjects) > 0 {
+	if len(r.UnmarkedProjects) > 0 || len(r.EmptyProjects) > 0 || len(r.ProjectIssues) > 0 {
  return true
 	}
 	for _, result := range r.ScopeResults {
@@ -182,6 +191,12 @@ func (s *Service) doctorScan(ctx context.Context, host string, all bool) (Doctor
 	report.UnmarkedProjects = unmarked
 	report.EmptyProjects = emptyProjects
 
+	projectIssues, err := s.scanProjectIssues(ctx)
+	if err != nil {
+ return DoctorReport{}, err
+	}
+	report.ProjectIssues = projectIssues
+
 	return report, nil
 }
 

README.md

@@ -157,10 +157,12 @@ lnk list --all # all scopes
 ```bash
 lnk doctor # audit repo and profile health
 lnk doctor --fix # apply safe automatic fixes
-lnk doctor --fix --prune-empty # also remove empty host scopes
+lnk doctor --fix --prune-empty # also remove empty host scopes and project storage
 lnk doctor --all # check all scopes
 ```
 
+`lnk doctor` checks project scope as well as host/common scope: it reports orphaned project storage, broken project symlinks, and `.lnkinclude` patterns that match no files. Project issues are listed with severity and a suggested fix.
+
 When restoring symlinks, if a real file exists at the target location (not a symlink), it will be renamed to `<path>.lnk-backup` to preserve your data before the symlink is created. Check for `.lnk-backup` files after running `restore`, `update`, or `doctor` if you expect them.
 
 ### Format migration
@@ -207,6 +209,12 @@ lnk project untrack --keep .crush/** # remove a pattern but leave files man
 lnk project remove # stop managing the project, restore all files
 lnk project forget # stop managing the project, keep stored files
 
+# implicit detection in update/restore
+lnk update # also restores any detected project scope
+lnk restore # also restores any detected project scope
+lnk update --no-project # skip automatic project-scope detection
+lnk restore --no-project # skip automatic project-scope detection
+
 # global patterns (apply to every project)
 lnk project add --global AGENTS.md # include AGENTS.md everywhere
 lnk project add '!AGENTS.md' # then exclude it in one project
@@ -215,6 +223,8 @@ lnk project untrack --global AGENTS.md # remove the global pattern
 
 Matched files are stored under `projects/<normalized-origin>/<path>/` in your lnk repo (derived from the project's origin remote) and symlinked back into the project. Existing files at symlink locations are backed up to `<path>.lnk-backup` during restore, just like host/common scope restores.
 
+`lnk update` and `lnk restore` automatically detect project scope when they run inside a git repo that contains a `.lnkinclude` file. The project scope is restored alongside the common and host scopes, and a `(project scope: <id>)` message is printed to stderr. Use the global `--no-project` flag to skip automatic detection.
+
 ### Notes and edge cases
 
 - **Global patterns are hand-managed** (or edited via `--global`): they apply to every project, so negate them per project with a local `!` pattern. Quote the `!` in your shell (`'!AGENTS.md'`) or zsh's history expansion will eat it before lnk sees it.
@@ -248,9 +258,9 @@ man man/lnk-project-push.1 # read a generated page
 | `commit [-m message]` | Stage all changes and commit |
 | `push` | Push existing commits |
 | `pull` | Pull repo changes |
-| `restore [--host H] [--dry-run]` | Restore symlinks without pulling |
-| `update [--host H]` | Pull and restore the effective profile |
-| `doctor [--host H \| --all] [--fix] [--prune-empty]` | Audit and fix repo health |
+| `restore [--host H] [--dry-run] [--no-project]` | Restore symlinks without pulling (auto-detects project scope) |
+| `update [--host H] [--no-project]` | Pull and restore the effective profile (auto-detects project scope) |
+| `doctor [--host H \| --all] [--fix] [--prune-empty]` | Audit and fix repo health, including project scope |
 | `format [--v1 \| --v2]` | Migrate repo format |
 | `bootstrap` | Run bootstrap.sh explicitly |
 | `project init` | Activate project scope in the current git repo |
@@ -271,6 +281,7 @@ Available with all commands:
 | Option | Default | What it does |
 | --- | --- | --- |
 | `--repo <path>` | `~/.config/lnk` | Path to the lnk repository |
+| `--no-project` | `false` | Skip automatic project-scope detection |
 
 ## Acknowledgements
 

VERSION

@@ -1 +1 @@
-v2.0.0
+v2.1.0

cmd/root.go

@@ -37,6 +37,7 @@ func NewRootCommand() *cobra.Command {
 	}
 
 	rootCmd.PersistentFlags().StringVar(&repoPath, "repo", "", "path to the lnk repository")
+	rootCmd.PersistentFlags().Bool("no-project", false, "skip automatic project scope detection")
 
 	rootCmd.AddCommand(newInitCmd(&repoPath))
 	rootCmd.AddCommand(newCloneCmd(&repoPath))
@@ -913,7 +914,8 @@ func newRestoreCmd(repoFlag *string) *cobra.Command {
  Short: "Restore the effective machine profile",
  RunE: func(cmd *cobra.Command, args []string) error {
  app := svc(repoFlag)
- info, err := app.Restore(cmd.Context(), host, dryRun)
+ noProject, _ := cmd.Flags().GetBool("no-project")
+ info, err := app.RestoreWithProject(cmd.Context(), host, noProject, dryRun)
  if err != nil {
  return err
  }
@@ -935,7 +937,8 @@ func newUpdateCmd(repoFlag *string) *cobra.Command {
  Short: "Pull repo changes and restore the effective machine profile",
  RunE: func(cmd *cobra.Command, args []string) error {
  app := svc(repoFlag)
- info, err := app.Update(cmd.Context(), host)
+ noProject, _ := cmd.Flags().GetBool("no-project")
+ info, err := app.UpdateWithProject(cmd.Context(), host, noProject)
  if err != nil {
  return err
  }
@@ -1141,6 +1144,24 @@ func printDoctor(w io.Writer, report service.DoctorReport) error {
  }
  }
 	}
+	if len(report.ProjectIssues) > 0 {
+ if _, err := fmt.Fprintln(w, "Project issues:"); err != nil {
+ return err
+ }
+ for _, issue := range report.ProjectIssues {
+ if _, err := fmt.Fprintf(w, " [%s] %s: %s", issue.Severity, issue.ProjectID, issue.Issue); err != nil {
+ return err
+ }
+ if issue.Suggestion != "" {
+ if _, err := fmt.Fprintf(w, " -> %s", issue.Suggestion); err != nil {
+ return err
+ }
+ }
+ if _, err := fmt.Fprintln(w); err != nil {
+ return err
+ }
+ }
+	}
 	if len(report.PrunedProjects) > 0 {
  if _, err := fmt.Fprintln(w, "Pruned empty project storage:"); err != nil {
  return err

service/doctor.go

@@ -61,14 +61,23 @@ type DoctorReport struct {
 	UnmarkedProjects []string // storage under projects/ without a marker
 	EmptyProjects []string // marked projects with no stored files
 	PrunedProjects []string // empty project storage removed by --fix --prune-empty
+	ProjectIssues []ProjectIssue
+}
+
+// ProjectIssue captures a project-scope health finding for doctor.
+type ProjectIssue struct {
+	ProjectID string
+	Issue string
+	Severity string // "error" or "warning"
+	Suggestion string
 }
 
 // HasIssues reports whether the doctor found actionable issues.
 func (r DoctorReport) HasIssues() bool {
 	if r.MarkerMissing || len(r.Collisions) > 0 || len(r.EmptyScopes) > 0 {
  return true
 	}
-	if len(r.UnmarkedProjects) > 0 || len(r.EmptyProjects) > 0 {
+	if len(r.UnmarkedProjects) > 0 || len(r.EmptyProjects) > 0 || len(r.ProjectIssues) > 0 {
  return true
 	}
 	for _, result := range r.ScopeResults {
@@ -182,6 +191,12 @@ func (s *Service) doctorScan(ctx context.Context, host string, all bool) (Doctor
 	report.UnmarkedProjects = unmarked
 	report.EmptyProjects = emptyProjects
 
+	projectIssues, err := s.scanProjectIssues(ctx)
+	if err != nil {
+ return DoctorReport{}, err
+	}
+	report.ProjectIssues = projectIssues
+
 	return report, nil
 }
 

README.md

@@ -157,10 +157,12 @@ lnk list --all # all scopes
 ```bash
 lnk doctor # audit repo and profile health
 lnk doctor --fix # apply safe automatic fixes
-lnk doctor --fix --prune-empty # also remove empty host scopes
+lnk doctor --fix --prune-empty # also remove empty host scopes and project storage
 lnk doctor --all # check all scopes
 ```
 
+`lnk doctor` checks project scope as well as host/common scope: it reports orphaned project storage, broken project symlinks, and `.lnkinclude` patterns that match no files. Project issues are listed with severity and a suggested fix.
+
 When restoring symlinks, if a real file exists at the target location (not a symlink), it will be renamed to `<path>.lnk-backup` to preserve your data before the symlink is created. Check for `.lnk-backup` files after running `restore`, `update`, or `doctor` if you expect them.
 
 ### Format migration
@@ -207,6 +209,12 @@ lnk project untrack --keep .crush/** # remove a pattern but leave files man
 lnk project remove # stop managing the project, restore all files
 lnk project forget # stop managing the project, keep stored files
 
+# implicit detection in update/restore
+lnk update # also restores any detected project scope
+lnk restore # also restores any detected project scope
+lnk update --no-project # skip automatic project-scope detection
+lnk restore --no-project # skip automatic project-scope detection
+
 # global patterns (apply to every project)
 lnk project add --global AGENTS.md # include AGENTS.md everywhere
 lnk project add '!AGENTS.md' # then exclude it in one project
@@ -215,6 +223,8 @@ lnk project untrack --global AGENTS.md # remove the global pattern
 
 Matched files are stored under `projects/<normalized-origin>/<path>/` in your lnk repo (derived from the project's origin remote) and symlinked back into the project. Existing files at symlink locations are backed up to `<path>.lnk-backup` during restore, just like host/common scope restores.
 
+`lnk update` and `lnk restore` automatically detect project scope when they run inside a git repo that contains a `.lnkinclude` file. The project scope is restored alongside the common and host scopes, and a `(project scope: <id>)` message is printed to stderr. Use the global `--no-project` flag to skip automatic detection.
+
 ### Notes and edge cases
 
 - **Global patterns are hand-managed** (or edited via `--global`): they apply to every project, so negate them per project with a local `!` pattern. Quote the `!` in your shell (`'!AGENTS.md'`) or zsh's history expansion will eat it before lnk sees it.
@@ -248,9 +258,9 @@ man man/lnk-project-push.1 # read a generated page
 | `commit [-m message]` | Stage all changes and commit |
 | `push` | Push existing commits |
 | `pull` | Pull repo changes |
-| `restore [--host H] [--dry-run]` | Restore symlinks without pulling |
-| `update [--host H]` | Pull and restore the effective profile |
-| `doctor [--host H \| --all] [--fix] [--prune-empty]` | Audit and fix repo health |
+| `restore [--host H] [--dry-run] [--no-project]` | Restore symlinks without pulling (auto-detects project scope) |
+| `update [--host H] [--no-project]` | Pull and restore the effective profile (auto-detects project scope) |
+| `doctor [--host H \| --all] [--fix] [--prune-empty]` | Audit and fix repo health, including project scope |
 | `format [--v1 \| --v2]` | Migrate repo format |
 | `bootstrap` | Run bootstrap.sh explicitly |
 | `project init` | Activate project scope in the current git repo |
@@ -271,6 +281,7 @@ Available with all commands:
 | Option | Default | What it does |
 | --- | --- | --- |
 | `--repo <path>` | `~/.config/lnk` | Path to the lnk repository |
+| `--no-project` | `false` | Skip automatic project-scope detection |
 
 ## Acknowledgements
 

VERSION

@@ -1 +1 @@
-v2.0.0
+v2.1.0

cmd/root.go

@@ -37,6 +37,7 @@ func NewRootCommand() *cobra.Command {
 	}
 
 	rootCmd.PersistentFlags().StringVar(&repoPath, "repo", "", "path to the lnk repository")
+	rootCmd.PersistentFlags().Bool("no-project", false, "skip automatic project scope detection")
 
 	rootCmd.AddCommand(newInitCmd(&repoPath))
 	rootCmd.AddCommand(newCloneCmd(&repoPath))
@@ -913,7 +914,8 @@ func newRestoreCmd(repoFlag *string) *cobra.Command {
  Short: "Restore the effective machine profile",
  RunE: func(cmd *cobra.Command, args []string) error {
  app := svc(repoFlag)
- info, err := app.Restore(cmd.Context(), host, dryRun)
+ noProject, _ := cmd.Flags().GetBool("no-project")
+ info, err := app.RestoreWithProject(cmd.Context(), host, noProject, dryRun)
  if err != nil {
  return err
  }
@@ -935,7 +937,8 @@ func newUpdateCmd(repoFlag *string) *cobra.Command {
  Short: "Pull repo changes and restore the effective machine profile",
  RunE: func(cmd *cobra.Command, args []string) error {
  app := svc(repoFlag)
- info, err := app.Update(cmd.Context(), host)
+ noProject, _ := cmd.Flags().GetBool("no-project")
+ info, err := app.UpdateWithProject(cmd.Context(), host, noProject)
  if err != nil {
  return err
  }
@@ -1141,6 +1144,24 @@ func printDoctor(w io.Writer, report service.DoctorReport) error {
  }
  }
 	}
+	if len(report.ProjectIssues) > 0 {
+ if _, err := fmt.Fprintln(w, "Project issues:"); err != nil {
+ return err
+ }
+ for _, issue := range report.ProjectIssues {
+ if _, err := fmt.Fprintf(w, " [%s] %s: %s", issue.Severity, issue.ProjectID, issue.Issue); err != nil {
+ return err
+ }
+ if issue.Suggestion != "" {
+ if _, err := fmt.Fprintf(w, " -> %s", issue.Suggestion); err != nil {
+ return err
+ }
+ }
+ if _, err := fmt.Fprintln(w); err != nil {
+ return err
+ }
+ }
+	}
 	if len(report.PrunedProjects) > 0 {
  if _, err := fmt.Fprintln(w, "Pruned empty project storage:"); err != nil {
  return err

service/doctor.go

@@ -61,14 +61,23 @@ type DoctorReport struct {
 	UnmarkedProjects []string // storage under projects/ without a marker
 	EmptyProjects []string // marked projects with no stored files
 	PrunedProjects []string // empty project storage removed by --fix --prune-empty
+	ProjectIssues []ProjectIssue
+}
+
+// ProjectIssue captures a project-scope health finding for doctor.
+type ProjectIssue struct {
+	ProjectID string
+	Issue string
+	Severity string // "error" or "warning"
+	Suggestion string
 }
 
 // HasIssues reports whether the doctor found actionable issues.
 func (r DoctorReport) HasIssues() bool {
 	if r.MarkerMissing || len(r.Collisions) > 0 || len(r.EmptyScopes) > 0 {
  return true
 	}
-	if len(r.UnmarkedProjects) > 0 || len(r.EmptyProjects) > 0 {
+	if len(r.UnmarkedProjects) > 0 || len(r.EmptyProjects) > 0 || len(r.ProjectIssues) > 0 {
  return true
 	}
 	for _, result := range r.ScopeResults {
@@ -182,6 +191,12 @@ func (s *Service) doctorScan(ctx context.Context, host string, all bool) (Doctor
 	report.UnmarkedProjects = unmarked
 	report.EmptyProjects = emptyProjects
 
+	projectIssues, err := s.scanProjectIssues(ctx)
+	if err != nil {
+ return DoctorReport{}, err
+	}
+	report.ProjectIssues = projectIssues
+
 	return report, nil
 }
 

README.md

@@ -157,10 +157,12 @@ lnk list --all # all scopes
 ```bash
 lnk doctor # audit repo and profile health
 lnk doctor --fix # apply safe automatic fixes
-lnk doctor --fix --prune-empty # also remove empty host scopes
+lnk doctor --fix --prune-empty # also remove empty host scopes and project storage
 lnk doctor --all # check all scopes
 ```
 
+`lnk doctor` checks project scope as well as host/common scope: it reports orphaned project storage, broken project symlinks, and `.lnkinclude` patterns that match no files. Project issues are listed with severity and a suggested fix.
+
 When restoring symlinks, if a real file exists at the target location (not a symlink), it will be renamed to `<path>.lnk-backup` to preserve your data before the symlink is created. Check for `.lnk-backup` files after running `restore`, `update`, or `doctor` if you expect them.
 
 ### Format migration
@@ -207,6 +209,12 @@ lnk project untrack --keep .crush/** # remove a pattern but leave files man
 lnk project remove # stop managing the project, restore all files
 lnk project forget # stop managing the project, keep stored files
 
+# implicit detection in update/restore
+lnk update # also restores any detected project scope
+lnk restore # also restores any detected project scope
+lnk update --no-project # skip automatic project-scope detection
+lnk restore --no-project # skip automatic project-scope detection
+
 # global patterns (apply to every project)
 lnk project add --global AGENTS.md # include AGENTS.md everywhere
 lnk project add '!AGENTS.md' # then exclude it in one project
@@ -215,6 +223,8 @@ lnk project untrack --global AGENTS.md # remove the global pattern
 
 Matched files are stored under `projects/<normalized-origin>/<path>/` in your lnk repo (derived from the project's origin remote) and symlinked back into the project. Existing files at symlink locations are backed up to `<path>.lnk-backup` during restore, just like host/common scope restores.
 
+`lnk update` and `lnk restore` automatically detect project scope when they run inside a git repo that contains a `.lnkinclude` file. The project scope is restored alongside the common and host scopes, and a `(project scope: <id>)` message is printed to stderr. Use the global `--no-project` flag to skip automatic detection.
+
 ### Notes and edge cases
 
 - **Global patterns are hand-managed** (or edited via `--global`): they apply to every project, so negate them per project with a local `!` pattern. Quote the `!` in your shell (`'!AGENTS.md'`) or zsh's history expansion will eat it before lnk sees it.
@@ -248,9 +258,9 @@ man man/lnk-project-push.1 # read a generated page
 | `commit [-m message]` | Stage all changes and commit |
 | `push` | Push existing commits |
 | `pull` | Pull repo changes |
-| `restore [--host H] [--dry-run]` | Restore symlinks without pulling |
-| `update [--host H]` | Pull and restore the effective profile |
-| `doctor [--host H \| --all] [--fix] [--prune-empty]` | Audit and fix repo health |
+| `restore [--host H] [--dry-run] [--no-project]` | Restore symlinks without pulling (auto-detects project scope) |
+| `update [--host H] [--no-project]` | Pull and restore the effective profile (auto-detects project scope) |
+| `doctor [--host H \| --all] [--fix] [--prune-empty]` | Audit and fix repo health, including project scope |
 | `format [--v1 \| --v2]` | Migrate repo format |
 | `bootstrap` | Run bootstrap.sh explicitly |
 | `project init` | Activate project scope in the current git repo |
@@ -271,6 +281,7 @@ Available with all commands:
 | Option | Default | What it does |
 | --- | --- | --- |
 | `--repo <path>` | `~/.config/lnk` | Path to the lnk repository |
+| `--no-project` | `false` | Skip automatic project-scope detection |
 
 ## Acknowledgements
 

VERSION

@@ -1 +1 @@
-v2.0.0
+v2.1.0

cmd/root.go

@@ -37,6 +37,7 @@ func NewRootCommand() *cobra.Command {
 	}
 
 	rootCmd.PersistentFlags().StringVar(&repoPath, "repo", "", "path to the lnk repository")
+	rootCmd.PersistentFlags().Bool("no-project", false, "skip automatic project scope detection")
 
 	rootCmd.AddCommand(newInitCmd(&repoPath))
 	rootCmd.AddCommand(newCloneCmd(&repoPath))
@@ -913,7 +914,8 @@ func newRestoreCmd(repoFlag *string) *cobra.Command {
  Short: "Restore the effective machine profile",
  RunE: func(cmd *cobra.Command, args []string) error {
  app := svc(repoFlag)
- info, err := app.Restore(cmd.Context(), host, dryRun)
+ noProject, _ := cmd.Flags().GetBool("no-project")
+ info, err := app.RestoreWithProject(cmd.Context(), host, noProject, dryRun)
  if err != nil {
  return err
  }
@@ -935,7 +937,8 @@ func newUpdateCmd(repoFlag *string) *cobra.Command {
  Short: "Pull repo changes and restore the effective machine profile",
  RunE: func(cmd *cobra.Command, args []string) error {
  app := svc(repoFlag)
- info, err := app.Update(cmd.Context(), host)
+ noProject, _ := cmd.Flags().GetBool("no-project")
+ info, err := app.UpdateWithProject(cmd.Context(), host, noProject)
  if err != nil {
  return err
  }
@@ -1141,6 +1144,24 @@ func printDoctor(w io.Writer, report service.DoctorReport) error {
  }
  }
 	}
+	if len(report.ProjectIssues) > 0 {
+ if _, err := fmt.Fprintln(w, "Project issues:"); err != nil {
+ return err
+ }
+ for _, issue := range report.ProjectIssues {
+ if _, err := fmt.Fprintf(w, " [%s] %s: %s", issue.Severity, issue.ProjectID, issue.Issue); err != nil {
+ return err
+ }
+ if issue.Suggestion != "" {
+ if _, err := fmt.Fprintf(w, " -> %s", issue.Suggestion); err != nil {
+ return err
+ }
+ }
+ if _, err := fmt.Fprintln(w); err != nil {
+ return err
+ }
+ }
+	}
 	if len(report.PrunedProjects) > 0 {
  if _, err := fmt.Fprintln(w, "Pruned empty project storage:"); err != nil {
  return err

service/doctor.go

@@ -61,14 +61,23 @@ type DoctorReport struct {
 	UnmarkedProjects []string // storage under projects/ without a marker
 	EmptyProjects []string // marked projects with no stored files
 	PrunedProjects []string // empty project storage removed by --fix --prune-empty
+	ProjectIssues []ProjectIssue
+}
+
+// ProjectIssue captures a project-scope health finding for doctor.
+type ProjectIssue struct {
+	ProjectID string
+	Issue string
+	Severity string // "error" or "warning"
+	Suggestion string
 }
 
 // HasIssues reports whether the doctor found actionable issues.
 func (r DoctorReport) HasIssues() bool {
 	if r.MarkerMissing || len(r.Collisions) > 0 || len(r.EmptyScopes) > 0 {
  return true
 	}
-	if len(r.UnmarkedProjects) > 0 || len(r.EmptyProjects) > 0 {
+	if len(r.UnmarkedProjects) > 0 || len(r.EmptyProjects) > 0 || len(r.ProjectIssues) > 0 {
  return true
 	}
 	for _, result := range r.ScopeResults {
@@ -182,6 +191,12 @@ func (s *Service) doctorScan(ctx context.Context, host string, all bool) (Doctor
 	report.UnmarkedProjects = unmarked
 	report.EmptyProjects = emptyProjects
 
+	projectIssues, err := s.scanProjectIssues(ctx)
+	if err != nil {
+ return DoctorReport{}, err
+	}
+	report.ProjectIssues = projectIssues
+
 	return report, nil
 }
 

README.md

@@ -157,10 +157,12 @@ lnk list --all # all scopes
 ```bash
 lnk doctor # audit repo and profile health
 lnk doctor --fix # apply safe automatic fixes
-lnk doctor --fix --prune-empty # also remove empty host scopes
+lnk doctor --fix --prune-empty # also remove empty host scopes and project storage
 lnk doctor --all # check all scopes
 ```
 
+`lnk doctor` checks project scope as well as host/common scope: it reports orphaned project storage, broken project symlinks, and `.lnkinclude` patterns that match no files. Project issues are listed with severity and a suggested fix.
+
 When restoring symlinks, if a real file exists at the target location (not a symlink), it will be renamed to `<path>.lnk-backup` to preserve your data before the symlink is created. Check for `.lnk-backup` files after running `restore`, `update`, or `doctor` if you expect them.
 
 ### Format migration
@@ -207,6 +209,12 @@ lnk project untrack --keep .crush/** # remove a pattern but leave files man
 lnk project remove # stop managing the project, restore all files
 lnk project forget # stop managing the project, keep stored files
 
+# implicit detection in update/restore
+lnk update # also restores any detected project scope
+lnk restore # also restores any detected project scope
+lnk update --no-project # skip automatic project-scope detection
+lnk restore --no-project # skip automatic project-scope detection
+
 # global patterns (apply to every project)
 lnk project add --global AGENTS.md # include AGENTS.md everywhere
 lnk project add '!AGENTS.md' # then exclude it in one project
@@ -215,6 +223,8 @@ lnk project untrack --global AGENTS.md # remove the global pattern
 
 Matched files are stored under `projects/<normalized-origin>/<path>/` in your lnk repo (derived from the project's origin remote) and symlinked back into the project. Existing files at symlink locations are backed up to `<path>.lnk-backup` during restore, just like host/common scope restores.
 
+`lnk update` and `lnk restore` automatically detect project scope when they run inside a git repo that contains a `.lnkinclude` file. The project scope is restored alongside the common and host scopes, and a `(project scope: <id>)` message is printed to stderr. Use the global `--no-project` flag to skip automatic detection.
+
 ### Notes and edge cases
 
 - **Global patterns are hand-managed** (or edited via `--global`): they apply to every project, so negate them per project with a local `!` pattern. Quote the `!` in your shell (`'!AGENTS.md'`) or zsh's history expansion will eat it before lnk sees it.
@@ -248,9 +258,9 @@ man man/lnk-project-push.1 # read a generated page
 | `commit [-m message]` | Stage all changes and commit |
 | `push` | Push existing commits |
 | `pull` | Pull repo changes |
-| `restore [--host H] [--dry-run]` | Restore symlinks without pulling |
-| `update [--host H]` | Pull and restore the effective profile |
-| `doctor [--host H \| --all] [--fix] [--prune-empty]` | Audit and fix repo health |
+| `restore [--host H] [--dry-run] [--no-project]` | Restore symlinks without pulling (auto-detects project scope) |
+| `update [--host H] [--no-project]` | Pull and restore the effective profile (auto-detects project scope) |
+| `doctor [--host H \| --all] [--fix] [--prune-empty]` | Audit and fix repo health, including project scope |
 | `format [--v1 \| --v2]` | Migrate repo format |
 | `bootstrap` | Run bootstrap.sh explicitly |
 | `project init` | Activate project scope in the current git repo |
@@ -271,6 +281,7 @@ Available with all commands:
 | Option | Default | What it does |
 | --- | --- | --- |
 | `--repo <path>` | `~/.config/lnk` | Path to the lnk repository |
+| `--no-project` | `false` | Skip automatic project-scope detection |
 
 ## Acknowledgements
 

VERSION

@@ -1 +1 @@
-v2.0.0
+v2.1.0

cmd/root.go

@@ -37,6 +37,7 @@ func NewRootCommand() *cobra.Command {
 	}
 
 	rootCmd.PersistentFlags().StringVar(&repoPath, "repo", "", "path to the lnk repository")
+	rootCmd.PersistentFlags().Bool("no-project", false, "skip automatic project scope detection")
 
 	rootCmd.AddCommand(newInitCmd(&repoPath))
 	rootCmd.AddCommand(newCloneCmd(&repoPath))
@@ -913,7 +914,8 @@ func newRestoreCmd(repoFlag *string) *cobra.Command {
  Short: "Restore the effective machine profile",
  RunE: func(cmd *cobra.Command, args []string) error {
  app := svc(repoFlag)
- info, err := app.Restore(cmd.Context(), host, dryRun)
+ noProject, _ := cmd.Flags().GetBool("no-project")
+ info, err := app.RestoreWithProject(cmd.Context(), host, noProject, dryRun)
  if err != nil {
  return err
  }
@@ -935,7 +937,8 @@ func newUpdateCmd(repoFlag *string) *cobra.Command {
  Short: "Pull repo changes and restore the effective machine profile",
  RunE: func(cmd *cobra.Command, args []string) error {
  app := svc(repoFlag)
- info, err := app.Update(cmd.Context(), host)
+ noProject, _ := cmd.Flags().GetBool("no-project")
+ info, err := app.UpdateWithProject(cmd.Context(), host, noProject)
  if err != nil {
  return err
  }
@@ -1141,6 +1144,24 @@ func printDoctor(w io.Writer, report service.DoctorReport) error {
  }
  }
 	}
+	if len(report.ProjectIssues) > 0 {
+ if _, err := fmt.Fprintln(w, "Project issues:"); err != nil {
+ return err
+ }
+ for _, issue := range report.ProjectIssues {
+ if _, err := fmt.Fprintf(w, " [%s] %s: %s", issue.Severity, issue.ProjectID, issue.Issue); err != nil {
+ return err
+ }
+ if issue.Suggestion != "" {
+ if _, err := fmt.Fprintf(w, " -> %s", issue.Suggestion); err != nil {
+ return err
+ }
+ }
+ if _, err := fmt.Fprintln(w); err != nil {
+ return err
+ }
+ }
+	}
 	if len(report.PrunedProjects) > 0 {
  if _, err := fmt.Fprintln(w, "Pruned empty project storage:"); err != nil {
  return err

service/doctor.go

@@ -61,14 +61,23 @@ type DoctorReport struct {
 	UnmarkedProjects []string // storage under projects/ without a marker
 	EmptyProjects []string // marked projects with no stored files
 	PrunedProjects []string // empty project storage removed by --fix --prune-empty
+	ProjectIssues []ProjectIssue
+}
+
+// ProjectIssue captures a project-scope health finding for doctor.
+type ProjectIssue struct {
+	ProjectID string
+	Issue string
+	Severity string // "error" or "warning"
+	Suggestion string
 }
 
 // HasIssues reports whether the doctor found actionable issues.
 func (r DoctorReport) HasIssues() bool {
 	if r.MarkerMissing || len(r.Collisions) > 0 || len(r.EmptyScopes) > 0 {
  return true
 	}
-	if len(r.UnmarkedProjects) > 0 || len(r.EmptyProjects) > 0 {
+	if len(r.UnmarkedProjects) > 0 || len(r.EmptyProjects) > 0 || len(r.ProjectIssues) > 0 {
  return true
 	}
 	for _, result := range r.ScopeResults {
@@ -182,6 +191,12 @@ func (s *Service) doctorScan(ctx context.Context, host string, all bool) (Doctor
 	report.UnmarkedProjects = unmarked
 	report.EmptyProjects = emptyProjects
 
+	projectIssues, err := s.scanProjectIssues(ctx)
+	if err != nil {
+ return DoctorReport{}, err
+	}
+	report.ProjectIssues = projectIssues
+
 	return report, nil
 }
 

README.md

@@ -157,10 +157,12 @@ lnk list --all # all scopes
 ```bash
 lnk doctor # audit repo and profile health
 lnk doctor --fix # apply safe automatic fixes
-lnk doctor --fix --prune-empty # also remove empty host scopes
+lnk doctor --fix --prune-empty # also remove empty host scopes and project storage
 lnk doctor --all # check all scopes
 ```
 
+`lnk doctor` checks project scope as well as host/common scope: it reports orphaned project storage, broken project symlinks, and `.lnkinclude` patterns that match no files. Project issues are listed with severity and a suggested fix.
+
 When restoring symlinks, if a real file exists at the target location (not a symlink), it will be renamed to `<path>.lnk-backup` to preserve your data before the symlink is created. Check for `.lnk-backup` files after running `restore`, `update`, or `doctor` if you expect them.
 
 ### Format migration
@@ -207,6 +209,12 @@ lnk project untrack --keep .crush/** # remove a pattern but leave files man
 lnk project remove # stop managing the project, restore all files
 lnk project forget # stop managing the project, keep stored files
 
+# implicit detection in update/restore
+lnk update # also restores any detected project scope
+lnk restore # also restores any detected project scope
+lnk update --no-project # skip automatic project-scope detection
+lnk restore --no-project # skip automatic project-scope detection
+
 # global patterns (apply to every project)
 lnk project add --global AGENTS.md # include AGENTS.md everywhere
 lnk project add '!AGENTS.md' # then exclude it in one project
@@ -215,6 +223,8 @@ lnk project untrack --global AGENTS.md # remove the global pattern
 
 Matched files are stored under `projects/<normalized-origin>/<path>/` in your lnk repo (derived from the project's origin remote) and symlinked back into the project. Existing files at symlink locations are backed up to `<path>.lnk-backup` during restore, just like host/common scope restores.
 
+`lnk update` and `lnk restore` automatically detect project scope when they run inside a git repo that contains a `.lnkinclude` file. The project scope is restored alongside the common and host scopes, and a `(project scope: <id>)` message is printed to stderr. Use the global `--no-project` flag to skip automatic detection.
+
 ### Notes and edge cases
 
 - **Global patterns are hand-managed** (or edited via `--global`): they apply to every project, so negate them per project with a local `!` pattern. Quote the `!` in your shell (`'!AGENTS.md'`) or zsh's history expansion will eat it before lnk sees it.
@@ -248,9 +258,9 @@ man man/lnk-project-push.1 # read a generated page
 | `commit [-m message]` | Stage all changes and commit |
 | `push` | Push existing commits |
 | `pull` | Pull repo changes |
-| `restore [--host H] [--dry-run]` | Restore symlinks without pulling |
-| `update [--host H]` | Pull and restore the effective profile |
-| `doctor [--host H \| --all] [--fix] [--prune-empty]` | Audit and fix repo health |
+| `restore [--host H] [--dry-run] [--no-project]` | Restore symlinks without pulling (auto-detects project scope) |
+| `update [--host H] [--no-project]` | Pull and restore the effective profile (auto-detects project scope) |
+| `doctor [--host H \| --all] [--fix] [--prune-empty]` | Audit and fix repo health, including project scope |
 | `format [--v1 \| --v2]` | Migrate repo format |
 | `bootstrap` | Run bootstrap.sh explicitly |
 | `project init` | Activate project scope in the current git repo |
@@ -271,6 +281,7 @@ Available with all commands:
 | Option | Default | What it does |
 | --- | --- | --- |
 | `--repo <path>` | `~/.config/lnk` | Path to the lnk repository |
+| `--no-project` | `false` | Skip automatic project-scope detection |
 
 ## Acknowledgements
 

VERSION

@@ -1 +1 @@
-v2.0.0
+v2.1.0

cmd/root.go

@@ -37,6 +37,7 @@ func NewRootCommand() *cobra.Command {
 	}
 
 	rootCmd.PersistentFlags().StringVar(&repoPath, "repo", "", "path to the lnk repository")
+	rootCmd.PersistentFlags().Bool("no-project", false, "skip automatic project scope detection")
 
 	rootCmd.AddCommand(newInitCmd(&repoPath))
 	rootCmd.AddCommand(newCloneCmd(&repoPath))
@@ -913,7 +914,8 @@ func newRestoreCmd(repoFlag *string) *cobra.Command {
  Short: "Restore the effective machine profile",
  RunE: func(cmd *cobra.Command, args []string) error {
  app := svc(repoFlag)
- info, err := app.Restore(cmd.Context(), host, dryRun)
+ noProject, _ := cmd.Flags().GetBool("no-project")
+ info, err := app.RestoreWithProject(cmd.Context(), host, noProject, dryRun)
  if err != nil {
  return err
  }
@@ -935,7 +937,8 @@ func newUpdateCmd(repoFlag *string) *cobra.Command {
  Short: "Pull repo changes and restore the effective machine profile",
  RunE: func(cmd *cobra.Command, args []string) error {
  app := svc(repoFlag)
- info, err := app.Update(cmd.Context(), host)
+ noProject, _ := cmd.Flags().GetBool("no-project")
+ info, err := app.UpdateWithProject(cmd.Context(), host, noProject)
  if err != nil {
  return err
  }
@@ -1141,6 +1144,24 @@ func printDoctor(w io.Writer, report service.DoctorReport) error {
  }
  }
 	}
+	if len(report.ProjectIssues) > 0 {
+ if _, err := fmt.Fprintln(w, "Project issues:"); err != nil {
+ return err
+ }
+ for _, issue := range report.ProjectIssues {
+ if _, err := fmt.Fprintf(w, " [%s] %s: %s", issue.Severity, issue.ProjectID, issue.Issue); err != nil {
+ return err
+ }
+ if issue.Suggestion != "" {
+ if _, err := fmt.Fprintf(w, " -> %s", issue.Suggestion); err != nil {
+ return err
+ }
+ }
+ if _, err := fmt.Fprintln(w); err != nil {
+ return err
+ }
+ }
+	}
 	if len(report.PrunedProjects) > 0 {
  if _, err := fmt.Fprintln(w, "Pruned empty project storage:"); err != nil {
  return err

service/doctor.go

@@ -61,14 +61,23 @@ type DoctorReport struct {
 	UnmarkedProjects []string // storage under projects/ without a marker
 	EmptyProjects []string // marked projects with no stored files
 	PrunedProjects []string // empty project storage removed by --fix --prune-empty
+	ProjectIssues []ProjectIssue
+}
+
+// ProjectIssue captures a project-scope health finding for doctor.
+type ProjectIssue struct {
+	ProjectID string
+	Issue string
+	Severity string // "error" or "warning"
+	Suggestion string
 }
 
 // HasIssues reports whether the doctor found actionable issues.
 func (r DoctorReport) HasIssues() bool {
 	if r.MarkerMissing || len(r.Collisions) > 0 || len(r.EmptyScopes) > 0 {
  return true
 	}
-	if len(r.UnmarkedProjects) > 0 || len(r.EmptyProjects) > 0 {
+	if len(r.UnmarkedProjects) > 0 || len(r.EmptyProjects) > 0 || len(r.ProjectIssues) > 0 {
  return true
 	}
 	for _, result := range r.ScopeResults {
@@ -182,6 +191,12 @@ func (s *Service) doctorScan(ctx context.Context, host string, all bool) (Doctor
 	report.UnmarkedProjects = unmarked
 	report.EmptyProjects = emptyProjects
 
+	projectIssues, err := s.scanProjectIssues(ctx)
+	if err != nil {
+ return DoctorReport{}, err
+	}
+	report.ProjectIssues = projectIssues
+
 	return report, nil
 }
 

README.md

@@ -157,10 +157,12 @@ lnk list --all # all scopes
 ```bash
 lnk doctor # audit repo and profile health
 lnk doctor --fix # apply safe automatic fixes
-lnk doctor --fix --prune-empty # also remove empty host scopes
+lnk doctor --fix --prune-empty # also remove empty host scopes and project storage
 lnk doctor --all # check all scopes
 ```
 
+`lnk doctor` checks project scope as well as host/common scope: it reports orphaned project storage, broken project symlinks, and `.lnkinclude` patterns that match no files. Project issues are listed with severity and a suggested fix.
+
 When restoring symlinks, if a real file exists at the target location (not a symlink), it will be renamed to `<path>.lnk-backup` to preserve your data before the symlink is created. Check for `.lnk-backup` files after running `restore`, `update`, or `doctor` if you expect them.
 
 ### Format migration
@@ -207,6 +209,12 @@ lnk project untrack --keep .crush/** # remove a pattern but leave files man
 lnk project remove # stop managing the project, restore all files
 lnk project forget # stop managing the project, keep stored files
 
+# implicit detection in update/restore
+lnk update # also restores any detected project scope
+lnk restore # also restores any detected project scope
+lnk update --no-project # skip automatic project-scope detection
+lnk restore --no-project # skip automatic project-scope detection
+
 # global patterns (apply to every project)
 lnk project add --global AGENTS.md # include AGENTS.md everywhere
 lnk project add '!AGENTS.md' # then exclude it in one project
@@ -215,6 +223,8 @@ lnk project untrack --global AGENTS.md # remove the global pattern
 
 Matched files are stored under `projects/<normalized-origin>/<path>/` in your lnk repo (derived from the project's origin remote) and symlinked back into the project. Existing files at symlink locations are backed up to `<path>.lnk-backup` during restore, just like host/common scope restores.
 
+`lnk update` and `lnk restore` automatically detect project scope when they run inside a git repo that contains a `.lnkinclude` file. The project scope is restored alongside the common and host scopes, and a `(project scope: <id>)` message is printed to stderr. Use the global `--no-project` flag to skip automatic detection.
+
 ### Notes and edge cases
 
 - **Global patterns are hand-managed** (or edited via `--global`): they apply to every project, so negate them per project with a local `!` pattern. Quote the `!` in your shell (`'!AGENTS.md'`) or zsh's history expansion will eat it before lnk sees it.
@@ -248,9 +258,9 @@ man man/lnk-project-push.1 # read a generated page
 | `commit [-m message]` | Stage all changes and commit |
 | `push` | Push existing commits |
 | `pull` | Pull repo changes |
-| `restore [--host H] [--dry-run]` | Restore symlinks without pulling |
-| `update [--host H]` | Pull and restore the effective profile |
-| `doctor [--host H \| --all] [--fix] [--prune-empty]` | Audit and fix repo health |
+| `restore [--host H] [--dry-run] [--no-project]` | Restore symlinks without pulling (auto-detects project scope) |
+| `update [--host H] [--no-project]` | Pull and restore the effective profile (auto-detects project scope) |
+| `doctor [--host H \| --all] [--fix] [--prune-empty]` | Audit and fix repo health, including project scope |
 | `format [--v1 \| --v2]` | Migrate repo format |
 | `bootstrap` | Run bootstrap.sh explicitly |
 | `project init` | Activate project scope in the current git repo |
@@ -271,6 +281,7 @@ Available with all commands:
 | Option | Default | What it does |
 | --- | --- | --- |
 | `--repo <path>` | `~/.config/lnk` | Path to the lnk repository |
+| `--no-project` | `false` | Skip automatic project-scope detection |
 
 ## Acknowledgements
 

VERSION

@@ -1 +1 @@
-v2.0.0
+v2.1.0

cmd/root.go

@@ -37,6 +37,7 @@ func NewRootCommand() *cobra.Command {
 	}
 
 	rootCmd.PersistentFlags().StringVar(&repoPath, "repo", "", "path to the lnk repository")
+	rootCmd.PersistentFlags().Bool("no-project", false, "skip automatic project scope detection")
 
 	rootCmd.AddCommand(newInitCmd(&repoPath))
 	rootCmd.AddCommand(newCloneCmd(&repoPath))
@@ -913,7 +914,8 @@ func newRestoreCmd(repoFlag *string) *cobra.Command {
  Short: "Restore the effective machine profile",
  RunE: func(cmd *cobra.Command, args []string) error {
  app := svc(repoFlag)
- info, err := app.Restore(cmd.Context(), host, dryRun)
+ noProject, _ := cmd.Flags().GetBool("no-project")
+ info, err := app.RestoreWithProject(cmd.Context(), host, noProject, dryRun)
  if err != nil {
  return err
  }
@@ -935,7 +937,8 @@ func newUpdateCmd(repoFlag *string) *cobra.Command {
  Short: "Pull repo changes and restore the effective machine profile",
  RunE: func(cmd *cobra.Command, args []string) error {
  app := svc(repoFlag)
- info, err := app.Update(cmd.Context(), host)
+ noProject, _ := cmd.Flags().GetBool("no-project")
+ info, err := app.UpdateWithProject(cmd.Context(), host, noProject)
  if err != nil {
  return err
  }
@@ -1141,6 +1144,24 @@ func printDoctor(w io.Writer, report service.DoctorReport) error {
  }
  }
 	}
+	if len(report.ProjectIssues) > 0 {
+ if _, err := fmt.Fprintln(w, "Project issues:"); err != nil {
+ return err
+ }
+ for _, issue := range report.ProjectIssues {
+ if _, err := fmt.Fprintf(w, " [%s] %s: %s", issue.Severity, issue.ProjectID, issue.Issue); err != nil {
+ return err
+ }
+ if issue.Suggestion != "" {
+ if _, err := fmt.Fprintf(w, " -> %s", issue.Suggestion); err != nil {
+ return err
+ }
+ }
+ if _, err := fmt.Fprintln(w); err != nil {
+ return err
+ }
+ }
+	}
 	if len(report.PrunedProjects) > 0 {
  if _, err := fmt.Fprintln(w, "Pruned empty project storage:"); err != nil {
  return err

service/doctor.go

@@ -61,14 +61,23 @@ type DoctorReport struct {
 	UnmarkedProjects []string // storage under projects/ without a marker
 	EmptyProjects []string // marked projects with no stored files
 	PrunedProjects []string // empty project storage removed by --fix --prune-empty
+	ProjectIssues []ProjectIssue
+}
+
+// ProjectIssue captures a project-scope health finding for doctor.
+type ProjectIssue struct {
+	ProjectID string
+	Issue string
+	Severity string // "error" or "warning"
+	Suggestion string
 }
 
 // HasIssues reports whether the doctor found actionable issues.
 func (r DoctorReport) HasIssues() bool {
 	if r.MarkerMissing || len(r.Collisions) > 0 || len(r.EmptyScopes) > 0 {
  return true
 	}
-	if len(r.UnmarkedProjects) > 0 || len(r.EmptyProjects) > 0 {
+	if len(r.UnmarkedProjects) > 0 || len(r.EmptyProjects) > 0 || len(r.ProjectIssues) > 0 {
  return true
 	}
 	for _, result := range r.ScopeResults {
@@ -182,6 +191,12 @@ func (s *Service) doctorScan(ctx context.Context, host string, all bool) (Doctor
 	report.UnmarkedProjects = unmarked
 	report.EmptyProjects = emptyProjects
 
+	projectIssues, err := s.scanProjectIssues(ctx)
+	if err != nil {
+ return DoctorReport{}, err
+	}
+	report.ProjectIssues = projectIssues
+
 	return report, nil
 }
 

README.md

@@ -157,10 +157,12 @@ lnk list --all # all scopes
 ```bash
 lnk doctor # audit repo and profile health
 lnk doctor --fix # apply safe automatic fixes
-lnk doctor --fix --prune-empty # also remove empty host scopes
+lnk doctor --fix --prune-empty # also remove empty host scopes and project storage
 lnk doctor --all # check all scopes
 ```
 
+`lnk doctor` checks project scope as well as host/common scope: it reports orphaned project storage, broken project symlinks, and `.lnkinclude` patterns that match no files. Project issues are listed with severity and a suggested fix.
+
 When restoring symlinks, if a real file exists at the target location (not a symlink), it will be renamed to `<path>.lnk-backup` to preserve your data before the symlink is created. Check for `.lnk-backup` files after running `restore`, `update`, or `doctor` if you expect them.
 
 ### Format migration
@@ -207,6 +209,12 @@ lnk project untrack --keep .crush/** # remove a pattern but leave files man
 lnk project remove # stop managing the project, restore all files
 lnk project forget # stop managing the project, keep stored files
 
+# implicit detection in update/restore
+lnk update # also restores any detected project scope
+lnk restore # also restores any detected project scope
+lnk update --no-project # skip automatic project-scope detection
+lnk restore --no-project # skip automatic project-scope detection
+
 # global patterns (apply to every project)
 lnk project add --global AGENTS.md # include AGENTS.md everywhere
 lnk project add '!AGENTS.md' # then exclude it in one project
@@ -215,6 +223,8 @@ lnk project untrack --global AGENTS.md # remove the global pattern
 
 Matched files are stored under `projects/<normalized-origin>/<path>/` in your lnk repo (derived from the project's origin remote) and symlinked back into the project. Existing files at symlink locations are backed up to `<path>.lnk-backup` during restore, just like host/common scope restores.
 
+`lnk update` and `lnk restore` automatically detect project scope when they run inside a git repo that contains a `.lnkinclude` file. The project scope is restored alongside the common and host scopes, and a `(project scope: <id>)` message is printed to stderr. Use the global `--no-project` flag to skip automatic detection.
+
 ### Notes and edge cases
 
 - **Global patterns are hand-managed** (or edited via `--global`): they apply to every project, so negate them per project with a local `!` pattern. Quote the `!` in your shell (`'!AGENTS.md'`) or zsh's history expansion will eat it before lnk sees it.
@@ -248,9 +258,9 @@ man man/lnk-project-push.1 # read a generated page
 | `commit [-m message]` | Stage all changes and commit |
 | `push` | Push existing commits |
 | `pull` | Pull repo changes |
-| `restore [--host H] [--dry-run]` | Restore symlinks without pulling |
-| `update [--host H]` | Pull and restore the effective profile |
-| `doctor [--host H \| --all] [--fix] [--prune-empty]` | Audit and fix repo health |
+| `restore [--host H] [--dry-run] [--no-project]` | Restore symlinks without pulling (auto-detects project scope) |
+| `update [--host H] [--no-project]` | Pull and restore the effective profile (auto-detects project scope) |
+| `doctor [--host H \| --all] [--fix] [--prune-empty]` | Audit and fix repo health, including project scope |
 | `format [--v1 \| --v2]` | Migrate repo format |
 | `bootstrap` | Run bootstrap.sh explicitly |
 | `project init` | Activate project scope in the current git repo |
@@ -271,6 +281,7 @@ Available with all commands:
 | Option | Default | What it does |
 | --- | --- | --- |
 | `--repo <path>` | `~/.config/lnk` | Path to the lnk repository |
+| `--no-project` | `false` | Skip automatic project-scope detection |
 
 ## Acknowledgements
 

VERSION

@@ -1 +1 @@
-v2.0.0
+v2.1.0

cmd/root.go

@@ -37,6 +37,7 @@ func NewRootCommand() *cobra.Command {
 	}
 
 	rootCmd.PersistentFlags().StringVar(&repoPath, "repo", "", "path to the lnk repository")
+	rootCmd.PersistentFlags().Bool("no-project", false, "skip automatic project scope detection")
 
 	rootCmd.AddCommand(newInitCmd(&repoPath))
 	rootCmd.AddCommand(newCloneCmd(&repoPath))
@@ -913,7 +914,8 @@ func newRestoreCmd(repoFlag *string) *cobra.Command {
  Short: "Restore the effective machine profile",
  RunE: func(cmd *cobra.Command, args []string) error {
  app := svc(repoFlag)
- info, err := app.Restore(cmd.Context(), host, dryRun)
+ noProject, _ := cmd.Flags().GetBool("no-project")
+ info, err := app.RestoreWithProject(cmd.Context(), host, noProject, dryRun)
  if err != nil {
  return err
  }
@@ -935,7 +937,8 @@ func newUpdateCmd(repoFlag *string) *cobra.Command {
  Short: "Pull repo changes and restore the effective machine profile",
  RunE: func(cmd *cobra.Command, args []string) error {
  app := svc(repoFlag)
- info, err := app.Update(cmd.Context(), host)
+ noProject, _ := cmd.Flags().GetBool("no-project")
+ info, err := app.UpdateWithProject(cmd.Context(), host, noProject)
  if err != nil {
  return err
  }
@@ -1141,6 +1144,24 @@ func printDoctor(w io.Writer, report service.DoctorReport) error {
  }
  }
 	}
+	if len(report.ProjectIssues) > 0 {
+ if _, err := fmt.Fprintln(w, "Project issues:"); err != nil {
+ return err
+ }
+ for _, issue := range report.ProjectIssues {
+ if _, err := fmt.Fprintf(w, " [%s] %s: %s", issue.Severity, issue.ProjectID, issue.Issue); err != nil {
+ return err
+ }
+ if issue.Suggestion != "" {
+ if _, err := fmt.Fprintf(w, " -> %s", issue.Suggestion); err != nil {
+ return err
+ }
+ }
+ if _, err := fmt.Fprintln(w); err != nil {
+ return err
+ }
+ }
+	}
 	if len(report.PrunedProjects) > 0 {
  if _, err := fmt.Fprintln(w, "Pruned empty project storage:"); err != nil {
  return err

service/doctor.go

@@ -61,14 +61,23 @@ type DoctorReport struct {
 	UnmarkedProjects []string // storage under projects/ without a marker
 	EmptyProjects []string // marked projects with no stored files
 	PrunedProjects []string // empty project storage removed by --fix --prune-empty
+	ProjectIssues []ProjectIssue
+}
+
+// ProjectIssue captures a project-scope health finding for doctor.
+type ProjectIssue struct {
+	ProjectID string
+	Issue string
+	Severity string // "error" or "warning"
+	Suggestion string
 }
 
 // HasIssues reports whether the doctor found actionable issues.
 func (r DoctorReport) HasIssues() bool {
 	if r.MarkerMissing || len(r.Collisions) > 0 || len(r.EmptyScopes) > 0 {
  return true
 	}
-	if len(r.UnmarkedProjects) > 0 || len(r.EmptyProjects) > 0 {
+	if len(r.UnmarkedProjects) > 0 || len(r.EmptyProjects) > 0 || len(r.ProjectIssues) > 0 {
  return true
 	}
 	for _, result := range r.ScopeResults {
@@ -182,6 +191,12 @@ func (s *Service) doctorScan(ctx context.Context, host string, all bool) (Doctor
 	report.UnmarkedProjects = unmarked
 	report.EmptyProjects = emptyProjects
 
+	projectIssues, err := s.scanProjectIssues(ctx)
+	if err != nil {
+ return DoctorReport{}, err
+	}
+	report.ProjectIssues = projectIssues
+
 	return report, nil
 }