@gluecharm-lab/easyspecs-cli 0.0.13 → 0.0.15

package/README.md

@@ -1,14 +1,15 @@
 # EasySpecs CLI
 
-Headless **EasySpecs** command-line tool for **context analysis**, **diagnoses**, **macro pipelines**, **upload 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`**.
 
 ## Requirements
 
 - **Node.js** ≥ 18  
-- **OpenCode** (`opencode` on `PATH`) for flows that run agents — install from OpenCode’s own documentation  
-- A **git repository** with **`.gluecharm/`** (documentation + context layout) when running analysis, diagnose, or upload against a project  
+- **OpenCode** (`opencode` on `PATH`) for flows that run agents — install OpenCode using its own install instructions 
 
 ## Install
 
@@ -33,57 +34,68 @@ 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**, **`update context`**, **diagnose**, **upload**, and **download context**:
+
 ```bash
 cd /your/repo
 easyspecs-cli doctor
-easyspecs-cli doctor --inspect-config
-easyspecs-cli help
+easyspecs-cli config init
+easyspecs-cli analysis
 ```
 
-Use **`config init`** to create **`.easyspecs/config.json`** with defaults (add **`--overwrite`** to replace an existing file). Set **`easyspecs.easyspecsProjectId`** and **`easyspecs.defaultGitRemoteUrl`** from the shell with **`config set-project-id <id>`** and **`config set-git-remote <url>`** (each overwrites that field). Use **`--ci`** for non-interactive CI: no prompts, stricter defaults (e.g. macro outer-iteration cap). Tunables belong in **`<repo>/.easyspecs/config.json`** — do not rely on **`EASYSPECS_*`** environment variables for product settings.
+**`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.
+
+Optional checks:
 
 ```bash
+easyspecs-cli doctor --inspect-config
+easyspecs-cli help
 easyspecs-cli diagnose coordination-duplicates --cwd /your/repo --ci --json
 ```
 
-## Commands (overview)
+## Download context (pull from EasySpecs)
 
-| Area | Examples |
-| ---- | ---------- |
-| **Health** | `doctor` (`--readiness`, `--inspect-config`), `version` |
-| **Config** | `doctor --inspect-config`, `config init`, `config set-project-id`, `config set-git-remote` |
-| **Auth** | `auth login --email … --password …`, `auth logout`, `auth status` |
-| **Run synthesis** | `run synthesis`; **`run synthesis resume-missing`** / **`resume-synthesis`** |
-| **Analysis** (full macro pipeline) | `analysis` (optional **`--upload`** after login; **`--synthesis-only`** stops after synthesis) |
-| **Diagnose** | `diagnose reference-coverage`, `coordination-duplicates`, `coverage-report`, … |
-| **Upload** | `upload context`, `upload republish` |
-| **ACE** | `ace clear`, `ace learn`, `ace auto-learn` |
+Use this when you want the **application context** that is already stored in EasySpecs (CMS **`srs_discovery`** rows) written into your repo’s **`.gluecharm/context`**, for example after a fresh clone or to align with the cloud.
 
-Run **`easyspecs-cli help`** for the full command tree. This README does not duplicate every flag; the built-in help matches the installed package version.
+**Prerequisites:** same as **`upload context`**: a prior **`auth login`**, and **`easyspecs.easyspecsProjectId`** set (e.g. **`easyspecs-cli config set-project-id <uuid>`**). The CLI creates minimal **`.gluecharm/`** layout when needed, including **`.gluecharm/context`**.
 
-## Terminal diagnostics (colors)
+**Behaviour:** the CLI **GET**s the application, reads linked **`srs_discovery`** ids, then **POST**s **batch get** to **`/api/batch/content/srs_discovery/get`** and writes one file per row under **`<repo>/.gluecharm/context`**, using each row’s **`name`** as a safe relative path (path traversal is rejected). Rows named **`easyspecs-upload-target.json`** are skipped. When files are written, ids are merged into **`index-application-context.json`** the same way as after upload, if that index file exists.
 
-Long-running commands (**`run synthesis`**, **`analysis`**, **`diagnose`** with **`--verbose`**, etc.) print **structured lines** on stderr with bracket prefixes such as **`[pool]`**, **`[queue]`**, **`[setup]`**, **`[AgentCode]`**, **`[context]`**, **`[index]`** — same vocabulary as the EasySpecs Analysis output in VS Code. Logs say **AgentCode** for the agent subprocess; the executable on your machine may still be **`opencode`** on **`PATH`**.
+```bash
+cd /your/repo
+easyspecs-cli auth login --email you@example.com --password '…'
+easyspecs-cli config set-project-id <your-easyspecs-project-uuid>
+easyspecs-cli download context
+```
 
