@unbrained/pm-cli 2026.5.1 → 2026.5.2

package/docs/COMMANDS.md

@@ -0,0 +1,199 @@
+# Command Reference
+
+This is a task-oriented command guide. For exact flags, use runtime help because extensions and settings can change the active surface:
+
+```bash
+pm <command> --help
+pm <command> --help --json
+pm contracts --command <command> --flags-only --json
+```
+
+## Agent Quick Context
+
+- Prefer `pm context`, `pm search`, and narrow list commands before mutation.
+- Prefer TOON for reading and `--json` for strict parsing.
+- Use `pm contracts` for machine clients.
+- Every mutation writes history.
+
+Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
+
+## Command Families
+
+| Family | Commands | Purpose |
+|--------|----------|---------|
+| Bootstrap | `init`, `config`, `health` | create and inspect tracker setup |
+| Triage | `context`, `search`, `list*`, `aggregate`, `dedupe-audit` | find work and audit decomposition |
+| Lifecycle | `create`, `claim`, `update`, `append`, `close`, `release`, `delete` | mutate item state |
+| Logs | `comments`, `notes`, `learnings`, `comments-audit` | record progress and durable context |
+| Links | `files`, `docs`, `test`, `deps` | connect items to artifacts, tests, and relationships |
+| Verification | `test`, `test-all`, `test-runs`, `validate`, `gc` | run linked tests and repository checks |
+| History | `history`, `activity`, `restore`, `stats` | inspect and recover item state |
+| Calendar | `calendar`, `cal` | project deadlines, reminders, and events |
+| Extensions | `extension`, extension command groups | install, manage, and run extension commands |
+| Machines | `contracts`, `completion`, `help` | expose stable command contracts and shell helpers |
+
+## Bootstrap
+
+```bash
+pm init
+pm config project list
+pm health --check-only
+```
+
+`pm init` creates `.agents/pm`. `pm health --check-only` inspects without refreshing optional search artifacts.
+
+## Triage
+
+```bash
+pm context --limit 10
+pm search "calendar reminder validation" --limit 10
+pm list-open --type Task --priority 1 --limit 20
+pm list-in-progress --limit 20
+pm aggregate --group-by parent,type --status open
+pm dedupe-audit --mode parent_scope --limit 20
+```
+
+Use `context` first for a compact active-work snapshot. Use `search` when the request names a concept, component, or prior issue.
+
+## Create and Update
+
+Minimal progressive create:
+
+```bash
+pm create \
+  --title "Document command contracts" \
+  --description "Add command contract examples for agents." \
+  --type Task \
+  --status open \
+  --priority 1 \
+  --create-mode progressive
+```
+
+Strict create is best when metadata is ready:
+
+```bash
+pm create \
+  --title "Fix restore replay" \
+  --description "Restore should replay patches through the target version." \
+  --type Issue \
+  --status open \
+  --priority 1 \
+  --tags "restore,history" \
+  --ac "Restore reproduces the target state and has regression coverage." \
+  --message "Create restore replay issue"
+```
+
+Update existing work:
+
+```bash
+pm update <id> --status in_progress --message "Start implementation"
+pm update <id> --deadline +1d --estimate 120
+pm update <id> --parent <parent-id>
+pm append <id> --body "Detailed implementation notes."
+```
+
+Use `pm close <id> "<reason>"` instead of `pm update --status closed`.
+
+## Ownership
+
+```bash
+pm claim <id>
+pm release <id>
+pm release <id> --allow-audit-release --author <you>
+```
+
+`claim` is the normal start signal. Use `--force` only when explicitly overriding terminal-state or lock conflicts.
+
+## Logs
+
+```bash
+pm comments <id> "Implemented command parsing fix."
+pm notes <id> --add "Keep renderer changes isolated to TOON output."
+pm learnings <id> --add "Use runtime contracts instead of duplicating flag lists."
+```
+
+Use comments for progress and evidence, notes for implementation context, and learnings for durable future guidance.
+
+## Linked Artifacts
+
+```bash
+pm files <id> --add path=src/cli/main.ts,scope=project,note="command wiring"
+pm files <id> --add-glob "src/cli/**/*.ts"
+pm docs <id> --add path=docs/COMMANDS.md,scope=project,note="public command docs"
+pm deps <id> --format tree
+```
+
+Linked files and docs keep reviews reproducible. `deps` is read-only and projects item relationships.
+
+## Linked Tests
+
+```bash
+pm test <id> --add command="node scripts/run-tests.mjs test -- tests/unit/output.spec.ts",scope=project,timeout_seconds=240
+pm test <id> --run --progress
+pm test-all --status in_progress --progress
+```
+
+Linked test commands should be sandbox-safe. Prefer `node scripts/run-tests.mjs ...` because it sets temporary `PM_PATH` and `PM_GLOBAL_PATH`.
+
+Strict linked-test guards:
+
+```bash
+pm test <id> --run \
+  --check-context \
+  --fail-on-context-mismatch \
+  --fail-on-skipped \
+  --require-assertions-for-pm
+```
+
+## Calendar and Context
+
+```bash
+pm calendar --view week --date today --full-period
+pm calendar --from today --to +7d --include deadlines,reminders,events
+pm context --from today --to +7d --limit 10
+```
+
+`calendar` defaults to markdown for human and agent readability. Other commands default to TOON unless configured otherwise.
+
+## Validation and Maintenance
+
+```bash
+pm validate --check-resolution --check-history-drift
+pm validate --check-files --scan-mode tracked-all
+pm normalize --dry-run --json
+pm gc --dry-run
+```
+
+Use dry-run modes before broad lifecycle or cleanup changes.
+
+## History and Recovery
+
+```bash
+pm history <id> --limit 20
+pm history <id> --diff --verify
+pm activity --id <id> --limit 50
+pm restore <id> <timestamp-or-version>
+```
+
+History is append-only. Restore appends a new restore event instead of rewriting old history.
+
+## Machine Contracts
+
+```bash
+pm contracts --json
+pm contracts --command create --flags-only --json
+pm contracts --action create --schema-only --json
+pm help create --json
+```
+
+Agents should use runtime contracts instead of hard-coding flag lists. Contract output includes extension-provided command surfaces when active.
+
+## Completion
+
+```bash
+pm completion bash
+pm completion zsh
+pm completion fish
+```
+
+Generated completions resolve tags lazily by default. Use `--eager-tags` only when embedding static tags is required.

