myte 0.0.19 → 0.0.20

package/README.md

@@ -1,426 +1,71 @@
-# myte (CLI)
+# myte
 
-Canonical npm package for the Myte developer CLI.
+Canonical npm package for the Myte CLI.
 
-## Install and run
+## Install
 
-Use one of these flows:
+Local install:
 
-- Local dependency in your project:
-  - `npm install myte`
-  - then run `npx myte ai "Explain this repository"`
-  - then run `npx myte ai "Return a JSON object with risks and next_steps" --json-response`
-  - then run `npx myte config --json`
-  - then run `npx myte bootstrap`
-  - then run `npx myte run-qaqc --mission-ids M001 --wait --sync`
-  - then run `npx myte mission status --mission-ids M001 --status done`
-  - then run `npx myte sync-qaqc`
-  - then run `npx myte feedback-sync`
-  - then run `npx myte suggestions sync`
-  - then run `npx myte suggestions create`
-  - then run `npx myte suggestions revise`
-  - then run `npx myte suggestions review`
-  - then run `npx myte query "What changed in logging?" --with-diff`
-  - then run `npx myte update-team "Backend deploy completed; QAQC rerun queued."`
-  - then run `npx myte update-owner --subject "QAQC progress" --body-file ./updates/owner.md`
-  - then run `npx myte update-client --subject "Weekly client update" --body-file ./updates/week-12.md`
-  - or `npm exec myte -- query "What changed in logging?" --with-diff`
-- Global install:
-  - `npm i -g myte`
-  - then run `myte ai "Explain this repository"`
-  - then run `myte bootstrap`
-  - then run `myte run-qaqc --mission-ids M001 --wait --sync`
-  - then run `myte mission status --mission-ids M001 --status done`
-  - then run `myte sync-qaqc`
-  - then run `myte feedback-sync`
-  - then run `myte suggestions sync`
-  - then run `myte suggestions create`
-  - then run `myte suggestions revise`
-  - then run `myte suggestions review`
-  - then run `myte query "What changed in logging?" --with-diff`
-  - then run `myte update-team "Backend deploy completed; QAQC rerun queued."`
-  - then run `myte update-owner --subject "QAQC progress" --body-file ./updates/owner.md`
-  - then run `myte update-client --subject "Weekly client update" --body-file ./updates/week-12.md`
-- No install:
-  - `npx myte@latest ai "Explain this repository"`
-  - `npx myte@latest bootstrap`
-  - `npx myte@latest run-qaqc --mission-ids M001 --wait --sync`
-  - `npx myte@latest mission status --mission-ids M001 --status done`
-  - `npx myte@latest sync-qaqc`
-  - `npx myte@latest feedback-sync`
-  - `npx myte@latest suggestions sync`
-  - `npx myte@latest suggestions create`
-  - `npx myte@latest suggestions revise`
-  - `npx myte@latest suggestions review`
-  - `npx myte@latest query "What changed in logging?" --with-diff`
-  - `npx myte@latest update-team "Backend deploy completed; QAQC rerun queued."`
-  - `npx myte@latest update-owner --subject "QAQC progress" --body-file ./updates/owner.md`
-  - `npx myte@latest update-client --subject "Weekly client update" --body-file ./updates/week-12.md`
-
-`npm install myte` by itself does not put `myte` on your shell PATH. Use `npx myte` or `npm exec myte -- ...` unless you installed globally.
-
-Important:
-- `npm install myte` gives the user everything needed locally.
-- The normal local command is `npx myte ...` or `npm exec myte -- ...`.
-- Bare `myte ...` only works after `npm i -g myte`.
-- `myte ai` uses `MYTEAI_API_KEY` and the `api.myte.ai` gateway.
-
-## Requirements
-
-- Node `18+`
-- macOS, Linux, and Windows are supported
-- `git` available in `PATH` for `--with-diff`
-- `MYTEAI_API_KEY=<inference_api_key>` available in your shell or in a `.env` for `myte ai`
-- `MYTE_API_KEY=<project_api_key>` available in your shell or in a `.env`
-- the CLI searches for `.env` in the current folder and then up parent directories
-- For deterministic diff capture, run from:
-  - a configured repo folder, or
-  - a parent workspace that contains the configured repo folders by name
-
-Important: repo folder names on disk must match the project repo names configured in Myte, including casing on case-sensitive filesystems. If the API says the repos are `Mytegroup-api-mytecody` and `Mytegroup-web-mytecody`, the local folders must use those names for automatic diff discovery.
-
-## Verify setup
-
-Run this first when onboarding on a new machine:
+- `npm install myte`
+- run with `npx myte ...`
+- or `npm exec myte -- ...`
 
