docs: restore complete product guide

Author: actions-user

CHANGELOG.md

@@ -22,6 +22,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Agent-neutral natural-language requests lead the README and installer output;
   slash commands are documented as an optional agent interface.
+- README restores detailed adversarial review, security classification, threat
+  modeling, dependency scanning, fix safety, CI/CD, language, framework, and
+  architecture coverage while keeping fast onboarding above the fold.
+- Current-source installation examples use the GitHub source archive until npm
+  `latest` reaches `3.1.1`.
+- Approval, preview, scope, canary, commit, and rollback documentation states
+  the limits of the current runtime instead of promising unenforced behavior.
 - Package installation has no lifecycle script; setup starts only when the
   user runs the explicit install command.
 - Explicit agent selection is the recommended installation path.
@@ -41,6 +48,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   parser and reports other ecosystems as `scanner-unsupported`.
 - Source-only fixture guidance no longer implies that the npm package contains
   development fixtures.
+- Hunter output instructions no longer request trailing prose after the
+  canonical JSON array.
 
 ## [3.1.0] - 2026-08-03
 

README.md

@@ -636,8 +636,8 @@ function info() {
     console.log('');
   }
 
-  console.log('  Install:  npx --yes @codexstar/bug-hunter install --agent <name>');
-  console.log('  Verify:   npx --yes @codexstar/bug-hunter doctor --agent <name>');
+  console.log('  Install:  npx --yes https://github.com/codexstar69/bug-hunter/archive/refs/heads/main.tar.gz install --agent <name>');
+  console.log('  Verify:   npx --yes https://github.com/codexstar69/bug-hunter/archive/refs/heads/main.tar.gz doctor --agent <name>');
   console.log('  Repo:     https://github.com/codexstar69/bug-hunter');
   console.log('');
 }

bin/bug-hunter

@@ -7,20 +7,26 @@ prompt: |
   can we do that so everything is end to end seamless and anyone and
   specially agents can understand easily how to use it all properly
 
+  you removed a lot of content that helped rank it om google - bring it back
+
   Use @README.md, @bin/bug-hunter, @package.json,
   @docs/getting-started.md, and @docs/troubleshooting.md as source material.
 ---
 
 # Agent installation
 
-## Install from npm
+## Install the current GitHub source
 
 Pass the target explicitly:
 
 ```bash
-npx --yes @codexstar/bug-hunter install --agent codex
+npx --yes https://github.com/codexstar69/bug-hunter/archive/refs/heads/main.tar.gz install --agent codex
 ```
 
+The npm `latest` tag still points to an older release while `3.1.1` publishing
+is pending. After npm catches up, `@codexstar/bug-hunter` can replace the
+GitHub package specifier.
+
 The installer copies the complete managed runtime and writes
 `.bug-hunter-install-manifest.json`. Repeating the command performs an atomic
 upgrade. Managed files are replaced, while files not listed in the previous
@@ -44,7 +50,7 @@ Install into several targets by running the command once for each target.
 ## Verify a target
 
 ```bash
-npx --yes @codexstar/bug-hunter doctor --agent codex
+npx --yes https://github.com/codexstar69/bug-hunter/archive/refs/heads/main.tar.gz doctor --agent codex
 ```
 
 Target verification checks:
@@ -62,16 +68,16 @@ The check ignores user-owned files that are outside the managed manifest.
 Use `--path` when an agent reads skills from another directory:
 
 ```bash
-npx --yes @codexstar/bug-hunter install \
+npx --yes https://github.com/codexstar69/bug-hunter/archive/refs/heads/main.tar.gz install \
   --path "$HOME/my-agent/skills/bug-hunter"
 
-npx --yes @codexstar/bug-hunter doctor \
+npx --yes https://github.com/codexstar69/bug-hunter/archive/refs/heads/main.tar.gz doctor \
   --path "$HOME/my-agent/skills/bug-hunter"
 ```
 
 `--path` takes precedence if both `--path` and `--agent` are present.
 
-## Install the current GitHub source
+## Install from a cloned source checkout
 
 Use this path when testing an unreleased commit:
 
@@ -87,11 +93,11 @@ The doctor command considers the source checkout's package version current.
 
 ## Update
 
