myte 0.0.46 → 0.0.47

package/README.md

@@ -46,14 +46,14 @@ The CLI searches for `.env` in the current folder and then up parent directories
 - `npx myte feedback assign --feedback-id <id> --user-id <user_id> --reason "Assign to builder"`
 - `npx myte feedback archive --feedback-id <id> --reason "Superseded"`
 - `npx myte feedback validate --file ./MyteCommandCenter/reviews/feedback/<id>-edit.yml`
-- `npx myte feedback submit --file ./MyteCommandCenter/reviews/feedback/<id>-edit.yml`
-- `npx myte feedback reviews --status open`
-- `npx myte feedback revise --request-id <id> --file ./MyteCommandCenter/reviews/feedback/<id>-edit.yml`
-- `npx myte feedback review --request-id <id> --action approve --reason "Looks correct"`
-- `npx myte feedback review --request-ids "<id1,id2>" --action approve --reason "Batch approval"`
-- `npx myte feedback move --feedback-id <id> --to-state in_progress --reason "Started"`
-- `npx myte feedback move --feedback-ids "<id1,id2>" --to-state in_progress --reason "Batch move"`
-- `npx myte feedback comment --feedback-id <id> --body-file ./updates/feedback-comment.md`
+- `npx myte feedback submit --file ./MyteCommandCenter/reviews/feedback/<id>-edit.yml --confirm-write --approval-artifact ./MyteCommandCenter/reviews/feedback/<id>-edit.yml`
+- `npx myte feedback reviews --status open`
+- `npx myte feedback revise --request-id <id> --file ./MyteCommandCenter/reviews/feedback/<id>-edit.yml --confirm-write --approval-artifact ./MyteCommandCenter/reviews/feedback/<id>-edit.yml`
+- `npx myte feedback review --request-id <id> --action approve --reason "Looks correct"`
+- `npx myte feedback review --request-ids "<id1,id2>" --action approve --reason "Batch approval"`
+- `npx myte feedback move --feedback-id <id> --to-state in_progress --reason "Started"`
+- `npx myte feedback move --feedback-ids "<id1,id2>" --to-state in_progress --reason "Batch move"`
+- `npx myte feedback comment --feedback-id <id> --body-file ./updates/feedback-comment.md --confirm-write --approval-artifact ./updates/feedback-comment.md`
 - `npx myte feedback undo --feedback-id <id> --event-id <event_id> --reason "Undo accidental move"`
 - `npx myte feedback prd-versions --feedback-id <id>`
 - `npx myte feedback prd-diff --feedback-id <id> --version-id <version_id> --compare-to <base_version_id>`
@@ -61,10 +61,10 @@ The CLI searches for `.env` in the current folder and then up parent directories
 - `npx myte suggestions sync`
 - `npx myte mission archive --mission-ids "M001" --reason "Duplicate disposable mission"`
 - `npx myte query "Summarize the current branch changes" --with-diff`
-- `npx myte create-prd ./drafts/auth-prd.md`
-- `npx myte update-team "Backend deploy completed."`
-- `npx myte update-owner --subject "QAQC progress" --body-file ./updates/owner.md`
-- `npx myte update-client --subject "Weekly client update" --body-file ./updates/week-12.md`
+- `npx myte create-prd ./drafts/auth-prd.md --confirm-write --approval-artifact ./drafts/auth-prd.md`
+- `npx myte update-team "Backend deploy completed." --confirm-write --approval-artifact ./updates/team.md`
+- `npx myte update-owner --subject "QAQC progress" --body-file ./updates/owner.md --confirm-write --approval-artifact ./updates/owner.md`
+- `npx myte update-client --subject "Weekly client update" --body-file ./updates/week-12.md --confirm-write --approval-artifact ./updates/week-12.md`
 - `npx mytecody doctor`
 - `npx mytecody doctor --probe-gateway`
 - `npx mytecody update --dry-run`