-- `npx myte config --json`
-- or `npm exec myte -- config --json`
-- or `npx myte@latest config --json`
+Global install:
 
-## Myte AI gateway
+- `npm i -g myte`
+- run with `myte ...`
 
-Use `myte ai` as the thin inference gateway client. The npm package does not ship models or backend internals; it sends your request to `api.myte.ai` with `MYTEAI_API_KEY`.
+No install:
 
-`--json-response` asks for strict JSON and now sends both `myte_json_response: true` and the OpenAI-compatible `response_format: { type: "json_object" }` shape. On the public developer API, that strict-JSON path also defaults to `medium` reasoning unless the caller explicitly overrides reasoning.
+- `npx myte@latest ...`
 
-Examples:
+`npm install myte` does not add `myte` to your shell `PATH`. Use `npx myte` or `npm exec myte -- ...` unless you installed globally.
 
-- `npx myte ai "Explain what this repository does"`
-- `npx myte ai "Return a JSON object with risks and next_steps" --json-response`
-- `npm exec myte -- ai "Summarize this file"`
-- `myte ai "Return clean JSON only" --json-response`
+## Requirements
 
-It confirms:
-- the API key resolves to the expected project
-- which repo names the project is configured with
-- which of those repos were found locally
+- Node `18+`
+- macOS, Linux, or Windows
+- `MYTE_API_KEY=<project_api_key>` in your shell or workspace `.env`
+- `MYTEAI_API_KEY=<inference_api_key>` only for `myte ai`
+- `git` in `PATH` only for `query --with-diff`
 
-## Bootstrap Command Center cards
+The CLI searches for `.env` in the current folder and then up parent directories.
 
-Run this from the wrapper root that contains the project's repo folders:
+## Common Commands
 
+- `npx myte config --json`
 - `npx myte bootstrap`
-- or `npm exec myte -- bootstrap`
-- or `myte bootstrap`
-
-What it does:
-- fetches a project-scoped bootstrap snapshot from the API using your project key
-- validates the current wrapper workspace against the configured repo names
-- writes local files under `MyteCommandCenter/data`
-- writes a normalized public Command Center schema, not raw backend mission/proposal documents
-- mission cards now include richer execution context like `complexity`, `estimated_hours`, `due_date`, `subtasks`, `technical_requirements`, `resources_needed`, `labels`, and normalized `test_cases`
-- excludes internal fields like `_id`, `org_id`, `project_id`, `created_by`, `assigned_to`, and raw `qa_qc_results`
-- if the workspace still has old Command Center artifacts, rerunning current commands prunes legacy outputs like `bootstrap-manifest.json`, `data/qaqc/`, and `data/feedback/` automatically as the new files are written
-
-Files written:
-- `MyteCommandCenter/data/project.yml`
-- `MyteCommandCenter/data/phases/*.yml`
-- `MyteCommandCenter/data/epics/*.yml`
-- `MyteCommandCenter/data/stories/*.yml`
-- `MyteCommandCenter/data/missions/*.yml`
-
-Useful forms:
-- `npx myte bootstrap --json`
-- `npx myte bootstrap --dry-run --json`
-- `npx myte bootstrap --output-dir ./MyteCommandCenter`
-
-## Queue mission QAQC and refresh local QAQC context
-
-Run this from any workspace with a valid project key:
-
-- `npx myte run-qaqc --mission-ids "M001,M002" --wait --sync`
-- or `npm exec myte -- run-qaqc --mission-ids "M001,M002" --wait --sync`
-- or `myte run-qaqc --mission-ids "M001,M002" --wait --sync`
-
-What it does:
-- queues QAQC for up to 10 explicit mission ids through the project-key API surface
-- returns a `batch_id` immediately
-- uses `--wait` to poll the batch until it reaches a terminal state
-- uses `--sync` to refresh `MyteCommandCenter/data/qaqc.yml` after a completed batch
-- on PowerShell, quote comma-separated multi-id values: `--mission-ids "M001,M002"`
-- runs through the dedicated `project_api_qaqc` queue inside the existing Celery service, with a global budget of `20` dispatch starts/minute and `20` live jobs
-- a saturated `run-qaqc --wait` batch can take roughly `5-10` minutes before sync has final data to pull
-
-Useful forms:
-- `npx myte run-qaqc --mission-ids M001`
-- `npx myte run-qaqc --mission-ids "M001,M002" --wait`
-- `npx myte run-qaqc --mission-ids "M001,M002" --wait --sync --json`
-
-## Update mission status from the IDE
-
-- `npx myte mission status --mission-ids "M001,M002" --status done`
-- or `npm exec myte -- mission status --mission-ids "M001,M002" --status done`
-- or `myte mission status --mission-ids "M001,M002" --status done`
-
-What it does:
-- updates one or many mission business ids through the project-key API
-- updates the same mission `status` field used by the app board and mission routes
-- accepts `todo`, `in_progress`, and `done` aliases and normalizes them before sending
-- sends the canonical backend mission statuses: `Todo`, `In Progress`, or `Done`
-- only changes mission state; it does not queue QAQC and it does not sync `MyteCommandCenter/data/qaqc.yml`
-
-## Sync active mission QAQC context
-
-Run this from the wrapper root that contains the project's repo folders:
-
 - `npx myte sync-qaqc`
