@mytegroupinc/myte-core 0.0.47 → 0.0.50

package/README.md

@@ -9,25 +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+`
+## 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`
-- No runtime npm dependencies. The CLI uses Node 18+ built-ins for env loading, argument parsing, HTTP, and local context serialization.
+- 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|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 --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
@@ -60,7 +84,11 @@ Only selected project-key writes require a server-validated approval envelope. T
 - 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.
-- PRD batches use one `create-prd fileA.md fileB.md ...`; list each PRD file/title/client ref and make `batch_count` match the number of PRDs.
+- 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.
 - 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.
@@ -78,6 +106,9 @@ Coding agents should treat `MYTE_API_KEY` as a project-scoped Project Assistant
 - 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.
+- 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`.
@@ -102,14 +133,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.
-
-Feedback comment support:
+- 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-sync` includes existing feedback comment turns in local context.
-- Feedback-specific comment creation exists in the web backend at `/api/feedbacks/<feedback_id>/comments`, protected by JWT/project assignment.
+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.
+- 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
 
@@ -200,16 +263,42 @@ Agent rule: never guess `suggestion_id`. If `mission-ops.yml` is missing or stal
 | `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.
 
-Canonical feedback lifecycle states are `frozen`, `todo`, `in_progress`, `in_review`, `completed`, `deployed`, `rejected`, and `archived`.
-
-Reusable live smoke harness after deploy:
-
-```bash
-node ./scripts/feedback-live-full-harness.js --confirm-live --base-url https://api.myte.dev/api
-```
-
-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.
+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