@@ -76,7 +76,10 @@ The CLI searches for `.env` in the current folder and then up parent directories
 - `bootstrap` writes mission cards and mission suggestion thread state together; agents should run it before looking for mission or suggestion ids.
 - `mission status` is active-state only (`todo`, `in_progress`, `done`). Use `mission archive` for project-key lifecycle archival; restore archived missions from the web archived-board view.
 - `mission status` and `mission archive` refresh local bootstrap + mission-ops state by default after a successful mutation. Use `--no-sync` only when you intentionally want to skip the local refresh.
-- `feedback status|edit|assign|archive` writes local review artifacts under `MyteCommandCenter/reviews/feedback`; `feedback submit|revise|reviews|review` routes proposed edits through the backend owner-review membrane.
+- `feedback status|edit|assign|archive|refine` writes local review artifacts under `MyteCommandCenter/reviews/feedback`.
+- `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 review --request-ids` sends one backend batch review request with grouped notifications; do not loop single-review calls for batch decisions.
 - `feedback move|comment|undo|prd-versions|prd-diff|history` calls the project-key Feedback API while authorization, stale snapshot checks, allowed transitions, and history remain enforced by the backend. `feedback move --feedback-ids` sends one batch board move request.
 - `feedback comment` creates text-only feedback-specific comments. Attachments remain web UI only for this project-key endpoint.
@@ -86,15 +89,42 @@ The CLI searches for `.env` in the current folder and then up parent directories
 - If diff-scoped repo configuration is missing or no local project repo can be resolved, `query --with-diff` exits with an error instead of silently dropping diff context.
 - Most markdown files are excluded from diff context by default so code and runtime configuration changes dominate the payload. Key instruction files such as `README.md` and `AGENTS.md` remain eligible.
 
-## Live Write Approval
+## Approval Artifact Requirements
 
-All live project-key writes must be approved by the user before the CLI sends them to Myte.
+Only selected project-key writes require a local approval artifact. The CLI adds `write_approval` metadata only when the command is in the required set and the caller supplies `--confirm-write --approval-artifact <path>`.
 
-- First create a local `.md`, `.yml`, `.yaml`, or `.json` approval artifact that lists the command, every target id, and the proposed change.
-- Show the artifact path and full content or concise complete summary to the user.
+| 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 |
+
+For required actions:
+
+- First create a local `.md`, `.markdown`, `.yml`, `.yaml`, or `.json` approval artifact that lists the command, every target id, and the proposed change.
+- Show the artifact path and full content or a concise complete summary to the user.
 - After explicit approval, rerun the write with `--confirm-write --approval-artifact <path>`.
-- Batch writes must enumerate every feedback id, mission id, suggestion id, request id, or PRD item in the artifact. QAQC batches are capped by the API at 10 mission ids.
-- The API also validates the approval envelope, payload hash, targets, and true batch count, so direct HTTP calls with only the API key are rejected.
+- Batch artifacts must enumerate every feedback id, suggestion id, request id, or PRD item.
+
+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. It tells the API that a human approved this payload.
+
+Minimum artifact contents:
+
+- `command`: the exact CLI command to run.
+- `targets`: every affected feedback id, request id, suggestion id, mission id, PRD file/client ref, project, or contact id.
+- `proposed_change`: a complete summary of the status, text, PRD, comment, or mission change.
+- `batch_count`: required when one command sends multiple items.
+- `reason` or `approval_note`: why the write is being sent.
+
+Batch guidance:
+
+- Mission edit/create batches use `myte suggestions create` or `myte suggestions revise`. The artifact must list each item. For edits include `change_type: update`, the existing `mission_id`, and changed fields. For new missions include `change_type: create`, title, description, and acceptance details. For revisions include each `suggestion_id` and expected revision.
+- PRD batches use one `myte create-prd fileA.md fileB.md ...`; the artifact must list each PRD file/title/client ref and `batch_count` must match the number of PRD items.
+- Feedback submit/revise/comment artifacts are usually the same YAML or markdown file being submitted. If the command uses inline text or stdin, create a separate approval memo with the feedback id or request id and exact content.
+- 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.
+
+For actions marked `Not required`, call the command directly. The backend still enforces project-key authentication, idempotency, owner/delegate capability rules, stale-state guards, validation, rate limits, and audit history.
 
 ## Agent Usage Contract
 
