agent-wiki-cli 1.3.0__tar.gz → 1.4.0__tar.gz

{agent_wiki_cli-1.3.0/src/agent_wiki_cli.egg-info → agent_wiki_cli-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-wiki-cli
-Version: 1.3.0
+Version: 1.4.0
 Summary: CLI tool to maintain hybrid LLM Wikis for multi-language projects.
 Author-email: Denis Sivagin <denissvgn@gmail.com>
 License: MIT
@@ -115,11 +115,13 @@ helper dependencies and binaries with `llm-wiki prepare-extractors`. Lint, CI,
 and extract never run `npm install`, `go build`, `go run`, `cargo build`,
 `cargo run`, or `ghc` automatically.
 
-Source discovery honors `.gitignore` before extractors run. A root, unanchored
-`lib/` rule is treated as a generic build-output pattern for TypeScript
-projects, so `.ts`, `.tsx`, `.js`, and `.jsx` files under `src/lib/` remain
-first-party source; top-level `lib/`, excluded dependency/build directories,
-and explicit nested `.gitignore` rules still stay excluded. Generated agent
+Source discovery honors `.gitignore` before extractors run. Unescaped trailing
+ASCII spaces in ignore entries are ignored, while `\ ` preserves a literal
+final space. A root, unanchored `lib/` rule is treated as a generic build-output
+pattern for TypeScript projects, so `.ts`, `.tsx`, `.js`, and `.jsx` files under
+`src/lib/` remain first-party source; top-level `lib/`, excluded
+dependency/build directories, and explicit nested `.gitignore` rules still stay
+excluded. Generated agent
 worktree copies such as `.claude/worktrees/**` are excluded from default
 snapshots; pass an exact `--paths` entry if you intentionally want to inspect
 one file there.
@@ -240,9 +242,17 @@ Install a post-commit hook:
 llm-wiki install-hook
 ```
 
-`init` writes the selected agent and quality-hint setting to
+`init` writes the selected agent and instruction preferences to
 `.git/.llm-wiki-agent` when the project is a Git repo. Outside Git, it falls
-back to `<wiki-dir>/.llm-wiki-agent`.
+back to `<wiki-dir>/.llm-wiki-agent`. Tool-issue reporting guidance is omitted
+by default; opt in when you want agents to create local bug-report files:
+
+```bash
+llm-wiki init --agent claude --issue-reporting
+```
+
+This only adds guidance to the generated agent instruction block. It does not
+upload reports, submit issues, or enable telemetry.
 
 ## Automation
 
@@ -291,6 +301,30 @@ llm-wiki install-hook --force
 
 ## Command Reference
 
+### Resource-aware execution
+
+In an interactive IDE or whenever host capacity is unknown, run one heavy gate
+at a time. Heavy gates include `context`, full tests, coverage, builds, browser
+suites, `sync`, `lint`, and `ci-check`. The supervising agent owns that
+schedule; subagents may inspect bounded files and diffs, but should not launch
+heavy gates unless explicitly assigned.
+
+Use `--jobs 1` for interactive source scans. `--jobs auto` remains an uncapped
+opt-in for an isolated terminal or a controlled CI runner with reserved
+capacity; do not combine it with nested heavy-gate fan-out. If ENOSPC, inotify,
+file-descriptor, severe swapping, or editor-responsiveness failures occur, stop
+launching work and do not retry the same burst. Recover capacity first, then
+attempt at most one manual retry with `--jobs 1`; unfinished gates remain
+inconclusive. Watcher-limit symptoms are host/IDE resource evidence, not proof
+that `llm-wiki` leaked a watcher.
+
+Before extraction, `sync`, `lint`, `ci-check`, and `context` write one flushed
+plan line to stderr without contaminating stdout, for example:
+
+```text
+Extractor plan: requested=auto resolved=20 eligible_parallel=2 effective_workers=2 parallel=python,typescript sequential=- cache_elided=-
+```
+
 ### `init`
 
 Scaffold the wiki structure and agent constraint file.
@@ -299,10 +333,16 @@ Scaffold the wiki structure and agent constraint file.
 llm-wiki init --agent claude
 llm-wiki init --agent copilot --wiki-dir .wiki
 llm-wiki init --agent cursor --no-quality-hints
+llm-wiki init --agent generic --issue-reporting
 ```
 
 Supported agents are `claude`, `aider`, `opencode`, `copilot`, `cursor`, and
-`generic`.
+`generic`. `--issue-reporting` includes instructions that ask agents to record
+`llm-wiki` tool failures under the local `llm-wiki-issues/` directory. The
+instructions are off by default; use `--no-issue-reporting` to explicitly omit
+them when refreshing an existing initialization. On a refresh, omitting
+`--agent` reuses the stored agent; a project with no stored selection defaults
+to `generic`.
 
 ### `bootstrap`
 
@@ -367,7 +407,7 @@ manifest.
 
 ```bash
 llm-wiki sync --src-dir . --wiki-dir docs/llm_wiki
-llm-wiki sync --jobs auto --cache-stats --src-dir . --wiki-dir docs/llm_wiki
+llm-wiki sync --jobs 1 --cache-stats --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki sync --cache-dir .cache/llm-wiki-inventory --helper-cache-dir .cache/llm-wiki-helpers
 llm-wiki sync --include-tests go --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki sync --initialize-surfaces flows,dependencies --flow-category http --exclude-tests --dry-run
@@ -382,8 +422,10 @@ persistent inventory cache as lint when a git directory is available. Use
 `--no-cache`, `--rebuild-cache`, `--cache-dir PATH`, and `--cache-stats` to
 control or inspect inventory cache behavior. Use `--helper-cache-dir PATH` to
 point Go/Rust/Haskell extraction at prepared helpers in a separate cache. Use
-`--jobs N` or `--jobs auto` to opt into parallel extraction for built-in
-languages and plugin extractors whose manifests set `"parallel_safe": true`.
+The interactive default is `--jobs 1`. Use `--jobs N` or `--jobs auto` to opt
+into parallel extraction for built-in languages and plugin extractors whose
+manifests set `"parallel_safe": true`; reserve `auto` for an isolated terminal
+or controlled CI runner with known capacity.
 Sync repairs
 manifests with invalid source hashes without touching pages, and stops unusually
 broad diffs unless `--force` is used.
@@ -576,7 +618,7 @@ llm-wiki lint --profile --wiki-dir docs/llm_wiki --src-dir .
 llm-wiki lint --cache-stats --wiki-dir docs/llm_wiki --src-dir .
 llm-wiki lint --cache-dir .cache/llm-wiki-inventory --helper-cache-dir .cache/llm-wiki-helpers
 llm-wiki lint --include-tests go --wiki-dir docs/llm_wiki --src-dir .
-llm-wiki lint --jobs auto --wiki-dir docs/llm_wiki --src-dir .
+llm-wiki lint --jobs 1 --wiki-dir docs/llm_wiki --src-dir .
 llm-wiki lint --wiki-dir docs/llm_wiki --src-dir /path/to/repo --allow-external-src
 ```
 
@@ -585,6 +627,27 @@ Strict mode also requires the core wiki structure and a fresh sync manifest.
 to stdout containing the normal lint report, diagnostics, and phase timings.
 The JSON contract is preserved for extractor failures as well; lint still exits
 nonzero, but stdout remains machine-readable.
+`lint --profile` and `ci-check --format json` additionally include this shape:
+
+```json
+{
+  "execution": {
+    "extractor_jobs": {
+      "requested_jobs": "auto",
+      "resolved_jobs": 20,
+      "eligible_parallel_plans": 2,
+      "effective_workers": 2,
+      "parallel_plan_ids": ["python", "typescript"],
+      "sequential_plan_ids": [],
+      "cache_elided_plan_ids": []
+    }
+  }
+}
+```
+
+This metadata is additive only in those two JSON modes. Default lint report
+serialization, MCP lint responses, CI text/Markdown output, sync state and
+manifests, and the `llm-wiki-context/v1` protocol stay unchanged.
 Lint uses a persistent deep-inventory cache by default when a git directory is
 available, storing `.git/llm-wiki-inventory-cache.json`. Override the cache
 directory with `LLM_WIKI_CACHE_DIR` or `--cache-dir PATH`; the CLI flag wins for
@@ -596,8 +659,9 @@ Cache corruption or invalid fingerprints fall back to a full extraction without
 reducing lint coverage. With `--profile --cache-stats`, the JSON payload includes a top-level
 `cache` object. Use `--jobs N` or `--jobs auto` to opt into parallel extraction
 for built-in languages and plugin extractors whose manifests set
-`"parallel_safe": true`; the default is `--jobs 1`. Plugin extractors without
-that opt-in remain sequential.
+`"parallel_safe": true`; the default and recommended interactive setting is
+`--jobs 1`. Reserve `auto` for an isolated terminal or controlled CI runner
+with known capacity. Plugin extractors without that opt-in remain sequential.
 Use `--include-tests go` when a wiki intentionally documents Go `_test.go`
 files; omit it to lint against the default production-source inventory.
 For trusted source trees outside the runner workspace, pass
@@ -661,6 +725,7 @@ For CI:
 
 ```bash
 llm-wiki ci-check --src-dir . --wiki-dir docs/llm_wiki
+# Capacity-reserved CI only; shared or unknown-capacity runners should use jobs 1.
 llm-wiki ci-check --jobs auto --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki ci-check --helper-cache-dir .cache/llm-wiki-helpers --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki ci-check --include-tests go --src-dir . --wiki-dir docs/llm_wiki
@@ -694,6 +759,13 @@ llm-wiki context --budget 12000 --format json --focus all --output context.json
 `--focus changed` is the default. Changed files get full detail, one-hop import
 neighbors get slim detail, and remaining files get names only.
 
+For broad repository-wide work, run one serialized
+`llm-wiki context --budget 8000 --focus changed --read-only`, then read only the
+source and wiki pages it selects. For a narrow task with supplied files or a
+supplied diff, skip the full context scan and use the wiki index only for
+navigation. The budget and focus bound emitted output after a full deep
+inventory; they do not make the scan computationally cheap.
+
 External tools can use the `llm-wiki-context/v1` JSON request protocol:
 
 ```bash
@@ -1165,10 +1237,15 @@ llm-wiki upgrade --agent copilot
 llm-wiki upgrade --wiki-dir .wiki
 llm-wiki upgrade --force
 llm-wiki upgrade --no-quality-hints
+llm-wiki upgrade --issue-reporting
+llm-wiki upgrade --no-issue-reporting
 ```
 
 `upgrade` refreshes agent instruction blocks, wiki directories, hooks, plugin
-skill blocks, and persisted local config. For older wiki layouts, it
+skill blocks, and persisted local config. The issue-reporting pair explicitly
+enables or disables the local agent guidance; without either flag, `upgrade`
+preserves the stored preference. Configurations created before this preference
+existed default to disabled. For older wiki layouts, `upgrade`
 idempotently adds registry-standard directories such as `flows/` and missing
 `.gitkeep` files without rewriting existing index, log, semantic pages, or
 optional `dependencies.md` / `load-order.md` pages. Run `bootstrap` or `sync`

{agent_wiki_cli-1.3.0 → agent_wiki_cli-1.4.0}/README.md

@@ -84,11 +84,13 @@ helper dependencies and binaries with `llm-wiki prepare-extractors`. Lint, CI,
 and extract never run `npm install`, `go build`, `go run`, `cargo build`,
 `cargo run`, or `ghc` automatically.
 
-Source discovery honors `.gitignore` before extractors run. A root, unanchored
-`lib/` rule is treated as a generic build-output pattern for TypeScript
-projects, so `.ts`, `.tsx`, `.js`, and `.jsx` files under `src/lib/` remain
-first-party source; top-level `lib/`, excluded dependency/build directories,
-and explicit nested `.gitignore` rules still stay excluded. Generated agent
+Source discovery honors `.gitignore` before extractors run. Unescaped trailing
+ASCII spaces in ignore entries are ignored, while `\ ` preserves a literal
+final space. A root, unanchored `lib/` rule is treated as a generic build-output
+pattern for TypeScript projects, so `.ts`, `.tsx`, `.js`, and `.jsx` files under
+`src/lib/` remain first-party source; top-level `lib/`, excluded
+dependency/build directories, and explicit nested `.gitignore` rules still stay
+excluded. Generated agent
 worktree copies such as `.claude/worktrees/**` are excluded from default
 snapshots; pass an exact `--paths` entry if you intentionally want to inspect
 one file there.
@@ -209,9 +211,17 @@ Install a post-commit hook:
 llm-wiki install-hook
 ```
 
-`init` writes the selected agent and quality-hint setting to
+`init` writes the selected agent and instruction preferences to
 `.git/.llm-wiki-agent` when the project is a Git repo. Outside Git, it falls
-back to `<wiki-dir>/.llm-wiki-agent`.
+back to `<wiki-dir>/.llm-wiki-agent`. Tool-issue reporting guidance is omitted
+by default; opt in when you want agents to create local bug-report files:
+
+```bash
+llm-wiki init --agent claude --issue-reporting
+```
+
+This only adds guidance to the generated agent instruction block. It does not
+upload reports, submit issues, or enable telemetry.
 
 ## Automation
 
@@ -260,6 +270,30 @@ llm-wiki install-hook --force
 
 ## Command Reference
 
+### Resource-aware execution
+
+In an interactive IDE or whenever host capacity is unknown, run one heavy gate
+at a time. Heavy gates include `context`, full tests, coverage, builds, browser
+suites, `sync`, `lint`, and `ci-check`. The supervising agent owns that
+schedule; subagents may inspect bounded files and diffs, but should not launch
+heavy gates unless explicitly assigned.
+
+Use `--jobs 1` for interactive source scans. `--jobs auto` remains an uncapped
+opt-in for an isolated terminal or a controlled CI runner with reserved
+capacity; do not combine it with nested heavy-gate fan-out. If ENOSPC, inotify,
+file-descriptor, severe swapping, or editor-responsiveness failures occur, stop
+launching work and do not retry the same burst. Recover capacity first, then
+attempt at most one manual retry with `--jobs 1`; unfinished gates remain
+inconclusive. Watcher-limit symptoms are host/IDE resource evidence, not proof
+that `llm-wiki` leaked a watcher.
+
+Before extraction, `sync`, `lint`, `ci-check`, and `context` write one flushed
+plan line to stderr without contaminating stdout, for example:
+
+```text
+Extractor plan: requested=auto resolved=20 eligible_parallel=2 effective_workers=2 parallel=python,typescript sequential=- cache_elided=-
+```
+
 ### `init`
 
 Scaffold the wiki structure and agent constraint file.
@@ -268,10 +302,16 @@ Scaffold the wiki structure and agent constraint file.
 llm-wiki init --agent claude
 llm-wiki init --agent copilot --wiki-dir .wiki
 llm-wiki init --agent cursor --no-quality-hints
+llm-wiki init --agent generic --issue-reporting
 ```
 
 Supported agents are `claude`, `aider`, `opencode`, `copilot`, `cursor`, and
-`generic`.
+`generic`. `--issue-reporting` includes instructions that ask agents to record
+`llm-wiki` tool failures under the local `llm-wiki-issues/` directory. The
+instructions are off by default; use `--no-issue-reporting` to explicitly omit
+them when refreshing an existing initialization. On a refresh, omitting
+`--agent` reuses the stored agent; a project with no stored selection defaults
+to `generic`.
 
 ### `bootstrap`
 
@@ -336,7 +376,7 @@ manifest.
 
 ```bash
 llm-wiki sync --src-dir . --wiki-dir docs/llm_wiki
-llm-wiki sync --jobs auto --cache-stats --src-dir . --wiki-dir docs/llm_wiki
+llm-wiki sync --jobs 1 --cache-stats --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki sync --cache-dir .cache/llm-wiki-inventory --helper-cache-dir .cache/llm-wiki-helpers
 llm-wiki sync --include-tests go --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki sync --initialize-surfaces flows,dependencies --flow-category http --exclude-tests --dry-run
@@ -351,8 +391,10 @@ persistent inventory cache as lint when a git directory is available. Use
 `--no-cache`, `--rebuild-cache`, `--cache-dir PATH`, and `--cache-stats` to
 control or inspect inventory cache behavior. Use `--helper-cache-dir PATH` to
 point Go/Rust/Haskell extraction at prepared helpers in a separate cache. Use
-`--jobs N` or `--jobs auto` to opt into parallel extraction for built-in
-languages and plugin extractors whose manifests set `"parallel_safe": true`.
+The interactive default is `--jobs 1`. Use `--jobs N` or `--jobs auto` to opt
+into parallel extraction for built-in languages and plugin extractors whose
+manifests set `"parallel_safe": true`; reserve `auto` for an isolated terminal
+or controlled CI runner with known capacity.
 Sync repairs
 manifests with invalid source hashes without touching pages, and stops unusually
 broad diffs unless `--force` is used.
@@ -545,7 +587,7 @@ llm-wiki lint --profile --wiki-dir docs/llm_wiki --src-dir .
 llm-wiki lint --cache-stats --wiki-dir docs/llm_wiki --src-dir .
 llm-wiki lint --cache-dir .cache/llm-wiki-inventory --helper-cache-dir .cache/llm-wiki-helpers
 llm-wiki lint --include-tests go --wiki-dir docs/llm_wiki --src-dir .
-llm-wiki lint --jobs auto --wiki-dir docs/llm_wiki --src-dir .
+llm-wiki lint --jobs 1 --wiki-dir docs/llm_wiki --src-dir .
 llm-wiki lint --wiki-dir docs/llm_wiki --src-dir /path/to/repo --allow-external-src
 ```
 
@@ -554,6 +596,27 @@ Strict mode also requires the core wiki structure and a fresh sync manifest.
 to stdout containing the normal lint report, diagnostics, and phase timings.
 The JSON contract is preserved for extractor failures as well; lint still exits
 nonzero, but stdout remains machine-readable.
+`lint --profile` and `ci-check --format json` additionally include this shape:
+
+```json
+{
+  "execution": {
+    "extractor_jobs": {
+      "requested_jobs": "auto",
+      "resolved_jobs": 20,
+      "eligible_parallel_plans": 2,
+      "effective_workers": 2,
+      "parallel_plan_ids": ["python", "typescript"],
+      "sequential_plan_ids": [],
+      "cache_elided_plan_ids": []
+    }
+  }
+}
+```
+
+This metadata is additive only in those two JSON modes. Default lint report
+serialization, MCP lint responses, CI text/Markdown output, sync state and
+manifests, and the `llm-wiki-context/v1` protocol stay unchanged.
 Lint uses a persistent deep-inventory cache by default when a git directory is
 available, storing `.git/llm-wiki-inventory-cache.json`. Override the cache
 directory with `LLM_WIKI_CACHE_DIR` or `--cache-dir PATH`; the CLI flag wins for
@@ -565,8 +628,9 @@ Cache corruption or invalid fingerprints fall back to a full extraction without
 reducing lint coverage. With `--profile --cache-stats`, the JSON payload includes a top-level
 `cache` object. Use `--jobs N` or `--jobs auto` to opt into parallel extraction
 for built-in languages and plugin extractors whose manifests set
-`"parallel_safe": true`; the default is `--jobs 1`. Plugin extractors without
-that opt-in remain sequential.
+`"parallel_safe": true`; the default and recommended interactive setting is
+`--jobs 1`. Reserve `auto` for an isolated terminal or controlled CI runner
+with known capacity. Plugin extractors without that opt-in remain sequential.
 Use `--include-tests go` when a wiki intentionally documents Go `_test.go`
 files; omit it to lint against the default production-source inventory.
 For trusted source trees outside the runner workspace, pass
@@ -630,6 +694,7 @@ For CI:
 
 ```bash
 llm-wiki ci-check --src-dir . --wiki-dir docs/llm_wiki
+# Capacity-reserved CI only; shared or unknown-capacity runners should use jobs 1.
 llm-wiki ci-check --jobs auto --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki ci-check --helper-cache-dir .cache/llm-wiki-helpers --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki ci-check --include-tests go --src-dir . --wiki-dir docs/llm_wiki
@@ -663,6 +728,13 @@ llm-wiki context --budget 12000 --format json --focus all --output context.json
 `--focus changed` is the default. Changed files get full detail, one-hop import
 neighbors get slim detail, and remaining files get names only.
 
+For broad repository-wide work, run one serialized
+`llm-wiki context --budget 8000 --focus changed --read-only`, then read only the
+source and wiki pages it selects. For a narrow task with supplied files or a
+supplied diff, skip the full context scan and use the wiki index only for
+navigation. The budget and focus bound emitted output after a full deep
+inventory; they do not make the scan computationally cheap.
+
 External tools can use the `llm-wiki-context/v1` JSON request protocol:
 
 ```bash
@@ -1134,10 +1206,15 @@ llm-wiki upgrade --agent copilot
 llm-wiki upgrade --wiki-dir .wiki
 llm-wiki upgrade --force
 llm-wiki upgrade --no-quality-hints
+llm-wiki upgrade --issue-reporting
+llm-wiki upgrade --no-issue-reporting
 ```
 
 `upgrade` refreshes agent instruction blocks, wiki directories, hooks, plugin
-skill blocks, and persisted local config. For older wiki layouts, it
+skill blocks, and persisted local config. The issue-reporting pair explicitly
+enables or disables the local agent guidance; without either flag, `upgrade`
+preserves the stored preference. Configurations created before this preference
+existed default to disabled. For older wiki layouts, `upgrade`
 idempotently adds registry-standard directories such as `flows/` and missing
 `.gitkeep` files without rewriting existing index, log, semantic pages, or
 optional `dependencies.md` / `load-order.md` pages. Run `bootstrap` or `sync`

{agent_wiki_cli-1.3.0 → agent_wiki_cli-1.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-wiki-cli"
-version = "1.3.0"
+version = "1.4.0"
 description = "CLI tool to maintain hybrid LLM Wikis for multi-language projects."
 readme = "README.md"
 license = {text = "MIT"}

{agent_wiki_cli-1.3.0 → agent_wiki_cli-1.4.0/src/agent_wiki_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-wiki-cli
-Version: 1.3.0
+Version: 1.4.0
 Summary: CLI tool to maintain hybrid LLM Wikis for multi-language projects.
 Author-email: Denis Sivagin <denissvgn@gmail.com>
 License: MIT
@@ -115,11 +115,13 @@ helper dependencies and binaries with `llm-wiki prepare-extractors`. Lint, CI,
 and extract never run `npm install`, `go build`, `go run`, `cargo build`,
 `cargo run`, or `ghc` automatically.
 
-Source discovery honors `.gitignore` before extractors run. A root, unanchored
-`lib/` rule is treated as a generic build-output pattern for TypeScript
-projects, so `.ts`, `.tsx`, `.js`, and `.jsx` files under `src/lib/` remain
-first-party source; top-level `lib/`, excluded dependency/build directories,
-and explicit nested `.gitignore` rules still stay excluded. Generated agent
+Source discovery honors `.gitignore` before extractors run. Unescaped trailing
+ASCII spaces in ignore entries are ignored, while `\ ` preserves a literal
+final space. A root, unanchored `lib/` rule is treated as a generic build-output
+pattern for TypeScript projects, so `.ts`, `.tsx`, `.js`, and `.jsx` files under
+`src/lib/` remain first-party source; top-level `lib/`, excluded
+dependency/build directories, and explicit nested `.gitignore` rules still stay
+excluded. Generated agent
 worktree copies such as `.claude/worktrees/**` are excluded from default
 snapshots; pass an exact `--paths` entry if you intentionally want to inspect
 one file there.
@@ -240,9 +242,17 @@ Install a post-commit hook:
 llm-wiki install-hook
 ```
 
-`init` writes the selected agent and quality-hint setting to
+`init` writes the selected agent and instruction preferences to
 `.git/.llm-wiki-agent` when the project is a Git repo. Outside Git, it falls
-back to `<wiki-dir>/.llm-wiki-agent`.
+back to `<wiki-dir>/.llm-wiki-agent`. Tool-issue reporting guidance is omitted
+by default; opt in when you want agents to create local bug-report files:
+
+```bash
+llm-wiki init --agent claude --issue-reporting
+```
+
+This only adds guidance to the generated agent instruction block. It does not
+upload reports, submit issues, or enable telemetry.
 
 ## Automation
 
@@ -291,6 +301,30 @@ llm-wiki install-hook --force
 
 ## Command Reference
 
+### Resource-aware execution
+
+In an interactive IDE or whenever host capacity is unknown, run one heavy gate
+at a time. Heavy gates include `context`, full tests, coverage, builds, browser
+suites, `sync`, `lint`, and `ci-check`. The supervising agent owns that
+schedule; subagents may inspect bounded files and diffs, but should not launch
+heavy gates unless explicitly assigned.
+
+Use `--jobs 1` for interactive source scans. `--jobs auto` remains an uncapped
+opt-in for an isolated terminal or a controlled CI runner with reserved
+capacity; do not combine it with nested heavy-gate fan-out. If ENOSPC, inotify,
+file-descriptor, severe swapping, or editor-responsiveness failures occur, stop
+launching work and do not retry the same burst. Recover capacity first, then
+attempt at most one manual retry with `--jobs 1`; unfinished gates remain
+inconclusive. Watcher-limit symptoms are host/IDE resource evidence, not proof
+that `llm-wiki` leaked a watcher.
+
+Before extraction, `sync`, `lint`, `ci-check`, and `context` write one flushed
+plan line to stderr without contaminating stdout, for example:
+
+```text
+Extractor plan: requested=auto resolved=20 eligible_parallel=2 effective_workers=2 parallel=python,typescript sequential=- cache_elided=-
+```
+
 ### `init`
 
 Scaffold the wiki structure and agent constraint file.
@@ -299,10 +333,16 @@ Scaffold the wiki structure and agent constraint file.
 llm-wiki init --agent claude
 llm-wiki init --agent copilot --wiki-dir .wiki
 llm-wiki init --agent cursor --no-quality-hints
+llm-wiki init --agent generic --issue-reporting
 ```
 
 Supported agents are `claude`, `aider`, `opencode`, `copilot`, `cursor`, and
-`generic`.
+`generic`. `--issue-reporting` includes instructions that ask agents to record
+`llm-wiki` tool failures under the local `llm-wiki-issues/` directory. The
+instructions are off by default; use `--no-issue-reporting` to explicitly omit
+them when refreshing an existing initialization. On a refresh, omitting
+`--agent` reuses the stored agent; a project with no stored selection defaults
+to `generic`.
 
 ### `bootstrap`
 
@@ -367,7 +407,7 @@ manifest.
 
 ```bash
 llm-wiki sync --src-dir . --wiki-dir docs/llm_wiki
-llm-wiki sync --jobs auto --cache-stats --src-dir . --wiki-dir docs/llm_wiki
+llm-wiki sync --jobs 1 --cache-stats --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki sync --cache-dir .cache/llm-wiki-inventory --helper-cache-dir .cache/llm-wiki-helpers
 llm-wiki sync --include-tests go --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki sync --initialize-surfaces flows,dependencies --flow-category http --exclude-tests --dry-run
@@ -382,8 +422,10 @@ persistent inventory cache as lint when a git directory is available. Use
 `--no-cache`, `--rebuild-cache`, `--cache-dir PATH`, and `--cache-stats` to
 control or inspect inventory cache behavior. Use `--helper-cache-dir PATH` to
 point Go/Rust/Haskell extraction at prepared helpers in a separate cache. Use
-`--jobs N` or `--jobs auto` to opt into parallel extraction for built-in
-languages and plugin extractors whose manifests set `"parallel_safe": true`.
+The interactive default is `--jobs 1`. Use `--jobs N` or `--jobs auto` to opt
+into parallel extraction for built-in languages and plugin extractors whose
+manifests set `"parallel_safe": true`; reserve `auto` for an isolated terminal
+or controlled CI runner with known capacity.
 Sync repairs
 manifests with invalid source hashes without touching pages, and stops unusually
 broad diffs unless `--force` is used.
@@ -576,7 +618,7 @@ llm-wiki lint --profile --wiki-dir docs/llm_wiki --src-dir .
 llm-wiki lint --cache-stats --wiki-dir docs/llm_wiki --src-dir .
 llm-wiki lint --cache-dir .cache/llm-wiki-inventory --helper-cache-dir .cache/llm-wiki-helpers
 llm-wiki lint --include-tests go --wiki-dir docs/llm_wiki --src-dir .
-llm-wiki lint --jobs auto --wiki-dir docs/llm_wiki --src-dir .
+llm-wiki lint --jobs 1 --wiki-dir docs/llm_wiki --src-dir .
 llm-wiki lint --wiki-dir docs/llm_wiki --src-dir /path/to/repo --allow-external-src
 ```
 
@@ -585,6 +627,27 @@ Strict mode also requires the core wiki structure and a fresh sync manifest.
 to stdout containing the normal lint report, diagnostics, and phase timings.
 The JSON contract is preserved for extractor failures as well; lint still exits
 nonzero, but stdout remains machine-readable.
+`lint --profile` and `ci-check --format json` additionally include this shape:
+
+```json
+{
+  "execution": {
+    "extractor_jobs": {
+      "requested_jobs": "auto",
+      "resolved_jobs": 20,
+      "eligible_parallel_plans": 2,
+      "effective_workers": 2,
+      "parallel_plan_ids": ["python", "typescript"],
+      "sequential_plan_ids": [],
+      "cache_elided_plan_ids": []
+    }
+  }
+}
+```
+
+This metadata is additive only in those two JSON modes. Default lint report
+serialization, MCP lint responses, CI text/Markdown output, sync state and
+manifests, and the `llm-wiki-context/v1` protocol stay unchanged.
 Lint uses a persistent deep-inventory cache by default when a git directory is
 available, storing `.git/llm-wiki-inventory-cache.json`. Override the cache
 directory with `LLM_WIKI_CACHE_DIR` or `--cache-dir PATH`; the CLI flag wins for
@@ -596,8 +659,9 @@ Cache corruption or invalid fingerprints fall back to a full extraction without
 reducing lint coverage. With `--profile --cache-stats`, the JSON payload includes a top-level
 `cache` object. Use `--jobs N` or `--jobs auto` to opt into parallel extraction
 for built-in languages and plugin extractors whose manifests set
-`"parallel_safe": true`; the default is `--jobs 1`. Plugin extractors without
-that opt-in remain sequential.
+`"parallel_safe": true`; the default and recommended interactive setting is
+`--jobs 1`. Reserve `auto` for an isolated terminal or controlled CI runner
+with known capacity. Plugin extractors without that opt-in remain sequential.
 Use `--include-tests go` when a wiki intentionally documents Go `_test.go`
 files; omit it to lint against the default production-source inventory.
 For trusted source trees outside the runner workspace, pass
@@ -661,6 +725,7 @@ For CI:
 
 ```bash
 llm-wiki ci-check --src-dir . --wiki-dir docs/llm_wiki
+# Capacity-reserved CI only; shared or unknown-capacity runners should use jobs 1.
 llm-wiki ci-check --jobs auto --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki ci-check --helper-cache-dir .cache/llm-wiki-helpers --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki ci-check --include-tests go --src-dir . --wiki-dir docs/llm_wiki
@@ -694,6 +759,13 @@ llm-wiki context --budget 12000 --format json --focus all --output context.json
 `--focus changed` is the default. Changed files get full detail, one-hop import
 neighbors get slim detail, and remaining files get names only.
 
+For broad repository-wide work, run one serialized
+`llm-wiki context --budget 8000 --focus changed --read-only`, then read only the
+source and wiki pages it selects. For a narrow task with supplied files or a
+supplied diff, skip the full context scan and use the wiki index only for
+navigation. The budget and focus bound emitted output after a full deep
+inventory; they do not make the scan computationally cheap.
+
 External tools can use the `llm-wiki-context/v1` JSON request protocol:
 
 ```bash
@@ -1165,10 +1237,15 @@ llm-wiki upgrade --agent copilot
 llm-wiki upgrade --wiki-dir .wiki
 llm-wiki upgrade --force
 llm-wiki upgrade --no-quality-hints
+llm-wiki upgrade --issue-reporting
+llm-wiki upgrade --no-issue-reporting
 ```
 
 `upgrade` refreshes agent instruction blocks, wiki directories, hooks, plugin
-skill blocks, and persisted local config. For older wiki layouts, it
+skill blocks, and persisted local config. The issue-reporting pair explicitly
+enables or disables the local agent guidance; without either flag, `upgrade`
+preserves the stored preference. Configurations created before this preference
+existed default to disabled. For older wiki layouts, `upgrade`
 idempotently adds registry-standard directories such as `flows/` and missing
 `.gitkeep` files without rewriting existing index, log, semantic pages, or
 optional `dependencies.md` / `load-order.md` pages. Run `bootstrap` or `sync`

{agent_wiki_cli-1.3.0 → agent_wiki_cli-1.4.0}/src/agent_wiki_cli.egg-info/SOURCES.txt

@@ -75,6 +75,7 @@ src/llm_wiki_cli/services/dependencies.py
 src/llm_wiki_cli/services/diagrams.py
 src/llm_wiki_cli/services/documentation_queries.py
 src/llm_wiki_cli/services/entrypoints.py
+src/llm_wiki_cli/services/extraction_jobs.py
 src/llm_wiki_cli/services/extractor_helpers.py
 src/llm_wiki_cli/services/imports.py
 src/llm_wiki_cli/services/infrastructure_inventory.py
@@ -90,6 +91,7 @@ src/llm_wiki_cli/services/paths.py
 src/llm_wiki_cli/services/plugin_samples.py
 src/llm_wiki_cli/services/plugins.py
 src/llm_wiki_cli/services/relationships.py
+src/llm_wiki_cli/services/resource_diagnostics.py
 src/llm_wiki_cli/services/schema.py
 src/llm_wiki_cli/services/secure_file.py
 src/llm_wiki_cli/services/site_export.py
@@ -181,6 +183,7 @@ tests/test_phase4_quality.py
 tests/test_plugins.py
 tests/test_relationships.py
 tests/test_release.py
+tests/test_resource_diagnostics.py
 tests/test_rust_extract.py
 tests/test_schema.py
 tests/test_secure_file.py