-- or `npm exec myte -- sync-qaqc`
-- or `myte sync-qaqc`
-
-What it does:
-- fetches a project-scoped QAQC sync snapshot from the API using your project key
-- works even if `bootstrap` has not been run yet
-- creates `MyteCommandCenter/data/qaqc.yml` automatically if it does not exist
-- syncs only active `Todo` and `In Progress` missions
-- writes a public QAQC summary per mission, not raw `qa_qc_results` or raw batch docs
-- keeps active mission QAQC state in one deterministic file that grows and shrinks with the current working set
-- fully rewrites `MyteCommandCenter/data/qaqc.yml` on every sync and does not delete `MyteCommandCenter/data/missions/*.yml`
-
-Files written:
-- `MyteCommandCenter/data/project.yml`
-- `MyteCommandCenter/data/qaqc.yml`
-
-Useful forms:
-- `npx myte sync-qaqc --json`
-- `npx myte sync-qaqc --dry-run --json`
-- `npx myte sync-qaqc --output-dir ./MyteCommandCenter`
-
-## Sync feedback and PRD context
-
-Run this from the wrapper root that contains the project's repo folders:
-
 - `npx myte feedback-sync`
-- or `npm exec myte -- feedback-sync`
-- or `myte feedback-sync`
-
-What it does:
-- fetches a project-scoped feedback snapshot from the API using your project key
-- defaults to pending feedback; use `--status` when you want a different slice
-- writes one deterministic feedback snapshot under `MyteCommandCenter/data/feedback.yml`
-- keeps feedback metadata plus conversation turns in `feedback.yml`
-- writes full PRD markdown/text into `MyteCommandCenter/PRD/feedback-sync/*.md` and stores a pointer in `feedback.yml`
-- fully replaces the aggregated feedback sync file so stale feedback does not accumulate locally
-- does not delete `MyteCommandCenter/data/missions/*.yml`
-
-Files written:
-- `MyteCommandCenter/data/project.yml`
-- `MyteCommandCenter/data/feedback.yml`
-- `MyteCommandCenter/PRD/feedback-sync/*.md`
-
-Useful forms:
-- `npx myte feedback-sync --json`
-- `npx myte feedback-sync --dry-run --json`
-- `npx myte feedback-sync --status Pending --source User`
-
-## Sync and iterate on mission suggestions
-
 - `npx myte suggestions sync`
