@mytegroupinc/myte-core 0.0.19 → 0.0.21

package/README.md

@@ -1,151 +1,24 @@
 # @mytegroupinc/myte-core
 
-Internal implementation package for the `myte` CLI.
+Implementation package for the `myte` CLI.
 
-Most users should install the unscoped wrapper instead:
-- `npm install myte` then `npx myte ai "Explain this repository"`
-- `npm install myte` then `npx myte ai "Return a JSON object with risks and next_steps" --json-response`
-- `npm install myte` then `npx myte bootstrap`
-- `npm install myte` then `npx myte run-qaqc --mission-ids M001 --wait --sync`
-- `npm install myte` then `npx myte mission status --mission-ids M001 --status done`
-- `npm install myte` then `npx myte sync-qaqc`
-- `npm install myte` then `npx myte feedback-sync`
-- `npm install myte` then `npx myte suggestions sync`
-- `npm install myte` then `npx myte suggestions create`
-- `npm install myte` then `npx myte suggestions revise`
-- `npm install myte` then `npx myte suggestions review`
-- `npm install myte` then `npx myte query "..." --with-diff`
-- `npm install myte` then `npm exec myte -- query "..." --with-diff`
-- `npm install myte` then `npx myte update-team "Backend deploy completed; QAQC rerun queued."`
-- `npm install myte` then `npx myte update-owner --subject "QAQC progress" --body-file ./updates/owner.md`
-- `npm install myte` then `npx myte update-client --subject "Weekly client update" --body-file ./updates/week-12.md`
-- `npm i -g myte` then `myte bootstrap`
-- `npm i -g myte` then `myte run-qaqc --mission-ids M001 --wait --sync`
-- `npm i -g myte` then `myte mission status --mission-ids M001 --status done`
-- `npm i -g myte` then `myte sync-qaqc`
-- `npm i -g myte` then `myte feedback-sync`
-- `npm i -g myte` then `myte suggestions sync`
-- `npm i -g myte` then `myte suggestions create`
-- `npm i -g myte` then `myte suggestions revise`
-- `npm i -g myte` then `myte suggestions review`
-- `npm i -g myte` then `myte query "..." --with-diff`
-- `npm i -g myte` then `myte update-team "Backend deploy completed; QAQC rerun queued."`
-- `npm i -g myte` then `myte update-owner --subject "QAQC progress" --body-file ./updates/owner.md`
-- `npm i -g myte` then `myte update-client --subject "Weekly client update" --body-file ./updates/week-12.md`
-- `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 "..." --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` then `npx myte create-prd ./drafts/auth-prd.md`
-- `npm install myte` then `npx myte create-prd ./drafts/auth-prd.md ./drafts/billing-prd.md`
-- `cat ./drafts/auth-prd.md | npx myte create-prd --stdin`
+Most users should install the public wrapper instead:
 
-Requirements:
-- Node `18+`
-- macOS, Linux, or Windows
-- `git` in `PATH` for `--with-diff`
-- `MYTEAI_API_KEY=<inference_api_key>` in env or `.env` for `myte ai`
-- `MYTE_API_KEY=<project_api_key>` in env or `.env`
-- repo folder names must match the project repo names configured in Myte, including casing on case-sensitive filesystems
+- `npm install myte`
+- run with `npx myte ...`
 
