@mytegroupinc/myte-core 0.0.54 → 0.0.55

package/README.md

@@ -9,49 +9,49 @@ Most users should install the public wrapper instead:
 
 This package exists so the public wrapper can stay small and versioned cleanly. It is not the recommended public install target.
 
-## Requirements
-
-- Node `18.17+`
+## Requirements
+
+- Node `18.17+`
 - `MYTE_API_KEY` for project-scoped commands
 - `MYTEAI_API_KEY` for `myte ai`
 - `MYTEAI_API_KEY` for `mytecody`
 - `git` only when using `query --with-diff`
-- The CLI uses Node built-ins for env loading, argument parsing, direct HTTP,
-  and local serialization. `undici` supplies portable
-  `HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY` support across the supported Node
-  versions.
-
-## Behavior Summary
-
-- `myte doctor --json` performs read-only package, credential-presence, DNS,
-  TCP/TLS, authenticated config, proxy, and workspace checks without exposing
-  keys, proxy values, request bodies, or response bodies.
-- `myte info` and `myte --version --verbose` show the wrapper/core topology,
-  runtime dependencies, expected npm graph size, and version compatibility.
-- Network diagnostics preserve nested transport causes and distinguish DNS,
-  TCP, TLS/certificate, timeout, captive portal/non-JSON, authentication,
-  authorization, rate-limit, and server failures.
-- Safe transient reads and query polling use bounded retries. Query creation
-  reuses one idempotency key across ambiguous retries.
-- Snapshot-style commands such as `bootstrap`, `sync-qaqc`, `feedback-sync`, and `suggestions sync` write local `MyteCommandCenter` data.
-- `feedback-sync` prefers stable ObjectId cursor pagination so concurrent
-  inserts cannot shift later pages. It remains compatible with older
-  offset-only API versions and rejects duplicate cross-page records instead of
-  committing an ambiguous local snapshot.
-- `feedback-sync` keeps stable comment IDs and nests every comment attachment
-  under its originating comment. Readable text, Markdown, and DOCX attachment
-  context is materialized under
-  `MyteCommandCenter/feedback-sync/comment-attachments`; binary formats remain
-  visible as metadata-only context. Raw S3/object-storage URLs are not written
-  into local sync artifacts.
-- `feedback status|edit|document-add|assign|archive|refine` writes reviewable local YAML artifacts.
-- `feedback submit|revise|comment` are live writes that require `--confirm-write --approval-artifact <path>`.
-- `feedback review|move|undo|apply` are governed writes with backend permission checks but no approval artifact flags.
-- `feedback-sync|get|history|reviews|prd-versions|prd-diff|validate` are read/sync/validation commands with no approval artifact flags.
+- The CLI uses Node built-ins for env loading, argument parsing, direct HTTP,
+  and local serialization. `undici` supplies portable
+  `HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY` support across the supported Node
+  versions.
+
+## Behavior Summary
+
+- `myte doctor --json` performs read-only package, credential-presence, DNS,
+  TCP/TLS, authenticated config, proxy, and workspace checks without exposing
+  keys, proxy values, request bodies, or response bodies.
+- `myte info` and `myte --version --verbose` show the wrapper/core topology,
+  runtime dependencies, expected npm graph size, and version compatibility.
+- Network diagnostics preserve nested transport causes and distinguish DNS,
+  TCP, TLS/certificate, timeout, captive portal/non-JSON, authentication,
+  authorization, rate-limit, and server failures.
+- Safe transient reads and query polling use bounded retries. Query creation
+  reuses one idempotency key across ambiguous retries.
+- Snapshot-style commands such as `bootstrap`, `sync-qaqc`, `feedback-sync`, and `suggestions sync` write local `MyteCommandCenter` data.
+- `feedback-sync` prefers stable ObjectId cursor pagination so concurrent
+  inserts cannot shift later pages. It remains compatible with older
+  offset-only API versions and rejects duplicate cross-page records instead of
+  committing an ambiguous local snapshot.
+- `feedback-sync` keeps stable comment IDs and nests every comment attachment
+  under its originating comment. Readable text, Markdown, and DOCX attachment
+  context is materialized under
+  `MyteCommandCenter/feedback-sync/comment-attachments`; binary formats remain
+  visible as metadata-only context. Raw S3/object-storage URLs are not written
+  into local sync artifacts.
+- `feedback status|edit|document-add|assign|archive|refine` writes reviewable local YAML artifacts.
+- `feedback submit|revise|comment` are live writes that require `--confirm-write --approval-artifact <path>`.
+- `feedback review|move|undo|apply` are governed writes with backend permission checks but no approval artifact flags.
+- `feedback-sync|get|history|reviews|prd-versions|prd-diff|validate` are read/sync/validation commands with no approval artifact flags.
 - `feedback move|comment|undo|prd-versions|prd-diff|history` calls the project-key Feedback API while leaving lifecycle rules and permissions server-side. `feedback move --feedback-ids` sends one batch move request.
 - `feedback validate|apply` remains available for validation and owner-direct apply paths; live authorization, stale checks, and history stay server-side.
