expedait-cli 0.2.2__tar.gz → 0.4.0__tar.gz

expedait_cli-0.4.0/CHANGELOG.md

@@ -0,0 +1,92 @@
+# Changelog
+
+## 0.4.0
+
+Bring the CLI to parity with the hosted MCP server's write surface — agents can
+now create and adapt content, processes, and roles, not just read them. Every
+new command supports `--format json` and reports a per-op summary.
+
+### Added
+- **Deliverable writes** (mirror MCP `write_deliverable`):
+  - `deliverables write --ops @file.json` — ordered batch of `create` / `edit` /
+    `rename` / `save_version` / `set_state` ops, chainable with `id="$last"` or
+    named refs (`ref="x"` on create, `id="@x"` later). Pre-flight validates op
+    shape and reference ordering; ops stop on first failure (rest `skipped`) and
+    the command exits non-zero on partial failure.
+  - Ergonomic subcommands on top: `deliverables create`, `edit`, `rename`,
+    `save-version`, `set-state` (states: Not Started, In Progress, Review,
+    Approved, Completed, Final). `--content` / `--instructions` accept `@file`,
+    `-` (stdin), or a literal.
+- **`processes` command group** (mirror MCP `list_processes` / `get_process` /
+  `write_process`): `processes list`, `processes get PROCESS_ID` (full template
+  tree — phases, rows, deliverable-type cards, owner roles, objective
+  subprocesses), and `processes write --ops` (create/update/delete process,
+  phases, rows, deliverable types; `set_dependencies`; `set_owner_roles`). Named
+  refs, optional card layout with auto-placement (`after_type_id` / append),
+  role-name resolution, and an in-use delete guard (`confirm_in_use`).
+- **`roles` command group** (mirror MCP `list_roles` / `write_role`):
+  `roles list`, `roles create`, `roles update`, `roles delete`, and
+  `roles write --ops`.
+- **Context-file management** under the `context` group — manage the uploaded
+  files that feed a deliverable's (or objective's) LLM context: `context files`
+  (list), `context add` (upload; re-upload by name replaces), `context
+  file-content` (parsed text), `context download-file`, `context remove-file`,
+  and `context set-file --exclude/--include` (toggle a file in/out of the LLM
+  context). External source links remain web-app integration flows.
+- `expedait_cli/ops.py` — shared multi-op engine (`RefResolver`, `run_ops`,
+  `render_ops`) behind all three write surfaces, mirroring the MCP server's
+  `_common.py` run-ops scaffold.
+- `client.BackendError` + an op-safe request path so per-op failures are
+  captured and reported instead of aborting the whole command.
+- `deliverables types` — list deliverable types so you can find the `--type` id
+  that `deliverables create` needs.
+- `projects workspace [PROJECT_ID]` — deliverables grouped by phase (mirrors the
+  MCP `get_project_workspace` tool); the structure-aware view the flat
+  `deliverables list` can't give.
+
+### Fixed
+- `processes write` no longer crashes with an uncaught `KeyError` when an
+  `update_phase_row` op omits `position`; it now reports a clean per-op
+  `missing_field` error.
+- `--content` / `--instructions` / `--ops` with a missing or unreadable `@file`
+  now raise a clear usage error instead of leaking an `OSError` traceback. The
+  three duplicate readers were consolidated into one helper (`ops.read_value_arg`).
+- `projects download` no longer crashes. It passed a `fmt=` argument that the
+  client method never accepted (a `TypeError` on every run, hidden by a loosely
+  mocked test). The backend `/download` endpoint has no format parameter, so the
+  dead `--download-format` option was removed; the command always extracts the
+  markdown + images ZIP.
+
+## 0.3.0
+
+Adapt the CLI to the product's four-primitive domain model (objectives,
+deliverables, context, review).
+
+### Added
+- `deliverables` command group (`list`, `get`, `inspect`, `download`) — the
+  rename of `pages`, pointed at `/api/v1/deliverables/...`.
+- `deliverables get --include` — comma-separated section reads (`meta`,
+  `content`, `template`, `requirements`, `writer_instructions`, `dependencies`,
+  `external_context`, `score`, `comments`, `versions`), defaulting to `content`.
+  `meta` surfaces `parent_deliverable_id`.
+- `objectives overview DELIVERABLE_ID` — objective metadata plus its full
+  descendant tree.
+- `context get DELIVERABLE_ID` — read-only LLM context snapshot for a
+  deliverable.
+- `review` command group: `review issues DELIVERABLE_ID [--state open|muted|all]`
+  and `review mute ISSUE_ID [--note TEXT] [--unmute]`.
+- `comments create --agent-run-id` to link a comment to a build run.
+- `expedait-cli` console-script alias so `uvx expedait-cli …` keeps working.
+
+### Changed
+- `comments create` now resolves anchor offsets from the deliverable content;
+  only `--text` and `--selected-text` are required. `--start-offset` /
+  `--end-offset` remain available as explicit overrides.
+- Renamed `comments create --source-page-id` → `--source-deliverable-id`
+  (payload field `source_page_id` → `source_deliverable_id`).
+- `comments resolve` / `comments delete` now use the deliverable-scoped routes
+  `/api/v1/deliverables/{id}/comments/{comment_id}`.
+
+### Deprecated
+- The `pages` command group. `expedait pages …` still works for one release
+  (warns and forwards to `deliverables`) and will then be removed.