-- or `npm exec myte -- suggestions sync`
-- or `myte suggestions sync`
-
-What it does:
-- fetches the project suggestion workflow snapshot with the project API key
-- writes one deterministic workflow file at `MyteCommandCenter/data/mission-ops.yml`
-- keeps active first-come-first-serve queue state in `queue`
-- keeps full lineage for active and terminal items in `threads[]`
-- `suggestions sync` should be the first step before ideating locally so new submissions start from the latest aggregated thread state
-- preserves top-level `workspace.<actor_scope>` blocks and per-thread `workspace.<actor_scope>` drafts across sync so coding agents can keep local drafts in one file
-- synced `threads[]` include aggregate diffs, conflict summaries, and archived decision lineage so local agents do not need to reconstruct review state
-
-Create/revise/review:
-- `npx myte suggestions create --file ./changes/create.yml`
-- `npx myte suggestions revise --file ./changes/revise.yml`
-- `npx myte suggestions review --file ./changes/review.yml`
-
-Local single-file mode:
-- `suggestions create` can read local `workspace.<actor_scope>.draft_submissions[]` from `mission-ops.yml`
-- `suggestions revise` can read local per-thread `workspace.<actor_scope>` draft blocks when `draft_status` is `submit`, `ready`, or `pending_submit`
-- `suggestions review` is owner-only and can read local per-thread owner review blocks using `review_action`, `review_note`, `final_change_set`, and `review_revision`
-- `suggestions review` requires an explicit `review_action` of `request_changes`, `approve`, or `reject`
-- there is no persisted save-draft review action
-- suggestion notifications deep-link into the project Reviews workspace for the affected thread
-- create/revise/review resync `mission-ops.yml` by default unless `--no-sync` is passed
-- create/revise/review auto-send idempotency and client-session metadata so retries stay deterministic without manual headers
-- `--print-context` prints the JSON payload that would be submitted for create/revise/review
-- after successful review approvals, the CLI rewrites the affected `MyteCommandCenter/data/missions/*.yml` cards automatically
-
-Useful forms:
-- `npx myte suggestions sync --json`
-- `npx myte suggestions create --file ./changes/create.yml --json`
-- `npx myte suggestions create`
-- `npx myte suggestions revise`
-- `npx myte suggestions review`
-
-## Query with deterministic diff context
-
-Example:
-
-- `npx myte query "What changed in logging?" --with-diff`
-- or `npm exec myte -- query "What changed in logging?" --with-diff`
-- or `npx myte@latest query "What changed in logging?" --with-diff`
-
-When `--with-diff` is enabled, the CLI:
-- resolves project config from the API using your project API key
-- finds the configured repos locally
-- compares the current branch against `origin/main` or `origin/master`
-- includes committed branch changes, staged changes, unstaged changes, and untracked files
-
-If diff context is missing, run `myte config --json` and check:
-- repo folder names match the configured repo names
-- you are running inside the repo or a parent workspace
-- `git` is installed and the repo has `origin/main` or `origin/master` available
-
-If only part of your repos are resolved, the CLI still runs and includes that status in:
-- command output warnings (`Repo "<name>": ...`)
-- payload `diff_diagnostics` (in `--print-context` and sent with `--with-diff`)
-- a structured message in additional context that explains per-repo outcomes.
-
-## Deterministic PRD upload
-
-Create the PRD locally first, then upload it directly to Myte Cody as feedback.
-
-Examples:
-
-- File path:
-  - `npx myte create-prd ./drafts/auth-prd.md`
-  - `npx myte create-prd ./drafts/auth-prd.md ./drafts/billing-prd.md`
-  - or `npm exec myte -- create-prd ./drafts/auth-prd.md`
-  - or `npm exec myte -- create-prd ./drafts/auth-prd.md ./drafts/billing-prd.md`
-  - or `npx myte@latest create-prd ./drafts/auth-prd.md`
-- From stdin on macOS/Linux:
-  - `cat ./drafts/auth-prd.md | npx myte create-prd --stdin`
-- From stdin on PowerShell:
-  - `Get-Content -Raw .\drafts\auth-prd.md | npx myte create-prd --stdin`
-
-This path is deterministic. It does not generate a PRD with an LLM.
-
-Preferred file format matches `script/MyteCodyPRD.py`:
-
-````markdown
-```myte-kanban
-{
-  "title": "Authentication PRD",
-  "description": "Short card summary shown in the feedback list",
-  "priority": "Medium",
-  "assigned_user_email": "dev@mytegroup.com",
-  "tags": ["mission-board"]
-}
-```
-
-# PRD
-
-Detailed markdown body here.
-````
-
-Raw markdown also works:
-- include a top-level `# Title`
-- or pass `--title "..."` when using `--stdin`
-- pass `--description "..."` if you want an explicit feedback description/card summary
-
-Deterministic field mapping:
-- Required: a valid project API key, the PRD markdown body, and a title.
-- One command can upload one file or many files. Single uploads hit `/project-assistant/create-prd`; multi-file uploads automatically use the batch upload path.
-- `title` maps to the feedback title.
-- `description` maps to the feedback description/card summary. Legacy `feedback_text` is still accepted for older payloads.
-- The context blob that becomes the stored PRD document is the full `prd_markdown`, or the markdown body after the `myte-kanban` metadata block when using `ticket_markdown`.
-- That PRD markdown blob is stored verbatim as PRD content.
-- The backend uses that stored PRD markdown/text to generate the downloadable PRD DOCX.
-- Additional structured fields should go in the `myte-kanban` JSON block. Supported keys include `priority`, `status`, `tags`, `assigned_user_email`, `assigned_user_id`, `due_date`, `repo_name`, `repo_id`, `preview_url`, and `source`.
-
-To inspect the exact payload before sending it:
-- `npx myte create-prd ./drafts/auth-prd.md --print-context`
-- `npx myte create-prd ./drafts/auth-prd.md ./drafts/billing-prd.md --print-context`
-- `npx myte create-prd ./drafts/auth-prd.md --description "Short card summary" --print-context`
-
-## Team updates
-
-Use `update-team` to add a project comment through the project-key Project Assistant surface.
-
-Examples:
-
-- `npx myte update-team "Backend deploy completed; QAQC rerun queued."`
-- `npm exec myte -- update-team "Frontend review is ready for sign-off."`
-- `Get-Content -Raw .\notes\team-update.md | npx myte update-team --stdin`
-
-What it sends:
-
-- `POST /api/project-assistant/project-comment`
-- payload: `{ "content": "..." }`
-
-Useful forms:
-
-- `npx myte update-team "Backend deploy completed." --print-context`
-- `npx myte update-team "Backend deploy completed." --json`
-
-## Owner updates
-
-Use `update-owner` to send a direct project-owner email through the project-key Project Assistant surface.
-
-Examples:
-
+- `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-owner --subject "Board cleanup needed" --body-markdown "## Status\n- Phase 2 review pending"`
-- `Get-Content -Raw .\updates\owner.md | npx myte update-owner --stdin --subject "Owner update"`
-
-What it sends:
-
-- `POST /api/project-assistant/update-owner`
-- payload: `{ "subject": "...", "body_markdown": "..." }`
-
-Notes:
-
-- the owner recipient is resolved from the authenticated project
-- the CLI cannot set an arbitrary recipient address
-- the backend sends the email through Myte SMTP and stores a durable send record
-
-## Client update drafts
-
-Use `update-client` to draft a branded client update email for owner review.
-
-Examples:
-
 - `npx myte update-client --subject "Weekly client update" --body-file ./updates/week-12.md`