-- `query --with-diff` requires project repos to be configured for diff collection and fails fast when no matching local project repo can be resolved.
-- `query --json` returns the stable request ID, query job ID, answer, context-block count payload, and telemetry without echoing the query text.
+- `query --with-diff` requires project repos to be configured for diff collection and fails fast when no matching local project repo can be resolved.
+- `query --json` returns the stable request ID, query job ID, answer, context-block count payload, and telemetry without echoing the query text.
 - Public package documentation is intentionally minimal. Internal rollout and design notes are not part of the npm package contract.
 - `mytecody` is a model-agnostic MyteCody team launcher. It supports `doctor`,
   `doctor --probe-gateway`, `update --dry-run`, and `update`. On first coding
@@ -61,42 +61,42 @@ This package exists so the public wrapper can stay small and versioned cleanly.
   gateway, and `MYTEAI_API_KEY`. Normal coding runs use the branded Codex
   harness with Myte context hardening; the experimental controller is not the
   default product path.
-- `mytecody doctor` reports both the signed MyteCody engine state and this npm
-  package version. `mytecody update` updates the engine only. Use
-  `npm install -g myte@latest` to update the launcher and the Myte API CLI
-  commands shipped by npm.
-
-## Live Write Approval
-
-Only selected project-key writes require a server-validated approval envelope. The CLI adds `write_approval` metadata only for those commands after the caller supplies `--confirm-write --approval-artifact <path>`.
-
-| Category | Commands | Artifact |
-| --- | --- | --- |
-| Required | `create-prd`, `update-team`, `update-owner`, `update-client`, `feedback submit`, `feedback revise`, `feedback comment`, `suggestions create`, `suggestions revise` | Yes |
-| Not required | `run-qaqc`, `mission status`, `mission archive`, `suggestions review`, `feedback review`, `feedback move`, `feedback undo`, `feedback apply` | No |
-| Never required | `config`, `query`, `bootstrap`, `sync-qaqc`, `feedback-sync`, `suggestions sync`, `feedback get/history/reviews/prd-versions/prd-diff/validate`, local feedback draft commands | No |
-
-- The approval artifact must be a local `.md`, `.markdown`, `.yml`, `.yaml`, or `.json` file shown to and approved by the user.
-- The artifact must list the exact operation, proposed change, and every target id or PRD item.
-- Batch artifacts for required actions must enumerate every item and the CLI sends the matching batch count to the API.
-- For required actions, the API validates the payload hash after stripping transport metadata, so direct HTTP writes with only the API key do not bypass approval.
-- For actions marked `Not required`, the backend still enforces project-key authentication, idempotency, owner/delegate capability rules, stale-state guards, validation, rate limits, and audit history.
-- In plain language, the artifact is the human-reviewed record of the exact write the agent is about to send. It is not a permission grant and it does not bypass project owner/delegate checks, idempotency, stale-state guards, validation, or audit.
-- Minimum artifact contents are the exact command, every target id or PRD item, a complete proposed-change summary, a reason, and `batch_count` when one command sends multiple items.
-- Mission edit/create batches use `suggestions create` or `suggestions revise`; list every item, including `change_type`, `mission_id` for updates, proposed title/description for creates, and `suggestion_id` plus expected revision for revisions.
-- Without `--document-set`, `create-prd fileA.md fileB.md ...` creates
-  independent Feedback items as before. With `--document-set`, one to three
-  Markdown files of at most 250,000 characters each create one parent Feedback
-  with ordered PRD documents. List every file/title/client ref and the matching
-  count in the approval artifact.
-- Feedback submit/revise/comment artifacts are usually the same YAML or markdown file being submitted. For inline text or stdin, use a separate approval memo with the feedback id or request id and exact content.
-- `feedback document-add --feedback-id <id> --prd-file ./document.md` creates a governed proposal to append one linked PRD document to the existing Feedback context. The addition is not live until the normal `feedback submit` -> owner/delegate `feedback review` flow applies it.
-- Governed document additions preserve existing document IDs, append a new stable document, create a new immutable PRD version, and emit `feedback_prd_document_added` so the Feedback context bubble/notification feed can link users back to the updated PRD context. Existing PRD sets may grow to twelve documents; new `create-prd --document-set` uploads remain capped at three.
-- Team, owner, and client update artifacts should name the audience and include the exact message body or a complete summary. Client updates should include target contact ids when used.
-- `feedback review --request-ids`, `feedback move --feedback-ids`, `mission status --mission-ids`, `mission archive --mission-ids`, and `run-qaqc --mission-ids` are batched governed writes, but they are marked `Not required` and should not receive approval artifact flags.
-- The package does not bundle the large MyteCody engine binary or the async
-  Responses bridge implementation. See `THIRD_PARTY_NOTICES.md` and
-  `TRADEMARKS.md` for Codex lineage and Myte brand notices.
+- `mytecody doctor` reports both the signed MyteCody engine state and this npm
+  package version. `mytecody update` updates the engine only. Use
+  `npm install -g myte@latest` to update the launcher and the Myte API CLI
+  commands shipped by npm.
+
+## Live Write Approval
+
+Only selected project-key writes require a server-validated approval envelope. The CLI adds `write_approval` metadata only for those commands after the caller supplies `--confirm-write --approval-artifact <path>`.
+
+| Category | Commands | Artifact |
+| --- | --- | --- |
+| Required | `create-prd`, `update-team`, `update-owner`, `update-client`, `feedback submit`, `feedback revise`, `feedback comment`, `suggestions create`, `suggestions revise` | Yes |
+| Not required | `run-qaqc`, `mission status`, `mission archive`, `suggestions review`, `feedback review`, `feedback move`, `feedback undo`, `feedback apply` | No |
+| Never required | `config`, `query`, `bootstrap`, `sync-qaqc`, `feedback-sync`, `suggestions sync`, `feedback get/history/reviews/prd-versions/prd-diff/validate`, local feedback draft commands | No |
+
+- The approval artifact must be a local `.md`, `.markdown`, `.yml`, `.yaml`, or `.json` file shown to and approved by the user.
+- The artifact must list the exact operation, proposed change, and every target id or PRD item.
+- Batch artifacts for required actions must enumerate every item and the CLI sends the matching batch count to the API.
+- For required actions, the API validates the payload hash after stripping transport metadata, so direct HTTP writes with only the API key do not bypass approval.
+- For actions marked `Not required`, the backend still enforces project-key authentication, idempotency, owner/delegate capability rules, stale-state guards, validation, rate limits, and audit history.
+- In plain language, the artifact is the human-reviewed record of the exact write the agent is about to send. It is not a permission grant and it does not bypass project owner/delegate checks, idempotency, stale-state guards, validation, or audit.
+- Minimum artifact contents are the exact command, every target id or PRD item, a complete proposed-change summary, a reason, and `batch_count` when one command sends multiple items.
+- Mission edit/create batches use `suggestions create` or `suggestions revise`; list every item, including `change_type`, `mission_id` for updates, proposed title/description for creates, and `suggestion_id` plus expected revision for revisions.
+- Without `--document-set`, `create-prd fileA.md fileB.md ...` creates
+  independent Feedback items as before. With `--document-set`, one to three
+  Markdown files of at most 250,000 characters each create one parent Feedback
+  with ordered PRD documents. List every file/title/client ref and the matching
+  count in the approval artifact.
+- Feedback submit/revise/comment artifacts are usually the same YAML or markdown file being submitted. For inline text or stdin, use a separate approval memo with the feedback id or request id and exact content.
+- `feedback document-add --feedback-id <id> --prd-file ./document.md` creates a governed proposal to append one linked PRD document to the existing Feedback context. The addition is not live until the normal `feedback submit` -> owner/delegate `feedback review` flow applies it.
+- Governed document additions preserve existing document IDs, append a new stable document, create a new immutable PRD version, and emit `feedback_prd_document_added` so the Feedback context bubble/notification feed can link users back to the updated PRD context. Existing PRD sets may grow to twelve documents; new `create-prd --document-set` uploads remain capped at three.
+- Team, owner, and client update artifacts should name the audience and include the exact message body or a complete summary. Client updates should include target contact ids when used.
+- `feedback review --request-ids`, `feedback move --feedback-ids`, `mission status --mission-ids`, `mission archive --mission-ids`, and `run-qaqc --mission-ids` are batched governed writes, but they are marked `Not required` and should not receive approval artifact flags.
+- The package does not bundle the large MyteCody engine binary or the async
+  Responses bridge implementation. See `THIRD_PARTY_NOTICES.md` and
+  `TRADEMARKS.md` for Codex lineage and Myte brand notices.
 
 ## Agent Usage Contract
 
