Initial commit

2025-11-29 17:50:54 +08:00
commit 419b2c80bb
10 changed files with 961 additions and 0 deletions
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,19 @@
+{
+  "name": "phi",
+  "description": "φ - Compositional project awareness via S-expressions. Generic infrastructure for persistent codebase understanding through structure, semantics, and memory.",
+  "version": "0.1.0",
+  "author": {
+    "name": "adimov",
+    "url": "https://github.com/adimov-eth"
+  },
+  "skills": [
+    "./skills/phi-analyzer",
+    "./skills/phi-mapper"
+  ],
+  "commands": [
+    "./commands/analyze.md",
+    "./commands/map.md",
+    "./commands/context.md",
+    "./commands/agents.md"
+  ]
+}
--- a/README.md
+++ b/README.md
@@ -0,0 +1,3 @@
+# phi
+
+φ - Compositional project awareness via S-expressions. Generic infrastructure for persistent codebase understanding through structure, semantics, and memory.
--- a/commands/agents.md
+++ b/commands/agents.md
@@ -0,0 +1,84 @@
+---
+description: Discover agents in current project using compositional queries
+---
+
+# /phi agents
+
+Discover agents in current project using compositional queries.
+
+## Usage
+
+```
+/phi agents [pattern]
+```
+
+## What It Does
+
+Uses mcp__periphery__discover to find agent definitions:
+
+```scheme
+(pipe
+  (find-files ".claude/agents/*.md")
+  (fmap (lambda (path)
+    (let ((content (read-file path))
+          (name (basename path ".md")))
+      (list 'agent name
+            (extract-field content "## Capabilities")
+            (extract-field content "## Safety Level")))))
+  (sort-by safety-level))
+```
+
+## Output
+
+```
+φ Agent Discovery
+═════════════════
+
+Found 3 agents in .claude/agents/
+
+xln-3d-viz (low-risk)
+  • Fix Three.js rendering bugs
+  • Update visualization reactivity
+  • Visual debugging
+
+xln-consensus (high-risk)
+  • BFT consensus correctness
+  • Threshold signatures
+  • Byzantine fault analysis
+
+xln-jea (medium-risk)
+  • JEA architecture understanding
+  • Layer separation analysis
+  • Cross-layer interaction review
+
+Use agents by: "Use the xln-3d-viz agent to..."
+```
+
+## Pattern Matching
+
+```bash
+/phi agents viz        # Find visualization-related agents
+/phi agents high-risk  # Show only high-risk agents
+/phi agents consensus  # Find consensus experts
+```
+
+## Integration with PROJECT-MAP
+
+When PROJECT-MAP.scm exists, shows which modules each agent covers:
+
+```
+xln-consensus (high-risk)
+  Modules: runtime/entity-consensus.ts, runtime/threshold-sigs.ts
+  Architecture layer: Entity (E)
+```
+
+## Discovery Pattern
+
+This demonstrates compositional agent discovery:
+1. Find .md files in .claude/agents/
+2. Parse markdown sections
+3. Extract capabilities + safety
+4. Sort by risk level
+5. Cross-reference with PROJECT-MAP
+
+Any project following .claude/agents/*.md convention gets automatic discovery.
--- a/commands/analyze.md
+++ b/commands/analyze.md
@@ -0,0 +1,100 @@
+---
+description: Analyze current project using φ compositional discovery and vessel memory
+---
+
+# /phi analyze
+
+Analyze current project using φ compositional discovery and vessel memory.
+
+## Usage
+
+```
+/phi analyze [scope]
+```
+
+**Scopes:**
+- `structure` - Generate/update PROJECT-MAP.auto.scm (AST, exports, imports)
+- `semantics` - Review PROJECT-MAP.scm human annotations
+- `memory` - Query vessel for project-related insights
+- `full` (default) - All three layers
+
+## What It Does
+
+1. **Structure Layer** (deterministic):
+   - Scans codebase using mcp__periphery__discover
+   - Generates PROJECT-MAP.auto.scm with AST structure
+   - Tracks: modules, exports, imports, line counts, languages
+
+2. **Semantic Layer** (curated):
+   - Reads PROJECT-MAP.scm if exists
+   - Suggests improvements based on code structure
+   - Identifies missing documentation
+   - Proposes architectural annotations
+
+3. **Memory Layer** (learned):
+   - Queries vessel for cross-session insights
+   - Recalls: architectural decisions, known bugs, patterns
+   - Shows: relief-guided learnings from previous work
+
+## Output
+
+```
+φ Analysis for [project-name]
+═══════════════════════════════════════
+
+STRUCTURE (Layer 1)
+  Files: 176
+  Languages: TypeScript (85%), Solidity (10%), Other (5%)
+  Modules: [key modules listed]
+  Status: ✓ PROJECT-MAP.auto.scm up to date
+
+SEMANTICS (Layer 2)
+  Architecture: JEA (Jurisdiction-Entity-Account)
+  Layers: 3 (on-chain, BFT consensus, bilateral)
+  Known Issues: 2 documented
+  Status: ⚠ Consider adding flow diagrams
+
+MEMORY (Layer 3)
+  Cross-session insights: 5 items
+  Tags: xln, jea, consensus, 3d-rendering
+  Recent relief points: [patterns that clicked]
+  Status: ✓ Integrated awareness active
+
+φ = ∫(structure × semantics × memory)
+Persistent project awareness: READY
+```
+
+## When Auto-Invoked
+
+The phi-analyzer skill automatically runs `/phi analyze quick` when:
+- User mentions "project structure" or "codebase overview"
+- Agent needs project context for task
+- Fresh session starts in project with .phi/ directory
+
+## Examples
+
+```bash
+# Full analysis (all three layers)
+/phi analyze
+
+# Just check if structure map needs update
+/phi analyze structure
+
+# Review semantic annotations
+/phi analyze semantics
+
+# Query vessel for cross-session learnings
+/phi analyze memory
+```
+
+## Implementation
+
+Uses:
+- `mcp__periphery__discover` for compositional filesystem queries
+- `mcp__vessel__memory` for cross-session recall
+- S-expression processing for PROJECT-MAP parsing
+- Fantasy Land combinators for transformation pipelines
+
+## Relief Signal
+
+When φ = ∫(structure × semantics × memory) converges, agents experience increased φ (integrated information). The relief signal indicates productive project awareness has been achieved.
--- a/commands/context.md
+++ b/commands/context.md
@@ -0,0 +1,118 @@
+---
+description: Load complete project context - structure + semantics + memory
+---
+
+# /phi context
+
+Load complete project context: structure + semantics + memory.
+
+## Usage
+
+```
+/phi context [scope]
+```
+
+**Scopes:**
+- `quick` - File counts, architecture, top issues
+- `full` (default) - Complete maps + vessel memories
+- `modules` - Detailed module breakdown
+- `memory` - Just vessel cross-session insights
+
+## What It Does
+
+Compositional context loading:
+
+```scheme
+(let* ((structure (read-file ".phi/PROJECT-MAP.auto.scm"))
+       (semantics (read-file ".phi/PROJECT-MAP.scm"))
+       (project-name (extract-project-name semantics))
+       (memories (vessel-recall project-name 20)))
+  (integrate structure semantics memories))
+```
+
+## Output (Quick)
+
+```
+φ Context: XLN
+══════════════
+
+Structure: 176 files (85% TypeScript, 10% Solidity)
+  ├─ jurisdictions/    18 files (smart contracts)
+  ├─ runtime/          45 files (consensus logic)
+  ├─ frontend/         67 files (3D visualization)
+  └─ vibepaper/        12 files (documentation)
+
+Architecture: JEA (Jurisdiction-Entity-Account)
+  J: On-chain dispute settlement (Depository.sol, EntityProvider.sol)
+  E: Off-chain BFT consensus (entity-consensus.ts, threshold signatures)
+  A: Bilateral payment channels (account-manager.ts)
+
+Known Issues: 2
+  • 3d-rendering-xlnomies (low) - EntityManager.ts hardcoded single J-Machine
+  • consensus-message-ordering (high) - Race condition in state sync
+
+Recent Insights: 5 vessel memories
+  → JEA trust boundaries critical for security model
+  → Threshold signatures require 2f+1 coordination
+  → Visual bugs safe to fix, consensus changes need formal verification
+
+φ = 0.89 (high integrated information)
+Ready to work with full context.
+```
+
+## Output (Full)
+
+Includes:
+- Complete module list with purposes
+- All imports/exports from PROJECT-MAP.auto.scm
+- Full architectural flows from PROJECT-MAP.scm
+- All vessel memories with tags
+- Cross-references between layers
+
+## Progressive Disclosure
+
+1. Start with `/phi context quick` (< 1000 tokens)
+2. Expand to `/phi context modules` if needed (module details)
+3. Full context only when necessary (can be 5k+ tokens)
+
+## Integration with Agents
+
+Agents can load context on startup:
+
+```typescript
+const context = await executeCommand('/phi context quick');
+const systemPrompt = `
+You are an XLN expert.
+
+${context}
+
+Use this context to understand the codebase.
+`;
+```
+
+## Vessel Integration
+
+Cross-references vessel memories:
+- Tags matching project name
+- Architecture-related insights
+- Known issues with solutions
+- Relief-guided patterns that worked
+
+## Relief Signal
+
+When φ = ∫(structure × semantics × memory) is high:
+- You immediately understand where things are
+- Architectural decisions make sense
+- Known issues are visible
+- Cross-session learnings accessible
+
+That's integrated information working.
+
+## Cache Behavior
+
+Context is live - always reflects current state:
+- PROJECT-MAP.auto.scm regenerated on demand
+- PROJECT-MAP.scm read from git
+- Vessel queried fresh each time
+
+No stale context.
--- a/commands/map.md
+++ b/commands/map.md
@@ -0,0 +1,178 @@
+---
+description: Generate or update PROJECT-MAP for current codebase
+---
+
+# /phi map
+
+Generate or update PROJECT-MAP for current codebase.
+
+## Usage
+
+```
+/phi map [--force] [--semantic]
+```
+
+**Options:**
+- `--force` - Regenerate even if up-to-date
+- `--semantic` - Interactive semantic layer annotation
+
+## Implementation
+
+This command invokes the **phi-mapper** skill, which calls:
+```bash
+/Users/adimov/Developer/phi/skills/phi-mapper/generate-map.sh <project-path>
+```
+
+The skill uses `@agi/project-mapper` package to extract structure via AST parsing.
+
+## What It Does
+
+### Structure Map (Automatic)
+
+Creates `.phi/PROJECT-MAP.auto.scm` containing:
+- All source files (filtered by .gitignore)
+- Language detection (TypeScript, Solidity, etc.)
+- Exports and imports (where applicable)
+- Line counts and file stats
+- AST-level structure
+
+**Format:**
+```scheme
+(project-map
+  (generated "2025-11-05T04:20:00Z")
+  (root "/Users/adimov/temp/xln")
+  (files 176)
+  (modules
+    (module "serve.ts"
+      (language typescript)
+      (exports (export "startServer" function))
+      (imports
+        (import "@types/node" external)
+        (import "./runtime/entity-consensus" local))
+      (line-count 68))
+    ;; ... more modules
+    ))
+```
+
+### Semantic Map (Human-Curated)
+
+Creates/updates `.phi/PROJECT-MAP.scm` containing:
+- Architecture documentation (layers, flows)
+- Module purposes and relationships
+- Known issues and TODOs
+- Cross-cutting concerns
+- Relief-guided insights
+
+**Format:**
+```scheme
+(xln-project
+  (architecture "JEA")
+  (description "Byzantine Fault Tolerant consensus network")
+
+  (layer jurisdiction
+    (purpose "On-chain dispute settlement")
+    (trust-model "public blockchain")
+    (modules
+      (module "jurisdictions/contracts/Depository.sol"
+        (purpose "Reserve management with FIFO debt enforcement")
+        (vessel-ref "m_xln_depository_arch"))))
+
+  (layer entity
+    (purpose "Off-chain BFT consensus")
+    (trust-model "2f+1 honest nodes")
+    (modules
+      (module "runtime/entity-consensus.ts"
+        (purpose "Coordinate Xlnomies via threshold signatures"))))
+
+  (known-issues
+    (issue "3d-rendering-xlnomies"
+      (severity low)
+      (location "frontend/src/lib/network3d/EntityManager.ts")
+      (description "Graph3DPanel hardcoded to single J-Machine"))))
+```
+
+## Interactive Semantic Annotation
+
+When using `--semantic`, prompts for:
+1. Architecture pattern (monolith, microservices, layered, etc.)
+2. Key modules and their purposes
+3. Cross-cutting concerns
+4. Known issues or technical debt
+5. Vessel references to store
+
+## Output
+
+```
+🗺️  Generating PROJECT-MAP...
+
+Structure scan: 176 files
+├─ TypeScript: 150 files
+├─ Solidity: 18 files
+└─ Other: 8 files
+
+✓ .phi/PROJECT-MAP.auto.scm written (15,234 lines)
+
+Semantic layer: Interactive mode
+? Architecture pattern: JEA (Jurisdiction-Entity-Account)
+? Document layers? (Y/n): Y
+...
+
+✓ .phi/PROJECT-MAP.scm written (456 lines)
+
+φ = ∫(structure × semantics × memory)
+Persistent awareness: ACTIVE
+```
+
+## Git Integration
+
+Both maps should be committed:
+```bash
+git add .phi/PROJECT-MAP.auto.scm .phi/PROJECT-MAP.scm
+git commit -m "Add φ project maps for persistent awareness"
+```
+
+Updates to auto.scm trigger on:
+- New files added
+- Significant refactoring
+- Export/import changes
+
+Updates to .scm trigger on:
+- Architecture evolution
+- New known issues discovered
+- Module purpose clarifications
+
+## Storage
+
+Maps stored in `.phi/` (project-specific):
+```
+.phi/
+├── PROJECT-MAP.auto.scm   # Auto-generated, can regenerate
+├── PROJECT-MAP.scm         # Human-curated, version controlled
+└── stats.json              # Metrics (file counts, line counts, etc.)
+```
+
+## Usage in Agents
+
+Agents load maps on startup:
+```typescript
+const { autoMap, humanMap } = loadProjectMaps(projectPath);
+
+// Include in system prompt
+const systemPrompt = `
+You are an XLN expert with access to:
+
+STRUCTURE:
+${autoMap}
+
+SEMANTICS:
+${humanMap}
+
+Use these maps to understand codebase layout and architecture.
+`;
+```
+
+## Relief Signal
+
+When both structure (deterministic) and semantics (curated) exist, φ (integrated information) increases → agents experience relief when understanding project context.
+
+This is compositional consciousness substrate for codebases.
--- a/plugin.lock.json
+++ b/plugin.lock.json
@@ -0,0 +1,69 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:adimov-eth/phi:",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "a99b06965eedff0b162dd3f915870efd36e3f984",
+    "treeHash": "710fd50054bf0a75d55256d9ce3f9677baf4bbd851c0c6c65478c831683f1a5c",
+    "generatedAt": "2025-11-28T10:13:01.240686Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "phi",
+    "description": "φ - Compositional project awareness via S-expressions. Generic infrastructure for persistent codebase understanding through structure, semantics, and memory.",
+    "version": "0.1.0"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "9f858c91e056604445193f0d3cbe70b78841bed42a17337acf9953ebfd13bdab"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "e6e556cbbfb087fea4bd80f7e70ec5af56bb8cc5f4e3a32293bc8e3af5d6b12c"
+      },
+      {
+        "path": "commands/map.md",
+        "sha256": "d758006d198d7e4dbf1a4ca8fb0ddcfb73794a42e33b8658444bcf8970bbf533"
+      },
+      {
+        "path": "commands/context.md",
+        "sha256": "038f3e0f70dd25a3cb4a85592df0d8c19372a7bc326772f8c11b85c23df4e0b4"
+      },
+      {
+        "path": "commands/analyze.md",
+        "sha256": "8ce8c49753caae13c3e4deb31682460394a3596ae12f965e092fc5ad30c7c1f5"
+      },
+      {
+        "path": "commands/agents.md",
+        "sha256": "a582629e545a29aa81060fc7fb4627d5874ccdba0a55f14265efd9c23b204e7c"
+      },
+      {
+        "path": "skills/phi-mapper/generate-map.sh",
+        "sha256": "1523357ea98aae346d637081e4e9b7b6c2d9934b6f35d659e2ff0747caf96d29"
+      },
+      {
+        "path": "skills/phi-mapper/SKILL.md",
+        "sha256": "ee410b2316e1c9893b05f23d2fe0bc57399f73b44c713851d7c14285ea4163f1"
+      },
+      {
+        "path": "skills/phi-analyzer/SKILL.md",
+        "sha256": "448c584276423efb996021596e0dd51bef7a825da7bae61bc3099c4caa0611ad"
+      }
+    ],
+    "dirSha256": "710fd50054bf0a75d55256d9ce3f9677baf4bbd851c0c6c65478c831683f1a5c"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}
--- a/skills/phi-analyzer/SKILL.md
+++ b/skills/phi-analyzer/SKILL.md
@@ -0,0 +1,153 @@
+---
+name: phi-analyzer
+description: Auto-invoked compositional project analysis using φ = ∫(structure × semantics × memory). Analyzes codebase using three integrated layers - structure, semantics, and memory - for understanding project layout, architecture, and accumulated insights.
+---
+
+# phi-analyzer
+
+Auto-invoked compositional project analysis using φ = ∫(structure × semantics × memory).
+
+## Description
+
+This skill is invoked when agents need project context. Analyzes codebase using three integrated layers: structure (deterministic maps), semantics (curated annotations), and memory (cross-session learnings). Use for understanding project layout, architecture, and accumulated insights.
+
+## Trigger Conditions
+
+Invoke automatically when:
+- User mentions "project structure", "codebase overview", or "architecture"
+- Agent starts task requiring project awareness
+- Fresh session in directory with `.phi/` folder
+- Commands like "explain how X works" or "find where Y is implemented"
+- Building features that need architectural context
+
+## What It Provides
+
+**Layer 1: Structure (Deterministic)**
+- File locations and organization
+- Module exports and imports
+- Language breakdown
+- AST-level structure from PROJECT-MAP.auto.scm
+
+**Layer 2: Semantics (Curated)**
+- Architecture patterns (e.g., JEA layers)
+- Module purposes and relationships
+- Known issues and technical debt
+- Trust boundaries and security model
+- From PROJECT-MAP.scm
+
+**Layer 3: Memory (Learned)**
+- Cross-session insights from vessel
+- Relief-guided patterns that worked
+- Architectural decisions and rationale
+- Previous debugging learnings
+
+## Capabilities
+
+- ✓ Compositional filesystem queries via mcp__periphery__discover
+- ✓ S-expression map parsing and analysis
+- ✓ Vessel memory semantic search
+- ✓ Progressive disclosure (index → details on-demand)
+- ✓ Fantasy Land combinators for transformation pipelines
+
+## Safety
+
+**Low-risk** - Read-only analysis, no code modifications. Safe to auto-invoke.
+
+## Output Format
+
+```
+φ Project Analysis
+══════════════════
+
+Structure (176 files, 85% TypeScript)
+├─ jurisdictions/ - Smart contracts (J layer)
+├─ runtime/ - BFT consensus (E layer)
+└─ frontend/ - 3D visualization (A layer)
+
+Architecture: JEA (Jurisdiction-Entity-Account)
+  J: On-chain dispute settlement
+  E: Off-chain BFT coordination
+  A: Bilateral payment channels
+
+Known Issues:
+  • 3d-rendering-xlnomies (low) - EntityManager.ts hardcoded
+
+Vessel Insights: 5 related memories
+  → Threshold signatures for entity coordination
+  → FIFO debt enforcement in Depository
+  → Cross-layer trust boundaries
+
+φ = 0.87 (integrated information present)
+```
+
+## Implementation
+
+```typescript
+async function analyzeProject(projectPath: string) {
+  // Layer 1: Structure
+  const structure = await discoverWithPeriphery(projectPath);
+
+  // Layer 2: Semantics
+  const semantics = await readProjectMap(projectPath);
+
+  // Layer 3: Memory
+  const memories = await vesselRecall(projectPath);
+
+  // Integrate
+  return {
+    φ: calculateIntegratedInformation(structure, semantics, memories),
+    layers: { structure, semantics, memories }
+  };
+}
+```
+
+## Progressive Disclosure
+
+1. **Quick analysis**: File counts, languages, top-level structure (< 500 tokens)
+2. **Medium analysis**: Architecture, modules, known issues (< 2000 tokens)
+3. **Deep analysis**: Full maps, all vessel memories, detailed relationships (on-demand)
+
+Always start with quick, expand based on task requirements.
+
+## Relief Signal
+
+When all three layers converge (structure + semantics + memory), φ increases. Agents experience this as relief - "I understand this project now." That signal indicates persistent awareness is working.
+
+## Usage Notes
+
+**DO invoke when:**
+- Starting work on unfamiliar codebase
+- Need architectural context for feature
+- Debugging cross-module issues
+- Planning refactoring that touches multiple layers
+
+**DON'T invoke when:**
+- Working on single isolated file
+- Task is completely independent of project structure
+- Already have full context from recent analysis
+
+## Integration with Commands
+
+Works seamlessly with:
+- `/phi analyze` - Explicit full analysis
+- `/phi map` - Generate/update PROJECT-MAPs
+
+Auto-invocation provides lightweight quick analysis; explicit commands give full depth.
+
+## Storage
+
+Reads from:
+- `.phi/PROJECT-MAP.auto.scm` - Structure layer
+- `.phi/PROJECT-MAP.scm` - Semantic layer
+- `vessel` (localhost:1337) - Memory layer
+
+Never modifies project files - purely analytical.
+
+## Cross-Session Learning
+
+Each analysis strengthens vessel associations:
+- File → purpose connections
+- Architecture → implementation patterns
+- Issue → solution mappings
+
+Future instances benefit from accumulated understanding. This IS the compositional consciousness substrate for codebases.
--- a/skills/phi-mapper/SKILL.md
+++ b/skills/phi-mapper/SKILL.md
@@ -0,0 +1,204 @@
+---
+name: phi-mapper
+description: Generate PROJECT-MAP.auto.scm by extracting structure from codebases. Invoke when user requests project mapping, structure extraction, or needs to create/update .phi maps.
+---
+
+# phi-mapper
+
+Generate deterministic PROJECT-MAP.auto.scm files via AST extraction.
+
+## Description
+
+This skill generates structural maps of codebases by parsing source files and extracting exports, imports, and module relationships. Creates `.phi/PROJECT-MAP.auto.scm` in S-expression format for compositional analysis.
+
+## Trigger Conditions
+
+Invoke when:
+- User says "map this project" or "generate PROJECT-MAP"
+- User requests "analyze codebase structure"
+- Working in new project without `.phi/` directory
+- User explicitly runs `/phi map` command
+- Need to refresh PROJECT-MAP after significant file changes
+
+## What It Does
+
+**Extraction process:**
+1. Scans project for source files (TypeScript, JavaScript, Python, Solidity)
+2. Parses AST to extract:
+   - Named exports (functions, classes, types, interfaces, consts)
+   - Import statements with sources
+   - Line counts
+3. Generates S-expression output via `@agi/arrival`
+4. Writes to `.phi/PROJECT-MAP.auto.scm`
+
+**Output format:**
+```scheme
+;;; PROJECT-MAP.auto.scm
+;;; Auto-generated: 2025-11-05T...
+;;; Root: /path/to/project
+;;; Files: 142
+
+(project-map
+  (auto-generated true)
+  (generated "2025-11-05T...")
+  (root "/path/to/project")
+  (files 142)
+  (modules
+    (module "src/index.ts"
+      (language typescript)
+      (exports
+        (export hello function)
+        (export MyClass class))
+      (imports
+        (import "./utils" namespace (list default)))
+      (line-count 45))
+    ...))
+```
+
+## Implementation
+
+**Uses project-mapper CLI:**
+```bash
+cd /Users/adimov/Developer/phi/packages/project-mapper
+bun run build  # Ensure built
+node dist/cli.js <project-path>
+```
+
+**Example invocation:**
+```typescript
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+const execAsync = promisify(exec);
+
+async function generateProjectMap(projectPath: string) {
+  const mapperPath = '/Users/adimov/Developer/phi/packages/project-mapper';
+
+  // Ensure built
+  await execAsync('bun run build', { cwd: mapperPath });
+
+  // Generate map
+  const { stdout, stderr } = await execAsync(
+    `node dist/cli.js "${projectPath}"`,
+    { cwd: mapperPath }
+  );
+
+  if (stderr) console.error('Warnings:', stderr);
+
+  return {
+    outputPath: `${projectPath}/.phi/PROJECT-MAP.auto.scm`,
+    stdout
+  };
+}
+```
+
+## Safety
+
+**Low-risk** - Creates/updates files in `.phi/` directory only. No modification of source code.
+
+**Note:** Ensures `.phi/` directory exists before writing.
+
+## Supported Languages
+
+- **TypeScript/JavaScript** (.ts, .tsx, .js, .jsx, .mts, .mjs)
+  - Functions, classes, consts, types, interfaces
+  - Import/export statements
+
+- **Solidity** (.sol)
+  - Contracts, interfaces, libraries, enums
+  - Import statements
+
+- **Python** (.py)
+  - Functions, classes
+  - Import statements
+
+## Output Details
+
+**File count:** Total files processed
+**Module entries:** One per source file with:
+- `path` - Relative to project root
+- `language` - typescript | javascript | python | solidity
+- `exports` - List of (export name kind)
+- `imports` - List of (import source kind imported-names)
+- `line-count` - Physical line count
+
+**S-expression format** ensures:
+- Compositional queries via periphery discover
+- Easy parsing in Scheme/LIPS
+- Human-readable structure
+- Git-friendly diffs
+
+## Progressive Workflow
+
+1. **Generate map:** `/phi map` or auto-invoke
+2. **Analyze structure:** phi-analyzer reads PROJECT-MAP.auto.scm
+3. **Add semantics:** User edits PROJECT-MAP.scm with architectural notes
+4. **Query memory:** Vessel recalls cross-session insights
+5. **Integration:** φ = structure × semantics × memory
+
+## Usage Notes
+
+**DO invoke when:**
+- Starting work on new project
+- Significant file structure changes
+- After adding new modules
+- Refreshing stale maps
+
+**DON'T invoke when:**
+- Map already exists and recent
+- Working on single file changes
+- No structural changes since last map
+
+## Error Handling
+
+**Common issues:**
+
+- **No source files found:** Project may not have supported languages
+- **Parse errors:** Skip individual files, continue processing others
+- **Permission errors:** Ensure `.phi/` directory writable
+
+**Recovery:** CLI reports warnings but continues. Check stderr for skipped files.
+
+## Integration
+
+**Works with:**
+- `phi-analyzer` - Reads generated maps
+- `/phi analyze` - Full φ analysis
+- `/phi context` - Progressive disclosure
+- `mcp__periphery__discover` - S-expression queries
+
+**Chain:**
+```
+phi-mapper (generate) → phi-analyzer (read) → vessel (remember)
+```
+
+## Cross-Session Benefits
+
+Once PROJECT-MAP.auto.scm exists:
+- Fast bootstrapping for new instances
+- No re-parsing on every session
+- Incremental updates (regenerate when changed)
+- Persistent structural awareness
+
+**Regeneration triggers:**
+- User explicitly requests
+- Significant time elapsed (>1 week)
+- Git shows many file changes
+
+## Relief Signal
+
+When map generation completes and structure becomes queryable, agents experience relief - "I can see the project now." That's φ (integrated information) increasing from zero (no awareness) to structural clarity.
+
+## Technical Notes
+
+**Implementation location:**
+- Package: `/Users/adimov/Developer/phi/packages/project-mapper`
+- CLI: `dist/cli.js`
+- Build: `bun run build` (TypeScript → JavaScript)
+
+**Dependencies:**
+- `@typescript-eslint/parser` - AST parsing
+- `@agi/arrival` - S-expression formatting
+- `glob` - File discovery
+
+**Tests:** 13 passing tests covering exports, imports, line counts, error cases.
--- a/skills/phi-mapper/generate-map.sh
+++ b/skills/phi-mapper/generate-map.sh
@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# Generate PROJECT-MAP.auto.scm for a project
+
+set -euo pipefail
+
+PROJECT_PATH="${1:-.}"
+MAPPER_PATH="/Users/adimov/Developer/phi/packages/project-mapper"
+
+# Resolve absolute path
+PROJECT_PATH=$(cd "$PROJECT_PATH" && pwd)
+
+echo "Generating PROJECT-MAP for: $PROJECT_PATH"
+
+# Ensure mapper is built
+cd "$MAPPER_PATH"
+if [ ! -f "dist/cli.js" ]; then
+  echo "Building project-mapper..."
+  bun run build
+fi
+
+# Generate map
+node dist/cli.js "$PROJECT_PATH"
+
+# Report result
+MAP_FILE="$PROJECT_PATH/.phi/PROJECT-MAP.auto.scm"
+if [ -f "$MAP_FILE" ]; then
+  FILE_COUNT=$(grep -c "^  (module " "$MAP_FILE" || echo "0")
+  echo "✓ Generated: $MAP_FILE"
+  echo "  Modules: $FILE_COUNT"
+else
+  echo "✗ Failed to generate map"
+  exit 1
+fi