# {{PROJECT_NAME}}

A multi-surface AI application scaffolded with [Fragment](https://github.com/TheDigitalGriot/fragment-ai-scaffold) — **Prism-image**.

## Structure

```
{{PROJECT_NAME}}/
├── apps/                 # Surface apps (electron / vscode / tui — whichever were scaffolded)
├── packages/
│   ├── core/             # Shared logic: event bus, controllers, state
│   └── ui/               # Shared React components (chat, timeline, model selector)
├── .gitnexus/            # Code-intel index (config tracked, generated graph gitignored)
└── .prism/               # Prism workflow artifacts (run /prism-init to scaffold fully)
```

## Routing Table

Per-task load list — read only what's named, skip the rest.

| Task | Read first | Surface / tool |
|---|---|---|
| Wire an AI plugin into the surfaces | the plugin's `.claude-plugin/plugin.json` | `/fragment-connect` |
| Add a surface (electron / vscode / tui) | this file | `/fragment` (or `fragment add`) |
| Shared logic / event bus / state | `packages/core/src/` | (direct edit) |
| Shared UI components | `packages/ui/src/` | (direct edit) |
| Research / plan / implement / validate a feature | latest in `.prism/shared/` | `/prism-research` → `/prism-plan` → `/prism-implement` → `/prism-validate` |
| Run a stage headless (long / autonomous work) | `.prism/shared/ref/icm-run-contract.md` | ICM stage-walk (below) |

## Code-intel first

Before reaching for Glob / Grep / manual file-hunting, **query the code graph**. Prefer the discovery
agents — **graph-navigator** (structure, call-chains, blast-radius), **codebase-analyzer** (HOW,
file:line), **codebase-locator** (WHERE), **prism-locator** (`.prism/` docs). The generated index lives
in `.gitnexus/` (`config.json` tracked, cache gitignored). Read only the slice each step needs; never
photocopy whole files.

## ICM stage-walk (headless / autonomous runs)

Long or headless work runs as an Isolated-Context stage-walk, **not** one monolithic prompt:

1. **Write a stage contract** — copy `.prism/shared/plans/_TEMPLATE-stage-CONTEXT.md` to
   `<date>-<stage>-CONTEXT.md` (Role · Inputs [Working | Reference] · Locked Decisions · Process ·
   Success criteria · Heartbeat tokens). A headless run cannot ask questions — decide every fork here.
2. **Hand the run a thin router prompt** pointing at that contract path. It executes autonomously,
   loads context via the discovery agents, and heartbeats one token line per step to
   `.prism/local/<stage>-progress.txt`. Binding: `.prism/shared/ref/icm-run-contract.md`.

## Stuck Protocol — device/cloud tool recovery (non-negotiable)

When ANY device/cloud tool returns empty/`[]`/"not connected"/"no DOM"/403 or fails first-call, that is NOT "unavailable." Before reporting a tool blocked/skipped, run the ladder: **(1) retry 2-3x** (lazy bridges — Claude-in-Chrome, MCP attach — return empty at session start; `[]` != absent) -> **(2) switch surface** (built-in browser pane <-> Claude-in-Chrome; Windows-MCP PowerShell when the sandbox has no route; the Gmail *browser* when the *connector* is the wrong account) -> **(3) replay the logs** (session_info -> last successful run of this task -> copy its exact tool sequence) -> **(4) ask Gavin ONE direct question.** Gavin's word about his own machine is GROUND TRUTH — try his path before theorizing why it can't work. Reporting "blocked" without steps 1-3 is a DEFINED ERROR, not a status; a forced skip = INCOMPLETE run, said loudly. Applies to prism-verify/browse/screenshot/debug and any skill or agent that drives a browser, MCP, or device bridge.

## Prism Workflow

Artifacts live under `.prism/`: research → `shared/research/` · plans → `shared/plans/` · validation →
`shared/validation/` · personal notes → `local/` (gitignored). Run `/prism-init` to scaffold fully.

---
_Author: {{AUTHOR_NAME}} · {{YEAR}} · Generated by create-fragment (Prism-image)_