@@ -109,14 +139,14 @@ The key resolves the project server-side. Agents should not pass `project_id` ma
 Recommended agent flow:
 
 1. Run `myte config --json` to confirm the project, API base, configured repos, and local workspace detection.
-2. Run `myte bootstrap --json`, `myte feedback-sync --json`, or `myte sync-qaqc --json` to hydrate local context under `MyteCommandCenter`. Use `myte suggestions sync --json` only for narrow mission-review refreshes after bootstrap.
+2. Run `myte bootstrap --json`, `myte feedback-sync --json`, or `myte sync-qaqc --json` to hydrate local context under `MyteCommandCenter`. `bootstrap` also writes `MyteCommandCenter/AgentsMyteAPI.md`, the local action matrix agents should consult before mutating Myte state. Use `myte suggestions sync --json` only for narrow mission-review refreshes after bootstrap.
 3. Use `myte query "<goal/evidence/ask>" --with-diff` when local code changes matter.
-4. Use `myte create-prd <file.md>` only after the PRD markdown has been reviewed by a human, then send it with `--confirm-write --approval-artifact <path>`. The file body is the PRD document; `--description` is only the short board/card summary.
-5. Use `myte feedback status|edit|assign|archive` to create reviewable local artifacts, then `feedback submit` and `feedback review` for the owner-review membrane.
+4. Use `myte create-prd <file.md> --confirm-write --approval-artifact <path>` only after the PRD markdown has been reviewed by a human. The file body is the PRD document; `--description` is only the short board/card summary.
+5. Use `myte feedback status|edit|assign|archive|refine` to create reviewable local artifacts. `feedback submit` and `feedback revise` require an approval artifact; `feedback review` does not because the backend owner/delegate review membrane is the approval control.
 6. Use `myte feedback move` only for direct board movement that is intentionally audited, with a clear `--reason`; use `--feedback-ids` for batch moves or batch archive.
-7. Use `myte suggestions create|revise|review` for mission review threads. Valid create `change_type` values are exactly `update` and `create`; revisions keep the existing thread type and must not include `change_type`.
+7. Use `myte suggestions create|revise|review` for mission review threads. `suggestions create` and `suggestions revise` require an approval artifact; `suggestions review` does not because the backend Project Owner/elevated-delegate decision is the approval control. Valid create `change_type` values are exactly `update` and `create`; revisions keep the existing thread type and must not include `change_type`.
 8. Use `myte mission archive` for project-key mission lifecycle archival. Archive requires Project Owner or elevated delegate capability; restore is web-only from the archived missions board.
-9. Use `myte update-team "<content>"` for project/team comments through `/api/project-assistant/project-comment`, and `myte feedback comment --feedback-id <id> --body-file ./comment.md` for feedback-specific implementation notes.
+9. Use `myte update-team "<content>" --confirm-write --approval-artifact <path>` for project/team comments through `/api/project-assistant/project-comment`, and `myte feedback comment --feedback-id <id> --body-file ./comment.md --confirm-write --approval-artifact ./comment.md` for feedback-specific implementation notes.
 
 PRD document contract:
 
@@ -152,7 +182,7 @@ Feedback comments nuance:
 
 - `myte feedback-sync` reads existing feedback comment turns and stores them in `MyteCommandCenter/data/feedback.yml`.
 - The web product supports feedback-specific comment create/fetch through JWT-authenticated `/api/feedbacks/<feedback_id>/comments`.