-When **stderr** is an interactive **TTY**, those prefixes are **colorized** (ANSI) for faster scanning.
+| Flag | Meaning |
+| ---- | ------- |
+| *(none)* | Skip any local file that already exists (no silent overwrite). |
+| `--force` | Overwrite existing files that map to cloud rows. |
+| `--replace-from-cloud` | Delete local files under **`.gluecharm/context`** first, then write from the cloud. Root **`easyspecs-upload-target.json`** is preserved when present. Implies a full replace of downloaded content; pair with care. |
 
-| Mechanism | Effect |
-| --------- | ------ |
-| **`NO_COLOR`** set to any non-empty value | Colors **disabled** ([no-color.org](https://no-color.org/)). |
-| **`FORCE_COLOR`** set to any non-empty value | Colors **allowed** even if stderr is **not** a TTY (e.g. piping to **`tee`**). |
-| **`--json`** | Normal runs **suppress** stderr diagnostics; stderr never receives ANSI in that mode so JSON on stdout stays machine-safe. With **`--json --verbose`**, stderr lines are **plain text** (no ANSI). |
+**`--json`:** prints one summary line on stdout with **`ok`**, **`downloaded`**, **`skipped`**, **`failed`** (count), and **`localRemoved`** (files deleted when **`--replace-from-cloud`** was used). With **`--verbose`**, if **`failed` > 0`**, the line may include a **`failures`** array. A non-zero exit is used when **`failed` > 0`**.
 
-**Behaviour:** bracket tags are colorized; **`[pool]`** lines bold the work-item id and dim **`(active n/m)`**; **`[AgentCode]`** lines dim **`prompt` / `command` / `cwd` / `argv`** labels; multi-line **`stderr`/`stdout`** dumps are indented and dimmed; **blank lines** appear when the phase family changes (e.g. **`[setup]`** → **`[pool]`**, **`[pool]`** → **`[AgentCode]`**). Purely visual — message text is unchanged for grep.
+**Examples:**
+
+```bash
+easyspecs-cli download context
+easyspecs-cli download context --force
+easyspecs-cli download context --replace-from-cloud
+easyspecs-cli --json download context
+```
 
 ## Configuration
 
-Primary configuration file: **`<repo>/.easyspecs/config.json`** (auto-created when needed, except for **`help`**, **`version`**, and **`doctor`** which do not create the file on first run). **`auth login --email … --password …`** stores tokens for upload commands (optional **`--session-path`** on the command tail updates **`easyspecs.cliSessionPath`** in **`config.json`**).
+Primary configuration file: **`<repo>/.easyspecs/config.json`** (auto-created when needed, except for **`help`**, **`version`**, and **`doctor`** which do not create the file on first run). **`auth login --email … --password …`** stores tokens for **upload** and **download context** commands. You may append **`--session-path <file>`** at the **end** of the **`auth login`** argument list to update **`easyspecs.cliSessionPath`** in **`config.json`** for that login flow.
 
 After **`auth login`**, session data is stored at **`easyspecs.cliSessionPath`** in **`config.json`** when that path is set (otherwise **`~/.easyspecs/cli-session.json`**). Tools such as the VS Code extension may spawn **`easyspecs-cli`** with global **`--session-path <file>`** so this process uses a temporary session file without editing **`config.json`**.
 
 ### Default **`config.json`** (from **`easyspecs-cli config init`**)
 
-Run **`easyspecs-cli config init`** in your repo (add **`--overwrite`** to replace an existing file). A fresh install writes **`.easyspecs/config.json`** equivalent to the following default shape:
+Run **`easyspecs-cli config init`** in your repo (add **`--overwrite`** to replace an existing file). A fresh install writes **`.easyspecs/config.json`** with a shape similar to:
 
 ```json
 {
@@ -152,6 +164,8 @@ Run **`easyspecs-cli config init`** in your repo (add **`--overwrite`** to repla
 }
 ```
 
+Your file may gain additional keys over time (for example cloud-analysis cache fields under **`easyspecs.analysis`**); validate against the schema your package version documents.
+
 ### Config keys (reference)
 
 Merge order for **`easyspecs-cli`**: **`.easyspecs/config.json`** plus global CLI flags (for example **`--api-base-url`**, **`--environment`**). The CLI does **not** read **`EASYSPECS_*`** or **`VITE_*`** for product settings.
@@ -161,19 +175,24 @@ Merge order for **`easyspecs-cli`**: **`.easyspecs/config.json`** plus global CL
 | `schemaVersion` | Integer (e.g. `2`) for future migrations. |
 | `easyspecs.deploymentEnvironment` | `production` or `staging` (default `production`). Used with built-in System Manager URLs when `apiBaseUrl` is empty. |
 | `easyspecs.apiBaseUrl` | Explicit System Manager origin; wins after `--api-base-url`. Default non-empty value uses the production API host. Use **`""`** if you want the built-in URL from **`deploymentEnvironment`** / **`--environment`** only. |
-| `easyspecs.easyspecsProjectId` | EasySpecs **project** id (Content application UUID) for uploads. Set with **`config set-project-id`** or the EasySpecs app; legacy **`applicationId`** in older files may be migrated into this field. |
+| `easyspecs.easyspecsProjectId` | EasySpecs **project** id (Content application UUID) for **`upload context`**, **`upload republish`**, and **`download context`**. Set with **`config set-project-id`** or the EasySpecs app; legacy **`applicationId`** in older files may be migrated into this field. |
 | `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: argv template, timeouts, repair attempts, concurrency, `promoteContextToWorkspace`. |
-| `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.macro.debug` | When **`true`**, macro phase transitions log extra lines to stderr. |
+| `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.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 the command line. Prefer CI-generated **`config.json`**; avoid committing secrets. |
+| `easyspecs.auth.ciLogin.email` / `password` | Used with **`--ci`** when **`--email` / `--password`** are omitted on **`auth login`**. Prefer CI-generated **`config.json`**; avoid committing secrets. |
 
 **Resolved API base URL:** `--api-base-url` → non-empty **`easyspecs.apiBaseUrl`** → built-in URL from **`--environment`** or **`easyspecs.deploymentEnvironment`** or **`production`**.
 
@@ -181,69 +200,78 @@ Merge order for **`easyspecs-cli`**: **`.easyspecs/config.json`** plus global CL
 
 ## Global flags
 
-`--cwd`, `--ci`, `--json`, `--verbose`, `--api-base-url`, **`--session-path`**, `--environment`, `--promote` / `--no-promote` — details in **`easyspecs-cli --help`**.
-
-### Global options (table)
+These appear **before** the subcommand (everything after the first non-flag token is the command and its arguments).
 
 | 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`). |
+| `--session-path <file>` | Session JSON path for **this process only** (overrides **`easyspecs.cliSessionPath`**); does not rewrite **`config.json`** unless you use **`auth login`** tail **`--session-path`** as documented under **Auth**. |
 | `--environment production` \| `staging` | Alias **`--env`**. Overrides `easyspecs.deploymentEnvironment` for built-in URL selection when no explicit URL is set. |
 | `--promote` | After **`run synthesis`**, copy generated **`.gluecharm/context`** from the analysis worktree into the workspace repo when applicable. |
 | `--no-promote` | Disable that promotion for this run. |
 | `--help`, `-h` | Built-in help. Does **not** create **`.easyspecs/config.json`**. |
 | `--version`, `-V` | CLI package version. Does **not** create config. |
-| `--config <path>` | Reserved / unused in current releases; read **`<repo>/.easyspecs/config.json`** instead. |
+| `--config <path>` | Parsed but **unused** in current releases; read **`<repo>/.easyspecs/config.json`** instead. |
 
-### Diagnose-only flags
+## Diagnose / context flags
 
-Used after **`diagnose <subcommand>`**:
+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. |
-| `--worktree` | path | Analysis git checkout (use with **`--root worktree`** when needed). |
+| `--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)
 
-## Command reference
+Every command the CLI accepts, with command-specific tokens. Global flags above apply to all of these unless noted.
 
-| Command | Tokens / notes | Behaviour summary |
-| ------- | ---------------- | ------------------ |
-| `help`, `--help` | — | Prints usage. |
+| Command | Command-specific flags / tokens | Behaviour summary |
+| ------- | ------------------------------- | ------------------ |
+| `help` or first token `--help` | — | Prints usage (same as **`--help`** before the command). |
 | `version` | — | Prints the CLI package version string. |
-| `doctor` | **`--readiness`**, **`--inspect-config`** | Does **not** create **`config.json`**. Default (no flags) behaves like **`--readiness`**. **`--inspect-config`** prints redacted merged settings and config. |
-| `config init` | **`--overwrite`** optional | Writes full defaults; may import legacy **`.easyspecs/cli.json`** once if present. |
-| `config set-project-id <id>` | — | Sets **`easyspecs.easyspecsProjectId`**. |
-| `config set-git-remote <url>` | — | Sets **`easyspecs.defaultGitRemoteUrl`**. |
-| `auth login` | **`--email`**, **`--password`**, optional tail **`--session-path`** | Login against the resolved API; writes session file. With **`--ci`**, credentials may come from **`easyspecs.auth.ciLogin`** in **`config.json`** if argv omits email/password. |
-| `auth logout` | — | Clears the effective session file. |
-| `auth status` | — | Shows whether a session file exists / looks populated. |
-| `run synthesis` | — | Context artefact pipeline pass; **`requireOpenCode`** applies. |
-| `run synthesis resume-missing`, `resume-synthesis` | **`--worktree`** | Resumes remediation / synthesis on a known checkout. |
-| `analysis` | **`--synthesis-only`**, **`--upload`** | Full macro loop; **`--upload`** needs **`auth login`** and project id in config. |
-| `diagnose reference-coverage` | **`--root`**, **`--worktree`** | Optional percent gate via **`easyspecs.diagnose.zeroReference.maxPercentNonReferenced`**. |
-| `diagnose coordination-duplicates` | same | **`easyspecs.diagnose.coordinationDuplicates.strict`**. |
-| `diagnose coverage-report` | same | Coverage report path on disk. |
-| `diagnose missing-artefacts` | same | Lists missing artefacts from workspace state. |
-| `diagnose zero-reference` | **`--worktree`** | Zero-reference remediation pool (**OpenCode**). |
-| `upload context` | — | Requires auth session and **`easyspecs.easyspecsProjectId`**. |
-| `upload republish` | — | Same auth rules; context dir from **`easyspecs.upload.contextDirectory`** or analysis snapshot. |
+| `doctor` | **`--readiness`**, **`--inspect-config`** (optional; default if none → readiness-style check) | Does **not** create **`config.json`**. **`--readiness`**: repo root, API URL, OpenCode, agents dir. **`--inspect-config`**: redacted merged settings + config JSON. Both flags together runs both. |
+| `config init` | **`--overwrite`** (optional) | Writes **`.easyspecs/config.json`** with defaults; may import legacy **`.easyspecs/cli.json`** once if present. Existing file unchanged unless **`--overwrite`**. |
+| `config set-project-id <easyspecsProjectId>` | — | Sets **`easyspecs.easyspecsProjectId`** (creates config with defaults if missing). |
+| `config set-git-remote <url>` | — | Sets **`easyspecs.defaultGitRemoteUrl`** (same bootstrap-if-missing behaviour). |
+| `config dump` | — | **Deprecated.** Prints the same redacted payload as **`doctor --inspect-config`** and stderr warns to use **`doctor --inspect-config`**. |
+| `auth login` | **`--email <email> --password <password>`**, optional tail **`--session-path <path>`** | Login to resolved API; writes session file. With **`--ci`**, credentials may come from **`easyspecs.auth.ciLogin`** in **`config.json`** if argv omits email/password. Tail **`--session-path`** updates **`easyspecs.cliSessionPath`** in **`config.json`**. Global **`--session-path`** overrides effective session file without editing **`config.json`**. |
+| `auth logout` | — | Deletes the effective session file. |
+| `auth status` | — | Reports whether a session file exists / looks populated. |
+| `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 **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**). 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`, `ace auto-learn` | **`--worktree`** | ACE offline learning pools (**OpenCode**). |
+| `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.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`**, **`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.
 
 ## Product information
 
-**EasySpecs** is a product for agentic documentation and requirements: use the public marketing and app entry at **easyspecs.ai** (sign-in, projects, browser workspace). This npm package is the **headless CLI** only; it does not bundle the web app.
+**EasySpecs** is a product for agentic documentation and requirements. The public site and app live at **easyspecs.ai** (sign-in, projects, browser workspace). This npm package is the **headless CLI** only; it does not bundle the web app.
 
 ## License
 
 Copyright © **Spaii Edutainment SL** (Barcelona, Spain).
 
-This package is licensed under the **Elastic License 2.0** (**ELv2**, SPDX **`Elastic-2.0`**). The complete license text is included in the **`LICENSE`** file published inside **`@gluecharm-lab/easyspecs-cli`**. Other artifacts outside this tarball may use different licenses.
-
-## Bundled documentation
-
-This package also ships **`commands.md`** in the same directory as this **`README.md`**, with an extended command and configuration reference (same scope as this file, in alternate layout).
+This package is licensed under the **Elastic License 2.0** (**ELv2**, SPDX **`Elastic-2.0`**). The complete license text ships in the **`LICENSE`** file inside the published **`@gluecharm-lab/easyspecs-cli`** package on npm.

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,6 +52,8 @@ 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`**, **`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 |
 |------|---------|
 | `schemaVersion` | Integer (e.g. `2`) for future migrations. |
@@ -49,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. |
 
@@ -75,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 |
 |------|--------|---------|
@@ -103,13 +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)). |
-| `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. |
+| `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.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. |
@@ -120,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)).
-- **`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)).