prjct-cli 2.23.1 → 2.23.3

package/README.md

@@ -35,15 +35,39 @@ curl -sSL https://raw.githubusercontent.com/jlopezlira/prjct-cli/main/scripts/in
 
 The script auto-detects platform (mac arm64/intel + linux x64), downloads the right binary from GitHub Releases, sets up `~/.local/bin/prjct` on your PATH, runs `prjct setup` + `prjct sync`, and warns you if a stale package-manager install is shadowing the new binary.
 
-### After install — three upgrade paths
+### Updating prjct (built-in)
 
-| Method | Command | When |
-|---|---|---|
-| Re-paste the install prompt | (same prompt above) | Default. Claude re-runs `npm install -g prjct-cli@latest` and re-verifies. |
-| CLI shortcut | `prjct update` | Already in a terminal. Auto-detects npm/pnpm/bun/yarn/homebrew. |
-| Silent (set once) | `prjct config set auto-update on` | Background check 1/hour throttled, logs to `~/.prjct-cli/state/auto-update.log`. |
+prjct updates itself. The canonical command is **`prjct update`**, with
+**`prjct upgrade`** as an identical alias:
+
+```bash
+prjct update            # = prjct upgrade
+prjct update --dry-run  # show exactly what would change, touch nothing
+prjct upgrade --yes     # non-interactive (skip the consolidation prompt)
+```
+
+What it does, in three phases (`core/commands/update.ts`):
 