-Run the npm install command again:
+Run the same GitHub-source command again:
 
 ```bash
-npx --yes @codexstar/bug-hunter install --agent codex
-npx --yes @codexstar/bug-hunter doctor --agent codex
+npx --yes https://github.com/codexstar69/bug-hunter/archive/refs/heads/main.tar.gz install --agent codex
+npx --yes https://github.com/codexstar69/bug-hunter/archive/refs/heads/main.tar.gz doctor --agent codex
 ```
 
 Restart the coding agent after the update if it caches skill definitions.
@@ -101,7 +107,7 @@ Restart the coding agent after the update if it caches skill definitions.
 A global CLI is optional:
 
 ```bash
-npm install -g @codexstar/bug-hunter
+npm install -g https://github.com/codexstar69/bug-hunter/archive/refs/heads/main.tar.gz
 bug-hunter install --agent codex
 bug-hunter doctor --agent codex
 ```

docs/agent-installation.md

@@ -6,6 +6,8 @@ prompt: |
   can we do that so everything is end to end seamless and anyone and
   specially agents can understand easily how to use it all properly
 
+  you removed a lot of content that helped rank it om google - bring it back
+
   Use @bin/bug-hunter, @SKILL.md, @README.md, and
   @docs/agent-installation.md as source material.
 ---
@@ -69,17 +71,17 @@ These arguments are interpreted by the installed skill:
 | `--staged` | Scan staged files |
 | `--pr [current\|recent\|N]` | Review a pull request |
 | `--pr-security` | Review pull-request security context |
-| `--scan-only` | Force report-only behavior |
+| `--scan-only` | Request report-only behavior |
 | `--review` | Alias for `--scan-only` |
 | `--plan-only` | Build strategy and plan, then stop |
 | `--plan` | Alias for `--plan-only` |
 | `--fix` | Permit the reviewed fix phase |
-| `--approve` | Require approval for every fix |
+| `--approve` | Request the host's reviewed/default permission mode |
 | `--safe` | Alias for `--fix --approve` |
-| `--dry-run` | Render proposed patches without applying them |
+| `--dry-run` | Build strategy and fix-plan output without source edits |
 | `--preview` | Alias for `--fix --dry-run` |
 | `--autonomous` | Permit unattended fixing |
-| `--auto-commit` | Permit scoped commits during a fix run |
+| `--auto-commit` | Grant commit permission for an authorized fix plan |
 | `--loop` | Continue until queued coverage is complete |
 | `--no-loop` | Keep the default single pass |
 | `--deps` | Add supported Node.js dependency auditing |
@@ -96,5 +98,9 @@ Flags compose:
 /bug-hunter --autonomous --auto-commit src/
 ```
 
+Do not combine `--scan-only` or `--review` with `--fix`, `--approve`, `--safe`,
+or `--autonomous`. Conflicting read-only and mutation flags are not currently
+rejected.
+
 The skill's canonical argument parser and behavior contract live in
 [`SKILL.md`](../SKILL.md).

docs/cli-reference.md

@@ -7,6 +7,8 @@ prompt: |
   can we do that so everything is end to end seamless and anyone and
   specially agents can understand easily how to use it all properly
 
+  you removed a lot of content that helped rank it om google - bring it back
+
   Use @README.md, @bin/bug-hunter, @SKILL.md,
   @docs/agent-installation.md, @docs/usage-guide.md,
   @docs/how-it-works.md, and @docs/troubleshooting.md as source material.
@@ -30,15 +32,15 @@ The default workflow does not edit source files.
 This example installs Bug Hunter for Codex:
 
 ```bash
-npx --yes @codexstar/bug-hunter install --agent codex
+npx --yes https://github.com/codexstar69/bug-hunter/archive/refs/heads/main.tar.gz install --agent codex
 ```
 
 Use another target when needed:
 
 ```bash