package/docs/CONFIGURATION.md

@@ -0,0 +1,146 @@
+# Configuration
+
+`pm` reads settings from the project tracker root and optional global profile. Use this page for public, user-facing configuration. Use `pm config ... list` and `pm config ... export` for the active runtime shape.
+
+## Agent Quick Context
+
+- Do not override `PM_PATH` for real repository tracking.
+- Do set `PM_AUTHOR` for maintainer and agent mutations.
+- Use `--json` only when strict parsing is needed.
+- Use `pm contracts` for current command/schema metadata.
+
+Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
+
+## Configuration Commands
+
+```bash
+pm config project list
+pm config project export --json
+pm config project get item-format --json
+pm config project set item-format --format toon
+pm config project set test-result-tracking --policy enabled
+```
+
+Scopes:
+
+- `project` updates `.agents/pm/settings.json`.
+- `global` updates the global profile under `PM_GLOBAL_PATH` or the default global root.
+
+Precedence:
+
+1. CLI flags
+2. environment variables
+3. project settings
+4. global settings
+5. built-in defaults
+
+## Common Settings
+
+| Setting | Purpose |
+|---------|---------|
+| `id_prefix` | generated item ID prefix, default `pm-` |
+| `author_default` | fallback mutation author |
+| `item_format` | `toon` or `json_markdown` item files |
+| `output.default_format` | default renderer, usually `toon` |
+| `locks.ttl_seconds` | stale lock threshold |
+| `history.missing_stream` | `auto_create` or `strict_error` |
+| `testing.record_results_to_items` | persist bounded linked-test summaries |
+| `validation.sprint_release_format` | `warn` or `strict_error` |
+| `validation.parent_reference` | `warn` or `strict_error` |
+| `item_types.definitions[]` | custom item types and type options |
+| `search.*` | search mode, scoring, providers, and vector settings |
+
+## Environment Variables
+
+| Variable | Use |
+|----------|-----|
+| `PM_AUTHOR` | explicit mutation author |
+| `PM_PATH` | override project tracker root for tests or sandboxes |
+| `PM_GLOBAL_PATH` | override global profile root for tests or sandboxes |
+| `PM_OLLAMA_MODEL` | choose default Ollama embedding model |
+| `PM_DISABLE_OLLAMA_AUTO_DEFAULTS` | disable implicit Ollama search defaults |
+
+Tests should set both `PM_PATH` and `PM_GLOBAL_PATH` to temporary directories. The wrapper `node scripts/run-tests.mjs ...` does that automatically.
+
+## Item Storage Format
+
+TOON is the default:
+
+```bash
+pm config project set item-format --format toon
+```
+
+JSON-front-matter markdown is also supported:
+
+```bash
+pm config project set item-format --format json_markdown
+```
+
+Changing item format runs migration on item files. History stays JSONL.
+
+## Output Format
+
+Most commands default to sparse TOON:
+
+```bash
+pm list-open --limit 10
+```
+
+Use JSON for strict machine parsing:
+
+```bash
+pm get <id> --json
+pm contracts --json
+```
+
+`pm calendar` defaults to markdown because date-centric summaries are easier to scan in that format.
+
+## Validation Policies
+
+```bash
+pm config project set sprint-release-format-policy --policy warn
+pm config project set parent-reference-policy --policy strict_error
+pm config project set history-missing-stream-policy --policy auto_create
+pm config project set test-result-tracking --policy enabled
+```
+
+Use standalone checks when validating a repository:
+
+```bash
+pm validate --check-resolution --check-history-drift
+pm validate --check-files --scan-mode tracked-all
+pm health --check-only
+```
+
+## Search Configuration
+
+Keyword search is always available:
+
+```bash
+pm search "release docs" --mode keyword --limit 10
+```
+
+Semantic and hybrid search can use built-in OpenAI-compatible or Ollama providers plus vector stores such as Qdrant or LanceDB. If local Ollama is available and semantic settings are unset, `pm` can resolve local defaults automatically.
+
+Useful commands:
+
+```bash
+pm search "calendar reminders" --mode hybrid --limit 10
+pm reindex --mode hybrid --progress
+pm health --check-only
+```
+
+## Custom Item Types
+
+Custom item types can be defined in settings and by extensions. Runtime type resolution affects create/update validation, list/search/calendar filters, completions, and storage folders.
+
+Use runtime contracts for exact active types:
+
+```bash
+pm contracts --json
+pm create --help --type Task
+```
+
+## Public Documentation Boundary
+
+Public docs should describe supported user configuration only. Ignored local operations material, unpublished evidence logs, credentials, hostnames, and private service details must stay outside tracked docs and package output.