@gluecharm-lab/easyspecs-cli 0.0.14 → 0.0.15

package/README.md

@@ -1,6 +1,8 @@
 # EasySpecs CLI
 
-Headless **EasySpecs** command-line tool for **context analysis**, **diagnoses**, **macro pipelines**, **download/upload context** to EasySpecs, **auth**, and **ACE** — the same orchestration ideas as the **EasySpecs VS Code extension**, without an editor.
+Headless **EasySpecs** command-line tool for **context analysis**, **diagnoses**, the **Generate Context** factory (**`analysis`**), **download/upload context** to EasySpecs, **auth**, and **ACE** — the same orchestration ideas as the **EasySpecs VS Code extension**, without an editor.
+
+**Vocabulary (SRS-53, same repo):** A **Factory** is the full ordered **`analysis`** run. A **Pipeline** is one major stage inside it (synthesis, coverage, remediation, link mapping, upload). A **Workstation** is one atomic OpenCode or programmatic step inside a pipeline. Canonical **`config.json`** keys live under **`easyspecs.factory.*`**, **`easyspecs.workstations.*`**, and **`easyspecs.pipelines.upload.*`**; legacy **`easyspecs.orchestration.*`**, **`easyspecs.macro.debug`**, and several **`easyspecs.analysis.*`** tunables still work for one deprecation cycle and may log **`[deprecated-setting]`** on stderr when read. Human stderr may tag lines **`[factory]`**, **`[pipeline:…]`**, **`[workstation:…]`**, **`[pool]`**, **`[ace]`**.
 
 Published as **`@gluecharm-lab/easyspecs-cli`** (npm org **gluecharm-lab**; **EasySpecs** is the product). The executable on your `PATH` is **`easyspecs-cli`**.
 
@@ -32,7 +34,7 @@ npx @gluecharm-lab/easyspecs-cli@latest help
 
 ## Quick start
 
-From a git repo (**OpenCode** on **`PATH`** for agent steps). The CLI creates minimal **`.gluecharm/`** directories when needed for **analysis**, **diagnose**, **upload**, and **download context**:
+From a git repo (**OpenCode** on **`PATH`** for agent steps). The CLI creates minimal **`.gluecharm/`** directories when needed for **analysis**, **`update context`**, **diagnose**, **upload**, and **download context**:
 
 ```bash
 cd /your/repo
@@ -41,7 +43,7 @@ easyspecs-cli config init
 easyspecs-cli analysis
 ```
 
-**`config init`** creates **`.easyspecs/config.json`** with defaults (add **`--overwrite`** to replace an existing file). **`analysis`** runs the full macro loop (synthesis convergence, coverage, reporting, indexing); add **`--synthesis-only`** to stop after the synthesis phase. Add **`--upload`** only after **`auth login`** and **`config set-project-id <id>`**. Use **`download context`** (same auth + project id) to pull context from EasySpecs into **`.gluecharm/context`**. Use **`--ci`** in automation for non-interactive behaviour and stricter defaults (e.g. macro outer-iteration cap).
+**`config init`** creates **`.easyspecs/config.json`** with defaults (add **`--overwrite`** to replace an existing file). **`analysis`** runs the full **Generate Context** factory (synthesis convergence, coverage, remediation, report, link mapping, index assembly; optional **`--upload`** for backend sync after **`auth login`** + **`config set-project-id <id>`**). Add **`--synthesis-only`** to stop after the synthesis phase. **`update context`** (SRS-55) refreshes context from a **git delta** since **`easyspecs.factory.updateContext.lastRunAt`** or the latest workspace **`.gluecharm/context`** mtime: writes **`changes-since-date.md`**, runs scoped zero-reference remediation when there are commits and touched paths, honors global **`--promote` / `--no-promote`**, optional **`--upload`**, and persists **`lastRunAt`** on success. Use **`download context`** (same auth + project id) to pull context from EasySpecs into **`.gluecharm/context`**. Use **`--ci`** in automation for non-interactive behaviour and stricter defaults (e.g. Factory outer-iteration cap).
 
 Set **`easyspecs.defaultGitRemoteUrl`** with **`config set-git-remote <url>`** when you want that recorded in config. Tunables belong in **`<repo>/.easyspecs/config.json`** — do not rely on **`EASYSPECS_*`** environment variables for product settings.
 
@@ -177,15 +179,18 @@ Merge order for **`easyspecs-cli`**: **`.easyspecs/config.json`** plus global CL
 | `easyspecs.defaultGitRemoteUrl` | Optional primary **`git remote`** URL (HTTPS or SSH) for reference; analysis still uses the live repo. |
 | `easyspecs.cliSessionPath` | Repo-relative or absolute path to **`cli-session.json`**. Empty **`""`** → **`~/.easyspecs/cli-session.json`**. Precedence: global **`--session-path`** → **`cliSessionPath`** → home default. |
 | `easyspecs.openCode` | `executable`, `skipCredentialsCheck` (shortcut; see **`openCodeRuntime`**). |
