---
feature_id: FTR-34
title: Repository Ledger Visualization
category: Continuity
optional: true
depends_on: none (soft: benefits from FTR-13 if installed)
source: Not from Project_Kickoff_Seed_Prompt_v2.3.md — supplied directly by the user as a complete, already-well-structured draft spec. No corresponding item in Bootstrap_Function_Registry.md. See coverage_report.md Section 10.
registry_refs: []
---

# Repository Ledger Visualization

## What this is
An on-demand, on-brand HTML snapshot of a project's whole file repository — folders and files grouped into a small number of meaningful categories, with counts, rendered every time from a saved, locked design template rather than redesigned from scratch per request. Triggered by a plain-language command ("show me the project ledger," "repository ledger," "visualize the repository" — adapt to the project's own established vocabulary), not shown automatically at session start. That last point is the whole distinction from its closest sibling in this category, FTR-09 (Startup Display & Reminder Mode): FTR-09 is automatic, every session, and text-based; this feature is on-demand, invoked by name, and rendered as a styled HTML document.

This is the first feature in this catalog to actually use the **pointer-style** mechanism documented in `feature_library\index.md` (added at v4.0, never yet applied to a real feature). The full design-derivation logic and category-grouping rules are long enough — and invoked rarely enough — that inlining all of it into every installing project's `admin\AGENT_INSTRUCTIONS.md` would be exactly the kind of bloat that mechanism exists to prevent. See the Write section below for exactly how that split works for this feature.

The actual raw HTML/CSS template — the reusable, copy-into-a-project starting point — is hosted as its own file rather than embedded in this specification, same pattern as FTR-18's Motion Branding Spec and generic motion template: [items/repository-ledger-visualization-template.html](https://claude.sotekzone.com/v/20260726a/items/repository-ledger-visualization-template.html). A fully populated, rendered example (fabricated sample data, a worked palette) is also hosted separately so a person can actually see what a finished ledger looks like before installing anything: [items/repository-ledger-visualization-preview.html](https://claude.sotekzone.com/v/20260726a/items/repository-ledger-visualization-preview.html).