@@ -104,24 +104,24 @@ Coding agents should treat `MYTE_API_KEY` as a project-scoped Project Assistant
 
 - Load it from the workspace `.env` or environment. `MYTE_PROJECT_API_KEY` is accepted as a compatibility fallback.
 - Call `myte config --json` first when project identity or local repo detection is uncertain.
-- Hydrate mission context with `bootstrap` first instead of scraping the web UI. `bootstrap` writes mission cards, mission suggestion thread state, and `MyteCommandCenter/AgentsMyteAPI.md`.
+- Hydrate mission context with `bootstrap` first instead of scraping the web UI. `bootstrap` writes mission cards, mission suggestion thread state, and `MyteCommandCenter/AgentsMyteAPI.md`.
 - Use `suggestions sync` only when you need to refresh mission review-thread state without refreshing the full board.
 - Use `query --with-diff` for project-scoped code review, planning, and implementation questions.
-- Use `create-prd` only with reviewed markdown files and `--confirm-write --approval-artifact <path>`. The markdown file body is the PRD document; `description` is only the short board/card summary.
-- New PRDs are unassigned by default. Add `--assigned-user-id <id>` or `--assigned-user-email <exact-email>` to validate and assign an eligible project user in the same create request.
-- Use `create-prd --document-set` only when the explicit intent is one parent
-  Feedback with one to three ordered documents; omitting it preserves
-  independent multi-file creation.
-- Use `feedback status|edit|assign|archive|refine` for reviewable local artifacts. `feedback submit` and `feedback revise` require an approval artifact; `feedback review` does not because the backend owner/delegate decision is the approval control.
+- Use `create-prd` only with reviewed markdown files and `--confirm-write --approval-artifact <path>`. The markdown file body is the PRD document; `description` is only the short board/card summary.
+- New PRDs are unassigned by default. Add `--assigned-user-id <id>` or `--assigned-user-email <exact-email>` to validate and assign an eligible project user in the same create request.
+- Use `create-prd --document-set` only when the explicit intent is one parent
+  Feedback with one to three ordered documents; omitting it preserves
+  independent multi-file creation.
+- Use `feedback status|edit|assign|archive|refine` for reviewable local artifacts. `feedback submit` and `feedback revise` require an approval artifact; `feedback review` does not because the backend owner/delegate decision is the approval control.
 - Use `feedback review --request-ids` for batch owner/delegate decisions; it sends one grouped backend batch, not one request per item.
