@pcircle/footprint 1.5.0 → 1.6.0

package/LICENSE

@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/README.md

@@ -3,168 +3,243 @@
 [![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.
+Project site: [footprint.memesh.ai](https://footprint.memesh.ai/)
 
-## Why Footprint?
+`@pcircle/footprint` is a local-first MCP server for AI-assisted work continuity. It gives you one place to:
 
-- **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
+- 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...>
+```
+
+If you want Footprint to suggest the right context before a run begins:
+
+```bash
+footprint run codex --prepare-context -- <args...>
+```
+
+### Install And Configure
+
+```bash
+npx @pcircle/footprint setup
+```
+
+Persistent install:
+
+```bash
+npm install -g @pcircle/footprint
+footprint setup
+```
+
+The setup wizard:
+
+- creates the local data directory
+- validates the passphrase
+- configures Claude Desktop when available
+- optionally appends environment variables to the active shell rc file
+
+Node.js `>=22` is required.
+
+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.
+
+### Open The Local Live Product
+
+```bash
+npx @pcircle/footprint demo
 ```
 
-For Claude Code, add to `~/.claude/mcp_settings.json` with the same structure.
+If you installed the CLI globally, use `footprint demo` or `footprint demo --open`.
 
-## MCP Tools (9 tools)
+This starts a local browser-facing surface for the current Footprint database and prints a localhost URL for:
 
-### capture-footprint
+- the session dashboard
+- deep-linked session detail pages
+- context review and correction flows
+- export and handoff interactions
 
-Capture and encrypt an LLM conversation. Use when: user explicitly asks to save, or high-value content (IP, legal, business, research, compliance).
+Optional flags:
 
-| 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)       |
+```bash
+footprint demo --host 127.0.0.1 --port 4310
+footprint demo --open
+```
 
-### list-footprints
+Recorder inspection commands:
 
-List all captured evidence with pagination.
+```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                    |
-| --------- | -------- | ------------------------------ |
-| `limit`   | No       | Results per page (default: 10) |
-| `offset`  | No       | Pagination offset              |
-| `tags`    | No       | Filter by tags                 |
+Context memory commands:
 
-### get-footprint
+```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]
+```
 
-Retrieve and decrypt specific evidence by ID.
+Add `--json` to the query commands above when you want scriptable output.
 
-| Parameter | Required | Description |
-| --------- | -------- | ----------- |
-| `id`      | Yes      | Evidence ID |
+### Run As An MCP Server
 
-### search-footprints
+When invoked without a CLI subcommand, Footprint starts the MCP server on stdio.
 
-Search conversations by query, tags, and date range. Query matches conversationId and tags (LIKE). Tags filter uses AND logic.
+### Manual MCP Configuration
 
-| 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              |
+Claude Desktop example:
 
-### export-footprints
+```json
+{
+  "mcpServers": {
+    "footprint": {
+      "command": "npx",
+      "args": ["@pcircle/footprint"],
+      "env": {
+        "FOOTPRINT_DATA_DIR": "/path/to/footprint-data",
+        "FOOTPRINT_PASSPHRASE": "your-secure-passphrase"
+      }
+    }
+  }
+}
+```
 
-Export evidence to encrypted ZIP archive.
+For Claude Code, use the same server definition in `~/.claude/mcp_settings.json`.
 
-| Parameter     | Required | Description                                           |
-| ------------- | -------- | ----------------------------------------------------- |
-| `evidenceIds` | No       | Specific IDs to export (all if omitted)               |
-| `outputMode`  | No       | `"file"`, `"base64"`, or `"both"` (default: `"both"`) |
+## Product Surfaces
 
-### verify-footprint
+### Session History And Context Memory
 
-Verify evidence integrity using stored checksums and Git timestamps.
+Use the recorder when you care about staying in the right line of work, seeing what happened, and handing it off cleanly:
 
-| Parameter | Required | Description |
-| --------- | -------- | ----------- |
-| `id`      | Yes      | Evidence ID |
+- 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
 
-Returns: `integrityVerified`, `checksumValid`, `gitTimestamp`
+Primary MCP tools:
 
-### delete-footprints
+- `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`
 
-Permanently delete evidence records. Uses two-step confirmation.
+Primary UI resources:
 
-| Parameter       | Required | Description                                          |
-| --------------- | -------- | ---------------------------------------------------- |
-| `evidenceIds`   | Yes      | Array of evidence IDs                                |
-| `confirmDelete` | No       | Set `true` to confirm (default: `false` for preview) |
+- `ui://footprint/session-dashboard.html`
+- `ui://footprint/session-detail.html`
 
-### suggest-capture
+### Encrypted Evidence
 
-AI-powered capture suggestion based on keyword analysis.
+Use the evidence flow when you need a discrete preserved record of a conversation.
 
-| Parameter | Required | Description                     |
-| --------- | -------- | ------------------------------- |
-| `content` | Yes      | Conversation content to analyze |
+Primary MCP tools:
 
-### manage-tags
+- `capture-footprint`
+- `list-footprints`
+- `get-footprint`
+- `search-footprints`
+- `export-footprints`
+- `verify-footprint`
+- `delete-footprints`
+- `manage-tags`
+- `suggest-capture`
 
-Unified tag management with three actions: `stats`, `rename`, `remove`.
+Primary UI resources:
 
-| 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                          |
+- `ui://footprint/dashboard.html`
+- `ui://footprint/detail.html`
+- `ui://footprint/export.html`
 
-## MCP Prompts (3 prompts)
+## Storage Model
 
-- **`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)
+Footprint uses one local SQLite database with three logical models:
 
-## Architecture
+- 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
 
-```
-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/
-```
+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.
 
 ## Security
 
@@ -175,22 +250,49 @@ packages/mcp-server/
 
 > **Store your password securely** — loss means permanent data loss.
 
+## 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`
+
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for further reading.
+
+## Prompts
+
+Footprint registers three prompts for MCP clients:
+
+- `footprint-skill`
+- `footprint-quick-ref`
+- `footprint-should-capture`
+
 ## Development
 
 ```bash
-git clone https://github.com/PCIRCLE-AI/footprint.git
-cd footprint
+git clone https://github.com/PCIRCLE-AI/footprint-mcp.git
+cd footprint-mcp
 pnpm install
 pnpm build
-pnpm test
+pnpm test:run
 ```
 
-## Support
+Repository CI 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 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.
+
+Set `FOOTPRINT_DEBUG_PERF=1` when you want lightweight timing traces for reingest, history query, and export paths while debugging large session sets.
+
+## Links
 
-- [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)
+- Repository: <https://github.com/PCIRCLE-AI/footprint-mcp>
+- Package: <https://www.npmjs.com/package/@pcircle/footprint>
+- Project site: <https://footprint.memesh.ai/>
+- Issues: <https://github.com/PCIRCLE-AI/footprint-mcp/issues>
 
 ## License