-| `easyspecs.analysis.*` | Pipeline settings, **`promoteContextToWorkspace`**, and optional **`cloudContextAnalyzed`** / **`cloudContextAnalyzedAt`** (when **`cloudContextAnalyzed`** is **`true`**, **`cloudContextAnalyzedAt`** should be a non-null ISO timestamp). |
-| `easyspecs.orchestration.*` | Macro delays, outer iterations, ping-pong cap. |
+| `easyspecs.analysis.*` | **`promoteContextToWorkspace`**, ACE toggles, and other analysis-only flags. Cloud “already analyzed” cache is canonical under **`easyspecs.factory.cloudContextAnalyzed`** / **`At`** (legacy **`easyspecs.analysis.cloudContext*`** still read once with deprecation stderr). |
+| `easyspecs.factory.*` | Factory debug, backoff, outer-iteration caps, ping-pong cap, cloud cache. Replaces **`easyspecs.orchestration.*`** and **`easyspecs.macro.debug`** (aliases still read). |
+| `easyspecs.workstations.*` | OpenCode argv, timeouts, repair attempts, pool width, coordination lock timeout (canonical; legacy **`easyspecs.analysis.openCodeTest*`** / **`markdown*`** / **`listJsonSchemaRepairAttempts`** / **`maxConcurrentOpenCodeAgents`** aliases). |
+| `easyspecs.pipelines.upload.useBatch` | Upload batching (legacy **`easyspecs.analysis.uploadUseBatch`**). |
+| `easyspecs.orchestration.*` | **Deprecated** — prefer **`easyspecs.factory.*`**. |
 | `easyspecs.openCodeRuntime` | Providers (`apiKey`, `defaultModel` per provider), `run`, `coordinationRepairs`, `pool`, `projectConfigOverlay`. |
 | `easyspecs.diagnose.zeroReference.maxPercentNonReferenced` | Number or **`null`**. **`null`** means **`diagnose reference-coverage`** does not fail on percentage alone. |
 | `easyspecs.diagnose.coordinationDuplicates.strict` | Boolean (default **`true`**). |
 | `easyspecs.upload.contextDirectory` | Repo-relative or absolute override for **`upload republish`**; empty **`""`** → automatic resolution from the analysis snapshot. |
 | `easyspecs.upload.fetchContextAnalyzedInCloud` | Boolean, default **`true`**. When **`true`**, after a successful **`upload context`** / **`upload republish`**, the CLI may **`GET`** application status and emit **`contextAnalyzedInCloud`** / **`contextAnalyzedInCloudAt`** on **`--json`**, and update **`easyspecs.analysis.cloudContext*`** cache. When **`false`**, skips that fetch. |
 | `easyspecs.upload.contextAnalyzedStatusTimeoutMs` | Optional positive integer (ms) for that GET; default **15000** if omitted. |
-| `easyspecs.macro.debug` | When **`true`**, macro phase transitions log extra lines to stderr. |
+| `easyspecs.factory.debug` | When **`true`**, Factory phase transitions log extra lines to stderr. Legacy **`easyspecs.macro.debug`**. |
 | `easyspecs.cli.bundledResourcesRoot` | Optional absolute or repo-relative path to the bundled **`resources/`** directory. Empty → resolve next to the installed CLI package. |
 | `easyspecs.auth.ciLogin.email` / `password` | Used with **`--ci`** when **`--email` / `--password`** are omitted on **`auth login`**. Prefer CI-generated **`config.json`**; avoid committing secrets. |
 