-- Use `suggestions create` for both existing-mission edits and new-mission proposals, with `--confirm-write --approval-artifact <path>`. The only valid `change_type` values are `update` and `create`.
-- Use `suggestions revise` only against an existing `suggestion_id`, with `--confirm-write --approval-artifact <path>`; do not send `change_type` on revisions because the backend keeps the thread's original type.
-- Use `suggestions review` for owner/elevated mission-review decisions: `approve`, `request_changes`, or `reject`. No approval artifact is required for review decisions.
+- Use `suggestions create` for both existing-mission edits and new-mission proposals, with `--confirm-write --approval-artifact <path>`. The only valid `change_type` values are `update` and `create`.
+- Use `suggestions revise` only against an existing `suggestion_id`, with `--confirm-write --approval-artifact <path>`; do not send `change_type` on revisions because the backend keeps the thread's original type.
+- Use `suggestions review` for owner/elevated mission-review decisions: `approve`, `request_changes`, or `reject`. No approval artifact is required for review decisions.
 - Use `mission archive` for project-key lifecycle archival. Do not send `Archived` through `mission status`; restore archived missions from the web archived-board view.
 - Use `feedback move` only when a direct audited state move is intended and include a concrete `--reason`. Use `--feedback-ids` for batch active-state moves or authorized batch archive.
-- Use `feedback comment --feedback-id <id> --body-file ./comment.md --confirm-write --approval-artifact ./comment.md` for text-only feedback-specific implementation notes. Attachments remain web UI only for this project-key endpoint.
+- Use `feedback comment --feedback-id <id> --body-file ./comment.md --confirm-write --approval-artifact ./comment.md` for text-only feedback-specific implementation notes. Attachments remain web UI only for this project-key endpoint.
 - Do not use the project-key API/CLI to unarchive Feedback. Normal `feedback-sync` excludes archived Feedback; unarchive from the web archived Feedback view.
-- Use `update-team --confirm-write --approval-artifact <path>` when an agent needs to leave a project-level implementation note or verification comment.
+- Use `update-team --confirm-write --approval-artifact <path>` when an agent needs to leave a project-level implementation note or verification comment.
 
 Do not use `MYTE_API_KEY` against account/JWT web endpoints. The direct project-key surface is `/api/project-assistant/*`.
 