expedait_cli-0.4.0/PKG-INFO

@@ -0,0 +1,301 @@
+Metadata-Version: 2.4
+Name: expedait-cli
+Version: 0.4.0
+Summary: CLI for Expedait project management — read and write deliverables, processes, roles, and comments
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# Expedait CLI
+
+[![PyPI](https://img.shields.io/pypi/v/expedait-cli)](https://pypi.org/project/expedait-cli/)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+
+CLI for [Expedait](https://expedait.org) — lets AI coding agents download project specs and post comments via the Expedait API.
+
+## The model
+
+Expedait organizes specs around four primitives:
+
+- **Objectives** — top-level goals. An objective is itself a deliverable that nests child deliverables beneath it (`parent_deliverable_id`).
+- **Deliverables** — the individual spec documents (formerly "pages").
+- **Context** — the assembled LLM context for one deliverable: dependency deliverables, linked external sources, uploaded files, and aggregate sizes.
+- **Review** — scoring findings raised on a deliverable: severity, description, the criteria that flagged them, and anchor offsets.
+
+## Usage
+
+### Run with `uvx` (recommended)
+
+No installation needed — run directly:
+
+```bash
+uvx expedait-cli auth login
+uvx expedait-cli projects list
+uvx expedait-cli projects download 1
+```
+
+### Add as a dev dependency
+
+If your AI agent needs it available in the project environment:
+
+```bash
+uv add --group dev expedait-cli
+```
+
+Then reference it in your agent configuration (e.g. `CLAUDE.md`, `.cursor/rules`, etc.).
+
+## Project Setup
+
+After authenticating, run `init` inside your project directory to store your tenant and project settings locally:
+
+```bash
+uvx expedait-cli init
+```
+
+This creates `.expedait/settings.json` with your `tenant_id` and `project_id`. Add `.expedait/` to your `.gitignore`.
+
+Once initialized, commands that need a project ID will resolve it automatically. Downloads default to `.expedait/context/`:
+
+```bash
+expedait projects download              # downloads to .expedait/context/
+expedait deliverables list              # no --project-id needed
+expedait deliverables download 42       # downloads to .expedait/context/
+```
+
+**Resolution order for tenant/project:** CLI flag > env var > `.expedait/settings.json` > `~/.expedait/config.json`.
+
+## Authentication
+
+### Interactive login
+
+```bash
+uvx expedait-cli auth login
+```
+
+Prompts for login method (SSO or email/password). Stores credentials in `~/.expedait/config.json`.
+
+### Environment variables (CI / agents)
+
+```bash
+export EXPEDAIT_TOKEN="your-jwt-token"
+export EXPEDAIT_API_URL="https://your-instance.expedait.org"
+export EXPEDAIT_TENANT_ID=1
+```
+
+**Token resolution order:** `EXPEDAIT_TOKEN` env var > `~/.expedait/config.json` > error.
+
+## Commands
+
+### Auth
+
+```bash
+expedait auth login       # Interactive login
+expedait auth status      # Show current user and tenant
+expedait auth logout      # Clear stored credentials
+```
+
+### Projects
+
+```bash
+expedait projects list                       # List all projects
+expedait projects get PROJECT_ID             # Get project details
+expedait projects workspace PROJECT_ID       # Deliverables grouped by phase (structure-aware view)
+expedait projects download PROJECT_ID        # Extract all deliverables to .expedait/context/
+expedait projects download PROJECT_ID --output-dir ./specs  # Extract to a custom directory
+```
+
+### Deliverables
+
+```bash
+expedait deliverables list --project-id PROJECT_ID   # List deliverables in a project
+expedait deliverables types                           # List deliverable types (find the --type ID for create)
+expedait deliverables get DELIVERABLE_ID             # Print deliverable markdown content
+expedait deliverables get DELIVERABLE_ID --include meta,content,dependencies,score
+expedait deliverables inspect DELIVERABLE_ID         # Full context (content + comments + deps + lock)
+expedait deliverables download DELIVERABLE_ID        # Extract to .expedait/context/
+```
+
+`--include` accepts a comma-separated subset of: `meta`, `content`, `template`,
+`requirements`, `writer_instructions`, `dependencies`, `external_context`,
+`score`, `comments`, `versions`. It defaults to `content`. `meta` surfaces
+`parent_deliverable_id` (non-null ⇒ this deliverable is a child nested under an
+objective).
+
+#### Writing deliverables
+
+Mirrors the MCP `write_deliverable` tool. Ergonomic subcommands cover the common
+cases; `write --ops` applies an ordered batch in one call.
+
+```bash
+expedait deliverables create --project P --type TYPE_ID --title "Vision" \
+  [--content @vision.md] [--parent-deliverable-id ID]   # create (content: @file, - for stdin, or literal)
+expedait deliverables edit DELIVERABLE_ID --content @body.md   # replace content (autosave, no version bump)
+expedait deliverables rename DELIVERABLE_ID --title "New title" # rename without touching content
+expedait deliverables save-version DELIVERABLE_ID --reason "checkpoint"  # explicit snapshot
+expedait deliverables set-state DELIVERABLE_ID --state "Review"          # transition workflow state
+```
+
+Valid states: `Not Started`, `In Progress`, `Review`, `Approved`, `Completed`,
+`Final`.
+
+For multi-step writes, `write --ops` takes a JSON ops array (`@file.json`, `-`
+for stdin, or inline). Each op is one of `create`, `edit`, `rename`,
+`save_version`, `set_state`. Chain ops on a freshly-created deliverable with
+`"id": "$last"` (the previous op's deliverable) or bind a name on create
+(`"ref": "x"`) and reference it later as `"id": "@x"`:
+
+```bash
+expedait deliverables write --ops @ops.json
+# ops.json:
+# [
+#   {"op": "create", "ref": "v", "project_id": 1, "deliverable_type_id": 3, "title": "Vision"},
+#   {"op": "edit", "id": "@v", "content": "# Product Vision\n..."},
+#   {"op": "set_state", "id": "@v", "state": "Review"}
+# ]
+```
+
+Ops run in order and stop on the first failure (the rest report `skipped`); the
+output reports per-op `{status: ok | error | skipped}`, and the command exits
+non-zero if any op failed.
+
+### Objectives
+
+```bash
+expedait objectives overview DELIVERABLE_ID   # Objective metadata + full descendant tree
+```
+
+### Context
+
+```bash
+expedait context get DELIVERABLE_ID           # The LLM context snapshot for one deliverable
+```
+
+A deliverable's (or objective's) context is built from dependency deliverables,
+linked external sources, and **uploaded context files**. The CLI manages the
+file half of that surface — attach reference docs an agent should write against,
+and toggle whether each one feeds the LLM context:
+
+```bash
+expedait context files DELIVERABLE_ID                 # List attached context files
+expedait context add DELIVERABLE_ID ./reference.md    # Upload a context file (re-upload by name replaces)
+expedait context file-content FILE_ID                 # Parsed text the file contributes to context
+expedait context download-file FILE_ID -o ./out.md    # Download a file's raw bytes
+expedait context set-file FILE_ID --exclude           # Exclude from LLM context (or --include)
+expedait context remove-file FILE_ID                  # Delete a context file
+```
+
+External source links (Notion, GitHub, etc.) are created through the web app's
+integration flows, not the CLI.
+
+### Review
+
+```bash
+expedait review issues DELIVERABLE_ID                 # List scoring findings (default: all)
+expedait review issues DELIVERABLE_ID --state open    # Only open findings
+expedait review mute ISSUE_ID --note "by design"      # Mute a finding
+expedait review mute ISSUE_ID --unmute                # Unmute a finding
+```
+
+### Comments
+
+```bash
+expedait comments list DELIVERABLE_ID                 # List comments on a deliverable
+expedait comments create DELIVERABLE_ID \             # Create a comment (offsets resolved automatically)
+  --text "Comment content" \
+  --selected-text "text from the deliverable" \
+  --source-deliverable-id 5                            # Optional: agent's source deliverable
+expedait comments resolve DELIVERABLE_ID COMMENT_ID   # Mark as resolved
+expedait comments delete DELIVERABLE_ID COMMENT_ID    # Delete a comment
+```
+
+Only `--text` and `--selected-text` are required; the CLI locates the selected
+text in the deliverable to compute anchor offsets. Pass `--start-offset` and
+`--end-offset` to anchor explicitly (e.g. when the selected text appears more
+than once).
+
+### Processes (Process Designer)
+
+A *process* is a project type plus the template tree it owns: phases → rows →
+deliverable-type cards, dependency edges, owner roles, and objective
+subprocesses. Editing it reshapes **every** project instantiated from it.
+Mirrors the MCP `list_processes` / `get_process` / `write_process` tools.
+
+```bash
+expedait processes list                   # List processes (project types)
+expedait processes get PROCESS_ID         # Full template tree (phases, rows, cards, roles)
+expedait processes write --ops @ops.json  # Build or adapt a process in one call
+```
+
+`write --ops` ops: `create_process`, `update_process`, `duplicate_process`,
+`delete_process`, `create_phase`, `update_phase`, `delete_phase`,
+`create_phase_row`, `update_phase_row`, `delete_phase_row`,
+`create_deliverable_type`, `update_deliverable_type`, `delete_deliverable_type`,
+`set_dependencies`, `set_owner_roles`. Ops chain via named refs (`"ref": "x"` on
+a create op, `"@x"` later). Card layout is optional — omit `col_position` and
+cards auto-place (append, or just after `after_type_id`). `set_owner_roles`
+accepts role names or ids. Delete ops refuse an in-use template unless the op
+carries `"confirm_in_use": true`.
+
+```jsonc
+// ops.json — build a process end to end in one call
+[
+  {"op": "create_process", "ref": "p", "name": "Product Dev"},
+  {"op": "create_phase", "ref": "ph", "process_id": "@p", "name": "Discovery"},
+  {"op": "create_deliverable_type", "ref": "vision", "phase_id": "@ph", "name": "Vision"},
+  {"op": "create_deliverable_type", "ref": "prd", "phase_id": "@ph", "name": "PRD", "after_type_id": "@vision"},
+  {"op": "set_dependencies", "type_id": "@prd", "dependency_ids": ["@vision"]},
+  {"op": "set_owner_roles", "type_id": "@prd", "role_names": ["Product Manager"]}
+]
+```
+
+### Roles
+
+A *role* is a workspace project role — the owner-role pool assigned to
+deliverable types. A role's `instructions` is its LLM coaching persona. Mirrors
+the MCP `list_roles` / `write_role` tools.
+
+```bash
+expedait roles list                                       # List project roles
+expedait roles create --name "Product Manager" \          # Create (instructions: @file, -, or literal)
+  [--description "owns the roadmap"] [--instructions @pm.md]
+expedait roles update ROLE_ID --name "Lead PM"            # Update name/description/instructions
+expedait roles delete ROLE_ID                             # Delete a role
+expedait roles write --ops @ops.json                      # Batch (create_role/update_role/delete_role)
+```
+
+### Global Options
+
+```bash
+expedait --api-url https://host:8000 ...    # Override API URL
+expedait --tenant-id 2 ...                  # Override tenant
+expedait --format json ...                  # Force JSON output
+expedait --format text ...                  # Force human-readable output
+expedait --version                          # Show version
+```
+
+Output format defaults to `text` when connected to a terminal, `json` when piped.
+
+> **Migration note:** the `pages` command group has been renamed to
+> `deliverables`. `expedait pages …` still works for one release (it warns and
+> forwards) but will be removed.
+
+## Agent Skills
+
+For step-by-step guides on using the CLI from AI coding agents, see [expedait-skills](https://github.com/Expedait/expedait-skills).
+
+## Development
+
+```bash
+git clone https://github.com/Expedait/expedait-cli.git
+cd expedait-cli
+uv sync --group dev
+uv run python -m pytest
+```
+
+## License
+
+[Apache License 2.0](LICENSE)

expedait_cli-0.4.0/README.md

@@ -0,0 +1,290 @@
+# Expedait CLI
+
+[![PyPI](https://img.shields.io/pypi/v/expedait-cli)](https://pypi.org/project/expedait-cli/)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+
+CLI for [Expedait](https://expedait.org) — lets AI coding agents download project specs and post comments via the Expedait API.
+
+## The model
+
+Expedait organizes specs around four primitives:
+
+- **Objectives** — top-level goals. An objective is itself a deliverable that nests child deliverables beneath it (`parent_deliverable_id`).
+- **Deliverables** — the individual spec documents (formerly "pages").
+- **Context** — the assembled LLM context for one deliverable: dependency deliverables, linked external sources, uploaded files, and aggregate sizes.
+- **Review** — scoring findings raised on a deliverable: severity, description, the criteria that flagged them, and anchor offsets.
+
+## Usage
+
+### Run with `uvx` (recommended)
+
+No installation needed — run directly:
+
+```bash
+uvx expedait-cli auth login
+uvx expedait-cli projects list
+uvx expedait-cli projects download 1
+```
+
+### Add as a dev dependency
+
+If your AI agent needs it available in the project environment:
+
+```bash
+uv add --group dev expedait-cli
+```
+
+Then reference it in your agent configuration (e.g. `CLAUDE.md`, `.cursor/rules`, etc.).
+
+## Project Setup
+
+After authenticating, run `init` inside your project directory to store your tenant and project settings locally:
+
+```bash
+uvx expedait-cli init
+```
+
+This creates `.expedait/settings.json` with your `tenant_id` and `project_id`. Add `.expedait/` to your `.gitignore`.
+
+Once initialized, commands that need a project ID will resolve it automatically. Downloads default to `.expedait/context/`:
+
+```bash
+expedait projects download              # downloads to .expedait/context/
+expedait deliverables list              # no --project-id needed
+expedait deliverables download 42       # downloads to .expedait/context/
+```
+
+**Resolution order for tenant/project:** CLI flag > env var > `.expedait/settings.json` > `~/.expedait/config.json`.
+
+## Authentication
+
+### Interactive login
+
+```bash
+uvx expedait-cli auth login
+```
+
+Prompts for login method (SSO or email/password). Stores credentials in `~/.expedait/config.json`.
+
+### Environment variables (CI / agents)
+
+```bash
+export EXPEDAIT_TOKEN="your-jwt-token"
+export EXPEDAIT_API_URL="https://your-instance.expedait.org"
+export EXPEDAIT_TENANT_ID=1
+```
+
+**Token resolution order:** `EXPEDAIT_TOKEN` env var > `~/.expedait/config.json` > error.
+
+## Commands
+
+### Auth
+
+```bash
+expedait auth login       # Interactive login
+expedait auth status      # Show current user and tenant
+expedait auth logout      # Clear stored credentials
+```
+
+### Projects
+
+```bash
+expedait projects list                       # List all projects
+expedait projects get PROJECT_ID             # Get project details
+expedait projects workspace PROJECT_ID       # Deliverables grouped by phase (structure-aware view)
+expedait projects download PROJECT_ID        # Extract all deliverables to .expedait/context/
+expedait projects download PROJECT_ID --output-dir ./specs  # Extract to a custom directory
+```
+
+### Deliverables
+
+```bash
+expedait deliverables list --project-id PROJECT_ID   # List deliverables in a project
+expedait deliverables types                           # List deliverable types (find the --type ID for create)
+expedait deliverables get DELIVERABLE_ID             # Print deliverable markdown content
+expedait deliverables get DELIVERABLE_ID --include meta,content,dependencies,score
+expedait deliverables inspect DELIVERABLE_ID         # Full context (content + comments + deps + lock)
+expedait deliverables download DELIVERABLE_ID        # Extract to .expedait/context/
+```
+
+`--include` accepts a comma-separated subset of: `meta`, `content`, `template`,
+`requirements`, `writer_instructions`, `dependencies`, `external_context`,
+`score`, `comments`, `versions`. It defaults to `content`. `meta` surfaces
+`parent_deliverable_id` (non-null ⇒ this deliverable is a child nested under an
+objective).
+
+#### Writing deliverables
+
+Mirrors the MCP `write_deliverable` tool. Ergonomic subcommands cover the common
+cases; `write --ops` applies an ordered batch in one call.
+
+```bash
+expedait deliverables create --project P --type TYPE_ID --title "Vision" \
+  [--content @vision.md] [--parent-deliverable-id ID]   # create (content: @file, - for stdin, or literal)
+expedait deliverables edit DELIVERABLE_ID --content @body.md   # replace content (autosave, no version bump)
+expedait deliverables rename DELIVERABLE_ID --title "New title" # rename without touching content
+expedait deliverables save-version DELIVERABLE_ID --reason "checkpoint"  # explicit snapshot
+expedait deliverables set-state DELIVERABLE_ID --state "Review"          # transition workflow state
+```
+
+Valid states: `Not Started`, `In Progress`, `Review`, `Approved`, `Completed`,
+`Final`.
+
+For multi-step writes, `write --ops` takes a JSON ops array (`@file.json`, `-`
+for stdin, or inline). Each op is one of `create`, `edit`, `rename`,
+`save_version`, `set_state`. Chain ops on a freshly-created deliverable with
+`"id": "$last"` (the previous op's deliverable) or bind a name on create
+(`"ref": "x"`) and reference it later as `"id": "@x"`:
+
+```bash
+expedait deliverables write --ops @ops.json
+# ops.json:
+# [
+#   {"op": "create", "ref": "v", "project_id": 1, "deliverable_type_id": 3, "title": "Vision"},
+#   {"op": "edit", "id": "@v", "content": "# Product Vision\n..."},
+#   {"op": "set_state", "id": "@v", "state": "Review"}
+# ]
+```
+
+Ops run in order and stop on the first failure (the rest report `skipped`); the
+output reports per-op `{status: ok | error | skipped}`, and the command exits
+non-zero if any op failed.
+
+### Objectives
+
+```bash
+expedait objectives overview DELIVERABLE_ID   # Objective metadata + full descendant tree
+```
+
+### Context
+
+```bash
+expedait context get DELIVERABLE_ID           # The LLM context snapshot for one deliverable
+```
+
+A deliverable's (or objective's) context is built from dependency deliverables,
+linked external sources, and **uploaded context files**. The CLI manages the
+file half of that surface — attach reference docs an agent should write against,
+and toggle whether each one feeds the LLM context:
+
+```bash
+expedait context files DELIVERABLE_ID                 # List attached context files
+expedait context add DELIVERABLE_ID ./reference.md    # Upload a context file (re-upload by name replaces)
+expedait context file-content FILE_ID                 # Parsed text the file contributes to context
+expedait context download-file FILE_ID -o ./out.md    # Download a file's raw bytes
+expedait context set-file FILE_ID --exclude           # Exclude from LLM context (or --include)
+expedait context remove-file FILE_ID                  # Delete a context file
+```
+
+External source links (Notion, GitHub, etc.) are created through the web app's
+integration flows, not the CLI.
+
+### Review
+
+```bash
+expedait review issues DELIVERABLE_ID                 # List scoring findings (default: all)
+expedait review issues DELIVERABLE_ID --state open    # Only open findings
+expedait review mute ISSUE_ID --note "by design"      # Mute a finding
+expedait review mute ISSUE_ID --unmute                # Unmute a finding
+```
+
+### Comments
+
+```bash
+expedait comments list DELIVERABLE_ID                 # List comments on a deliverable
+expedait comments create DELIVERABLE_ID \             # Create a comment (offsets resolved automatically)
+  --text "Comment content" \
+  --selected-text "text from the deliverable" \
+  --source-deliverable-id 5                            # Optional: agent's source deliverable
+expedait comments resolve DELIVERABLE_ID COMMENT_ID   # Mark as resolved
+expedait comments delete DELIVERABLE_ID COMMENT_ID    # Delete a comment
+```
+
+Only `--text` and `--selected-text` are required; the CLI locates the selected
+text in the deliverable to compute anchor offsets. Pass `--start-offset` and
+`--end-offset` to anchor explicitly (e.g. when the selected text appears more
+than once).
+
+### Processes (Process Designer)
+
+A *process* is a project type plus the template tree it owns: phases → rows →
+deliverable-type cards, dependency edges, owner roles, and objective
+subprocesses. Editing it reshapes **every** project instantiated from it.
+Mirrors the MCP `list_processes` / `get_process` / `write_process` tools.
+
+```bash
+expedait processes list                   # List processes (project types)
+expedait processes get PROCESS_ID         # Full template tree (phases, rows, cards, roles)
+expedait processes write --ops @ops.json  # Build or adapt a process in one call
+```
+
+`write --ops` ops: `create_process`, `update_process`, `duplicate_process`,
+`delete_process`, `create_phase`, `update_phase`, `delete_phase`,
+`create_phase_row`, `update_phase_row`, `delete_phase_row`,
+`create_deliverable_type`, `update_deliverable_type`, `delete_deliverable_type`,
+`set_dependencies`, `set_owner_roles`. Ops chain via named refs (`"ref": "x"` on
+a create op, `"@x"` later). Card layout is optional — omit `col_position` and
+cards auto-place (append, or just after `after_type_id`). `set_owner_roles`
+accepts role names or ids. Delete ops refuse an in-use template unless the op
+carries `"confirm_in_use": true`.
+
+```jsonc
+// ops.json — build a process end to end in one call
+[
+  {"op": "create_process", "ref": "p", "name": "Product Dev"},
+  {"op": "create_phase", "ref": "ph", "process_id": "@p", "name": "Discovery"},
+  {"op": "create_deliverable_type", "ref": "vision", "phase_id": "@ph", "name": "Vision"},
+  {"op": "create_deliverable_type", "ref": "prd", "phase_id": "@ph", "name": "PRD", "after_type_id": "@vision"},
+  {"op": "set_dependencies", "type_id": "@prd", "dependency_ids": ["@vision"]},
+  {"op": "set_owner_roles", "type_id": "@prd", "role_names": ["Product Manager"]}
+]
+```
+
+### Roles
+
+A *role* is a workspace project role — the owner-role pool assigned to
+deliverable types. A role's `instructions` is its LLM coaching persona. Mirrors
+the MCP `list_roles` / `write_role` tools.
+
+```bash
+expedait roles list                                       # List project roles
+expedait roles create --name "Product Manager" \          # Create (instructions: @file, -, or literal)
+  [--description "owns the roadmap"] [--instructions @pm.md]
+expedait roles update ROLE_ID --name "Lead PM"            # Update name/description/instructions
+expedait roles delete ROLE_ID                             # Delete a role
+expedait roles write --ops @ops.json                      # Batch (create_role/update_role/delete_role)
+```
+
+### Global Options
+
+```bash
+expedait --api-url https://host:8000 ...    # Override API URL
+expedait --tenant-id 2 ...                  # Override tenant
+expedait --format json ...                  # Force JSON output
+expedait --format text ...                  # Force human-readable output
+expedait --version                          # Show version
+```
+
+Output format defaults to `text` when connected to a terminal, `json` when piped.
+
+> **Migration note:** the `pages` command group has been renamed to
+> `deliverables`. `expedait pages …` still works for one release (it warns and
+> forwards) but will be removed.
+
+## Agent Skills
+
+For step-by-step guides on using the CLI from AI coding agents, see [expedait-skills](https://github.com/Expedait/expedait-skills).
+
+## Development
+
+```bash
+git clone https://github.com/Expedait/expedait-cli.git
+cd expedait-cli
+uv sync --group dev
+uv run python -m pytest
+```
+
+## License
+
+[Apache License 2.0](LICENSE)