@pcircle/footprint 1.3.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,219 +3,297 @@
 [![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)
 
-Model Context Protocol (MCP) server that automatically captures and encrypts LLM conversations as legal evidence.
+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 LLM-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
 
-**One command to set up everything:**
+If you only want to see the product locally first:
 
 ```bash
 npx @pcircle/footprint setup
+npx @pcircle/footprint demo --open
 ```
 
-The interactive wizard will:
+If you want the CLI installed for repeated use:
 
-- ✅ Auto-detect your system (OS, shell, Claude Desktop config)
-- ✅ Validate your encryption password strength
-- ✅ Configure Claude Desktop automatically
-- ✅ Set up environment variables in your shell
-- ✅ Create backup of existing config
+```bash
+npm install -g @pcircle/footprint
+footprint setup
+```
 
-**That's it!** Restart Claude Desktop and your conversations are being captured.
+If you want to start recording live CLI work immediately:
 
-### Advanced Installation
+```bash
+footprint run claude -- <args...>
+footprint run gemini -- <args...>
+footprint run codex -- <args...>
+```
 
-For manual setup or custom configurations, see the [full installation guide](https://github.com/PCIRCLE-AI/footprint-mcp#installation).
+If you want Footprint to suggest the right context before a run begins:
 
-## Features
+```bash
+footprint run codex --prepare-context -- <args...>
+```
 
-- 🔐 XChaCha20-Poly1305 encryption
-- 🕒 Git commit timestamps
-- 📦 Tamper-proof ZIP exports
-- 🔍 Search and retrieve evidence
-- 🤖 AI-powered capture suggestions
-- ✅ Integrity verification
-- 🏷️ Tag management
-- 📊 Interactive UI dashboard
+### Install And Configure
 
-## Architecture
+```bash
+npx @pcircle/footprint setup
+```
 
-The Footprint MCP server follows a modular, layered architecture:
+Persistent install:
 
-```
-src/
-├── index.ts              # Main MCP server
-├── tools/                # MCP tool handlers (11 tools)
-│   ├── capture-footprint.ts
-│   ├── list-footprints.ts
-│   ├── get-footprint.ts
-│   ├── export-footprints.ts
-│   ├── search-footprints.ts
-│   ├── verify-footprint.ts
-│   ├── suggest-capture.ts
-│   ├── delete-footprints.ts
-│   ├── rename-tag.ts
-│   ├── remove-tag.ts
-│   └── get-tag-stats.ts
-├── analyzers/            # Content analysis modules
-│   └── content-analyzer.ts
-├── lib/
-│   ├── crypto/           # Encryption & key derivation
-│   ├── storage/          # Database & export
-│   ├── tool-wrapper.ts   # Error handling wrapper
-│   └── tool-response.ts  # Response formatters
-└── ui/                   # Interactive dashboards
+```bash
+npm install -g @pcircle/footprint
+footprint setup
 ```
 
-### Design Principles
+The setup wizard:
 
-- **Modular**: Each tool is self-contained with schema, metadata, and handler
-- **Type-Safe**: Full TypeScript with Zod schema validation
-- **Testable**: Dependency injection enables isolated testing
-- **Secure**: Encrypted storage with integrity verification
-- **Maintainable**: Clear separation of concerns across layers
+- creates the local data directory
+- validates the passphrase
+- configures Claude Desktop when available
+- optionally appends environment variables to the active shell rc file
 
-## MCP Tools
+Node.js `>=22` is required.
 
-### Core Tools
+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.
 
-#### capture-footprint
+### Open The Local Live Product
 
-Captures and encrypts an LLM conversation as evidence.
-
-**Parameters:**
+```bash
+npx @pcircle/footprint demo
+```
 
-- `conversationId` - Unique identifier for the conversation
-- `llmProvider` - LLM provider name (e.g., "Claude Sonnet 4.5")
-- `content` - Full conversation content
-- `messageCount` - Number of messages in conversation
-- `tags` (optional) - Comma-separated tags
+If you installed the CLI globally, use `footprint demo` or `footprint demo --open`.
 
-#### list-footprints
+This starts a local browser-facing surface for the current Footprint database and prints a localhost URL for:
 
-Lists all captured evidence with pagination support.
+- the session dashboard
+- deep-linked session detail pages
+- context review and correction flows
+- export and handoff interactions
 
-**Parameters:**
+Optional flags:
 
-- `limit` (optional) - Maximum results per page
-- `offset` (optional) - Pagination offset
+```bash
+footprint demo --host 127.0.0.1 --port 4310
+footprint demo --open
+```
 
-#### get-footprint
+Recorder inspection commands:
 
-Retrieves and decrypts specific evidence by ID.
+```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>]
+```
 
-**Parameters:**
+Context memory commands:
 
-- `id` - Evidence ID
+```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]
+```
 
-#### export-footprints
+Add `--json` to the query commands above when you want scriptable output.
 
-Exports evidence to tamper-proof encrypted ZIP archive.
+### Run As An MCP Server
 
-**Parameters:**
+When invoked without a CLI subcommand, Footprint starts the MCP server on stdio.
 
-- `evidenceIds` - Array of evidence IDs to export
-- `includeGitInfo` (optional) - Include git metadata
+### Manual MCP Configuration
 
-### Search & Discovery
+Claude Desktop example:
 
-#### search-footprints
+```json
+{
+  "mcpServers": {
+    "footprint": {
+      "command": "npx",
+      "args": ["@pcircle/footprint"],
+      "env": {
+        "FOOTPRINT_DATA_DIR": "/path/to/footprint-data",
+        "FOOTPRINT_PASSPHRASE": "your-secure-passphrase"
+      }
+    }
+  }
+}
+```
 
-Search and filter evidence by query, tags, or date range.
+For Claude Code, use the same server definition in `~/.claude/mcp_settings.json`.
 
-**Parameters:**
+## Product Surfaces
 
-- `query` (optional) - Search text (matches conversationId, tags)
-- `tags` (optional) - Array of tags to filter by
-- `dateFrom` (optional) - Start date (ISO format)
-- `dateTo` (optional) - End date (ISO format)
-- `limit` (optional) - Maximum results
-- `offset` (optional) - Pagination offset
+### Session History And Context Memory
 
-#### suggest-capture
+Use the recorder when you care about staying in the right line of work, seeing what happened, and handing it off cleanly:
 
-Analyze conversation content and suggest whether to capture it as evidence.
+- 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
 
-**Parameters:**
+Primary MCP tools:
 
-- `summary` - Conversation summary or key content to analyze
+- `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`
 
-**Returns:**
+Primary UI resources:
 
-- `shouldCapture` - Whether to capture (based on keyword analysis)
-- `reason` - Human-readable explanation
-- `suggestedTags` - Recommended tags
-- `suggestedConversationId` - Recommended ID
-- `confidence` - Confidence score (0-1)
+- `ui://footprint/session-dashboard.html`
+- `ui://footprint/session-detail.html`
 