-- The project-key npm CLI supports `myte feedback comment --feedback-id <id> --body "..."` and `--body-file ./comment.md`.
+- The project-key npm CLI supports `myte feedback comment --feedback-id <id> --body "..." --confirm-write --approval-artifact ./comment.md` and `--body-file ./comment.md --confirm-write --approval-artifact ./comment.md`.
 - Project-key feedback comments are text-only in this slice and cap content at 500,000 characters. Use the web UI when attachments are required.
 
 ## Commands
@@ -164,7 +194,10 @@ Feedback comments nuance:
 - `mission archive`: archive missions without hard delete
 - `sync-qaqc`: refresh active mission QAQC context locally
 - `feedback-sync`: refresh feedback and PRD context locally
-- `feedback status|edit|assign|archive|submit|revise|reviews|review|move|comment|undo|prd-versions|prd-diff|validate|apply|history|get`: create reviewable feedback artifacts and operate the governed Feedback API
+- `feedback status|edit|assign|archive|refine`: create reviewable local feedback artifacts only
+- `feedback submit|revise|comment`: live Feedback writes requiring `--confirm-write --approval-artifact <path>`
+- `feedback review|move|undo|apply`: governed Feedback writes with no approval artifact flags
+- `feedback-sync|get|history|reviews|prd-versions|prd-diff|validate`: read, sync, or validate Feedback state
 - `suggestions sync|create|revise|review`: work with mission suggestion workflow state
 - `query`: ask the project assistant, optionally with local diff context
 - `ai`: use the Myte AI gateway
@@ -201,12 +234,12 @@ Feedback comments nuance:
 | --- | --- | --- |
 | 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` | Narrow refresh for `mission-ops.yml` after bootstrap or a mutation. |
-| Suggest edit to existing mission | `myte suggestions create` 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` with `change_type: create` | Requires `change_set.title` and `change_set.description`; mission card is created only after approval. |
-| Revise a suggestion | `myte suggestions revise` 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. |
-| Update mission status | `myte mission status --mission-ids "M001" --status todo|in_progress|done` | Active status update only; refreshes local bootstrap + mission-ops by default. |
-| Archive mission | `myte mission archive --mission-ids "M001" --reason "..."` | Project Owner or elevated delegate required. Keeps the mission record, hides it from normal board/bootstrap state, 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`; 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. |
+| Update mission status | `myte mission status --mission-ids "M001" --status todo|in_progress|done` | Active status update only; no approval artifact required; refreshes local bootstrap + mission-ops by default. |
+| Archive mission | `myte mission archive --mission-ids "M001" --reason "..."` | Project Owner or elevated delegate required; no approval artifact required. Keeps the mission record, hides it from normal board/bootstrap state, and refreshes local bootstrap + mission-ops by default. |
 
 After `bootstrap`, find ids locally:
 
@@ -226,18 +259,18 @@ After `bootstrap`, find ids locally:
 | `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 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. | Does not mutate live feedback before approval. |
-| `feedback revise` | Resubmits the original submitter's request after `request_changes`. | 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`. | 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. | `--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. | 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. | 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. | Not the normal collaborator flow; normal flow is `submit` -> `review`. |
+| `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`.
 
@@ -249,13 +282,16 @@ npx --package @mytegroupinc/myte-core node ./node_modules/@mytegroupinc/myte-cor
 
 The harness creates five disposable `TEST` feedback items from markdown, verifies batch review and batch board movement, batch archives the disposable items, verifies normal `feedback-sync` excludes archived items, and verifies the project-key surface does not expose Feedback unarchive/restore.
 
-## Direct Project API Surface
-
-All routes use `Authorization: Bearer <MYTE_API_KEY>`. The CLI adds idempotency and client-session headers on mutation routes.
-
-Read/sync routes:
-
-- `GET /api/project-assistant/config`
+## 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`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "myte",
-  "version": "0.0.46",
+  "version": "0.0.47",
   "description": "Myte developer CLI.",
   "type": "commonjs",
   "license": "MIT",
@@ -19,6 +19,6 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@mytegroupinc/myte-core": "0.0.46"
+    "@mytegroupinc/myte-core": "0.0.47"
   }
 }