@moda-ai/cli 1.31.3 → 1.32.0

package/README.md

@@ -132,24 +132,88 @@ codes, event schema) for agents.
 
 ## Prompt Management
 
-Prompt management is code-first. Keep prompts in `prompts/**/*.prompt.md` or
-`prompts/**/*.prompt.json`, sync them with the CLI, and render them through the
-SDK so LLM spans include prompt metadata.
-
-JSON definitions can provide `content`, `systemPrompt`, or `messages`. Existing
-files with a nonempty text `template` also work: the CLI uses it as content when
-none of those fields supplies usable text. Sync preserves placeholders and
-leaves the source file unchanged; empty definitions still produce an error.
+Prompt management is code-first. Keep existing files and inline definitions in
+place. The CLI resolves selected sources without importing or executing your app.
+Existing `prompts/**/*.prompt.md` and `prompts/**/*.prompt.json` projects continue
+to work unchanged.
 
 ```bash
-moda prompts init
-moda prompts status
+# Discover prompt sources and preview the sync without saving local state.
+moda prompts sync --dry-run
+# Run prompt-specific discovery, upload verified definitions, and save mappings.
 moda prompts sync
+# Optionally investigate unresolved sources with an installed coding agent.
+moda prompts sync --analyst=claude
+# Sync only configured sources, without discovery.
+moda prompts sync --no-analyze
+```
+
+Every sync reuses the prompt-specific harness analyzer. The default is a bounded,
+deterministic local scan with no agent calls. Successful sync saves newly verified
+mappings in `.moda/prompts.yml`; existing keys and legacy prompt-file metadata are
+preserved. Explicit negative `prompt_paths` patterns also exclude new discoveries.
+Analysis diagnostics and partial coverage are returned in the sync result. A dry
+run performs deterministic discovery without changing the manifest or lockfile.
+`--watch` starts with analysis and then watches mapped definitions; re-run sync to
+look for newly added sources that do not affect an existing mapping.
+
+For unresolved candidates, select `--analyst=claude`, `codex`, or `cursor` on sync.
+The CLI launches a bounded investigation through the installed coding-agent CLI.
+It accepts source selectors, then reads and validates the source itself; agent
+text never becomes registered prompt content. `--assist=none` disables assistance.
+You can still run `harness analyze --experimental --concern=prompts` separately
+and import its report with `prompts init --from-harness=<report>`.
+Discovery reports partial coverage explicitly; finding some prompts does not
+prove that every model call is covered.
+
+You can also configure `.moda/prompts.yml` directly:
+
+```yaml
+version: 2
+prompt_paths:
+  - instructions/**/*.txt
+  - '!instructions/archive/**'
+sources:
+  - key: support.system
+    path: src/agent.ts
+    selector:
+      symbol: SYSTEM_PROMPT
+  - key: support.policy
+    path: config/agents.yaml
+    selector:
+      pointer: /support/prompt
+  - key: support.build
+    path: src/prompt.py
+    selector:
+      symbol: build_prompt
+    kind: builder
+    dependencies:
+      - path: config/policy.txt
 ```
 
-`status` and `diff` are read-only. `sync` uploads changed versions and writes
-`.moda/prompts.lock.json`. `promote` moves a remote `dev`, `staging`, or `prod`
-label.
+Selectors support named TypeScript/JavaScript/Python definitions and JSON Pointer
+selection in JSON/YAML. Python resolution requires `python3`; the helper parses
+ASTs without importing customer modules. Static literals and supported constant
+compositions become text or messages. Templates retain placeholders. Functions,
+unsupported expressions, and runtime composition remain builder definitions with
+source/dependency fingerprints and explicit incomplete coverage. Builders and
+templates cannot be replayed as plain prompt text; execute the application's
+builder and attribute the resulting model call to its registry version.
+
+JSON definitions accept `content`, `systemPrompt`, or `messages`, with `template`
+as a fallback when none supplies usable text. Explicit mappings are required for
+ambiguous definitions. Exact file paths and globs are honored; duplicate keys,
+missing selectors, unsafe paths, and malformed manifests fail before upload.
+
+`status` and `diff` are read-only. `sync` uploads changed versions and atomically
+writes `.moda/prompts.lock.json` only after validating the response and rechecking
+local sources. A failed sync preserves the prior lock. Removing a tracked source
+requires `--allow-untrack`; this removes its local lock entry, not remote versions.
+`promote` moves a remote `dev`, `staging`, or `prod` label.
+
+Use the lock entry's `{ key, promptId, versionId }` to attribute runtime calls.
+Actual rendered messages belong in traces; request data should not produce a new
+registry definition on each call. Plain renderable definitions can use the SDK:
 
 ```typescript
 const rendered = Moda.prompt("support.triage").render({