-Notes:
-- `npm install myte` installs the wrapper locally; use `npx myte` or `npm exec myte -- ...` to run it.
-- `npm install myte` means the CLI is available locally; bare `myte ...` still requires a global install.
-- `bootstrap` is a local file materialization path, not a hosted file download.
-- `bootstrap` expects to run from a wrapper root that contains the project's configured repo folders.
-- `bootstrap` writes `MyteCommandCenter/data/project.yml` plus itemized `phases`, `epics`, `stories`, and `missions`.
-- `bootstrap` materializes a public Command Center DTO, not raw backend documents.
-- `bootstrap` mission cards now include richer execution context like `complexity`, `estimated_hours`, `due_date`, `subtasks`, `technical_requirements`, `resources_needed`, `labels`, and normalized `test_cases`.
-- `bootstrap` excludes internal keys like `_id`, `org_id`, `project_id`, `created_by`, `assigned_to`, and raw `qa_qc_results`.
-- rerunning current commands on an older workspace automatically prunes legacy artifacts like `bootstrap-manifest.json`, `data/qaqc/`, and `data/feedback/` as the new files are written.
-- `run-qaqc` queues QAQC for up to 10 explicit mission ids through `/api/project-assistant/run-qaqc`.
-- On PowerShell, quote comma-separated multi-id values: `--mission-ids "M001,M002"`.
-- `run-qaqc --wait` polls `/api/project-assistant/run-qaqc/<batch_id>` until the batch is terminal.
-- `run-qaqc --sync` refreshes `MyteCommandCenter/data/qaqc.yml` after a completed batch.
-- `mission status` updates one or many mission business ids through `/api/project-assistant/mission-status-update`.
-- `mission status` normalizes status aliases like `todo`, `in_progress`, and `done`, then sends the canonical mission status values `Todo`, `In Progress`, or `Done`.
-- `mission status` updates only the mission `status` field used by the app. It does not run QAQC and it does not rewrite `MyteCommandCenter/data/qaqc.yml`.
-- project-key QAQC 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 write.
-- `sync-qaqc` works without `bootstrap`; it creates `MyteCommandCenter/data/qaqc.yml` automatically if missing.
-- `sync-qaqc` writes the active mission QAQC working set to `MyteCommandCenter/data/qaqc.yml`.
-- `sync-qaqc` only exports active `Todo` / `In Progress` missions plus a public QAQC summary and sanitized latest batch metadata.
-- `sync-qaqc` keeps QAQC state in one deterministic file so the working set grows and shrinks with current active-mission reality.
-- `sync-qaqc` fully rewrites `MyteCommandCenter/data/qaqc.yml` on every sync and does not delete `MyteCommandCenter/data/missions/*.yml`.
-- `feedback-sync` writes one deterministic feedback snapshot under `MyteCommandCenter/data/feedback.yml`.
-- `feedback-sync` defaults to pending feedback unless `--status` is provided.
-- `feedback-sync` keeps feedback metadata plus comment turns in `MyteCommandCenter/data/feedback.yml`.
-- `feedback-sync` writes full PRD context into `MyteCommandCenter/PRD/feedback-sync/*.md` and points to those files from `feedback.yml`.
-- `feedback-sync` fully replaces the feedback-owned sync file to avoid stale local feedback noise.
-- `feedback-sync` fully rewrites `MyteCommandCenter/data/feedback.yml` on every sync and does not delete `MyteCommandCenter/data/missions/*.yml`.
-- `suggestions sync` writes one merge-safe workflow file at `MyteCommandCenter/data/mission-ops.yml`.
-- `suggestions sync` should be the first step before ideating locally so new submissions start from the latest aggregated thread state.
-- `suggestions sync` rewrites the canonical synced state into `threads[]` and preserves top-level `workspace.<actor_scope>` blocks plus per-thread `workspace.<actor_scope>` drafts from the existing file.
-- synced `threads[]` include aggregate diffs, conflict summaries, and archived decision lineage so local agents do not need to reconstruct review state.
-- `suggestions create` reads a structured file payload or local `workspace.<actor_scope>.draft_submissions[]` blocks from `mission-ops.yml`.
-- `suggestions revise` reads structured file payloads or local per-thread `workspace.<actor_scope>` drafts only when `draft_status` is `submit`, `ready`, or `pending_submit`.
-- `suggestions review` is owner-only, reads structured file payloads or local per-thread owner review intent, and refreshes `data/missions/*.yml` when approvals apply changes.
-- `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 automatically send `X-Idempotency-Key` and a default `client_session_id` so retries stay deterministic and auditable.
-- `--print-context` prints the JSON payload that would be submitted for create/revise/review.
-- `mission-ops.yml` keeps synced thread lineage plus actor-local draft space in one file; terminal items fall out of `queue` after sync but remain in `threads[]`.
-- `create-prd` is the deterministic PRD upload path, not an LLM generation command.
-- `update-team` creates a project comment through `/api/project-assistant/project-comment`.
-- `update-owner` sends a direct owner email through `/api/project-assistant/update-owner`.
-- `update-owner` requires `--subject` plus body markdown from `--body-markdown`, `--body-file`, positional input, or `--stdin`.
-- `update-client` creates a client update draft through `/api/project-assistant/client-update-drafts`.
-- `update-client` requires `--subject` plus body markdown from `--body-markdown`, `--body-file`, positional input, or `--stdin`.
-- `update-client` accepts optional `--target-contact-id` repeats or `--target-contact-ids <id1,id2>`.
-- If no linked client contacts exist, the backend falls back to the project owner for internal projects.
-- `--with-diff` only searches repo folders whose names match the project repo names configured in Myte.
-- `--with-diff` includes per-repo diagnostics in `print-context` payload:
-  - missing repo directories
-  - per-repo errors (for example fetch or command failures)
-  - clean/no-change repo summaries
-- `--with-diff` query payload includes `diff_diagnostics` so backend/UI can report exactly why context may be missing.
+This package exists so the public wrapper can stay small and versioned cleanly. It is not the recommended public install target.
 
-Deterministic `create-prd` contract:
-- Required: `MYTE_API_KEY`, a PRD markdown body, and a title.
-- Accepts one file or many files per command. The CLI uses `/project-assistant/create-prd` for one item and automatically uses the batch upload path for multi-file requests.
-- Title source: `myte-kanban.title`, the first markdown `# Heading`, or `--title`.
-- Description source: `myte-kanban.description` or `--description`.
-- The markdown body (`prd_markdown`, or the body portion of `ticket_markdown`) is stored verbatim as PRD content and is what the backend uses to build the PRD DOCX.
-- Legacy `feedback_text` is still accepted for older payloads, but new callers should use `description`.
-- Optional structured fields: `priority`, `status`, `tags`, `assigned_user_email`, `assigned_user_id`, `due_date`, `repo_name`, `repo_id`, `preview_url`, `source`.
+## Requirements
 
