forgedock 1.0.22 → 1.1.2

package/docs/CONFIG.md

@@ -12,18 +12,26 @@ echo "forge.yaml" >> .gitignore  # if your credentials path is sensitive
 
 ---
 
-## CLI Flags for `init`
+## CLI Flags
 
-`npx forgedock init` accepts two optional flags that change how configuration is generated:
+`--verbose` and `--fast` apply to both `npx forgedock` (the full install journey) and `npx forgedock init` (config-only regeneration); `--manual` and `--minimal` apply to `init` only:
 
 | Flag | Behavior |
 |------|----------|
-| `--manual` | Skips AI autopilot enrichment entirely. Presents the annotated review screen with detection baseline values only (no AI-enriched suggestions). Detection still runs to provide defaults — you review and edit the raw inferred values on the same single-screen interface. |
-| `--verbose` | Surfaces each field's detection source and confidence rationale during the init flow. Helpful for understanding where ForgeDock inferred values from (e.g. `git remote`, `package.json`, `gh api`). |
+| `--manual` | `npx forgedock init` only. Skips the annotated review screen and asks plain, one-field-at-a-time prompts instead, pre-filled with the detected values as defaults. |
+| `--minimal` | `npx forgedock init` only. Skips detection enrichment and the review screen entirely, and writes a short `forge.yaml` containing only the three required sections (`project`, `paths`, `branches`) with detected values. |
+| `--verbose` | Shows each field's detection source and confidence rationale on the review screen (e.g. `git remote`, `package.json`, `gh api`), instead of only flagging low-confidence fields. |
+| `--fast` | Skips the animation/motion frames and jumps straight to the static screens. |
 
-The two flags can be combined: `npx forgedock init --manual --verbose` shows the annotated review screen with detection baseline values and field provenance at each entry.
+**Environment variables:**
 
-The default (`npx forgedock init` with no flags) remains the zero-question autopilot: AI enrichment fills in everything it can, and you review the result on a single annotated screen.
+| Variable | Behavior |
+|----------|----------|
+| `FORGE_NO_MOTION=1` | Same effect as `--fast` — disables animation frames. Color is unaffected. |
+| `NO_COLOR=1` | Disables ANSI color output only. Motion is unaffected (monochrome choreography). |
+| Non-TTY / piped output (or `CI=1`) | Plain sequential log: no color **and** no animation. |
+
+The default (no flags) is the annotated review screen: detection runs, AI enrichment fills in what it can (when an API key is available), and you review the result on a single screen — Enter accepts everything, low-confidence fields are flagged with a `# TODO(forgedock:<field>)` comment if left unedited.
 
 ---
 
@@ -326,7 +334,7 @@ review:
 
 Path configuration for the devdocs knowledge tree. Pipeline agents (work-on, review-pr, etc.) read these files as **authoritative project knowledge** before acting.
 