-### Verification
+### Encrypted Evidence
 
-#### verify-footprint
+Use the evidence flow when you need a discrete preserved record of a conversation.
 
-Verify the integrity and authenticity of captured evidence.
+Primary MCP tools:
 
-**Parameters:**
+- `capture-footprint`
+- `list-footprints`
+- `get-footprint`
+- `search-footprints`
+- `export-footprints`
+- `verify-footprint`
+- `delete-footprints`
+- `manage-tags`
+- `suggest-capture`
 
-- `id` - Evidence ID to verify
+Primary UI resources:
 
-**Returns:**
+- `ui://footprint/dashboard.html`
+- `ui://footprint/detail.html`
+- `ui://footprint/export.html`
 
-- `verified` - Overall verification status
-- `checks` - Detailed checks (content integrity, git timestamp, encryption)
-- `legalReadiness` - Whether evidence meets legal standards
+## Storage Model
 
-### Management
+Footprint uses one local SQLite database with three logical models:
 
-#### delete-footprints
+- 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
 
-Delete evidence records permanently.
+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.
 
-**Parameters:**
+## Security
 
-- `evidenceIds` - Array of evidence IDs to delete
+- **Encryption**: XChaCha20-Poly1305 (256-bit)
+- **Key Derivation**: Argon2id (OWASP recommended)
+- **Storage**: Local SQLite with encrypted BLOBs
+- **No cloud, no tracking, no data collection**
 
-#### rename-tag
+> **Store your password securely** — loss means permanent data loss.
 
-Rename a tag across all evidence.
+## Architecture
 
-**Parameters:**
+Key runtime components:
 
-- `oldTag` - Current tag name
-- `newTag` - New tag name
+- 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`
 
-#### remove-tag
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for further reading.
 
-Remove a tag from all evidence.
+## Prompts
 
-**Parameters:**
+Footprint registers three prompts for MCP clients:
 
-- `tag` - Tag name to remove
+- `footprint-skill`
+- `footprint-quick-ref`
+- `footprint-should-capture`
 
-#### get-tag-stats
+## Development
 
-Get statistics about tag usage.
+```bash
+git clone https://github.com/PCIRCLE-AI/footprint-mcp.git
+cd footprint-mcp
+pnpm install
+pnpm build
+pnpm test:run
+```
 
-**Returns:**
+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.
 
-- Tag names and their usage counts
+`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.
 
-## Security
+Set `FOOTPRINT_DEBUG_PERF=1` when you want lightweight timing traces for reingest, history query, and export paths while debugging large session sets.
 
-- **Encryption**: XChaCha20-Poly1305 (256-bit)
-- **Key Derivation**: Argon2id (OWASP recommended)
-- **Storage**: Local SQLite with encrypted BLOBs
+## Links
 
-⚠️ **Store your password securely** - Loss means permanent data loss.
+- 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>
 
-## Support
+## License
 
-- [Documentation](https://github.com/PCIRCLE-AI/footprint#readme)
-- [Issues](https://github.com/PCIRCLE-AI/footprint/issues)
-- [License](https://github.com/PCIRCLE-AI/footprint/blob/main/LICENSE)
+MIT License — see [LICENSE](./LICENSE) for details.