-- `npx myte update-client --subject "Weekly client update" --body-markdown "## Progress\n- Login complete" --target-contact-ids 507f1f77bcf86cd799439011,507f1f77bcf86cd799439012`
-- `Get-Content -Raw .\updates\week-12.md | npx myte update-client --stdin --subject "Weekly client update"`
 
-What it sends:
+## Behavior
 
-- `POST /api/project-assistant/client-update-drafts`
-- payload: `{ "subject": "...", "body_markdown": "...", "target_contact_ids": ["..."] }`
+- `bootstrap`, `sync-qaqc`, `feedback-sync`, and `suggestions sync` write project-scoped local context under `MyteCommandCenter` in the current workspace unless `--output-dir` is provided.
+- `query --with-diff` is stricter than the snapshot commands. It requires project repositories to be configured by the project owner or builder, and it requires at least one matching local project repo to be resolved for diff collection.
+- 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.
 
-Notes:
+## Commands
 
-- `--subject` is required.
-- The body can come from `--body-markdown`, `--body-file`, a positional file path, positional inline text, or `--stdin`.
-- `target_contact_ids` are optional. If omitted, the backend selects the linked primary client contact when available.
-- If no linked client contacts exist, the backend falls back to the project owner so internal projects can still draft/send updates through the same flow.
-- Use `--target-contact-id <id>` multiple times or `--target-contact-ids <id1,id2>`.
-- The CLI prints the returned draft summary, including the draft id, status, recipients, and snippet.
+- `config`: verify the project key and inspect local repo resolution
+- `bootstrap`: write project board context locally
+- `run-qaqc`: queue QAQC for explicit mission ids
+- `mission status`: update mission state
+- `sync-qaqc`: refresh active mission QAQC context locally
+- `feedback-sync`: refresh feedback and PRD context locally
+- `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
+- `create-prd`: upload deterministic PRD markdown
+- `update-team`, `update-owner`, `update-client`: send project updates through the project-key surface
 
-## Common commands
+## Notes
 
-- `npm install myte`
-- `npx myte bootstrap`
-- `npx myte mission status --mission-ids "M001,M002" --status done`
-- `npx myte sync-qaqc`
-- `npx myte feedback-sync`
-- `npx myte suggestions sync`
-- `npx myte suggestions create --file ./changes/create.yml`
-- `npx myte suggestions revise`
-- `npx myte suggestions review`
-- `npx myte config --json`
-- `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; QAQC rerun queued."`
-- `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`
+- The package ships the CLI only. Internal rollout notes, validation logs, and project-specific operating docs are not part of the public npm contract.
+- The public `myte` package is the supported entrypoint. The scoped `@mytegroupinc/myte-core` package is the implementation dependency used by the wrapper.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "myte",
-  "version": "0.0.19",
-  "description": "Myte developer CLI (Project Assistant + Myte AI gateway).",
+  "version": "0.0.20",
+  "description": "Myte developer CLI.",
   "type": "commonjs",
   "license": "MIT",
   "files": [
@@ -16,6 +16,6 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@mytegroupinc/myte-core": "0.0.19"
+    "@mytegroupinc/myte-core": "0.0.20"
   }
 }