-Run `npx forgedock docs init` to scaffold the tree from ForgeDock's seed templates into the configured path.
+Create the devdocs tree by copying the seed templates from `devdocs/templates/` (in this repo) into your configured path, or scaffold it manually by creating `devdocs/project/architecture.md`, `devdocs/agent/using-forgedock.md`, and an optional `devdocs/index.yaml`.
 
 ```yaml
 devdocs:
@@ -337,9 +345,9 @@ devdocs:
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `path` | string (relative path) | No | Path to the devdocs tree, relative to project root. Default: `devdocs`. |
-| `index_path` | string (relative or absolute path) | No | Path to the selective loading index file. Default: `{path}/index.yaml`. When the index file exists at this path, agents read it first (~400 tokens) and load only docs whose domain matches the current issue's labels. When absent, agents fall back to loading all docs with `applies_to: work-on` (backward compatible). Scaffold the index with `npx forgedock docs init`. |
+| `index_path` | string (relative or absolute path) | No | Path to the selective loading index file. Default: `{path}/index.yaml`. When the index file exists at this path, agents read it first (~400 tokens) and load only docs whose domain matches the current issue's labels. When absent, agents fall back to loading all docs with `applies_to: work-on` (backward compatible). Create the index manually or copy the seed template from `devdocs/templates/`. |
 
-**Commands that use this section**: `docs init`, `work-on/build/context` (Phase C-1), `work-on/build/architect` (Phase A0)
+**Commands that use this section**: `work-on/build/context` (Phase C-1), `work-on/build/architect` (Phase A0)
 
 ### Selective Loading (index.yaml)
 
@@ -358,14 +366,11 @@ When `devdocs/index.yaml` exists, agents use **domain-filtered selective loading
 
 **Backward compatibility**: If `index.yaml` is absent, behavior is unchanged — all docs with `applies_to: work-on` are loaded. No migration required for existing devdocs trees.
 
-Scaffold the index with:
-```bash
-npx forgedock docs init
-```
+Scaffold the index manually by creating `devdocs/index.yaml` (or copy the seed template from `devdocs/templates/` in the ForgeDock repo).
 
 ### Migration from `review.context`
 
-If you previously stored project context in `forge.yaml → review.context`, move that content into the appropriate devdocs file after running `npx forgedock docs init`:
+If you previously stored project context in `forge.yaml → review.context`, move that content into the appropriate devdocs file:
 
 | `review.context` content | Target devdocs file |
 |--------------------------|---------------------|
@@ -686,46 +691,43 @@ Downstream consumers read `field.value` for the raw value and `field.confidence`
 
 ---
 
-## CLAUDE.md Integration
+## SessionStart Hook Integration
 
-ForgeDock can inject a managed usage block into your project's `CLAUDE.md` so every Claude Code session opened in the repo automatically knows that ForgeDock drives development here and which commands to use.
+ForgeDock does **not** write anything into your project's `CLAUDE.md` or `AGENTS.md`. Instead, `npx forgedock` registers a `SessionStart` hook in `~/.claude/settings.json` — a small script that runs at the start of every Claude Code session and prints ForgeDock's context straight to that session, without touching any file in your repo.
 
 ### How It Works
 
-Running `npx forgedock init` or `npx forgedock integrate` writes a marker-bounded block into `CLAUDE.md`:
-
-```
-<!-- BEGIN FORGEDOCK -->
-## ForgeDock — Autonomous Development Pipeline
-...command index and conventions...
-<!-- END FORGEDOCK -->
-```
+The hook resolves the current directory's state and reacts accordingly:
 
-The block is **idempotent** — re-running replaces only the managed section and leaves all other `CLAUDE.md` content untouched. If `CLAUDE.md` does not exist, it is created.
+| State | Behavior |
+|-------|----------|
+| `managed-active` (`forge.yaml` present, not opted out) | Prints a summary of `forge.yaml` (project, repo, branches) plus the available pipeline commands |
+| `managed-active`, no `forge.yaml` yet | Suggests running `npx forgedock init` |
+| `managed-optedout` | Completely silent — no output |
+| `unmanaged` | Prints a one-time, suppressible nudge to run `npx forgedock enable` |
 
-If `AGENTS.md` already exists in the project root, the same block is mirrored into it.
+The hook entry is registered idempotently: re-installing (`npx forgedock update`) will not duplicate it, and unrelated hooks or settings in `~/.claude/settings.json` are left untouched. If `settings.json` is malformed, the installer skips writing rather than risk corrupting it.
 
 ### Commands
 
 | Command | Action |
 |---------|--------|
-| `npx forgedock init` | Generates `forge.yaml` **and** injects the CLAUDE.md block |
-| `npx forgedock integrate` | Injects/refreshes the block without modifying `forge.yaml` |
+| `npx forgedock` / `npx forgedock install` | Registers the SessionStart hook (along with installing commands and writing `forge.yaml`) |
+| `npx forgedock update` | Re-registers the hook (relink only — does not touch `forge.yaml`) |
+| `npx forgedock uninstall` | Removes the hook entry from `settings.json` |
 
 ### Opting Out
 
-To prevent ForgeDock from managing the block, remove the `<!-- BEGIN FORGEDOCK -->` / `<!-- END FORGEDOCK -->` markers from `CLAUDE.md`. Without the markers, subsequent runs will append a new block rather than replacing one — so if you want to opt out permanently, delete or omit the markers **and** do not run `integrate` again.
-
-Alternatively, keep the markers but edit the content between them freely — ForgeDock will replace that section on the next run, so any manual edits inside the markers will be overwritten.
-
-### Re-generating
-
-The command index inside the block is auto-generated from the `description:` frontmatter in each `commands/*.md` file. To refresh it after a ForgeDock update:
+Per-directory, independent of the global hook registration. Each command acts on the current working directory — run it inside the project directory:
 
 ```bash
-npx forgedock integrate
+npx forgedock disable  # the current directory goes silent (managed-optedout)
+npx forgedock enable   # re-activate the current directory
+npx forgedock status   # show the current directory's resolved state
 ```
 
+See [Per-Directory State Registry](#per-directory-state-registry) below for how opt-out state is tracked.
+
 ---
 
 ## Per-Directory State Registry
@@ -788,22 +790,22 @@ If you downgrade to a build older than PR #467 **and** your project is accessed
 - The one-time "Enable ForgeDock here?" nudge may reappear once.
 - No data is lost. No crash. Fail-open behaviour holds throughout.
 
-**Recovery**: after downgrading, re-apply your opt-out with the older build:
+**Recovery**: after downgrading, re-apply your opt-out with the older build (run inside the project directory):
 
 ```bash
-npx forgedock disable [dir]
+npx forgedock disable
 ```
 
 This re-writes the entry under the key form the older build expects.
 
 ### Managing Opt-Out State
 
-Use the `forgedock enable` and `forgedock disable` commands to add or remove a directory from the opt-out set:
+Use the `forgedock enable` and `forgedock disable` commands to add or remove a directory from the opt-out set. Each command acts on the current working directory by default — run it inside the project directory, or pass an explicit path:
 
 ```bash
-npx forgedock enable [dir]   # Remove directory from opt-out set (default: cwd)
-npx forgedock disable [dir]  # Add directory to opt-out set (default: cwd)
-npx forgedock status [dir]   # Show resolved state for a directory
+npx forgedock enable [dir]   # Remove a directory from the opt-out set (default: cwd)
+npx forgedock disable [dir]  # Add a directory to the opt-out set (default: cwd)
+npx forgedock status [dir]   # Show a directory's resolved state (default: cwd)
 ```
 
 ---