-Full install + upgrade paths documented in [INSTALL_PROMPT.md](./INSTALL_PROMPT.md).
+1. **Package update** — auto-detects the package manager that owns your install
+   (npm / pnpm / bun / yarn / homebrew), resolves the **true registry-latest**
+   version and pins it exactly (so a stale `@latest` cache can't downgrade you),
+   and migrates a homebrew install to your detected PM if needed.
+2. **Global cleanup & consolidation** — migrates legacy state to SQLite,
+   reinstalls editor commands/config, and **consolidates parallel installs** so
+   you don't end up with shadowing copies in different PM bin dirs.
+3. **Daemon restart** — stops the stale background daemon and respawns it from
+   the freshly installed code.
+
+Flags: `--dry-run`, `--yes`/`-y`, `--cleanup` / `--no-cleanup` (default `auto`),
+`--md` (machine-readable output for agents/CI).
+
+**Knowing an update exists:** prjct checks at most once every 24h (cached, fully
+non-blocking — never delays a command) and, after the command's own output,
+prints a one-line banner: `Update available! x.y.z → a.b.c — Run: prjct upgrade`.
+Or set it and forget it: `prjct config set auto-update on` (throttled background
+check, logs to `~/.prjct-cli/state/auto-update.log`).
+
+Full install + upgrade paths: [INSTALL_PROMPT.md](./INSTALL_PROMPT.md).
 
 ## What you get
 
@@ -86,6 +110,85 @@ Claude Code session                       prjct
 
 State is the source of truth; the vault is recall. New knowledge enters via `prjct remember <type>`, `prjct capture`, or — automatically — the Stop hook's transcript scan.
 
+### Where data actually lives
+
+Not "all in a local `.prjct/` folder" — that's the pre-v1.24.1 model. Three tiers:
+
+| Tier | Location | Commit it? |
+|---|---|---|
+| Config / identity | `<repo>/.prjct/prjct.config.json` (`projectId`, persona) | **Yes** — small, machine-independent |
+| State (source of truth) | `~/.prjct-cli/projects/<projectId>/prjct.db` (SQLite) | No — per-device |
+| Vault (recall snapshot) | `~/Documents/prjct/<slug>/_generated/` (Markdown) | No — regenerated |
+
+Find a project's data: read `projectId` from `.prjct/prjct.config.json`, then the
+DB is `~/.prjct-cli/projects/<projectId>/`, the vault is
+`~/Documents/prjct/<slug>/` (`<slug>` = repo dir name lowercased; `PRJCT_CLI_HOME`
+relocates the global store). Teammates share knowledge via optional cloud sync
+(`prjct login` + `prjct sync`), **not** git — git never carries state. Full
+detail, worktrees, monorepos: **[docs/storage-and-paths.md](./docs/storage-and-paths.md)**.
+
+## Execution environments (zero-config)
+
+The same binary runs in a plain shell, inside Claude Code, in an OpenAI Codex
+sandbox, or in CI — and **detects which, with no configuration**, then adapts
+output accordingly. Here is the actual *how*.
+
+**Mechanism 1 — agent detection** (`core/infrastructure/agent-detector.ts`,
+`isClaudeEnvironment()`). prjct concludes it's inside **Claude** if *any* of
+these is true, evaluated **in this order** (first match wins, result cached for
+the process):
+
+1. env var `CLAUDE_AGENT` or `ANTHROPIC_CLAUDE` is set (Claude's runtime sets it);
+2. `global.mcp` is present **or** `MCP_AVAILABLE` is set (MCP is available);
+3. a `CLAUDE.md` file exists in the current working directory;
+4. a `~/.claude/` directory exists;
+5. the cwd path contains `/.claude/` or `/claude-workspace/`.
+
+If **none** match, prjct falls back to the **Terminal/CLI** profile — that *is*
+the plain-terminal detection: it's the default when no Claude signal is present.
+**OpenAI Codex** is detected separately (`ai-provider.ts`, `detectCodex()`) by
+the **`codex` CLI binary being on `PATH`** (a stray `~/.codex/` alone is not
+enough); Codex's context file is `AGENTS.md`, skills under `~/.codex/skills/`.
+
+**Mechanism 2 — output adaptation** (no flag needed; three independent signals):
+
+- **TTY** (`core/utils/output.ts`, `spin()`): `process.stdout.isTTY` decides the
+  spinner — `true` (human terminal) → animated branded spinner redrawn with `\r`;
+  `false` (Claude Code, Codex, CI, a pipe) → a **single static** `⚡ prjct …`
+  line, no animation.
+- **LLM-context gate** (`core/index.ts`):
+  `isLlmContext = !process.stdin.isTTY || options.md === true || options.json === true`.
+  Commands declared `requiresLlm` refuse to run in a *raw human terminal* unless
+  `--md`/`--json` is passed — inside an agent `stdin.isTTY` is already false, so
+  they run transparently with no flag.
+- **`--md` / `--json`** (any env): an explicit override — strips the branding
+  header/footer, emits machine-structured markdown/JSON.
+
+Every signal (env var, `PATH`, TTY, piped stdio) is something the **host sets on
+its own** — prjct reads those ambient facts instead of asking you to declare
+anything. Full per-environment output table:
+**[docs/environments.md](./docs/environments.md)**.
+
+### What it looks like
+
+In a real terminal — branded, animated, colored:
+
+```text
+$ prjct task "add OAuth refresh"
+⚡ prjct  ✓ Task started: add OAuth refresh
+         branch: task/add-oauth-refresh · status: active
+```
+
+Inside Claude Code / Codex / CI (non-TTY) — the same line, **static** (no
+animation), so logs stay clean. With `--md`, output is plain markdown an agent
+can consume directly:
+
+```text
+$ prjct task "add OAuth refresh" --md
+> Task started: **add OAuth refresh**
+> branch `task/add-oauth-refresh` · status `active`
+```
+
 ## Quick start (post-install)
 
 ```bash
@@ -206,12 +309,12 @@ prjct regen              Full vault rebuild from SQLite
 prjct watch              Auto-sync on file changes
 prjct doctor             Check system health
 prjct hooks <install|uninstall|status>  Git hooks for auto-sync
-prjct context <files|signatures|imports|recent|summary>  Smart context filters
+prjct context <memory|learnings|wiki>  Recall memory / sync the vault
 prjct review-risk        Advisory change-size + delivery-geometry hint (read-only)
 prjct workflow ["config"]  Configure hooks via natural language
 prjct stop / restart     Background daemon control
 prjct login / logout / auth   Cloud sync authentication
-prjct update             Update CLI system-wide
+prjct update             Update CLI system-wide (alias: prjct upgrade)
 prjct --version / --help
 ```
 
@@ -311,12 +414,120 @@ prjct-cli/
 - Node.js 22.22.2+ or Bun 1.0+
 - One of: Claude Code, Gemini CLI, Cursor IDE, Windsurf, OpenAI Codex, Antigravity
 
+## Common questions
+
+**How do I initialize / register a new project?**
+In any git repo, run `prjct sync` (it auto-runs on the first prjct command) or
+`prjct init`. This creates `.prjct/prjct.config.json` with a `projectId`, builds
+the SQLite store at `~/.prjct-cli/projects/<projectId>/`, and generates the vault.
+
+**How do I add a development task?**
+Run `prjct task "<description>"` from the repo. It registers the task in SQLite,
+creates a branch, and marks it active — worked example:
+
+```bash
+$ prjct task "add OAuth refresh"
+⚡ prjct  ✓ Task started: add OAuth refresh
+         branch: task/add-oauth-refresh · status: active
+
+$ prjct tag type:feature domain:auth     # optional: categorize it
+$ prjct status done                       # close it when finished
+$ prjct ship                              # bump version, commit, PR
+```
+
+Inside an agent you don't type the command — say it: `p. task "add OAuth
+refresh"` in Claude Code, `/task "…"` in Cursor/Windsurf. `prjct task` with no
+argument prints the currently active task.
+
+**How do I get AI assistance for a coding problem?**
+Inside Claude Code (or any wired agent) describe the problem in natural
+language — prjct maps the intent to a quality workflow and runs its methodology,
+persisting findings to memory. Concrete examples:
+
+| You say… | Workflow activated | What it does |
+|---|---|---|
+| "review my changes" | `review` | Production Bug Hunt + Completeness Gate over the diff |
+| "investigate why tests flake" | `investigate` | Iron Law — no fix without a root cause first |
+| "is this safe to ship?" | `security` | OWASP Top 10 + STRIDE, concrete exploit per finding |
+| "qa the checkout page" | `qa` | Real browser, atomic fixes, regression tests |
+
+You can also pull project knowledge directly: ask "what patterns does this
+project use?" and the agent reads `~/Documents/prjct/<slug>/_generated/patterns.md`
+instead of grepping source (the lookup-first protocol). Outside an agent, every
+command takes `--md` to emit agent-ready markdown.
+
+**What does prjct output look like in a normal terminal?**
+A branded, **animated** spinner with full colors and interactive prompts (the
+native human experience). See [What it looks like](#what-it-looks-like).
+
+**How do I check for and apply updates?**
+`prjct update` (alias `prjct upgrade`) — auto-detects your package manager, pins
+the true registry-latest, consolidates parallel installs, restarts the daemon.
+A non-blocking 24h-cached banner tells you when one is available. See
+[Updating prjct](#updating-prjct-built-in).
+
+**How does prjct tailor its output for Claude Code specifically?**
+Once it detects Claude (env vars / MCP / `CLAUDE.md` / `~/.claude/`) and sees
+piped stdio (non-TTY), it adapts on every axis, with no flag:
+
+- **Status line** — a single **static** `⚡ prjct …` line instead of the
+  animated, carriage-return-redrawn spinner, so the transcript stays clean.
+- **Prompts** — interactive confirmations are suppressed (nothing blocks on
+  stdin that the agent can't answer).
+- **`requiresLlm` commands** — run transparently (piped stdin means
+  `isLlmContext` is already true; in a raw human terminal they'd refuse without
+  `--md`).
+- **`--md`** — when passed, the branding header/footer is stripped and output is
+  structured markdown the model consumes directly.
+- **Context injection** — the installed hooks feed Claude persona + active task
+  + topical memory at `SessionStart`/`UserPromptSubmit`, and the lookup-first
+  protocol points it at the regenerated vault before it re-reads source.
+
+Full per-environment table: [docs/environments.md](./docs/environments.md).
+
+**What's the output in an OpenAI Codex sandbox?**
+Codex is detected by the `codex` CLI on PATH (context file `AGENTS.md`). The
+sandbox is non-interactive/non-TTY, so prjct emits the same static, prompt-free
+status line as any agent; add `--md` for fully markdown-structured output.
+
+**How do I quickly find the local `.prjct/` directory?**
+It's in your **project repo root** (created by `prjct init` / first `prjct`
+command) and is `.gitignore`d — that's why `git status` never shows it. Find it:
+
+```bash
+ls -la .prjct/                                    # from the repo root
+cat .prjct/prjct.config.json                      # projectId + persona
+ls -la "$(git rev-parse --show-toplevel)/.prjct/" # from any subdirectory
+git check-ignore -v .prjct                         # why git ignores it
+```
+
+The path is always `<repoRoot>/.prjct/` (strictly relative to the project — no
+env var, no global lookup). Read `projectId` from `prjct.config.json` to reach
+the *other* tiers: DB at `~/.prjct-cli/projects/<projectId>/prjct.db`, vault at
+`~/Documents/prjct/<slug>/_generated/` (`PRJCT_CLI_HOME` overrides the global
+base). The in-repo `.prjct/` holds only config, not state — full detail in
+[docs/storage-and-paths.md](./docs/storage-and-paths.md).
+
+**How does prjct detect its environment with no configuration?**
+Every signal is something the host sets itself — Claude exports env vars and
+pipes stdio, Codex puts `codex` on PATH, a real terminal has a TTY, CI doesn't.
+prjct reads those ambient facts (precedence in
+[docs/environments.md](./docs/environments.md)) rather than asking you to declare
+anything.
+
+**Is all project data really in a local `.prjct/` directory? Team/VCS implications?**
+No — only `.prjct/prjct.config.json` (small, **committable** identity) is in the
+repo. State is per-device SQLite under `~/.prjct-cli` (never committed); the
+vault is regenerated. Teams coordinate via optional cloud sync, not git. Full
+tradeoffs: [docs/storage-and-paths.md](./docs/storage-and-paths.md).
+
 ## Links
 
 - [Website](https://prjct.app)
 - [GitHub](https://github.com/jlopezlira/prjct-cli)
 - [npm](https://www.npmjs.com/package/prjct-cli)
 - [Changelog](CHANGELOG.md)
+- [Architecture](./docs/architecture.md) · [Execution environments](./docs/environments.md) · [Storage & paths](./docs/storage-and-paths.md) · [SQLite migration](./docs/sqlite-migration.md)
 
 ## License