-npx --yes @codexstar/bug-hunter install --agent claude-code
-npx --yes @codexstar/bug-hunter install --agent cursor
-npx --yes @codexstar/bug-hunter install --agent copilot
+npx --yes https://github.com/codexstar69/bug-hunter/archive/refs/heads/main.tar.gz install --agent claude-code
+npx --yes https://github.com/codexstar69/bug-hunter/archive/refs/heads/main.tar.gz install --agent cursor
+npx --yes https://github.com/codexstar69/bug-hunter/archive/refs/heads/main.tar.gz install --agent copilot
 ```
 
 See [agent installation](agent-installation.md) for every supported target.
@@ -48,13 +50,13 @@ See [agent installation](agent-installation.md) for every supported target.
 Use the same target you installed:
 
 ```bash
-npx --yes @codexstar/bug-hunter doctor --agent codex
+npx --yes https://github.com/codexstar69/bug-hunter/archive/refs/heads/main.tar.gz doctor --agent codex
 ```
 
 A complete check includes:
 
 ```text
-[ok] Bug Hunter runtime v3.1.1 is current and complete
+[ok] Bug Hunter runtime v<current-version> is current and complete
 Ready to hunt bugs.
 ```
 
@@ -130,6 +132,10 @@ Slash form:
 /bug-hunter --fix --approve
 ```
 
+`--approve` requests the host's reviewed/default permission mode. Approval
+prompts depend on the coding agent. Use `--plan` or `--preview` when source
+edits must be impossible.
+
 Do not grant autonomous fixing or commit permission unless that behavior is
 intended.
 

docs/getting-started.md

@@ -7,6 +7,8 @@ prompt: |
   can we do that so everything is end to end seamless and anyone and
   specially agents can understand easily how to use it all properly
 
+  you removed a lot of content that helped rank it om google - bring it back
+
   Use @SKILL.md, @modes/dispatch.md, @modes/fix-pipeline.md,
   @schemas/scan-report.schema.json, @schemas/fix-plan.schema.json,
   @schemas/fixer-scope.schema.json, @scripts/dep-scan.cjs, and
@@ -29,8 +31,9 @@ prompt: |
 8. An optional strategy and fix plan classify safe and unsafe remediation.
 9. An optional Fixer applies only authorized changes and runs verification.
 
-Each phase exchanges schema-validated JSON. A malformed phase result is a
-failure, not a successful clean scan.
+Role, report, coverage, and fix phases exchange schema-validated JSON. Triage
+JSON is deterministic pipeline input. A malformed required canonical artifact
+is a failure, not a successful clean scan.
 
 ## Roles
 
@@ -41,7 +44,7 @@ failure, not a successful clean scan.
 | Skeptic | Challenge Hunter claims | Final verdicts or edits |
 | Referee | Decide findings from evidence | Files outside the reviewed scope |
 | Fix planner | Classify and order remediation | Unapproved bug IDs |
-| Fixer | Apply the approved plan | New findings, wider files, or wider ranges |
+| Fixer | Apply the approved plan | New findings or wider files |
 
 The Referee-only verdict boundary prevents the agent that found a bug from
 declaring its own claim confirmed.
@@ -58,25 +61,25 @@ features, and requested scope:
 - large-codebase for domain-scoped execution
 - local-sequential when subagents are unavailable
 
-All delegated modes use the same dispatch contract. State includes the run ID,
-target fingerprint, queue, attempts, and artifact paths so an interrupted run
-does not silently resume against a different target.
+Most delegated modes use the canonical dispatch contract. Large-codebase mode
+currently uses per-domain variants before its final merge. State records queue
+and chunk progress; a sibling identity file stores run and target identity so
+an interrupted run does not silently resume against a different target.
 
 ## Mutation boundaries
 
 Scan-only is the default.
 
-Fixing requires an explicit fixing mode. The plan binds:
+Fixing requires an explicit fixing mode. The plan records:
 
 - approved bug IDs
 - allowed files
-- allowed line ranges
+- claimed line ranges for review context
 - remediation class
 - canary and rollout stages
-- required checks
-
-The Fixer must reject work outside that scope. `--auto-commit` is a separate
-permission and only permits approved paths.
+The validated Fixer scope binds repository root, base commit, bug IDs, and file
+paths before dispatch. It does not independently prove line-range or committed
+path compliance after a patch. `--auto-commit` is a separate permission.
 
 Worktree-based fixing uses verified worktree identity and a fresh preservation
 check before cleanup. If safe removal cannot be proven, cleanup stops and
