myte 0.0.3 → 0.0.4

package/README.md

@@ -1,12 +1,121 @@
 # myte (CLI)
 
-Canonical npm package name for the Myte developer CLI.
+Canonical npm package for the Myte developer CLI.
 
-Usage:
-- `npx myte@latest query "What changed in logging?" --with-diff`
-- `npm i -g myte` then `myte query "..." --with-diff`
+## Install and run
 
-Requirements:
-- Node 18+
-- `git` in PATH (for `--with-diff`)
-- Root `.env` (or env var) contains `MYTE_API_KEY=<project_api_key>`
+Use one of these flows:
+
+- Local dependency in your project:
+  - `npm install myte`
+  - then run `npx myte config --json`
+  - then run `npx myte query "What changed in logging?" --with-diff`
+  - or `npm exec myte -- query "What changed in logging?" --with-diff`
+- Global install:
+  - `npm i -g myte`
+  - then run `myte query "What changed in logging?" --with-diff`
+- No install:
+  - `npx myte@latest query "What changed in logging?" --with-diff`
+
+`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`.
+
+## Requirements
+
+- Node `18+`
+- macOS, Linux, and Windows are supported
+- `git` available in `PATH` for `--with-diff`
+- `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:
+
+- `npx myte config --json`
+- or `npm exec myte -- config --json`
+- or `npx myte@latest config --json`
+
+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
+
+## 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`
+  - or `npm exec myte -- create-prd ./drafts/auth-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",
+  "priority": "Medium",
+  "assigned_user_email": "dev@mytegroup.com",
+  "tags": ["mission-board"],
+  "feedback_text": "Short card summary"
+}
+```
+
+# PRD
+
+Detailed markdown body here.
+````
+
+Raw markdown also works:
+- include a top-level `# Title`
+- or pass `--title "..."` when using `--stdin`
+
+## Common commands
+
+- `npm install myte`
+- `npx myte config --json`
+- `npx myte query "Summarize the current branch changes" --with-diff`
+- `npx myte create-prd ./drafts/auth-prd.md`

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "myte",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Myte developer CLI (Project Assistant + deterministic diffs).",
   "type": "commonjs",
   "license": "MIT",
+  "files": [
+    "README.md",
+    "bin",
+    "package.json"
+  ],
   "bin": {
     "myte": "bin/myte.js"
   },
@@ -11,6 +16,6 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@mytegroupinc/myte-core": "0.0.3"
+    "@mytegroupinc/myte-core": "0.0.4"
   }
 }