@delorenj/pjangler 1.2.33 → 1.3.7

package/README.md

@@ -18,6 +18,77 @@ node dist/index.js --help
 pjangler --help
 ```
 
+## Orienting in a repo
+
+`describe` reads a repo and reports what it actually is — detected type,
+installed subsystems, config files present, and what to do next. It is the
+first call for an agent (or a human) landing somewhere unfamiliar, and it works
+in any repo, 33GOD or not.
+
+```bash
+pjangler describe                # current directory
+pjangler describe ../some-repo
+pjangler describe --json         # machine-parseable, for agent context
+pjangler describe --interactive  # tick off fixable findings, press A to apply
+```
+
+Subsystem presence and subsystem correctness are reported separately: presence
+comes from marker files on disk, parity from the recipe's own audit rules. A
+subsystem that was never installed reads `absent`, not `broken`.
+
+### Last activity, not lifecycle status
+
+Projects report **when work last happened**, not a lifecycle word. The old
+`status` field said `planned` for 22 of 27 registered projects — including ones
+with commits the same day — so it never varied and never informed.
+
+Activity is computed from git at read time, so it cannot go stale and no cron
+has to walk the registry. It spans more than the checked-out branch:
+
+| source | covers |
+| --- | --- |
+| refs | every local branch, remote-tracking branch, and tag |
+| worktrees | every linked worktree's HEAD, including detached ones whose commits are on no ref |
+| uncommitted | working-tree edits that are not committed yet |
+
+The newest of those wins, and the winning source is always reported. Remote
+state reflects your last fetch — nothing here touches the network.
+
+`pjangler project list` orders by that signal, newest work first.
+
+## Shell prompt
+
+`pjangler-prompt` prints one compact line when the working directory is inside a
+pjangler project, and nothing at all when it is not:
+
+```
+pjangler (PJAN) · 3m
+```
+
+It is a separate binary from the main CLI on purpose — the CLI loads the whole
+parity rule set and takes ~52ms to boot, while this runs in ~30ms, well inside
+starship's 500ms budget.
+
+Add it to `~/.config/starship.toml` as a second, project-scoped prompt line:
+
+```toml
+format = "…$all${custom.pjangler}$line_break$character"
+
+[custom.pjangler]
+description = "pjangler project context"
+when = true
+shell = ["sh"]
+symbol = "◆"
+style = "bold purple"
+# The newline lives INSIDE the conditional group, so nothing is emitted —
+# not even a blank line — outside a pjangler project.
+format = "(\n[$symbol $output]($style))"
+command = 'exec pjangler-prompt 2>/dev/null'
+```
+
+`$line_break` must be named explicitly: it is otherwise absorbed by `$all` and
+the extra line lands in the wrong place.
+
 ## MCP server usage
 
 Run over stdio:
@@ -38,6 +109,7 @@ Exposed tools:
 - `pjangler_project_init`
 - `pjangler_project_list`
 - `pjangler_project_show`
+- `pjangler_describe_project`
 - `pjangler_describe_recipe`
 - `pjangler_run_recipe`
 - `pjangler_deploy_hermes_agent`