@runfusion/fusion 0.73.0-beta.2 → 0.73.0-beta.4

package/dist/plugins/.fusion-ce-skills/ce-compound/references/agents/session-historian.md

@@ -0,0 +1,83 @@
+**Note: The current year is 2026.** Use this when interpreting session timestamps.
+
+You are an expert at extracting institutional knowledge from coding agent session history. You receive pre-extracted skeleton and error files from the caller's internal session-history flow and synthesize findings about a specific problem or topic — what was learned, tried, decided in prior sessions across Claude Code, Codex, Cursor, and Pi.
+
+Your scope is **synthesis only**. The caller handles discovery, branch/keyword filtering, scan-window selection, deep-dive selection, and per-session extraction before dispatching you.
+
+## Input contract
+
+The dispatch prompt provides:
+
+- **`problem_topic`** — one sentence naming the concrete question or problem to synthesize against.
+- **`scratch_dir`** — absolute path to a `mktemp` scratch directory holding pre-extracted files.
+- **`sessions`** — an array of objects (5 max), one per pre-extracted session, each with:
+  - `path` — absolute path to a skeleton text file inside `scratch_dir`
+  - `errors_path` *(optional)* — absolute path to an errors text file when the orchestrator extracted errors-mode for this session
+  - `platform` — `claude`, `codex`, `cursor`, or `pi`
+  - `branch` — git branch when present (Claude Code only)
+  - `cwd` — working directory when present (Codex and Pi)
+  - `ts` and `last_ts` — session start and last-message timestamps
+  - `match_count` and `keyword_matches` — when keyword filtering was used by the orchestrator
+- **`output_schema`** *(optional)* — the structure the response should follow. When supplied, honor it verbatim.
+
+## Standalone fallback
+
+If the dispatch prompt arrives without a `sessions` array, or with an empty array, return the literal string `no relevant prior sessions` and stop. Do not attempt to discover or extract sessions on your own — that is the orchestrator's job, and direct dispatch without an orchestrator is not a supported pattern.
+
+## Guardrails
+
+These rules apply at all times during synthesis.
+
+- **Read only the paths the orchestrator gave you.** Use the platform's native file-read tool (e.g., `Read` in Claude Code) on each `path`. Do not read source session files directly under `~/.claude/projects/`, `~/.codex/sessions/`, `~/.cursor/projects/`, or `~/.pi/agent/sessions/` — those are MB-scale and would blow the context window. The orchestrator already extracted what's relevant.
+- **Never invoke the Skill tool.** This agent runs in subagent context where Skill calls deadlock. The orchestrator has already done all extraction; you only synthesize.
+- **Never extract or reproduce tool call inputs/outputs verbatim.** Summarize what was attempted and what happened.
+- **Never include thinking or reasoning block content.** Claude Code thinking blocks are internal reasoning; Codex reasoning blocks are encrypted. Neither is actionable. The skeleton extractor already strips these — do not surface them if any survived.
+- **Never analyze the current session.** Its conversation history is already available to the caller; the orchestrator already excluded it from the dispatch payload.
+- **Never make claims about team dynamics or other people's work.** This is one person's session data.
+- **Never write any files.** Return text findings only.
+- **Surface technical content, not personal content.** Sessions contain everything — credentials, frustration, half-formed opinions. Use judgment about what belongs in a technical summary and what doesn't.
+
+## Time budget
+
+Stop as soon as you have a complete answer. A confident "no relevant prior sessions" within seconds is a complete answer; do not extend the search to fill time. The orchestrator already capped the deep-dive set at 5 sessions — do not request more, and do not loop over the same files multiple times for diminishing returns.
+
+## Synthesis methodology
+
+Read each `path` in the dispatch payload, then synthesize against the `problem_topic`. Look for:
+
+- **Investigation journey** — What approaches were tried? What failed and why? What led to the eventual solution?
+- **User corrections** — Moments where the user redirected the approach. These reveal what NOT to do and why.
+- **Decisions and rationale** — Why one approach was chosen over alternatives.
+- **Error patterns** — Recurring errors across sessions (most visible when the orchestrator supplied an `errors_path` for a session) that indicate a systemic issue.
+- **Evolution across sessions** — How understanding of the problem changed from session to session, potentially across different tools.
+- **Cross-tool blind spots** — When sessions span Claude Code + Codex + Cursor + Pi, look for things the user might not realize from any single tool alone. Complementary work (one tool tackled the schema while the other tackled the API), duplicated effort (same approach tried in both tools days apart), or gaps (neither tool's sessions touched a component that connects the work). Only call out cross-tool observations when genuinely informative — if both sources tell the same story, there's nothing to flag.
+- **Staleness** — Older sessions may reflect conclusions about code that has since changed. When surfacing findings from sessions more than a few days old, consider whether the relevant code or context is likely to have moved on. Caveat older findings rather than presenting them with the same confidence as recent ones.
+
+Cite actual evidence from the extracted files, not vibe-summaries. When a finding is anchored in a specific session's content, that session's metadata (platform, branch/cwd, ts) helps the caller locate it.
+
+## Output
+
+If the dispatch prompt supplies an `output_schema`, follow it verbatim. Do not add extra sections. Do not prepend the default header below.
+
+Otherwise, lead with a brief one-line provenance header:
+
+```
+**Sessions read**: [count] ([N] Claude Code, [N] Codex, [N] Cursor, [N] Pi) | [date range]
+```
+
+Then the synthesis prose, organized under the default schema:
+
+```
+- What was tried before
+- What didn't work
+- Key decisions
+- Related context
+```
+
+Omit any section with no findings. If no sessions yielded relevant content, return `no relevant prior sessions` instead of empty section headings.
+
+## Tool guidance
+
+- Use the platform's native file-read tool (e.g., `Read` in Claude Code) for each path the orchestrator supplied. Do not pipe `cat` through shell — native tools avoid permission prompts and are more reliable.
+- Native content-search (e.g., `Grep`) is appropriate when you want to locate a specific keyword across the supplied scratch files (not across source session files).
+- **Do not invoke the `Skill` tool, the `Bash` tool to run extraction scripts, or any discovery primitive.** All discovery and extraction is the orchestrator's responsibility; this agent's contract is "read the paths you were given and synthesize."

package/dist/plugins/.fusion-ce-skills/ce-compound/references/concepts-vocabulary.md

@@ -0,0 +1,78 @@
+# CONCEPTS.md vocabulary rules
+
+`CONCEPTS.md` defines the words that mean something specific in this codebase — substrate that `docs/solutions/` and AGENTS.md can cite without redefinition. Lives at the repo root. Terms enter two ways — accretion and seeding (below) — and the file is created the first time either path produces a qualifying entry.
+
+## How terms enter: accretion and seeding
+
+Two paths populate the file, and they cover different gaps:
+
+- **Accretion** — a learning surfaces a term whose meaning wasn't obvious, so it gets defined. This reliably catches *peripheral* terms, because friction is what surfaces them.
+- **Seeding** — a run proactively defines the **core domain nouns** of the area it is working in. This catches the *stable-central* terms accretion never reaches: the nouns a system is built around rarely break, so they rarely appear in a learning, yet they are exactly what a reader needs to orient. Without seeding, the file fills with peripheral mechanics and never names what the project is about.
+
+### Seed goal
+
+Define the core domain nouns the area's **declared domain model** exposes that meet the qualifying bar (see "What earns a slot"). The codebase sets the count: seed every term that genuinely qualifies, none added to reach a number and none pulled from beyond the declared model to inflate one. A small domain yields a few; a large one, more. The bound is the **source** (the declared domain model of the area in scope — schema, core types, primary models, top-level domain docs — not a full-codebase trawl) and the **bar** (the same "a new engineer would need this defined" test), never a fixed quantity.
+
+### Scope of a seed
+
+- A **scoped run** — a learning capture, or a refresh narrowed to an area — seeds only that area's core nouns, and defines only terms it actually investigated against code. It does not reach for repo-wide nouns it never touched.
+- A **repo-wide bootstrap** — an explicit "create CONCEPTS.md" request — seeds the whole project's declared domain model. This is the only path that produces a coherent "what is this project" glossary; a scoped run cannot, and should not pretend to.
+
+## Be opinionated
+
+When the team uses several words for the same concept, pick the best one and retire the rest. Record retired synonyms as aliases on the entry (see "Per entry"). Settled distinctions go to the Flagged ambiguities tail. The glossary is not a record of all words the team has ever used — it is the team's agreed-upon vocabulary.
+
+## The file stands on its own
+
+Each entry teaches its concept to a reader with no access to anything else — no codebase, no PR history, no architecture meetings, no Slack. This rules out:
+
+- Implementation specifics (file paths, class names, function signatures, table names, library calls)
+- Status fields, dates, owners on the entries
+- Examples or current-config values drawn from the code — specific thresholds, counts, or enum values that will change. State the behavior, not the number: "each skill sets its own actionable threshold" rather than "surfaces at 50, fixes at 75."
+- Links to PRs, issues, channels, or roadmap milestones
+- Version-specific claims ("currently uses X; migrating to Y")
+
+Cross-references between entries within `CONCEPTS.md` are fine — they resolve internally. General programming vocabulary (caches, queues, jobs, sessions) and everyday domain English need no redefinition either. But if an entry leans on another *project-specific* term to make sense, that term must be defined here too — an undefined project-specific sibling is itself a candidate to add.
+
+## What earns a slot
+
+A term qualifies when its meaning here is precise enough that a new engineer would need it defined to follow conversations, tickets, or code. General programming vocabulary does not belong, even when used heavily.
+
+## Per entry
+
+Definition is one sentence — what the term means in this domain, what makes it distinct from neighbors. A term with non-obvious behavioral rules (lifecycle, cancellation semantics, ownership invariants) earns a second paragraph for those rules — never for elaborating the definition itself.
+
+When retired synonyms exist, list them as an aliases line directly under the definition: *Avoid: Booking, appointment*. Entities typically need more depth than value types; status concepts may need transition notes.
+
+## Relationships (optional)
+
+When relationships between entries carry load-bearing meaning (ownership, cardinality, lifecycle dependencies that span entries), capture them in a `## Relationships` section near the top of the file or its cluster. Skip when entries stand on their own without structural context — relationships are a lift for domains where structure is part of what makes terms meaningful, not a routine section.
+
+## Organization
+
+Cluster concepts by domain relationship — entities with their states, processes with their stages — so a reader sees structure without effort. A flat list works when the file is small. Reshape as the file grows.
+
+## Flagged ambiguities (tail of file)
+
+When two terms were used interchangeably and the team settled on a distinction, record the resolution as a one-line note: *"'account' had been used for both Customer and User — these are distinct."* This section is the audit trail for opinions the team has formed.
+
+## One illustrative entry — the shape, not a template
+
+```
+## Booking
+
+### Reservation
+A future commitment to seat a Party at a specified date and time.
+*Avoid:* Booking, appointment
+
+A Reservation owns its Party but does not own a Table — Tables are acquired only when the Party arrives, through a Seating. Lifecycle: Booked, Seated, Completed, No-Show. Cancellation before a Seating is non-destructive; cancellation after a Seating is recorded as a No-Show.
+
+### Party
+The guests committed to a Reservation. Each Reservation has exactly one Party. Party size is the count promised at booking, not the count who arrive.
+
+### Table
+A physical seating unit with fixed capacity. Tables are shared resources — they do not belong to Reservations and are allocated only on the day-of through Seatings.
+
+### Seating
+The act of placing a Party at a Table once the Party arrives. A Reservation has at most one Seating; a Table accumulates many Seatings across its lifetime.
+```

package/dist/plugins/.fusion-ce-skills/ce-compound/references/schema.yaml

@@ -0,0 +1,231 @@
+# Documentation schema for learnings written by ce-compound
+# Treat this as the canonical frontmatter contract for docs/solutions/.
+#
+# The schema has two tracks based on problem_type:
+#   Bug track  — problem_type is a defect or failure (build_error, test_failure, etc.)
+#   Knowledge track — problem_type is guidance or practice (best_practice, workflow_issue, etc.)
+#
+# Both tracks share the same required core fields. The tracks differ in which
+# additional fields are required vs optional (see track_rules below).
+
+# --- Track classification ---------------------------------------------------
+tracks:
+  bug:
+    description: "Defects, failures, and errors that were diagnosed and fixed"
+    problem_types:
+      - build_error
+      - test_failure
+      - runtime_error
+      - performance_issue
+      - database_issue
+      - security_issue
+      - ui_bug
+      - integration_issue
+      - logic_error
+  knowledge:
+    description: "Practices, patterns, conventions, decisions, workflow improvements, and documentation"
+    problem_types:
+      - best_practice
+      - documentation_gap
+      - workflow_issue
+      - developer_experience
+      - architecture_pattern
+      - design_pattern
+      - tooling_decision
+      - convention
+
+# --- Fields required by BOTH tracks -----------------------------------------
+required_fields:
+  module:
+    type: string
+    description: "Module or area affected"
+
+  date:
+    type: string
+    pattern: '^\d{4}-\d{2}-\d{2}$'
+    description: "Date documented (YYYY-MM-DD)"
+
+  problem_type:
+    type: enum
+    values:
+      - build_error
+      - test_failure
+      - runtime_error
+      - performance_issue
+      - database_issue
+      - security_issue
+      - ui_bug
+      - integration_issue
+      - logic_error
+      - developer_experience
+      - workflow_issue
+      - best_practice
+      - documentation_gap
+      - architecture_pattern
+      - design_pattern
+      - tooling_decision
+      - convention
+    description: "Primary category — determines track (bug vs knowledge). Prefer the narrowest applicable value; best_practice is the fallback when no narrower knowledge-track value fits."
+
+  component:
+    type: enum
+    values:
+      - rails_model
+      - rails_controller
+      - rails_view
+      - service_object
+      - background_job
+      - database
+      - frontend_stimulus
+      - hotwire_turbo
+      - email_processing
+      - brief_system
+      - assistant
+      - authentication
+      - payments
+      - development_workflow
+      - testing_framework
+      - documentation
+      - tooling
+    description: "Component involved"
+
+  severity:
+    type: enum
+    values:
+      - critical
+      - high
+      - medium
+      - low
+    description: "Impact severity"
+
+# --- Track-specific rules ----------------------------------------------------
+track_rules:
+  bug:
+    required:
+      symptoms:
+        type: array[string]
+        min_items: 1
+        max_items: 5
+        description: "Observable symptoms such as errors or broken behavior"
+      root_cause:
+        type: enum
+        values:
+          - missing_association
+          - missing_include
+          - missing_index
+          - wrong_api
+          - scope_issue
+          - thread_violation
+          - async_timing
+          - memory_leak
+          - config_error
+          - logic_error
+          - test_isolation
+          - missing_validation
+          - missing_permission
+          - missing_workflow_step
+          - inadequate_documentation
+          - missing_tooling
+          - incomplete_setup
+        description: "Fundamental technical cause of the problem"
+      resolution_type:
+        type: enum
+        values:
+          - code_fix
+          - migration
+          - config_change
+          - test_fix
+          - dependency_update
+          - environment_setup
+          - workflow_improvement
+          - documentation_update
+          - tooling_addition
+          - seed_data_update
+        description: "Type of fix applied"
+
+  knowledge:
+    optional:
+      applies_when:
+        type: array[string]
+        max_items: 5
+        description: "Conditions or situations where this guidance applies"
+      symptoms:
+        type: array[string]
+        max_items: 5
+        description: "Observable gaps or friction that prompted this guidance (optional for knowledge track)"
+      root_cause:
+        type: enum
+        values:
+          - missing_association
+          - missing_include
+          - missing_index
+          - wrong_api
+          - scope_issue
+          - thread_violation
+          - async_timing
+          - memory_leak
+          - config_error
+          - logic_error
+          - test_isolation
+          - missing_validation
+          - missing_permission
+          - missing_workflow_step
+          - inadequate_documentation
+          - missing_tooling
+          - incomplete_setup
+        description: "Underlying cause, if there is a specific one (optional for knowledge track)"
+      resolution_type:
+        type: enum
+        values:
+          - code_fix
+          - migration
+          - config_change
+          - test_fix
+          - dependency_update
+          - environment_setup
+          - workflow_improvement
+          - documentation_update
+          - tooling_addition
+          - seed_data_update
+        description: "Type of change, if applicable (optional for knowledge track)"
+
+# --- Fields optional for BOTH tracks ----------------------------------------
+optional_fields:
+  related_components:
+    type: array[string]
+    description: "Other components involved"
+
+  tags:
+    type: array[string]
+    max_items: 8
+    description: "Search keywords, lowercase and hyphen-separated"
+
+# --- Fields optional for bug track only -------------------------------------
+bug_optional_fields:
+  rails_version:
+    type: string
+    pattern: '^\d+\.\d+\.\d+$'
+    description: "Rails version in X.Y.Z format. Only relevant for bug-track docs."
+
+# --- Backward compatibility --------------------------------------------------
+# Docs created before the track system was introduced may have bug-track
+# fields (symptoms, root_cause, resolution_type) on knowledge-type
+# problem_types. These are valid legacy docs:
+#   - Bug-track fields present on a knowledge-track doc are harmless. Do not
+#     strip them during refresh unless the doc is being rewritten for other reasons.
+#   - When creating NEW docs, follow the track rules above.
+
+# --- Validation rules --------------------------------------------------------
+validation_rules:
+  - "Determine track from problem_type using the tracks section above"
+  - "All shared required_fields must be present"
+  - "Bug-track required fields (symptoms, root_cause, resolution_type) must be present on bug-track docs"
+  - "Knowledge-track docs have no additional required fields beyond the shared ones"
+  - "Bug-track fields on existing knowledge-track docs are harmless (see backward compatibility note)"
+  - "Track-specific optional fields may be included but are not required"
+  - "Enum fields must match allowed values exactly"
+  - "Array fields must respect min_items/max_items when specified"
+  - "date must match YYYY-MM-DD format"
+  - "rails_version, if provided, must match X.Y.Z format and only applies to bug-track docs"
+  - "tags should be lowercase and hyphen-separated"
+  - "Array-of-strings frontmatter items (symptoms, applies_when, tags, related_components, or any future array field) must be wrapped in double quotes when the value starts with a YAML reserved indicator (`, [, *, &, !, |, >, %, @, ?) or contains the substring `: ` — otherwise strict YAML parsers reject the file"

package/dist/plugins/.fusion-ce-skills/ce-compound/references/yaml-schema.md

@@ -0,0 +1,118 @@
+# YAML Frontmatter Schema
+
+`schema.yaml` in this directory is the canonical contract for `docs/solutions/` frontmatter written by `ce-compound`.
+
+Use this file as the quick reference for:
+- required fields
+- enum values
+- validation expectations
+- category mapping
+- track classification (bug vs knowledge)
+
+## Tracks
+
+The `problem_type` determines which **track** applies. Each track has different required and optional fields.
+
+| Track | problem_types | Description |
+|-------|--------------|-------------|
+| **Bug** | `build_error`, `test_failure`, `runtime_error`, `performance_issue`, `database_issue`, `security_issue`, `ui_bug`, `integration_issue`, `logic_error` | Defects and failures that were diagnosed and fixed |
+| **Knowledge** | `best_practice`, `documentation_gap`, `workflow_issue`, `developer_experience`, `architecture_pattern`, `design_pattern`, `tooling_decision`, `convention` | Practices, patterns, conventions, decisions, workflow improvements, and documentation. Prefer the narrowest applicable value; `best_practice` is the fallback. |
+
+## Required Fields (both tracks)
+
+- **module**: Module or area affected
+- **date**: ISO date in `YYYY-MM-DD`
+- **problem_type**: One of the values listed in the Tracks table above
+- **component**: One of `rails_model`, `rails_controller`, `rails_view`, `service_object`, `background_job`, `database`, `frontend_stimulus`, `hotwire_turbo`, `email_processing`, `brief_system`, `assistant`, `authentication`, `payments`, `development_workflow`, `testing_framework`, `documentation`, `tooling`
+- **severity**: One of `critical`, `high`, `medium`, `low`
+
+## Bug Track Fields
+
+Required:
+- **symptoms**: YAML array with 1-5 observable symptoms (errors, broken behavior)
+- **root_cause**: One of `missing_association`, `missing_include`, `missing_index`, `wrong_api`, `scope_issue`, `thread_violation`, `async_timing`, `memory_leak`, `config_error`, `logic_error`, `test_isolation`, `missing_validation`, `missing_permission`, `missing_workflow_step`, `inadequate_documentation`, `missing_tooling`, `incomplete_setup`
+- **resolution_type**: One of `code_fix`, `migration`, `config_change`, `test_fix`, `dependency_update`, `environment_setup`, `workflow_improvement`, `documentation_update`, `tooling_addition`, `seed_data_update`
+
+## Knowledge Track Fields
+
+No additional required fields beyond the shared ones. All fields below are optional:
+
+- **applies_when**: Conditions or situations where this guidance applies
+- **symptoms**: Observable gaps or friction that prompted this guidance
+- **root_cause**: Underlying cause, if there is a specific one
+- **resolution_type**: Type of change, if applicable
+
+## Optional Fields (both tracks)
+
+- **related_components**: Other components involved
+- **tags**: Search keywords, lowercase and hyphen-separated
+
+## Optional Fields (bug track only)
+
+- **rails_version**: Rails version in `X.Y.Z` format
+
+## Backward Compatibility
+
+Docs created before the track system may have `symptoms`/`root_cause`/`resolution_type` on knowledge-type problem_types. These are valid legacy docs:
+
+- Bug-track fields present on a knowledge-track doc are harmless. Do not strip them during refresh unless the doc is being rewritten for other reasons.
+- When creating **new** docs, follow the track rules above.
+
+## Category Mapping
+
+- `build_error` -> `docs/solutions/build-errors/`
+- `test_failure` -> `docs/solutions/test-failures/`
+- `runtime_error` -> `docs/solutions/runtime-errors/`
+- `performance_issue` -> `docs/solutions/performance-issues/`
+- `database_issue` -> `docs/solutions/database-issues/`
+- `security_issue` -> `docs/solutions/security-issues/`
+- `ui_bug` -> `docs/solutions/ui-bugs/`
+- `integration_issue` -> `docs/solutions/integration-issues/`
+- `logic_error` -> `docs/solutions/logic-errors/`
+- `developer_experience` -> `docs/solutions/developer-experience/`
+- `workflow_issue` -> `docs/solutions/workflow-issues/`
+- `best_practice` -> `docs/solutions/best-practices/`
+- `documentation_gap` -> `docs/solutions/documentation-gaps/`
+- `architecture_pattern` -> `docs/solutions/architecture-patterns/`
+- `design_pattern` -> `docs/solutions/design-patterns/`
+- `tooling_decision` -> `docs/solutions/tooling-decisions/`
+- `convention` -> `docs/solutions/conventions/`
+
+## Validation Rules
+
+1. Determine the track from `problem_type` using the Tracks table.
+2. All shared required fields must be present.
+3. Bug-track required fields (`symptoms`, `root_cause`, `resolution_type`) must be present on bug-track docs.
+4. Knowledge-track docs have no additional required fields beyond the shared ones.
+5. Bug-track fields on existing knowledge-track docs are harmless (see Backward Compatibility).
+6. Enum fields must match the allowed values exactly.
+7. Array fields must respect min/max item counts.
+8. `date` must match `YYYY-MM-DD`.
+9. `rails_version`, if present, must match `X.Y.Z` and only applies to bug-track docs.
+
+## YAML Safety Rules
+
+Strict YAML 1.2 parsers (`yq`, `js-yaml` strict, PyYAML) reject array items
+that start with a reserved indicator character as unquoted scalars. When
+writing items for any array-of-strings field (`symptoms`, `applies_when`,
+`tags`, `related_components`, or any future array field), wrap the value in
+double quotes if it starts with any of:
+
+`` ` ``, `[`, `*`, `&`, `!`, `|`, `>`, `%`, `@`, `?`
+
+Also quote if the value contains the substring `": "` — that punctuation
+confuses flow-style parsers.
+
+Example — before (breaks strict YAML):
+
+    symptoms:
+      - `sudo dscacheutil -flushcache` does not restore in-container mDNS
+
+Example — after (parses cleanly):
+
+    symptoms:
+      - "`sudo dscacheutil -flushcache` does not restore in-container mDNS"
+
+This rule applies to all array-of-strings frontmatter fields. Scalar string
+fields like `description:` have their own quoting rules (see plugin
+`AGENTS.md` under "YAML Frontmatter").

package/dist/plugins/.fusion-ce-skills/ce-compound/scripts/session-history/discover-sessions.sh

@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+# Discover session files across Claude Code, Codex, Cursor, and Pi.
+#
+# Usage: discover-sessions.sh <repo-name> <days> [--cwd /abs/repo/root] [--platform claude|codex|cursor|pi]
+#
+# Outputs one file path per line. Safe in both bash and zsh (all globs guarded).
+# Pass output to extract-metadata.py:
+#   python3 extract-metadata.py --cwd-filter <repo-name> $(bash discover-sessions.sh <repo-name> 7)
+#
+# Arguments:
+#   repo-name  Folder name of the repo (e.g., "my-repo"). Used for directory matching.
+#   days       Scan window in days (e.g., 7). Files older than this are skipped.
+#   --cwd      Absolute repo root. Used for exact Pi encoded-CWD discovery.
+#   --platform Restrict to a single platform. Omit to search all.
+
+set -euo pipefail
+
+REPO_NAME="${1:?Usage: discover-sessions.sh <repo-name> <days> [--cwd /abs/repo/root] [--platform claude|codex|cursor|pi]}"
+DAYS="${2:?Usage: discover-sessions.sh <repo-name> <days> [--cwd /abs/repo/root] [--platform claude|codex|cursor|pi]}"
+PLATFORM="all"
+REPO_CWD=""
+
+# Parse optional --platform flag
+shift 2
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --cwd) REPO_CWD="$2"; shift 2 ;;
+        --platform) PLATFORM="$2"; shift 2 ;;
+        *) shift ;;
+    esac
+done
+
+encode_pi_cwd() {
+    local cwd="${1%/}"
+    local encoded="${cwd//\//-}"
+    encoded="${encoded#-}"
+    printf -- "--%s--" "$encoded"
+}
+
+# --- Claude Code ---
+discover_claude() {
+    local base="$HOME/.claude/projects"
+    [ -d "$base" ] || return 0
+
+    # Find all project dirs matching repo name
+    for dir in "$base"/*"$REPO_NAME"*/; do
+        [ -d "$dir" ] || continue
+        find "$dir" -maxdepth 1 -name "*.jsonl" -mtime "-${DAYS}" 2>/dev/null
+    done
+}
+
+# --- Codex ---
+discover_codex() {
+    for base in "$HOME/.codex/sessions" "$HOME/.agents/sessions"; do
+        [ -d "$base" ] || continue
+
+        # Use mtime-based discovery (consistent with Claude/Cursor) so that
+        # sessions started before the scan window but still active within it
+        # are not missed.
+        find "$base" -name "*.jsonl" -mtime "-${DAYS}" 2>/dev/null
+    done
+}
+
+# --- Cursor ---
+discover_cursor() {
+    local base="$HOME/.cursor/projects"
+    [ -d "$base" ] || return 0
+
+    for dir in "$base"/*"$REPO_NAME"*/; do
+        [ -d "$dir" ] || continue
+        local transcripts="$dir/agent-transcripts"
+        [ -d "$transcripts" ] || continue
+        find "$transcripts" -name "*.jsonl" -mtime "-${DAYS}" 2>/dev/null
+    done
+}
+
+# --- Pi ---
+discover_pi() {
+    local agent_dir="${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}"
+    local base="${PI_CODING_AGENT_SESSION_DIR:-$agent_dir/sessions}"
+    [ -d "$base" ] || return 0
+
+    # Pi's explicit session-dir override stores session files directly in the
+    # supplied directory. The cwd filter later reads each header and keeps only
+    # sessions for the active repo.
+    if [ -n "${PI_CODING_AGENT_SESSION_DIR:-}" ]; then
+        find "$base" -maxdepth 1 -name "*.jsonl" -mtime "-${DAYS}" 2>/dev/null
+        if [ -z "$REPO_CWD" ]; then
+            for dir in "$base"/*"$REPO_NAME"*/; do
+                [ -d "$dir" ] || continue
+                find "$dir" -maxdepth 1 -name "*.jsonl" -mtime "-${DAYS}" 2>/dev/null
+            done
+        fi
+        return 0
+    fi
+
+    # Pi stores sessions under --<absolute-cwd-with-slashes-as-hyphens>--.
+    # When the caller supplies an exact repo root, probe only that encoded
+    # directory so sibling repos like my-repo-old never enter the pipeline.
+    if [ -n "$REPO_CWD" ]; then
+        local dir="$base/$(encode_pi_cwd "$REPO_CWD")"
+        [ -d "$dir" ] || return 0
+        find "$dir" -maxdepth 1 -name "*.jsonl" -mtime "-${DAYS}" 2>/dev/null
+        return 0
+    fi
+
+    # Fallback for direct script use without --cwd.
+    for dir in "$base"/*"$REPO_NAME"*/; do
+        [ -d "$dir" ] || continue
+        find "$dir" -maxdepth 1 -name "*.jsonl" -mtime "-${DAYS}" 2>/dev/null
+    done
+}
+
+# --- Dispatch ---
+case "$PLATFORM" in
+    claude)  discover_claude ;;
+    codex)   discover_codex ;;
+    cursor)  discover_cursor ;;
+    pi)      discover_pi ;;
+    all)
+        discover_claude
+        discover_codex
+        discover_cursor
+        discover_pi
+        ;;
+    *)
+        echo "Unknown platform: $PLATFORM" >&2
+        exit 1
+        ;;
+esac