@pcircle/footprint 1.5.0 → 1.7.0

package/README.md

@@ -3,195 +3,364 @@
 [![npm version](https://img.shields.io/npm/v/@pcircle/footprint)](https://www.npmjs.com/package/@pcircle/footprint)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-MCP server that automatically captures and encrypts AI conversations as verifiable records with Git timestamps and end-to-end encryption.
+Read in:
+[English](../../README.md)
+|
+[繁體中文](../../README.zh-TW.md)
+|
+[日本語](../../README.ja.md)
 
-## Why Footprint?
+Project site:
+[footprint.memesh.ai](https://footprint.memesh.ai/)
 
-- **Prove IP Ownership** — Timestamped evidence of AI-assisted work
-- **Zero Effort** — Automatic capture via MCP protocol
-- **Privacy First** — End-to-end encrypted, locally stored
-- **Legally Valid** — Git timestamps + SHA-256 checksums
+`@pcircle/footprint` is a local-first MCP server for AI-assisted work continuity. It gives you one place to:
+
+- keep a usable history of ongoing AI-assisted work, including context memory and handoff-friendly summaries
+- preserve specific conversations as encrypted evidence when they need verification and export
+
+It is open source. No seats, no usage pricing, and no hosted-memory lock-in.
+
+The session recorder preserves raw transcript and timeline data first, then derives artifacts, narratives, decisions, and user-correctable context threads from that source history.
+
+Interactive sessions use `script`-backed PTY transport on BSD/macOS and Linux. BSD/macOS replays native `script -r` transcripts, while Linux replays util-linux advanced timing logs so transcript attribution stays consistent across platforms.
+
+## Start Here
+
+If you are new to Footprint, use this order:
+
+1. [Open the project site](https://footprint.memesh.ai/) and look at the product screenshots first.
+2. Run `npx @pcircle/footprint setup` to try it quickly, or install the CLI with `npm install -g @pcircle/footprint`.
+3. If you are still using the quick `npx` path, open the local product with `npx @pcircle/footprint demo --open`. If you installed the CLI, use `footprint demo --open`.
+4. Start recording real work with `footprint run ...`.
 
 ## Quick Start
 
+If you only want to see the product locally first:
+
 ```bash
 npx @pcircle/footprint setup
+npx @pcircle/footprint demo --open
 ```
 
-The interactive wizard auto-detects your system, validates your encryption password, and configures Claude Desktop automatically.
+If you want the CLI installed for repeated use:
 
-### Manual Configuration
+```bash
+npm install -g @pcircle/footprint
+footprint setup
+```
 
-Add to Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+If you want to start recording live CLI work immediately:
 
-```json
-{
-  "mcpServers": {
-    "footprint": {
-      "command": "npx",
-      "args": ["@pcircle/footprint"],
-      "env": {
-        "FOOTPRINT_DATA_DIR": "/path/to/footprint-data",
-        "FOOTPRINT_PASSPHRASE": "your-secure-passphrase"
-      }
-    }
-  }
-}
+```bash
+footprint run claude -- <args...>
+footprint run gemini -- <args...>
+footprint run codex -- <args...>
 ```
 
-For Claude Code, add to `~/.claude/mcp_settings.json` with the same structure.
+If you want Footprint to suggest the right context before a run begins:
 
-## MCP Tools (9 tools)
+```bash
+footprint run codex --prepare-context -- <args...>
+```
 
-### capture-footprint
+### Choose Your Next Read
 
-Capture and encrypt an LLM conversation. Use when: user explicitly asks to save, or high-value content (IP, legal, business, research, compliance).
+- Install and first-run setup:
+  [Getting Started](../../docs/getting-started.md)
+- Environment and deployment details:
+  [Configuration](../../docs/configuration.md)
+- MCP tool walkthrough:
+  [MCP Tools Overview](../../docs/mcp-tools.md)
+- Full docs map:
+  [Docs Index](../../docs/README.md)
 
-| Parameter        | Required | Description                                                        |
-| ---------------- | -------- | ------------------------------------------------------------------ |
-| `conversationId` | Yes      | Unique ID, format: `{topic}-{descriptor}-{YYYY-MM-DD}`             |
-| `content`        | Yes      | Full conversation text including both human and assistant messages |
-| `tags`           | No       | Comma-separated tags                                               |
-| `llmProvider`    | No       | Provider name (default: `"unknown"`)                               |
-| `messageCount`   | No       | Number of messages (auto-calculated from content if omitted)       |
+### Install And Configure
 
-### list-footprints
+```bash
+npx @pcircle/footprint setup
+```
 
-List all captured evidence with pagination.
+Persistent install:
 
-| Parameter | Required | Description                    |
-| --------- | -------- | ------------------------------ |
-| `limit`   | No       | Results per page (default: 10) |
-| `offset`  | No       | Pagination offset              |
-| `tags`    | No       | Filter by tags                 |
+```bash
+npm install -g @pcircle/footprint
+footprint setup
+```
 
-### get-footprint
+The setup wizard:
 
-Retrieve and decrypt specific evidence by ID.
+- creates the local data directory
+- validates the passphrase
+- configures Claude Desktop when available
+- optionally appends environment variables to the active shell rc file
 
-| Parameter | Required | Description |
-| --------- | -------- | ----------- |
-| `id`      | Yes      | Evidence ID |
+Node.js `>=22` is required.
 
-### search-footprints
+If you stay on the quick `npx` path, use `npx @pcircle/footprint ...` for later commands too. The bare `footprint` command is only available after a global install.
 
-Search conversations by query, tags, and date range. Query matches conversationId and tags (LIKE). Tags filter uses AND logic.
+### Open The Local Live Product
 
-| Parameter  | Required | Description                    |
-| ---------- | -------- | ------------------------------ |
-| `query`    | No       | Search text                    |
-| `tags`     | No       | Array of tags (AND logic)      |
-| `dateFrom` | No       | Start date (ISO 8601)          |
-| `dateTo`   | No       | End date (ISO 8601)            |
-| `limit`    | No       | Results per page (default: 10) |
-| `offset`   | No       | Pagination offset              |
+```bash
+npx @pcircle/footprint demo
+```
 
-### export-footprints
+If you installed the CLI globally, use `footprint demo` or `footprint demo --open`.
 
-Export evidence to encrypted ZIP archive.
+This starts a local browser-facing surface for the current Footprint database and prints a localhost URL for:
 
-| Parameter     | Required | Description                                           |
-| ------------- | -------- | ----------------------------------------------------- |
-| `evidenceIds` | No       | Specific IDs to export (all if omitted)               |
-| `outputMode`  | No       | `"file"`, `"base64"`, or `"both"` (default: `"both"`) |
+- the session dashboard
+- deep-linked session detail pages
+- context review and correction flows
+- export and handoff interactions
 
-### verify-footprint
+Optional flags:
 
-Verify evidence integrity using stored checksums and Git timestamps.
+```bash
+footprint demo --host 127.0.0.1 --port 4310
+footprint demo --open
+```
 
-| Parameter | Required | Description |
-| --------- | -------- | ----------- |
-| `id`      | Yes      | Evidence ID |
+Repo-local shortcut:
 
-Returns: `integrityVerified`, `checksumValid`, `gitTimestamp`
+```bash
+pnpm --dir packages/mcp-server demo:live
+```
 
-### delete-footprints
+Recorder inspection commands:
 
-Permanently delete evidence records. Uses two-step confirmation.
+```bash
+footprint sessions list [--query "<text>"] [--issue-key "<issue-key>"] [--host <claude|gemini|codex>] [--status <running|completed|failed|interrupted>]
+footprint session show <session-id> [--message-limit <n>] [--message-offset <n>] [--trend-limit <n>] [--trend-offset <n>] [--timeline-limit <n>] [--timeline-offset <n>] [--artifact-limit <n>] [--artifact-offset <n>] [--narrative-limit <n>] [--narrative-offset <n>] [--decision-limit <n>] [--decision-offset <n>]
+footprint session ingest <session-id>
+footprint session export <session-id> [--group-by <issue|family>]
+footprint session messages <session-id> [--limit <n>] [--offset <n>]
+footprint session trends <session-id> [--limit <n>] [--offset <n>]
+footprint session timeline <session-id> [--limit <n>] [--offset <n>]
+footprint session artifacts <session-id> [--limit <n>] [--offset <n>]
+footprint session narratives <session-id> [--kind <journal|project-summary|handoff>] [--limit <n>] [--offset <n>]
+footprint session decisions <session-id> [--limit <n>] [--offset <n>]
+footprint history search "<query>" [--host <claude|gemini|codex>] [--status <running|completed|failed|interrupted>]
+footprint history trends [--query "<text>"] [--issue-key "<issue-key>"] [--host <claude|gemini|codex>] [--status <running|completed|failed|interrupted>] [--group-by <issue|family>]
+footprint history handoff [--query "<text>"] [--issue-key "<issue-key>"] [--host <claude|gemini|codex>] [--status <running|completed|failed|interrupted>] [--group-by <issue|family>]
+```
 
-| Parameter       | Required | Description                                          |
-| --------------- | -------- | ---------------------------------------------------- |
-| `evidenceIds`   | Yes      | Array of evidence IDs                                |
-| `confirmDelete` | No       | Set `true` to confirm (default: `false` for preview) |
+Context memory commands:
 
-### suggest-capture
+```bash
+footprint contexts list
+footprint context resolve [--session <session-id>] [--cwd <path>] [--title "<text>"] [--host <claude|gemini|codex>]
+footprint context prepare [--session <session-id>] [--cwd <path>] [--title "<text>"] [--host <claude|gemini|codex>] [--interactive] [--json]
+footprint context show <context-id>
+footprint context confirm <session-id> [<session-id> ...] [--context <context-id>] [--label "<label>"] [--set-preferred]
+footprint context reject <session-id> --context <context-id>
+footprint context move <session-id> [--context <context-id>] [--label "<label>"] [--set-preferred]
+footprint context merge <source-context-id> <target-context-id>
+footprint context split <context-id> --sessions <session-id,session-id,...> [--label "<label>"] [--set-preferred]
+footprint context activate <context-id> [--cwd <path>]
+footprint demo [--host <address>] [--port <number>] [--open]
+```
 
-AI-powered capture suggestion based on keyword analysis.
+Compatibility aliases:
 
-| Parameter | Required | Description                     |
-| --------- | -------- | ------------------------------- |
-| `content` | Yes      | Conversation content to analyze |
+```bash
+footprint list-sessions [--query "<text>"] [--issue-key "<issue-key>"] [--host <claude|gemini|codex>] [--status <running|completed|failed|interrupted>]
+footprint get-session <session-id> [--message-limit <n>] [--message-offset <n>] [--trend-limit <n>] [--trend-offset <n>] [--timeline-limit <n>] [--timeline-offset <n>] [--artifact-limit <n>] [--artifact-offset <n>] [--narrative-limit <n>] [--narrative-offset <n>] [--decision-limit <n>] [--decision-offset <n>]
+footprint export-sessions [<session-id> ...] [--query "<text>"] [--issue-key "<issue-key>"] [--host <claude|gemini|codex>] [--status <running|completed|failed|interrupted>] [--group-by <issue|family>]
+footprint get-session-messages <session-id> [--limit <n>] [--offset <n>]
+footprint get-session-trends <session-id> [--limit <n>] [--offset <n>]
+footprint get-session-timeline <session-id> [--limit <n>] [--offset <n>]
+footprint get-session-artifacts <session-id> [--limit <n>] [--offset <n>]
+footprint get-session-narrative <session-id> [--kind <journal|project-summary|handoff>] [--limit <n>] [--offset <n>]
+footprint get-session-decisions <session-id> [--limit <n>] [--offset <n>]
+footprint search-history "<query>" [--host <claude|gemini|codex>] [--status <running|completed|failed|interrupted>]
+footprint get-history-trends [--query "<text>"] [--issue-key "<issue-key>"] [--host <claude|gemini|codex>] [--status <running|completed|failed|interrupted>] [--group-by <issue|family>]
+footprint get-history-handoff [--query "<text>"] [--issue-key "<issue-key>"] [--host <claude|gemini|codex>] [--status <running|completed|failed|interrupted>] [--group-by <issue|family>]
+footprint list-contexts
+footprint get-context <context-id>
+footprint resolve-context [--session <session-id>] [--cwd <path>] [--title "<text>"] [--host <claude|gemini|codex>]
+footprint prepare-context [--session <session-id>] [--cwd <path>] [--title "<text>"] [--host <claude|gemini|codex>] [--interactive] [--json]
+footprint confirm-context-link <session-id> [<session-id> ...] [--context <context-id>] [--label "<label>"] [--set-preferred]
+footprint reject-context-link <session-id> --context <context-id>
+footprint move-session-context <session-id> [--context <context-id>] [--label "<label>"] [--set-preferred]
+footprint merge-contexts <source-context-id> <target-context-id>
+footprint split-context <context-id> --sessions <session-id,session-id,...> [--label "<label>"] [--set-preferred]
+footprint set-active-context <context-id> [--cwd <path>]
+```
 
-### manage-tags
+Add `--json` to the query commands above when you want scriptable output.
 
-Unified tag management with three actions: `stats`, `rename`, `remove`.
+### Run As An MCP Server
 
-| Parameter | Required   | Description                           |
-| --------- | ---------- | ------------------------------------- |
-| `action`  | Yes        | `"stats"` \| `"rename"` \| `"remove"` |
-| `tag`     | For remove | Tag to remove                         |
-| `oldTag`  | For rename | Current tag name                      |
-| `newTag`  | For rename | New tag name                          |
+When invoked without a CLI subcommand, Footprint starts the MCP server on stdio.
 
-## MCP Prompts (3 prompts)
+## Product Surfaces
 
-- **`footprint-skill`** — Full agent behavior guide (decision tree, triggers, workflows, error recovery)
-- **`footprint-quick-ref`** — Condensed quick reference for tool selection and tag conventions
-- **`footprint-should-capture`** — Semantic decision framework for evaluating capture worthiness (takes `conversationSummary` argument)
+### Session History And Context Memory
 
-## Architecture
+Use the recorder when you care about staying in the right line of work, seeing what happened, and handing it off cleanly:
 
+- ordered user and assistant transcript
+- wrapper and adapter timeline events
+- command and test activity with richer command intent classification
+- file and git changes
+- conservative context-thread suggestions for new or resumed sessions
+- canonical context briefings with current truth, blockers, open questions, active decisions, and superseded decisions
+- correction operations so users can confirm, reject, move, merge, split, and prefer contexts instead of accepting black-box auto-linking
+- cross-session issue trends built from execution-backed retries and failures, with optional broader failure-family grouping
+- derived narratives and decisions, including retry-aware handoff summaries and clustered issue rollups
+- downloadable ZIP handoff bundles with raw and derived session state
+
+Primary MCP tools:
+
+- `list-sessions`
+- `list-contexts`
+- `get-context`
+- `resolve-context`
+- `confirm-context-link`
+- `reject-context-link`
+- `move-session-context`
+- `merge-contexts`
+- `split-context`
+- `set-active-context`
+- `get-session`
+- `export-sessions`
+- `get-session-messages`
+- `get-session-trends`
+- `get-session-timeline`
+- `get-session-artifacts`
+- `get-session-narrative`
+- `get-session-decisions`
+- `search-history`
+- `get-history-trends`
+- `get-history-handoff`
+- `reingest-session`
+
+Primary UI resources:
+
+- `ui://footprint/session-dashboard.html`
+- `ui://footprint/session-detail.html`
+
+The session dashboard now combines recent sessions, confirmed canonical contexts, a handoff-oriented scope summary, pinned `search-history` matches, and recurring execution-backed issue trends. It supports interactive query, issue key, host, status, and trend-grouping filters; search, handoff, trend, and context cards can drill directly into session detail or tighten the current dashboard investigation scope. The dashboard now also paginates recent sessions, search matches, and recurring trends with server-backed `limit` / `offset` calls instead of truncating large histories in the client. Those query and search surfaces are now backed by cached SQLite history indexes, so large histories do not require a full JavaScript detail scan just to filter, count, or aggregate matching sessions. The dashboard can also export the current filtered session set directly as a ZIP bundle. The session detail surface now renders recurring trend context for the current session, including the latest related sessions for each recurring issue so investigators can jump across retries without going back to the dashboard, and `footprint session show --json` / `get-session` include the same server-backed trend summary. Trend and handoff surfaces now carry blocker state plus remediation tracking, so repeated failures can be distinguished from recovered or regressed clusters instead of only reporting the latest outcome string. `get-session` now returns paginated transcript, recurring-trend, and timeline slices with page metadata, while `get-session-messages`, `get-session-trends`, `get-session-timeline`, `get-session-artifacts`, `get-session-narrative`, `get-session-decisions`, and the matching CLI commands support `--limit` / `--offset` for large-session inspection. `footprint session show` / `footprint get-session` also expose trend, artifact, narrative, and decision preview pagination through `--trend-*`, `--artifact-*`, `--narrative-*`, and `--decision-*` flags so the condensed CLI view does not need to materialize full derived histories just to render a handoff preview. Deterministic artifact metadata now also carries dependency actions, dependency names, failure signatures, lint rule IDs, test suite/case identifiers, and manifest or lockfile scope so CLI, MCP, UI, and export flows can expose richer execution context without reparsing raw transcript text. Semantic project summaries and handoff narratives now consume that metadata directly, so recurring clusters and dependency changes are described with concrete lint rules, failing test cases, dependency install targets, and manifest/lockfile updates instead of only generic command labels. The human-readable `footprint session show` output is now a condensed handoff/debug report with recurring trend, artifact, decision, and transcript/timeline previews instead of a raw full-session dump. From that detail surface, investigators can now load cross-session issue or family handoff summaries, review the currently linked canonical context, confirm or reject suggested context candidates, move a session into another context, set the preferred workspace context, load more trend/artifact/transcript/timeline/narrative/decision slices on demand, and export either the current session or the selected scope directly as a ZIP archive. The new context-memory layer uses that same session history to suggest likely canonical contexts, but it never auto-links canonical membership without an explicit confirm action. `resolve-context` returns candidates, confidence, reasons, and `confirmationRequired` so an agent host or interactive CLI can ask the user when evidence is ambiguous. `footprint context prepare --interactive` and `footprint run ... --prepare-context` are the shell-side bridge for that contract: they prompt before the session continues, confirm the chosen context, and then record `context.resolved` / `context.updated` timeline events without requiring the MCP server itself to block on user input. Once confirmed, `get-context` returns the latest valid direction for that context plus blockers, open questions, active decisions, superseded decisions, and the recent session trail. `get-history-handoff` / `footprint history handoff` summarize blockers, recoveries, follow-ups, and recent sessions for the current scope while following the same `issue` vs `family` grouping mode as `get-history-trends`; both surfaces now aggregate from materialized trend-attempt rows instead of rebuilding each session’s derived tree on demand. `get-history-trends` and `footprint history trends` now support `groupBy=family` / `--group-by family` when exact issue keys are too fine-grained. Export bundles now include machine-readable JSON snapshots, top-level recurring trend and history-handoff summaries, human-readable `history-handoff.md`, per-session `handoff.md` / `transcript.md` files, the selected `historyGrouping`, and manifest selection metadata when the export was created from filters.
+
+### Encrypted Evidence
+
+Use the evidence flow when you need a discrete preserved record of a conversation.
+
+Primary MCP tools:
+
+- `capture-footprint`
+- `list-footprints`
+- `get-footprint`
+- `search-footprints`
+- `export-footprints`
+- `verify-footprint`
+- `delete-footprints`
+- `manage-tags`
+- `suggest-capture`
+
+Primary UI resources:
+
+- `ui://footprint/dashboard.html`
+- `ui://footprint/detail.html`
+- `ui://footprint/export.html`
+
+## Manual MCP Configuration
+
+Claude Desktop example:
+
+```json
+{
+  "mcpServers": {
+    "footprint": {
+      "command": "npx",
+      "args": ["@pcircle/footprint"],
+      "env": {
+        "FOOTPRINT_DATA_DIR": "/path/to/footprint-data",
+        "FOOTPRINT_PASSPHRASE": "your-secure-passphrase"
+      }
+    }
+  }
+}
 ```
-packages/mcp-server/
-├── src/
-│   ├── index.ts              # Main MCP server
-│   ├── prompts/              # MCP prompt handlers
-│   │   └── skill-prompt.ts
-│   ├── tools/                # MCP tool handlers (9 tools)
-│   │   ├── capture-footprint.ts
-│   │   ├── list-footprints.ts
-│   │   ├── get-footprint.ts
-│   │   ├── search-footprints.ts
-│   │   ├── export-footprints.ts
-│   │   ├── verify-footprint.ts
-│   │   ├── delete-footprints.ts
-│   │   ├── suggest-capture.ts
-│   │   └── manage-tags.ts
-│   ├── analyzers/            # Content analysis
-│   ├── cli/                  # Setup wizard
-│   ├── lib/
-│   │   ├── crypto/           # XChaCha20-Poly1305 + Argon2id
-│   │   └── storage/          # SQLite + Git timestamps
-│   └── ui/                   # Interactive dashboards
-└── tests/
-```
 
-## Security
+For Claude Code, use the same server definition in `~/.claude/mcp_settings.json`.
+
+## Storage Model
+
+Footprint uses one local SQLite database with three logical models:
+
+- evidence tables for encrypted conversation capture
+- session-history tables for recorder transcript, events, artifacts, narratives, and decisions
+- context tables for canonical context threads, explicit corrections, and workspace preferences
+
+Evidence content is encrypted at rest. Session history is preserved as raw transcript plus raw timeline, derived views can be regenerated through `reingest-session`, and session exports package both raw and derived views into a portable ZIP archive. Context threading is suggestion-first and correction-driven: unresolved sessions stay isolated until the user confirms a canonical link. Cross-session filtering is backed by cached session-history text and exact issue-key rows inside SQLite so search and list surfaces stay incremental as histories grow.
+
+## Architecture
+
+Key runtime components:
+
+- MCP server registration in `src/index.ts`
+- CLI setup and recorder runtime in `src/cli/`
+- host adapters in `src/adapters/`
+- deterministic and semantic ingestion in `src/ingestion/`
+- SQLite schema and persistence in `src/lib/storage/`
+- MCP app resource registration in `src/ui/register.ts`
+
+Further reading:
+
+- [Architecture](./ARCHITECTURE.md)
+- [Docs Index](../../docs/README.md)
 
-- **Encryption**: XChaCha20-Poly1305 (256-bit)
-- **Key Derivation**: Argon2id (OWASP recommended)
-- **Storage**: Local SQLite with encrypted BLOBs
-- **No cloud, no tracking, no data collection**
+## Prompts
 
-> **Store your password securely** — loss means permanent data loss.
+Footprint also registers three prompts for MCP clients:
+
+- `footprint-skill`
+- `footprint-quick-ref`
+- `footprint-should-capture`
 
 ## Development
 
+Build and test:
+
+```bash
+pnpm --dir packages/mcp-server build
+pnpm --dir packages/mcp-server demo:live
+pnpm --dir packages/mcp-server test:pack-smoke
+pnpm --dir packages/mcp-server test:publish-gate
+pnpm --dir packages/mcp-server test:real-host-smoke
+# macOS only, requires python3 on PATH
+pnpm --dir packages/mcp-server test:macos-smoke
+pnpm --dir packages/mcp-server test:run
+pnpm --dir packages/mcp-server test:linux-smoke
+pnpm --dir packages/mcp-server test:browser
+```
+
+UI-only build:
+
 ```bash
-git clone https://github.com/PCIRCLE-AI/footprint.git
-cd footprint
-pnpm install
-pnpm build
-pnpm test
+pnpm --dir packages/mcp-server build:ui
 ```
 
-## Support
+Repository CI now runs Ubuntu and macOS jobs: Ubuntu covers install, lint, tarball install smoke, the default Vitest suite, the Linux PTY smoke path, browser-mode session UI tests, and the package publish gate; macOS covers recorder-focused PTY tests plus a real BSD `script -r` smoke path.
+
+`pnpm --dir packages/mcp-server test:publish-gate` is the package-level release check. It runs audit, build, the package Vitest suite, and the tarball install smoke so `prepublishOnly` blocks releases that are not installable from the packed artifact.
+
+Releases now have two supported paths:
+
+- local maintainer publish with `npm login` then `pnpm release:npm`
+- GitHub Actions publish through `.github/workflows/npm-publish.yml`
+
+Schema upgrades are exercised through legacy `v3` / `v4` / `v6` database fixtures, and older databases now backfill materialized history caches and trend-attempt rows during upgrade instead of waiting for the first query to discover missing rows.
+
+`pnpm --dir packages/mcp-server test:real-host-smoke` is an optional manual validation pass. It discovers installed `claude`, `gemini`, and `codex` binaries, skips hosts that are missing, and for hosts that are present it records a real `--version` session and verifies the stored transcript and recorder metadata.
 
-- [GitHub](https://github.com/PCIRCLE-AI/footprint)
-- [Issues](https://github.com/PCIRCLE-AI/footprint/issues)
-- [npm](https://www.npmjs.com/package/@pcircle/footprint)
-- [Website](https://footprint.memesh.ai)
+Set `FOOTPRINT_DEBUG_PERF=1` when you want lightweight timing traces for reingest, history query, and export paths while debugging large session sets.
 
-## License
+## Links
 
-MIT License — see [LICENSE](./LICENSE) for details.
+- Repository: <https://github.com/PCIRCLE-AI/footprint-mcp>
+- Package: <https://www.npmjs.com/package/@pcircle/footprint>
+- Project site: <https://footprint.memesh.ai/>
+- Homepage: <https://footprint.memesh.ai>
+- Issues: <https://github.com/PCIRCLE-AI/footprint-mcp/issues>