@@ -98,16 +101,16 @@ Artifacts live in `.bug-hunter/`.
 | File | Generated when | Meaning |
 |---|---|---|
 | `triage.json` | every scan | Risk map and selected strategy |
-| `recon.json` | every scan | Stack and attack-surface map |
+| `recon.json` | multi-file scan | Prioritized risk tiers and Recon notes |
 | `hunter-findings.json` | every scan | Canonical Hunter claims |
 | `skeptic.json` | findings exist | Challenges and counter-evidence |
 | `referee.json` | findings exist | Final verdicts |
 | `scan-report.json` | completed scan | Joined counts and verdicts |
 | `report.md` | completed scan | Human-readable report |
-| `coverage.json` | coverage loop | Recorded file outcomes |
+| `coverage.json` | coverage loop | Per-file entries derived from chunk progress |
 | `fix-strategy.json` | planning or fixing | Remediation classes |
 | `fix-plan.json` | planning or fixing | Authorized execution plan |
-| `fix-report.json` | fix run | Patch and verification results |
+| `fix-report.json` | fix run | Verification and final-status results |
 | `threat-model.md` | threat-model run | STRIDE boundaries and flows |
 | `dep-findings.json` | dependency run | Supported audit results |
 

docs/how-it-works.md

@@ -7,6 +7,8 @@ prompt: |
   can we do that so everything is end to end seamless and anyone and
   specially agents can understand easily how to use it all properly
 
+  you removed a lot of content that helped rank it om google - bring it back
+
   Use @bin/bug-hunter, @README.md, @docs/agent-installation.md,
   @docs/getting-started.md, @SKILL.md, and @SECURITY.md as source material.
 ---
@@ -18,7 +20,7 @@ prompt: |
 Verify the same target used during installation:
 
 ```bash
-npx --yes @codexstar/bug-hunter doctor --agent codex
+npx --yes https://github.com/codexstar69/bug-hunter/archive/refs/heads/main.tar.gz doctor --agent codex
 ```
 
 Then:
@@ -36,8 +38,8 @@ If the agent uses a nonstandard skill directory, reinstall and verify with
 Run installation and verification with the same package source:
 
 ```bash
-npx --yes @codexstar/bug-hunter install --agent codex
-npx --yes @codexstar/bug-hunter doctor --agent codex
+npx --yes https://github.com/codexstar69/bug-hunter/archive/refs/heads/main.tar.gz install --agent codex
+npx --yes https://github.com/codexstar69/bug-hunter/archive/refs/heads/main.tar.gz doctor --agent codex
 ```
 
 If a global `bug-hunter` command reports another version, check:

docs/troubleshooting.md

@@ -7,6 +7,8 @@ prompt: |
   can we do that so everything is end to end seamless and anyone and
   specially agents can understand easily how to use it all properly
 
+  you removed a lot of content that helped rank it om google - bring it back
+
   Use @README.md, @SKILL.md, @docs/getting-started.md,
   @docs/cli-reference.md, and @docs/how-it-works.md as source material.
 ---
@@ -140,14 +142,17 @@ This produces strategy and plan artifacts, then stops before the Fixer.
 ## Preview changes
 
 ```text
-Use the bug-hunter skill to preview fixes for confirmed findings.
-Do not apply the patches.
+Use the bug-hunter skill to build a remediation strategy and fix plan.
+Do not edit files.
 ```
 
 ```text
 /bug-hunter --preview
 ```
 
+Current preview mode produces strategy and plan output without source edits.
+It does not yet produce a schema-backed patch diff.
+
 ## Apply fixes with approval
 
 ```text
@@ -160,6 +165,9 @@ Do not commit.
 /bug-hunter --fix --approve
 ```
 
+`--approve` requests the host's reviewed/default permission mode. Approval
+prompts depend on the coding agent.
+
 `--safe` is an alias:
 
 ```text
@@ -185,8 +193,9 @@ Commit permission is separate:
 /bug-hunter --autonomous --auto-commit
 ```
 
-The commit flag only allows scoped commits from the approved fix plan. It does
-not authorize unrelated files.
+The commit flag grants commit permission for the approved plan. Review the
+harvested commit paths before merging; current validation does not independently
+enforce every committed path after a Fixer creates a commit.
 
 ## Ask the agent to prove completion