-Examples:
-- `npx myte ai "Explain what this project does"`
-- `npx myte ai "Return a JSON object with risks and next_steps" --json-response`
-- `npx myte bootstrap`
-- `npx myte run-qaqc --mission-ids "M001,M002" --wait --sync`
-- `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 create`
-- `npx myte suggestions revise`
-- `npx myte suggestions review`
-- `npx myte bootstrap --dry-run --json`
-- `npx myte sync-qaqc --dry-run --json`
-- `npx myte create-prd ./drafts/auth-prd.md --description "Short card summary"`
-- `npx myte create-prd ./drafts/auth-prd.md ./drafts/billing-prd.md`
-- `npx myte create-prd ./drafts/auth-prd.md --print-context`
-- `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`
+- Node `18+`
+- `MYTE_API_KEY` for project-scoped commands
+- `MYTEAI_API_KEY` for `myte ai`
+- `git` only when using `query --with-diff`
 
-This package is published under the org scope for governance; the public `myte` wrapper delegates here.
+## Behavior Summary
 
-`--json-response` sends both the Myte convenience flag (`myte_json_response: true`) and the OpenAI-compatible chat-completions shape (`response_format: { type: "json_object" }`). On the public developer API, that strict-JSON path also defaults to `medium` reasoning unless the caller explicitly overrides reasoning.
+- Snapshot-style commands such as `bootstrap`, `sync-qaqc`, `feedback-sync`, and `suggestions sync` write local `MyteCommandCenter` data.
+- `feedback status|edit|assign|archive` writes reviewable local YAML artifacts, while `feedback validate|apply` sends those artifacts to the backend so business rules 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.
+- Public package documentation is intentionally minimal. Internal rollout and design notes are not part of the npm package contract.