## Why this exists, and how it's different from FTR-15 and FTR-22
This is not the Project Cache (FTR-15, which keeps Claude's own Project Files current in claude.ai) and not the Project Audit / Health Check (FTR-22, which flags problems and recommends fixes). This feature has no diagnostic function at all — it exists purely so a person can see, at a glance and in a format they find genuinely pleasant to look at, what's actually in their project right now. Three features, three different jobs: FTR-15 keeps a *copy* of key files current somewhere Claude can read them; FTR-22 tells you *what's wrong*; this feature just shows you *what's there*, well.

The distinguishing design choice, worth stating plainly since it's easy to build this wrong: the visual identity is derived **once**, from the project's own actual subject matter, then locked and reused — never regenerated fresh (and inconsistently styled) on every request. A repository ledger that looks different every time it's rendered isn't a ledger, it's a mockup generator.

## The one-time design derivation
On first install (or first invocation, if the palette wasn't finalized at install time), the assistant:
1. Names the project's actual subject matter plainly (what kind of project this is, what it's for).
2. Proposes 4–6 named hex values that genuinely suit that subject — not a generic AI-default palette. Explicitly avoid, unless the subject genuinely calls for one of them: cream+terracotta, near-black+neon, or hairline-broadsheet defaults. Treat this exactly like any other bespoke design brief: name the subject, propose colors that fit it, justify the choice in one sentence each, and confirm with the person before locking anything in. See the hosted preview above for one full worked example (a fabricated "Thornwood Archive Project," navy-ink background with brass/sage/rust/violet accents) — a reference for the *shape* of a good derivation, not a palette to reuse.
3. Proposes a type pairing: a display face, a body face, and a monospace/data face — three roles, not one font doing everything.
4. Proposes one signature layout idea if the subject suggests one (optional — a strong default layout is fine if nothing subject-specific comes to mind).
5. Confirms the full derived set with the person before locking it into the template file. This step is not optional and not skippable by defaulting to the hosted template's own placeholder values — those are explicitly marked as an unrelated illustrative example, not a starting point to reuse.

## Category grouping
Groups the project's actual top-level folders into a small number of categories — typically 3–5: enough to be meaningful, few enough to scan at a glance. Category boundaries reflect what the categories actually *are* for this specific project (e.g. "control/source-of-truth files" vs. "raw intake" vs. "reference archive" vs. "active deliverables") — the labels and the count adapt to the real structure; there is no fixed number to fill. If FTR-13 (Document Tracker System) is installed, category boundaries can draw on existing tracker metadata; if it isn't, category boundaries come from folder structure and naming alone — this feature works either way (see the soft dependency note above).

## Data source rule
Every render comes from a **fresh, live scan** of the actual file system at generation time — never a cached or reused prior render. If an exact recount of a very large folder genuinely isn't practical, a tracker-sourced count is an acceptable substitute, but it must be visibly marked as approximate (a `~` prefix on the count) and disclosed in the footer — never presented as freshly counted if it wasn't. The hosted preview demonstrates this convention directly (its `#drop\` card shows `~4 files`, with the approximation disclosed in the footer).

## Storage
- **Template file** (the locked design reference — markup + CSS; only the data inside re-renders each time, the design itself doesn't): saved alongside the project's other tracker/dashboard display files if FTR-13's two-layer tracker system is installed; otherwise in the project's reference-documents location. Suggested filename: `[ProjectCode]_Repository_Ledger_TEMPLATE.html`.
- **Point-in-time snapshots** (optional — only if the person explicitly asks to keep a dated copy): saved separately from the template, dated, in the project's reference/archive location. A snapshot never overwrites the template itself.

## Customization stays open after first generation
The design is intentionally flexible, not a permanent constraint set at install time. The person can ask for a palette change, a layout change, or a category change at any point — the new choice becomes the new locked template, replacing the old one, not stacking on top of it. The one-time derivation above is a starting point picked to fit the subject as understood at install time, nothing more.

## Assess first
- Confirm the project's actual subject matter is already established (should exist from Agent Role & Project Identity, FTR-04) — the palette/type derivation needs something real to derive from, not a guess.
- Check whether FTR-13 (Document Tracker System) is installed — if so, category boundaries can draw on existing tracker metadata; if not, this feature still works from a plain folder scan, per its soft dependency.
- Check whether a template file already exists at the expected location (per Storage above) — if so, this is a re-invocation, not a first install; skip the design-derivation step entirely and go straight to a fresh data scan against the existing locked template.
- Check whether `admin\feature-prompts\` already exists as a folder in this project (per the pointer-style mechanism) — if not, it gets created as part of this feature's own install.

## Ask, only if needed
- If the project's subject matter genuinely isn't clear enough to derive a fitting palette from: ask plainly what the project is about, rather than defaulting to a generic palette.
- Present the derived palette + type pairing + any layout idea for confirmation before locking it into the template file — this is not optional, per the design-derivation section above.
- If a template already exists and the person is invoking this for the first time in the current session: no need to ask anything — just re-scan and render against the existing template.

## Write
1. If no template file exists yet: run the one-time design derivation (palette, type pairing, layout idea), present it for confirmation, then generate and save the template file per the Storage rules above — starting from the raw structure at [items/repository-ledger-visualization-template.html](https://claude.sotekzone.com/v/20260726a/items/repository-ledger-visualization-template.html), with the derived, confirmed values filled in.
2. Whether the template is new or already existed: run a fresh, live scan of the project's actual file system. Group real folders into the category structure (existing categories if the template already exists and the structure hasn't changed; freshly derived categories only on first generation or if the person asks for a category change).
3. Populate the template's data fields (file counts, folder paths, category assignments, status tags if applicable) from the fresh scan — never from a cached count, except where a `~`-marked approximate count is explicitly disclosed per the Data source rule.
4. Present the rendered ledger to the person.
5. If the person asks to keep a dated snapshot: save it separately, per the Storage rules — never overwriting the template.
6. Register the template file in the Document Tracker (FTR-13) if installed.

This feature uses the **pointer-style** mechanism (see `feature_library\index.md`'s POINTER-STYLE FEATURES section) rather than writing its full operating content inline into `admin\AGENT_INSTRUCTIONS.md`. Two things get written on install, not one:

**First**, add this short stub to `admin\AGENT_INSTRUCTIONS.md`:

```
◆ REPOSITORY LEDGER VISUALIZATION — POINTER
Full detail: admin\feature-prompts\repository-ledger-visualization.md
Invoke when: the person asks to see the project ledger, repository
  visualization, or a visual snapshot of what's in the project
```

**Second**, write the full operating content — the design-derivation process, category-grouping rules, storage rules, data-source rule, customization note, and the numbered Write steps above — to `admin\feature-prompts\repository-ledger-visualization.md` in the target project (creating `admin\feature-prompts\` if it doesn't already exist). Include, verbatim, the complete raw HTML/CSS structure from [items/repository-ledger-visualization-template.html](https://claude.sotekzone.com/v/20260726a/items/repository-ledger-visualization-template.html) as the actual reusable starting point — fetch or read that file directly rather than reconstructing it from memory, since it's the canonical source and this specification only points to it. This pointer file is what a future session actually reads when the trigger phrase comes up; the stub above is just the always-visible reminder that this capability exists.

**Notes for the installing/re-invoking assistant, carried into `admin\feature-prompts\repository-ledger-visualization.md` verbatim:**
- The palette derivation step is the whole point — do not skip it and fall back to the hosted template's own placeholder hex values for an unrelated project. Treat it like any other bespoke design brief: name the subject, name 4–6 hex values that suit it, justify the choice, confirm with the person, then lock it into the template file. See the hosted preview for the shape of a good derivation.
- Card accent colors should map to something meaningful (status, category type, freshness) — never purely decorative.
- If FTR-13 isn't installed, this feature still works from a plain folder scan; category boundaries come from folder structure and naming instead of tracker metadata.

## Confirm
Confirm: the pointer stub is in `admin\AGENT_INSTRUCTIONS.md`, the full operating content (including the raw template, pulled from its hosted source) is in `admin\feature-prompts\repository-ledger-visualization.md`, and — if this was a first install rather than a re-invocation — the derived palette and type pairing were actually confirmed with the person before the template file was locked in. Want to run it now to see the first render, or is that everything for now?