@@ -200,7 +205,7 @@ These appear **before** the subcommand (everything after the first non-flag toke
 | Flag | Effect |
 | ---- | ------ |
 | `--cwd <dir>` | Repository root for git resolution and paths (default: current working directory). |
-| `--ci` | Non-interactive mode; affects merged settings (e.g. macro outer-iteration default). **`EASYSPECS_CI` is not read** — use this flag. |
+| `--ci` | Non-interactive mode; affects merged settings (e.g. Factory outer-iteration default). **`EASYSPECS_CI` is not read** — use this flag. |
 | `--json` | On supported exits, one JSON summary line on stdout. |
 | `--verbose` | Extra stderr logging where implemented. |
 | `--api-base-url <url>` | System Manager API origin for this process (overrides `easyspecs.apiBaseUrl`). |
@@ -212,14 +217,14 @@ These appear **before** the subcommand (everything after the first non-flag toke
 | `--version`, `-V` | CLI package version. Does **not** create config. |
 | `--config <path>` | Parsed but **unused** in current releases; read **`<repo>/.easyspecs/config.json`** instead. |
 
-## Diagnose-only flags
+## Diagnose / context flags
 
-Used on the tail of **`diagnose <subcommand>`** (after the subcommand name):
+Used on the tail of **`diagnose <subcommand>`** or **`context link-graph`**:
 
 | Flag | Values | Meaning |
 | ---- | ------ | ------- |
-| `--root` | `workspace` or `worktree` | Resolve paths against the workspace repo root or an analysis checkout (**required** for **`reference-coverage`**, **`coordination-duplicates`**, **`coverage-report`**, **`missing-artefacts`**). |
-| `--worktree` | path | Analysis git checkout (use with **`--root worktree`**, or alone where documented below). |
+| `--root` | `workspace` or `worktree` | Resolve paths against the workspace repo root or an analysis checkout (**required** for **`reference-coverage`**, **`coordination-duplicates`**, **`coverage-report`**, **`missing-artefacts`**, **`context link-graph`**). |
+| `--worktree` | path | Analysis git checkout (use with **`--root worktree`**, or alone where **`diagnose zero-reference`** documents it). |
 
 ## Commands and flags (complete)
 
@@ -240,22 +245,24 @@ Every command the CLI accepts, with command-specific tokens. Global flags above
 | `run synthesis` | — | Context artefact pipeline pass; **`requireOpenCode`** applies. **`--promote` / `--no-promote`** affect promotion after success. |
 | `run synthesis resume-missing` | **`--worktree <path>`** (optional) | Parallel missing-artefact remediation pool on an existing checkout (from **`--worktree`** or last snapshot). **`requireOpenCode`**. |
 | `run synthesis resume-synthesis` | **`--worktree <path>`** (optional) | Same implementation as **`resume-missing`** (alias command path). |
-| `analysis` | **`--synthesis-only`**, **`--upload`**, **`--skip-upload`**, **`--force-new-context-analysis`** (any order among argv tokens after **`analysis`**) | Full macro loop unless **`--synthesis-only`**. **`--upload`** runs backend sync after macro (needs **`auth login`** + **`easyspecs.easyspecsProjectId`**). Without **`--upload`**, backend sync is skipped. **`--skip-upload`** appears in **`easyspecs-cli help`**; omit **`--upload`** to skip upload. If **`easyspecs.analysis.cloudContextAnalyzed`** is **`true`** and neither **`--synthesis-only`** nor **`--force-new-context-analysis`** is set, exits **0** early with **`analysisSkipped`** (machine JSON fields). |
+| `analysis` | **`--synthesis-only`**, **`--upload`**, **`--skip-upload`**, **`--force-new-context-analysis`** (any order among argv tokens after **`analysis`**) | Full **Generate Context** factory unless **`--synthesis-only`**. **`--upload`** runs backend sync after the factory (needs **`auth login`** + **`easyspecs.easyspecsProjectId`**). Without **`--upload`**, backend sync is skipped. **`--skip-upload`** appears in **`easyspecs-cli help`**; omit **`--upload`** to skip upload. If **`easyspecs.factory.cloudContextAnalyzed`** is **`true`** (legacy **`easyspecs.analysis.cloudContextAnalyzed`**) and neither **`--synthesis-only`** nor **`--force-new-context-analysis`** is set, exits **0** early with **`analysisSkipped`** (machine JSON fields). |
+| `update context` | **`--upload`** (optional; any order in tail) | **SRS-55** incremental refresh: git window after baseline → worktree → **`changes-since-date.md`** → optional remediation → **`--promote` / `--no-promote`** → optional **`--upload`** (mtime-scoped files) → **`easyspecs.factory.updateContext.lastRunAt`**. Needs seeded context on **HEAD** (or workspace copy); see **`commands.md`**. |
 | `diagnose reference-coverage` | **`--root workspace`** \| **`--root worktree`**, optional **`--worktree <path>`** | Reference coverage gate; optional percent limit via **`easyspecs.diagnose.zeroReference.maxPercentNonReferenced`**. |
 | `diagnose coordination-duplicates` | same | Duplicate/orphan reporting; **`easyspecs.diagnose.coordinationDuplicates.strict`**. |
 | `diagnose coverage-report` | same | Writes coverage execution report path. |
 | `diagnose missing-artefacts` | same | Lists missing artefacts from workspace state (JSON on stdout in human mode). |
-| `diagnose zero-reference` | **`--worktree <path>`** (optional; no **`--root`** branch) | Zero-reference remediation pool (**OpenCode**). |
+| `diagnose zero-reference` | **`--worktree <path>`** (optional; no **`--root`** branch) | Zero-reference remediation pool (**OpenCode**). After a successful pool run, applies **SRS-51** context markdown navigation links under the analysis checkout context directory (fails the command if that step reports broken links). |
+| `context link-graph` | **`--root workspace`** \| **`--root worktree`**, optional **`--worktree <path>`** | **SRS-51:** refreshes EasySpecs navigation marker blocks in **`.gluecharm/context/**/*.md`** from coordination JSON only (no agents). **`--json`** may include **`contextDir`**, **`error`**, **`brokenLinks`**. |
 | `download context` | **`--force`**, **`--replace-from-cloud`** (optional; any order after **`download context`**) | Requires **`auth login`** session + **`easyspecs.easyspecsProjectId`**. Fetches **`srs_discovery`** ids from **`GET /api/content/application/:id`**, hydrates rows with **`POST /api/batch/content/srs_discovery/get`**, writes UTF-8 files under **`<repo>/.gluecharm/context`**. Default skips existing paths; **`--force`** overwrites; **`--replace-from-cloud`** wipes local context files first (preserves root **`easyspecs-upload-target.json`**). **`--json`**: **`downloaded`**, **`skipped`**, **`failed`**, **`localRemoved`**. Non-zero exit if **`failed` > 0`. Full narrative under **Download context (pull from EasySpecs)** above. |
 | `upload context` | — | Requires auth session + **`easyspecs.easyspecsProjectId`**. Context dir: **`<repo>/.gluecharm/context`**. Optional cloud status GET per **`easyspecs.upload.fetchContextAnalyzedInCloud`**. |
 | `upload republish` | — | Same auth + project id; context dir from **`easyspecs.upload.contextDirectory`** or analysis worktree snapshot. Same optional cloud status behaviour as **`upload context`**. |
 | `ace clear` | — | Deletes learnings under **`.gluecharm/context/learnings`**. |
 | `ace learn` | **`--worktree <path>`** (optional) | Offline ACE learn from traces; **`requireOpenCode`**. Worktree = **`--worktree`** if it contains **`.opencode/schemas/ace`**, else workspace root. |
-| `ace auto-learn` | **`--worktree <path>`** (optional) | ACE auto-learn pool; **`requireOpenCode`**. Worktree = **`--worktree`** if valid git dir, else workspace root. Concurrency capped by **`merged.pipelineOpenCode.maxConcurrentOpenCodeAgents`**. |
+| `ace auto-learn` | **`--worktree <path>`** (optional) | ACE auto-learn pool; **`requireOpenCode`**. Worktree = **`--worktree`** if valid git dir, else workspace root. Concurrency capped by **`merged.pipelineOpenCode.maxConcurrentAgents`** (schema field name; mirrors **`easyspecs.workstations.maxConcurrentAi`** / legacy **`maxConcurrentOpenCodeAgents`**). |
 
 **OpenCode:** commands that spawn agents require **`opencode`** (or configured executable) on **`PATH`** and credentials unless **`skipCredentialsCheck`** or provider keys in **`config.json`** apply (**`requireOpenCode`**).
 
-**EasySpecs API session:** **`download context`**, **`upload context`**, **`upload republish`**, and **`analysis --upload`** need a prior **`auth login`** (or **`--ci`** with **`easyspecs.auth.ciLogin`** in **`config.json`** when argv omits email/password on login), plus **`easyspecs.easyspecsProjectId`** for the upload/download commands.
+**EasySpecs API session:** **`download context`**, **`upload context`**, **`upload republish`**, **`analysis --upload`**, and **`update context --upload`** need a prior **`auth login`** (or **`--ci`** with **`easyspecs.auth.ciLogin`** in **`config.json`** when argv omits email/password on login), plus **`easyspecs.easyspecsProjectId`** for the upload/download commands.
 
 **Unknown command:** prints help and exits with a usage error.
 

package/commands.md

@@ -1,6 +1,18 @@
 # EasySpecs CLI — commands, flags, and configuration
 
-Published package: **`@gluecharm-lab/easyspecs-cli`** (`easyspecs-cli`). Source of truth for routing: [`src/cli/main.ts`](../../src/cli/main.ts), argument parsing: [`src/cli/argv.ts`](../../src/cli/argv.ts), merged settings: [`mergeEasyspecsCliSettings`](../../src/cli/cliSettings.ts), per-repo config: [`src/config/easyspecsConfigFile.ts`](../../src/config/easyspecsConfigFile.ts), CLI API URL resolution: [`src/easyspecsApiBaseUrlCli.ts`](../../src/easyspecsApiBaseUrlCli.ts). The VS Code extension resolves API URLs via [`src/apiBaseUrlResolve.ts`](../../src/apiBaseUrlResolve.ts); **`easyspecs-cli` does not use that chain** for System Manager origin (**SRS-43 R30 / R34**).
+Published package: **`@gluecharm-lab/easyspecs-cli`** (`easyspecs-cli`). Source of truth for routing and option registration: [`src/cli/cliProgram.ts`](../../src/cli/cliProgram.ts), command dispatch and business flow wiring: [`src/cli/main.ts`](../../src/cli/main.ts), merged settings: [`mergeEasyspecsCliSettings`](../../src/cli/cliSettings.ts), per-repo config: [`src/config/easyspecsConfigFile.ts`](../../src/config/easyspecsConfigFile.ts), CLI API URL resolution: [`src/easyspecsApiBaseUrlCli.ts`](../../src/easyspecsApiBaseUrlCli.ts). The VS Code extension resolves API URLs via [`src/apiBaseUrlResolve.ts`](../../src/apiBaseUrlResolve.ts); **`easyspecs-cli` does not use that chain** for System Manager origin (**SRS-43 R30 / R34**).
+
+### Vocabulary (SRS-53)
+
+End-to-end behaviour and file layout: see the repo root companion **`run-analysis-flow.md`** (no URL; same repository).
+
+| Term | One-line meaning |
+|------|------------------|
+| **Factory** | The ordered **Generate Context** run (CLI: **`analysis`**; VS Code: Diagnosis **Run factory** / **Stop factory**). |
+| **Pipeline** | A named stage the Factory composes: Synthesis, Coverage, Remediation, Link Mapping, Upload, or Download. |
+| **Workstation** | One atomic unit inside a Pipeline (OpenCode agent + deterministic validators / repair loop, or a programmatic step). |
+
+**Stderr tags (human TTY mode):** phase changes may insert a blank line when the family changes. Tags include **`[factory]`**, **`[pipeline:synthesis]`** (and `coverage`, `remediation`, `link-mapping`, `upload`, `download`), **`[workstation:<id>]`** for OpenCode subprocess lines, **`[pool]`** / **`[queue]`** for work queues, **`[deprecated-setting]`** when a legacy **`config.json`** key was consumed (canonical keys: **`easyspecs.factory.*`**, **`easyspecs.workstations.*`**, **`easyspecs.pipelines.upload.*`** — see SRS-53 alias table). **`[ace]`** and **`[open questions]`** unchanged.
 
 Quick usage:
 
@@ -12,12 +24,12 @@ easyspecs-cli help
 
 ## Global options
 
-These flags may appear **before** the subcommand. Anything after the first non-flag token is treated as the command and its arguments ([`parseArgv`](../../src/cli/argv.ts)).
+These flags may appear **before** the subcommand. Parsing and command registration are implemented with Commander in [`src/cli/cliProgram.ts`](../../src/cli/cliProgram.ts), with command execution in [`src/cli/main.ts`](../../src/cli/main.ts).
 
 | Flag | Effect |
 |------|--------|
 | `--cwd <dir>` | Repository root for git resolution and file paths (default: current working directory). |
-| `--ci` | Non-interactive mode; feeds into merged settings (e.g. macro outer-iteration default when unlimited). **`EASYSPECS_CI` is not read** — use this flag in CI. |
+| `--ci` | Non-interactive mode; feeds into merged settings (e.g. Factory outer-iteration default when unlimited). **`EASYSPECS_CI` is not read** — use this flag in CI. |
 | `--json` | On supported exits, prints one JSON summary line on stdout; suppresses some human-oriented stderr unless `--verbose`. |
 | `--verbose` | Extra stderr logging where implemented. |
 | `--api-base-url <url>` | System Manager API origin for this process (overrides `easyspecs.apiBaseUrl` in config). |
@@ -28,7 +40,7 @@ These flags may appear **before** the subcommand. Anything after the first non-f
 | `--version`, `-V` | Print CLI package version (also `version` as first positional). Does **not** create config. |
 | `--config <path>` | Parsed but **unused** by `main.ts` today; configuration is read from `<repoRoot>/.easyspecs/config.json`. |
 
-Environment (stderr styling): **`NO_COLOR`** (any non-empty value) disables ANSI colors. **`FORCE_COLOR`** (any non-empty value) allows colors even when stderr is not a TTY. With **`--json`**, human stderr is normally suppressed; **`--json --verbose`** prints plain stderr **without** ANSI. In human mode, a **blank line** may be printed when the diagnostic **phase** changes (e.g. **`[setup]`** → **`[pool]`** / **`[AgentCode]`**). See **README** (Terminal diagnostics).
+Environment (stderr styling): **`NO_COLOR`** (any non-empty value) disables ANSI colors. **`FORCE_COLOR`** (any non-empty value) allows colors even when stderr is not a TTY. With **`--json`**, human stderr is normally suppressed; **`--json --verbose`** prints plain stderr **without** ANSI. In human mode, a **blank line** may be printed when the diagnostic **phase** changes (e.g. **`[factory]`** → **`[pool]`** / **`[workstation:listFeatures]`**). See **README** (Terminal diagnostics).
 
 ---
 
@@ -40,7 +52,7 @@ Canonical JSON created on first need (except **`help`**, **`version`**, and **`d
 
 Merge uses **this file + global CLI flags only** — no `EASYSPECS_*` / `VITE_*` product overrides on **`easyspecs-cli`** (**R34**).
 
-**Workspace layout (SRS-48):** For **`analysis`**, **`diagnose`**, **`upload`**, and **`download context`**, the CLI creates the minimal **`.gluecharm/`** directories (**`docs/srs`**, **`content`**, **`logs`**, **`context`**) under the relevant filesystem root when they are missing. You do not need to copy a Gluecharm template tree before first use.
+**Workspace layout (SRS-48):** For **`analysis`**, **`update context`**, **`diagnose`**, **`upload`**, **`download context`**, and **`context link-graph`**, the CLI creates the minimal **`.gluecharm/`** directories (**`docs/srs`**, **`content`**, **`logs`**, **`context`**) under the relevant filesystem root when they are missing. You do not need to copy a Gluecharm template tree before first use.
 
 | Path | Purpose |
 |------|---------|
@@ -51,15 +63,17 @@ Merge uses **this file + global CLI flags only** — no `EASYSPECS_*` / `VITE_*`
 | `easyspecs.defaultGitRemoteUrl` | Optional primary **`git remote`** URL (HTTPS or SSH) for documentation / tooling; analysis still uses the live repo. Related: **`index-application-context.json`** `repository`, **`.easyspecs/analysis-worktree.json`** `repositoryRoot`. |
 | `easyspecs.cliSessionPath` | Repo-relative or absolute path to **`cli-session.json`** written by **`auth login`**. Empty **`""`** → **`~/.easyspecs/cli-session.json`**. Effective path: global **`--session-path`** (if passed) → **`cliSessionPath`** → default home path ([`cliSession.ts`](../../src/cli/cliSession.ts)). |
 | `easyspecs.openCode` | `executable`, `skipCredentialsCheck` (legacy shortcut; see also `openCodeRuntime`). |
-| `easyspecs.analysis.*` | Pipeline: argv template, timeouts, repair attempts, concurrency, `promoteContextToWorkspace`. **SRS-46:** `cloudContextAnalyzed` (boolean), `cloudContextAnalyzedAt` (`null` or ISO `date-time` string; when `cloudContextAnalyzed` is `true`, `At` must be non-null). |
-| `easyspecs.orchestration.*` | Macro delays, outer iterations, ping-pong cap, etc. |
+| `easyspecs.analysis.*` | Remaining analysis flags (e.g. **`promoteContextToWorkspace`**, ACE toggles). **SRS-46 cache** now lives under **`easyspecs.factory.cloudContextAnalyzed`** / **`…At`** (canonical); legacy **`easyspecs.analysis.cloudContext*`** still read for one cycle. |
+| `easyspecs.factory.*` | Factory: **`debug`** (stderr phase transitions; legacy **`easyspecs.macro.debug`**), backoff (`initialDelayMs`, `multiplier`, `maxDelayMs`), `maxOuterIterationsPerPipeline`, `maxPingPongCycles`, `synthesisRemediationShareBackoff`, cloud-context-analyzed cache. Legacy **`easyspecs.orchestration.*`** aliases per SRS-53. |
+| `easyspecs.workstations.*` | OpenCode argv template, timeouts, repair attempts, pool width, coordination lock timeout. Legacy **`easyspecs.analysis.openCodeTest*`** / **`listJsonSchemaRepairAttempts`** / **`markdown*`** / **`maxConcurrentOpenCodeAgents`** / **`coordinationListLockTimeoutMs`** aliases. |
+| `easyspecs.pipelines.upload.useBatch` | Upload batching preference. Legacy **`easyspecs.analysis.uploadUseBatch`**. |
+| `easyspecs.orchestration.*` | **Deprecated** — use **`easyspecs.factory.*`** (SRS-53); still merged when present. |
 | `easyspecs.openCodeRuntime` | Annex-aligned block: `providers` (per-provider `apiKey`, `defaultModel`), `run`, `coordinationRepairs`, `pool`, `projectConfigOverlay` — see [`srs-43-opencode.schema.json`](../../.gluecharm/docs/srs/srs-43-opencode.schema.json). |
 | `easyspecs.diagnose.zeroReference.maxPercentNonReferenced` | `number` \| **`null`**. When **`null`**, `diagnose reference-coverage` does not fail on percent alone (**SRS-44**). |
 | `easyspecs.diagnose.coordinationDuplicates.strict` | Boolean (default **`true`**). When **`true`**, duplicate/orphan rows fail `diagnose coordination-duplicates`. |
 | `easyspecs.upload.contextDirectory` | Repo-relative or absolute override for **`upload republish`** context dir; empty **`""`** → automatic (analysis snapshot). |
-| `easyspecs.upload.fetchContextAnalyzedInCloud` | Boolean, default **`true`**. When **`true`**, after a fully successful **`upload context`** / **`upload republish`**, the CLI performs **`GET /api/content/application/:id`** and emits **`contextAnalyzedInCloud`** / **`contextAnalyzedInCloudAt`** on **`--json`**; updates **`easyspecs.analysis.cloudContext*`** cache. When **`false`**, skips that GET and omits those JSON keys. |
+| `easyspecs.upload.fetchContextAnalyzedInCloud` | Boolean, default **`true`**. When **`true`**, after a fully successful **`upload context`** / **`upload republish`**, the CLI performs **`GET /api/content/application/:id`** and emits **`contextAnalyzedInCloud`** / **`contextAnalyzedInCloudAt`** on **`--json`**; updates **`easyspecs.factory.cloudContext*`** cache (legacy **`easyspecs.analysis.cloudContext*`**). When **`false`**, skips that GET and omits those JSON keys. |
 | `easyspecs.upload.contextAnalyzedStatusTimeoutMs` | Optional positive integer (ms). GET timeout; default **15000** if omitted. |
-| `easyspecs.macro.debug` | When **`true`**, macro phase transitions log to stderr ([`macroHeadlessHost`](../../src/analysis/macroHeadlessHost.ts)). |
 | `easyspecs.cli.bundledResourcesRoot` | Optional path to bundled **`resources/`** (folder containing **`opencode-agents/`**). Empty → infer next to the CLI package. |
 | `easyspecs.auth.ciLogin.email` / `password` | Used only with **`--ci`** when **`--email` / `--password`** are omitted (**SRS-44**). Prefer CI-generated **`config.json`**; do not commit secrets. |
 
@@ -77,9 +91,9 @@ Provider API keys for OpenCode runs should live under **`easyspecs.openCodeRunti
 
 ---
 
-## Diagnose-only flags
+## Diagnose / context flags
 
-Used after `diagnose <subcommand>`:
+Used after `diagnose <subcommand>` or **`context link-graph`**:
 
 | Flag | Values | Meaning |
 |------|--------|---------|
@@ -105,14 +119,17 @@ Each row lists **command-specific CLI tokens**, then **what configuration applie
 | `auth status` | — | Reads session file. |
 | `run synthesis` | — | Single SRS-9 context pass (same as extension **Run Analysis**). **`requireOpenCode`** → executable + credentials unless skip flag. Uses **`merged.pipelineOpenCode`** from **`config.json`**. **`--promote` / `--no-promote`** controls promotion after success. |
 | `run synthesis resume-missing`, `run synthesis resume-synthesis` | Optional **`--worktree <path>`** | Same implementation: resolves checkout via `--worktree` or stored snapshot ([`resolveAdHocCheckoutRoot`](../../src/cli/main.ts)). OpenCode + **`merged.pipelineOpenCode`**. |
-| `analysis` | Optional tokens anywhere in argv: **`--synthesis-only`**, **`--upload`**, **`--force-new-context-analysis`** | **SRS-32** full loop: synthesis convergence (until no missing artefacts), then coverage, zero-ref, report, index, optional backend sync. **`merged.macroOrchestration`** from config + **`--ci`** defaults. **`--upload`** requires prior **`auth login`** session. Macro debug: **`easyspecs.macro.debug`**. OpenCode options from **`merged.pipelineOpenCode`**. **SRS-46:** if **`easyspecs.analysis.cloudContextAnalyzed`** is **`true`** and neither **`--synthesis-only`** nor **`--force-new-context-analysis`** is set, exits **0** without running the macro or **`--upload`** (machine fields: **`analysisSkipped`**, **`skipReason`**, **`cloudContextAnalyzedAt`**). |
+| `analysis` | Optional tokens anywhere in argv: **`--synthesis-only`**, **`--upload`**, **`--force-new-context-analysis`** | **SRS-32** full **Factory** loop: synthesis convergence (until no missing artefacts), coverage, zero-ref, report, **link mapping**, index assembly, optional backend sync. Factory timing from **`merged.factory`** (internal merge shape in [`cliSettings.ts`](../../src/cli/cliSettings.ts)) + **`--ci`** defaults. **`--upload`** requires prior **`auth login`** session. Debug: **`easyspecs.factory.debug`** (legacy **`easyspecs.macro.debug`**). OpenCode options from **`merged.pipelineOpenCode`**. **SRS-46:** if **`easyspecs.factory.cloudContextAnalyzed`** is **`true`** (legacy **`easyspecs.analysis.cloudContextAnalyzed`**) and neither **`--synthesis-only`** nor **`--force-new-context-analysis`** is set, exits **0** without running the Factory or **`--upload`** (machine fields: **`analysisSkipped`**, **`skipReason`**, **`cloudContextAnalyzedAt`**). |
+| `update context` | Optional **`--upload`** (anywhere in tail, same pattern as **`analysis --upload`**) | **SRS-55:** incremental context refresh — baseline **`easyspecs.factory.updateContext.lastRunAt`** **or** max workspace **`.gluecharm/context`** mtime → git commits after baseline → analysis worktree → seed check (optional copy from workspace if **HEAD** worktree lacks context) → **`changes-since-date.md`** → optional scoped zero-reference remediation → **`--promote` / `--no-promote`** (global) → optional **`--upload`** (files touched this run via mtime gate) → persist **`lastRunAt`**. **`--upload`** requires **`auth`** + **`easyspecs.easyspecsProjectId`**. |
 | `diagnose reference-coverage` | **`--root workspace`** \| **`--root worktree`**, optional **`--worktree <path>`** | Gate when **`easyspecs.diagnose.zeroReference.maxPercentNonReferenced`** is a finite number (not **`null`**): failure when metric exceeds it. |
 | `diagnose coordination-duplicates` | Same **`--root`** / **`--worktree`** | **`easyspecs.diagnose.coordinationDuplicates.strict`**: when **`true`** (default), duplicate/orphan issues fail the exit code. |
 | `diagnose coverage-report` | Same **`--root`** / **`--worktree`** | Uses repo/worktree paths only; no extra env in `main.ts`. |
 | `diagnose missing-artefacts` | Same **`--root`** / **`--worktree`** | Reads artefact snapshot from workspace state; no OpenCode. |
-| `diagnose zero-reference` | Optional **`--worktree <path>`** (no `--root` branch in this handler) | **`requireOpenCode`**; **`merged.pipelineOpenCode`** for pool concurrency/argv/timeout. Checkout from **`--worktree`** or snapshot ([`resolveAdHocCheckoutRoot`](../../src/cli/main.ts)). |
+| `diagnose zero-reference` | Optional **`--worktree <path>`** (no `--root` branch in this handler) | **`requireOpenCode`**; **`merged.pipelineOpenCode`** for pool concurrency/argv/timeout. Checkout from **`--worktree`** or snapshot ([`resolveAdHocCheckoutRoot`](../../src/cli/main.ts)). On full success, runs **SRS-51** markdown link graph on **`<checkout>/.gluecharm/context`** before exit (**non-zero** if link validation fails). |
+| `context link-graph` | **`--root workspace`** \| **`--root worktree`**, optional **`--worktree <path>`** | **SRS-51:** deterministic navigation sections in context markdown under **`<root>/.gluecharm/context`**. No OpenCode. **`--json`**: **`ok`**, **`contextDir`**, **`error`**, **`brokenLinks`**. Exit **`validation`** on broken relative links inside EasySpecs nav regions. |
+| `context drift <referencePath>` | **`--label <slug>`**, **`--index <path>`**, **`--dry-run`**. Optional **`--root`** / **`--worktree`** tail tokens are accepted and ignored for v1 routing. | **SRS-56:** analysis worktree → OpenCode drift agent → **`.gluecharm/context/drift/drift-<slug>-<date>.md`** + reference index patch → global **`--promote` / `--no-promote`**. Success stdout: drift report path. |
 | `download context` | Optional **`--force`**, **`--replace-from-cloud`** | **SRS-49:** requires **`auth`** session. **`GET /api/content/application/:id`** → **`srs_discovery`** ids → **`POST /api/batch/content/srs_discovery/get`** → writes files under **`<repoRoot>/.gluecharm/context`**. **`--force`** overwrites existing paths; **`--replace-from-cloud`** deletes local context files first (preserves root **`easyspecs-upload-target.json`**). **`--json`** stdout: **`downloaded`**, **`skipped`**, **`failed`**, **`localRemoved`**. Exit **`upload`** when any row fails. |
-| `upload context` | — | Requires **`auth`** session. Context dir: **`<repoRoot>/.gluecharm/context`**. Project id: **`easyspecs.easyspecsProjectId`** in **`config.json`** only. **SRS-46:** on full success, optional cloud status GET (see **`fetchContextAnalyzedInCloud`**); **`--json`** may add **`contextAnalyzedInCloud`** / **`contextAnalyzedInCloudAt`**; updates **`easyspecs.analysis.cloudContext*`** when fetch is enabled. |
+| `upload context` | — | Requires **`auth`** session. Context dir: **`<repoRoot>/.gluecharm/context`**. Project id: **`easyspecs.easyspecsProjectId`** in **`config.json`** only. **SRS-46:** on full success, optional cloud status GET (see **`fetchContextAnalyzedInCloud`**); **`--json`** may add **`contextAnalyzedInCloud`** / **`contextAnalyzedInCloudAt`**; updates **`easyspecs.factory.cloudContext*`** when fetch is enabled (legacy **`easyspecs.analysis.cloudContext*`**). |
 | `upload republish` | — | Same auth + upload pipeline; context dir from **`easyspecs.upload.contextDirectory`** if non-empty and valid, else analysis worktree **`…/.gluecharm/context`** from snapshot, else error. Same project id rule as **`upload context`**. Same **SRS-46** JSON + cache behaviour as **`upload context`**. |
 | `ace clear` | — | Deletes **`<repoRoot>/.gluecharm/context/learnings`**. |
 | `ace learn` | Optional **`--worktree <path>`** | **`requireOpenCode`**; worktree chosen if `--worktree` points at checkout with **`.opencode/schemas/ace`**, else **`repoRoot`** ([`main.ts`](../../src/cli/main.ts)). **`merged.pipelineOpenCode`** for spawn argv/timeout. |
@@ -123,6 +140,6 @@ Each row lists **command-specific CLI tokens**, then **what configuration applie
 ## Notes
 
 - Commands that **spawn OpenCode** call **`requireOpenCode`**: binary must respond (`easyspecs.openCode.executable` / `opencode` on **`PATH`**), and credentials must look ready unless **`easyspecs.openCode.skipCredentialsCheck`**, or provider keys exist in **`config.json`**, or the parent shell already has provider env (probe behaviour in [`opencodeCli`](../../src/opencodeCli.ts)).
-- **`download context`** / **`upload`** / **`analysis --upload`** require a prior **`auth login`** session (**`--email`** / **`--password`**, or **`--ci`** with **`easyspecs.auth.ciLogin`** in **`config.json`**).
+- **`download context`** / **`upload`** / **`analysis --upload`** / **`update context --upload`** require a prior **`auth login`** session (**`--email`** / **`--password`**, or **`--ci`** with **`easyspecs.auth.ciLogin`** in **`config.json`**).
 - Unknown commands print help and exit with a usage error.
-- Git subprocesses may set **`GIT_TERMINAL_PROMPT=0`** on the child environment ([`coverageReferenceValidation`](../../src/analysis/coverageReferenceValidation.ts)).
+- Git subprocesses may set **`GIT_TERMINAL_PROMPT=0`** on the child environment ([`runCoveragePipeline`](../../src/pipelines/coverage/coveragePipeline.ts)).