@@ -136,46 +136,46 @@ PRD document contract:
 - The UI renders the PRD from stored PRD text/document content, not from `description`.
 - Renderer-friendly PRDs should use one `# Title`, `##` sections, concise paragraphs, bullets, GitHub tables/checklists where useful, and fenced code blocks only for real code/config.
 - Do not wrap the whole PRD in a ` ```markdown ` fence. Do not use raw HTML, inline style blocks, or decorative banners.
-- PRD identity is explicit: `myte create-prd` creates a PRD asset with PRD metadata. Generic uploaded `.md`, `.docx`, `.pdf`, and `.txt` files remain normal attachments unless explicitly created as PRDs.
-- Document sets retain exact source Markdown plus canonical rendering
-  Markdown, stable document IDs, per-document hashes, and independent
-  download/read targets.
-
-## Project Assistant Connectivity
-
-`myte doctor --json` should be the first diagnostic when a command reports
-`fetch failed`. A DNS or TCP result means the request did not reach HTTP. A
-TLS reset means the secure connection was interrupted before Myte could
-receive the API key. Authentication and authorization are reported only when
-the API actually returns those responses.
-
-The CLI honors `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`. It does not log
-their values and does not disable TLS verification. Captive portals and
-intercepting gateways are reported as non-JSON/HTML transport failures rather
-than as malformed Myte API responses.
-
-Feedback comment support:
-
-- `feedback-sync` includes existing feedback comments with `comment_id`,
-  sender, content, timestamps, and attachments nested under the originating
-  comment.
-- Readable text, Markdown, and DOCX comment attachments are extracted by the
-  backend under attachment safety limits and written to
-  `MyteCommandCenter/feedback-sync/comment-attachments/<feedback>/<comment>/`.
-  The local YAML points to the file. Unsupported binary formats remain listed
-  with `context_status: metadata_only`. Extraction is capped at 20 readable
-  comment attachments per API page by default; additional readable files stay
-  linked to their comments with `context_status: deferred`. Use
-  `--comment-attachment-limit <0-100>` to change that bounded limit.
-- `--no-with-prd-text` disables readable PRD and comment-attachment extraction
-  while retaining comment and attachment metadata.
-- Feedback-specific comment creation exists in the web backend at `/api/feedbacks/<feedback_id>/comments`, protected by JWT/project assignment.
-- Project-key comment creation is available through `myte feedback comment --feedback-id <id> --body "..." --confirm-write --approval-artifact ./comment.md` or `--body-file ./comment.md --confirm-write --approval-artifact ./comment.md`.
-- The project-key feedback comment endpoint is text-only in this slice and caps content at 500,000 characters. Use the web UI when comment attachments are required.
-- `feedback apply --force` is an owner/elevated emergency override for a stale
-  local artifact. It requires the artifact to contain a non-empty reason and
-  returns the persisted force/warning audit context; normal edits should use
-  submit followed by owner/elevated review.
+- PRD identity is explicit: `myte create-prd` creates a PRD asset with PRD metadata. Generic uploaded `.md`, `.docx`, `.pdf`, and `.txt` files remain normal attachments unless explicitly created as PRDs.
+- Document sets retain exact source Markdown plus canonical rendering
+  Markdown, stable document IDs, per-document hashes, and independent
+  download/read targets.
+
+## Project Assistant Connectivity
+
+`myte doctor --json` should be the first diagnostic when a command reports
+`fetch failed`. A DNS or TCP result means the request did not reach HTTP. A
+TLS reset means the secure connection was interrupted before Myte could
+receive the API key. Authentication and authorization are reported only when
+the API actually returns those responses.
+
+The CLI honors `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`. It does not log
+their values and does not disable TLS verification. Captive portals and
+intercepting gateways are reported as non-JSON/HTML transport failures rather
+than as malformed Myte API responses.
+
+Feedback comment support:
+
+- `feedback-sync` includes existing feedback comments with `comment_id`,
+  sender, content, timestamps, and attachments nested under the originating
+  comment.
+- Readable text, Markdown, and DOCX comment attachments are extracted by the
+  backend under attachment safety limits and written to
+  `MyteCommandCenter/feedback-sync/comment-attachments/<feedback>/<comment>/`.
+  The local YAML points to the file. Unsupported binary formats remain listed
+  with `context_status: metadata_only`. Extraction is capped at 20 readable
+  comment attachments per API page by default; additional readable files stay
+  linked to their comments with `context_status: deferred`. Use
+  `--comment-attachment-limit <0-100>` to change that bounded limit.
+- `--no-with-prd-text` disables readable PRD and comment-attachment extraction
+  while retaining comment and attachment metadata.
+- Feedback-specific comment creation exists in the web backend at `/api/feedbacks/<feedback_id>/comments`, protected by JWT/project assignment.
+- Project-key comment creation is available through `myte feedback comment --feedback-id <id> --body "..." --confirm-write --approval-artifact ./comment.md` or `--body-file ./comment.md --confirm-write --approval-artifact ./comment.md`.
+- The project-key feedback comment endpoint is text-only in this slice and caps content at 500,000 characters. Use the web UI when comment attachments are required.
+- `feedback apply --force` is an owner/elevated emergency override for a stale
+  local artifact. It requires the artifact to contain a non-empty reason and
+  returns the persisted force/warning audit context; normal edits should use
+  submit followed by owner/elevated review.
 
 ## Mission Action Map
 
@@ -183,12 +183,12 @@ Feedback comment support:
 | --- | --- | --- |
 | Sync mission cards and review threads | `myte bootstrap --json` | Refreshes `MyteCommandCenter/data/missions/*.yml`, project structure, and `MyteCommandCenter/data/mission-ops.yml`. |
 | Sync only mission review threads | `myte suggestions sync --json` | Refreshes `MyteCommandCenter/data/mission-ops.yml` while preserving local workspace drafts. |
-| Suggest edit to existing mission | `myte suggestions create --file ./create.yml --confirm-write --approval-artifact ./create.yml` with `change_type: update` and `mission_id` | Creates or appends to an active review thread; live mission is unchanged until approval. |
-| Suggest new mission | `myte suggestions create --file ./create.yml --confirm-write --approval-artifact ./create.yml` with `change_type: create` | Requires `change_set.title` and `change_set.description`; creates a review thread only; the mission card is created only after approval. |
-| Revise a suggestion | `myte suggestions revise --file ./revise.yml --confirm-write --approval-artifact ./revise.yml` with `suggestion_id` | Adds another revision to the same thread. Do not include `change_type`. |
-| Review a suggestion | `myte suggestions review` with `review_action: approve|request_changes|reject` | Project Owner or elevated mission-review delegate required; no approval artifact required. Approval mutates/creates the mission once; reject archives the thread only; request_changes keeps it actionable. |
-| Update mission status | `myte mission status --mission-ids "M001" --status todo|in_progress|done` | Project-key surface updates canonical mission status for active cards; no approval artifact required; refreshes local bootstrap + mission-ops by default. |
-| Archive mission | `myte mission archive --mission-ids "M001[,M002]" --reason "..."` | Project Owner or elevated delegate required; no approval artifact required. Sets `Archived`, removes cards from normal bootstrap/board state, writes mission activity, and refreshes local bootstrap + mission-ops by default. |
+| Suggest edit to existing mission | `myte suggestions create --file ./create.yml --confirm-write --approval-artifact ./create.yml` with `change_type: update` and `mission_id` | Creates or appends to an active review thread; live mission is unchanged until approval. |
+| Suggest new mission | `myte suggestions create --file ./create.yml --confirm-write --approval-artifact ./create.yml` with `change_type: create` | Requires `change_set.title` and `change_set.description`; creates a review thread only; the mission card is created only after approval. |
+| Revise a suggestion | `myte suggestions revise --file ./revise.yml --confirm-write --approval-artifact ./revise.yml` with `suggestion_id` | Adds another revision to the same thread. Do not include `change_type`. |
+| Review a suggestion | `myte suggestions review` with `review_action: approve|request_changes|reject` | Project Owner or elevated mission-review delegate required; no approval artifact required. Approval mutates/creates the mission once; reject archives the thread only; request_changes keeps it actionable. |
+| Update mission status | `myte mission status --mission-ids "M001" --status todo|in_progress|done` | Project-key surface updates canonical mission status for active cards; no approval artifact required; refreshes local bootstrap + mission-ops by default. |
+| Archive mission | `myte mission archive --mission-ids "M001[,M002]" --reason "..."` | Project Owner or elevated delegate required; no approval artifact required. Sets `Archived`, removes cards from normal bootstrap/board state, writes mission activity, and refreshes local bootstrap + mission-ops by default. |
 
 Create payloads:
 
@@ -251,69 +251,69 @@ Agent rule: never guess `suggestion_id`. If `mission-ops.yml` is missing or stal
 | `feedback-sync` | Pulls non-archived feedback metadata, comments, and PRD context into `MyteCommandCenter`. | Read-only project-key API call; archived Feedback is intentionally excluded. |
 | `feedback get` | Reads one feedback item's current server snapshot and `snapshot_hash`. | Read-only; backend checks project access. |
 | `feedback status` | Creates a local YAML proposal to change canonical lifecycle state. | No live mutation until `submit` and owner/delegate review, except owner-direct `apply`. |
-| `feedback edit` / `feedback refine` | Creates a local YAML proposal for title, description/body, priority, due date, tags, or notes. | Content changes go through owner-review membrane. |
-| `feedback document-add` | Creates a local YAML proposal to append one linked Markdown PRD document to an existing Feedback item. | Owner-only field; normal submit/review/apply flow, stale protection, idempotency, version history, and notification apply. |
+| `feedback edit` / `feedback refine` | Creates a local YAML proposal for title, description/body, priority, due date, tags, or notes. | Content changes go through owner-review membrane. |
+| `feedback document-add` | Creates a local YAML proposal to append one linked Markdown PRD document to an existing Feedback item. | Owner-only field; normal submit/review/apply flow, stale protection, idempotency, version history, and notification apply. |
 | `feedback assign` | Creates a local YAML proposal to change assignee. | Goes through review unless applied through owner-direct path. |
 | `feedback archive` | Creates a local YAML proposal to archive. | Archive is governed by backend owner/delegate capability. |
-| `feedback submit` | Sends a local proposal artifact to the backend as a review request. | Requires `--confirm-write --approval-artifact <path>`; does not mutate live feedback before approval. |
-| `feedback revise` | Resubmits the original submitter's request after `request_changes`. | Requires `--confirm-write --approval-artifact <path>`; only valid for the original submitter and `needs_changes` requests. |
+| `feedback submit` | Sends a local proposal artifact to the backend as a review request. | Requires `--confirm-write --approval-artifact <path>`; does not mutate live feedback before approval. |
+| `feedback revise` | Resubmits the original submitter's request after `request_changes`. | Requires `--confirm-write --approval-artifact <path>`; only valid for the original submitter and `needs_changes` requests. |
 | `feedback reviews` | Lists review requests or fetches one request by `--request-id`. | Read-only; response includes backend permissions. |
-| `feedback review` | Approves, rejects, requests changes, or cancels one review request, or a batch with `--request-ids`. | No approval artifact required; backend restricts approval/review decisions to Project Owner or elevated delegate for Feedback scope; batch review uses one grouped notification path. |
-| `feedback move` | Moves a card or batch of cards across allowed board states directly with an audit event. | No approval artifact required. `--feedback-ids` sends one batch request. Blocked with `pending_feedback_review` while an active linked review request exists; governed states such as archive/reject/deploy/freeze remain backend-authorized. Project-key unarchive is not supported. |
-| `feedback comment` | Creates a text-only comment on one Feedback item. | Requires `--confirm-write --approval-artifact <path>`; backend checks project-key access, owner/assigned permission, idempotency, and the 500,000-character content cap. Attachments remain web UI only. |
-| `feedback undo` | Reverses an audited board event when there is no conflict. | No approval artifact required; backend validates event ownership/project scope and conflict state. |
+| `feedback review` | Approves, rejects, requests changes, or cancels one review request, or a batch with `--request-ids`. | No approval artifact required; backend restricts approval/review decisions to Project Owner or elevated delegate for Feedback scope; batch review uses one grouped notification path. |
+| `feedback move` | Moves a card or batch of cards across allowed board states directly with an audit event. | No approval artifact required. `--feedback-ids` sends one batch request. Blocked with `pending_feedback_review` while an active linked review request exists; governed states such as archive/reject/deploy/freeze remain backend-authorized. Project-key unarchive is not supported. |
+| `feedback comment` | Creates a text-only comment on one Feedback item. | Requires `--confirm-write --approval-artifact <path>`; backend checks project-key access, owner/assigned permission, idempotency, and the 500,000-character content cap. Attachments remain web UI only. |
+| `feedback undo` | Reverses an audited board event when there is no conflict. | No approval artifact required; backend validates event ownership/project scope and conflict state. |
 | `feedback prd-versions` | Lists retained PRD baselines/revisions for a feedback item. | Read-only; old S3 objects are retained by reference. |
 | `feedback prd-diff` | Fetches backend-generated text diff for PRD versions. | Read-only; backend controls version access. |
 | `feedback history` | Lists audited feedback board/refinement events. | Read-only; backend checks project access. |
 | `feedback validate` | Sends an artifact to backend validation without mutation. | Useful before submit or owner-direct apply. |
-| `feedback apply` | Applies an artifact through the owner-direct/emergency path. | No approval artifact required; not the normal collaborator flow; normal flow is `submit` -> `review`. |
-
-Canonical feedback lifecycle states are `frozen`, `todo`, `in_progress`, `in_review`, `completed`, `deployed`, `rejected`, and `archived`.
-
-### Feedback Permission Matrix
-
-| Project role | Feedback permissions |
-| --- | --- |
-| Project Owner | Full Feedback lifecycle: view/sync/comment, draft/validate/submit, direct apply, approve/request changes/reject/cancel reviews, assignment, governed board states, archive, version history, and diffs. |
-| Elevated collaborator (`owner_delegate`) | Same operational Feedback authority as the Project Owner, including direct apply, approval, assignment, governed board states, and archive. Project-level privilege grant/revoke and unrelated destructive infrastructure operations remain real-owner controls. |
-| Builder collaborator | View/sync/comment, create and validate local edits, submit/revise/cancel their review requests, self-assign, and move active work through `todo`, `in_progress`, `in_review`, and `completed`. Cannot approve, directly apply, unassign others, archive, reject, freeze, or deploy Feedback. |
-| Client collaborator | View/sync and participate in Feedback discussion. Does not receive builder edit, submit, assignment, or board-operation capabilities. |
-| Organisation owner not assigned to the project | View access only; no project Feedback mutation authority. |
-
-Stale local artifacts fail validation/apply with `snapshot_mismatch`. Re-sync,
-review the newer server state, and create a fresh artifact; `force` is not part
-of the normal collaborator workflow.
+| `feedback apply` | Applies an artifact through the owner-direct/emergency path. | No approval artifact required; not the normal collaborator flow; normal flow is `submit` -> `review`. |
 
-Reusable live smoke harness after deploy:
-
-```bash
-node ./scripts/feedback-live-full-harness.js --confirm-live --base-url https://api.myte.dev/api
-```
-
-For strict owner/elevated/builder permission certification, set distinct
-`MYTE_OWNER_API_KEY`, `MYTE_DELEGATE_API_KEY`, and
-`MYTE_COLLABORATOR_API_KEY` values scoped to the same test project and add
-`--require-role-matrix`. To certify a real web-created comment attachment,
-provide an ephemeral `MYTE_WEB_ACCESS_TOKEN` for an assigned test user and add
-`--require-comment-attachment-sync`.
-
-The harness creates five disposable `TEST` feedback items plus one
-three-document Feedback item. It verifies comment sync, optional comment
-attachment materialization, stale-artifact rejection and fresh re-sync,
-request-changes/revise, owner and elevated approvals, regular collaborator
-denials, batch review and board movement, per-document refinement/version diff,
-exact-ID archival, archived sync exclusion, and project-key unarchive denial.
-
-## Direct Project API Surface
-
-All routes use `Authorization: Bearer <MYTE_API_KEY>`. The CLI adds idempotency and client-session headers on mutation routes.
-
-`myte ai` is separate from this project-scoped surface. It uses `MYTEAI_API_KEY` and calls `POST https://api.myte.ai/v1/chat/completions`, or `${MYTEAI_API_BASE}/v1/chat/completions` when that base is configured.
-
-Read/sync routes:
-
-- `GET /api/project-assistant/query/<job_id>`
-- `GET /api/project-assistant/config`
+Canonical feedback lifecycle states are `frozen`, `todo`, `in_progress`, `in_review`, `completed`, `deployed`, `rejected`, and `archived`.
+
+### Feedback Permission Matrix
+
+| Project role | Feedback permissions |
+| --- | --- |
+| Project Owner | Full Feedback lifecycle: view/sync/comment, draft/validate/submit, direct apply, approve/request changes/reject/cancel reviews, assignment, governed board states, archive, version history, and diffs. |
+| Elevated collaborator (`owner_delegate`) | Same operational Feedback authority as the Project Owner, including direct apply, approval, assignment, governed board states, and archive. Project-level privilege grant/revoke and unrelated destructive infrastructure operations remain real-owner controls. |
+| Builder collaborator | View/sync/comment, create and validate local edits, submit/revise/cancel their review requests, self-assign, and move active work through `todo`, `in_progress`, `in_review`, and `completed`. Cannot approve, directly apply, unassign others, archive, reject, freeze, or deploy Feedback. |
+| Client collaborator | View/sync and participate in Feedback discussion. Does not receive builder edit, submit, assignment, or board-operation capabilities. |
+| Organisation owner not assigned to the project | View access only; no project Feedback mutation authority. |
+
+Stale local artifacts fail validation/apply with `snapshot_mismatch`. Re-sync,
+review the newer server state, and create a fresh artifact; `force` is not part
+of the normal collaborator workflow.
+
+Reusable live smoke harness after deploy:
+
+```bash
+node ./scripts/feedback-live-full-harness.js --confirm-live --base-url https://api.myte.dev/api
+```
+
+For strict owner/elevated/builder permission certification, set distinct
+`MYTE_OWNER_API_KEY`, `MYTE_DELEGATE_API_KEY`, and
+`MYTE_COLLABORATOR_API_KEY` values scoped to the same test project and add
+`--require-role-matrix`. To certify a real web-created comment attachment,
+provide an ephemeral `MYTE_WEB_ACCESS_TOKEN` for an assigned test user and add
+`--require-comment-attachment-sync`.
+
+The harness creates five disposable `TEST` feedback items plus one
+three-document Feedback item. It verifies comment sync, optional comment
+attachment materialization, stale-artifact rejection and fresh re-sync,
+request-changes/revise, owner and elevated approvals, regular collaborator
+denials, batch review and board movement, per-document refinement/version diff,
+exact-ID archival, archived sync exclusion, and project-key unarchive denial.
+
+## Direct Project API Surface
+
+All routes use `Authorization: Bearer <MYTE_API_KEY>`. The CLI adds idempotency and client-session headers on mutation routes.
+
+`myte ai` is separate from this project-scoped surface. It uses `MYTEAI_API_KEY` and calls `POST https://api.myte.ai/v1/chat/completions`, or `${MYTEAI_API_BASE}/v1/chat/completions` when that base is configured.
+
+Read/sync routes:
+
+- `GET /api/project-assistant/query/<job_id>`
+- `GET /api/project-assistant/config`
 - `GET /api/project-assistant/bootstrap`
 - `GET /api/project-assistant/qaqc-sync`
 - `GET /api/project-assistant/feedback-sync`
@@ -325,7 +325,7 @@ Read/sync routes:
 - `GET /api/project-assistant/feedback/<feedback_id>/prd/versions`
 - `GET /api/project-assistant/feedback/<feedback_id>/prd/versions/<version_id>/diff`
 - `GET /api/project-assistant/suggestions`
-- `GET /api/project-assistant/run-qaqc/<batch_id>`
+- `GET /api/project-assistant/run-qaqc/<batch_id>`
 
 Mutation routes:
 
@@ -352,4 +352,14 @@ Mutation routes:
 - `POST /api/project-assistant/feedback/<feedback_id>/events/<event_id>/undo`
 - `POST /api/project-assistant/suggestions`
 - `POST /api/project-assistant/suggestions/revise`
-- `POST /api/project-assistant/suggestions/review`
+- `POST /api/project-assistant/suggestions/review`
+
+Query and QAQC status polling honors additive server timing from `Retry-After`
+and `next_poll_after_ms`, with bounded client jitter. This keeps one busy IDE
+fleet from synchronizing poll bursts. Older servers remain compatible through
+the existing bounded backoff fallback.
+
+The API keeps bounded CRUD and snapshot reads synchronous. Query and QAQC are
+durable asynchronous workflows; the CLI never assumes that every API action is
+a separate Celery task. Feedback sync pages are bounded (100 by default, 500
+maximum) and `create-prd` batch uploads are capped at 20 items by the backend.

package/THIRD_PARTY_NOTICES.md

@@ -1,21 +1,21 @@
-# Third-Party Notices
-
-This package includes the Myte CLI launcher and MyteCody distribution client.
-
-The branded MyteCody engine installed by the launcher is derived from the
-OpenAI Codex open-source project. OpenAI Codex is licensed under the
-Apache License, Version 2.0.
-
-Source lineage tracked for this slice:
-
-- Project: OpenAI Codex
-- Version baseline: `0.139.0`
-- License: Apache-2.0
-- Upstream: https://github.com/openai/codex
-
-The MyteCody engine and signed client assets are distributed separately from
-this npm package through a Myte release manifest. This package verifies release
-artifacts before installing them into the user's Myte-owned local cache.
-
-Myte names, marks, logos, terminal branding, and product design are not part of
-the OpenAI Codex project and remain Myte-owned brand assets.
+# Third-Party Notices
+
+This package includes the Myte CLI launcher and MyteCody distribution client.
+
+The branded MyteCody engine installed by the launcher is derived from the
+OpenAI Codex open-source project. OpenAI Codex is licensed under the
+Apache License, Version 2.0.
+
+Source lineage tracked for this slice:
+
+- Project: OpenAI Codex
+- Version baseline: `0.139.0`
+- License: Apache-2.0
+- Upstream: https://github.com/openai/codex
+
+The MyteCody engine and signed client assets are distributed separately from
+this npm package through a Myte release manifest. This package verifies release
+artifacts before installing them into the user's Myte-owned local cache.
+
+Myte names, marks, logos, terminal branding, and product design are not part of
+the OpenAI Codex project and remain Myte-owned brand assets.

package/TRADEMARKS.md

@@ -1,10 +1,10 @@
-# Trademarks
-
-Myte, Myte AI, MyteCody, "MYTE CODY - Your Tech Your Way", logo assets, terminal
-animation assets, and related product branding are Myte-owned marks and brand
-assets.
-
-OpenAI and Codex are trademarks or project names of their respective owners.
-MyteCody uses a Codex-derived open-source engine under the applicable open
-source license, but MyteCody is a Myte product surface and is not presented as
-an official OpenAI product.
+# Trademarks
+
+Myte, Myte AI, MyteCody, "MYTE CODY - Your Tech Your Way", logo assets, terminal
+animation assets, and related product branding are Myte-owned marks and brand
+assets.
+
+OpenAI and Codex are trademarks or project names of their respective owners.
+MyteCody uses a Codex-derived open-source engine under the applicable open
+source license, but MyteCody is a Myte product surface and is not presented as
+an official OpenAI product.