@gluecharm-lab/easyspecs-cli 0.0.13 → 0.0.14

package/README.md

@@ -1,14 +1,13 @@
 # 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**, **macro pipelines**, **download/upload context** to EasySpecs, **auth**, and **ACE** — the same orchestration ideas as the **EasySpecs VS Code extension**, without an editor.
 
 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 +32,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**, **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 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).
+
+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)
+
+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.
 
-| 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` |
+**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`**.
 
-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.
+**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.
 
-## Terminal diagnostics (colors)
+```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
+```
 
-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`**.
+| 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. |
 
-When **stderr** is an interactive **TTY**, those prefixes are **colorized** (ANSI) for faster scanning.
+**`--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`**.
 
-| 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). |
+**Examples:**
 
-**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.
+```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 +162,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 +173,21 @@ 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.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.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.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,9 +195,7 @@ 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 |
 | ---- | ------ |
@@ -192,58 +204,67 @@ Merge order for **`easyspecs-cli`**: **`.easyspecs/config.json`** plus global CL
 | `--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-only flags
 
-Used after **`diagnose <subcommand>`**:
+Used on the tail of **`diagnose <subcommand>`** (after the subcommand name):
 
 | 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`**). |
+| `--worktree` | path | Analysis git checkout (use with **`--root worktree`**, or alone where documented below). |
+
+## 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 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). |
+| `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**). |
+| `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.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.
+
+**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

@@ -40,6 +40,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`**, **`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.
+
 | Path | Purpose |
 |------|---------|
 | `schemaVersion` | Integer (e.g. `2`) for future migrations. |
@@ -109,6 +111,7 @@ Each row lists **command-specific CLI tokens**, then **what configuration applie
 | `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)). |
+| `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 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`**. |
@@ -120,6 +123,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`** 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)).