Help

Using Archetype AI

Ingest a folder from this machine, inspect how the code actually connects, and ask questions against that graph — unused files, who last touched a line, which page reaches a helper, and whether a client module is importing server-only code.

What Archetype AI is

Archetype AI is a code architecture HUD (heads-up display). It does not replace your editor or git. It snapshots a TypeScript/JavaScript tree into a searchable graph: files, imports, public pages and routes, data flows, git recency, and parse failures.

You work in three layers. A project is a named workspace (for example “Protocol100” or “Archetype AI”). A codebase is one folder you ingested into that project (Studio and Web as two codebases, or an app’s src). The HUD is the graph of one codebase — or the public surface of every codebase in a project.

Typical jobs: “what is unused?”, “what would break if I change this file?”, “which commit introduced this?”, “why isn’t this module on the graph?”, “is the client importing a server module?”

Getting started

Built for people who already live in the repo: reviewing a TypeScript or JavaScript app, onboarding onto a route, or answering “what would this change hit?” It runs on the same machine as the folder you ingest. Sanity stores the graph; the HUD and Ask read that snapshot.

Prerequisites

This Next.js app running locally (typically npm run dev in web/).
A folder of TS/JS on this computer that the process can read.
Cursor installed if you want Open in Cursor from the inspector or Ask chips.

First ingest

Open Ingest. Create a new project or pick an existing one.
Browse to a folder on this computer (the machine running the app). You can ingest src, the repo root, or any subfolder. Recent folders are remembered per project.
Scan, then ingest. If a file fails the TypeScript checker, it is skipped and listed — it is not silently missing.
From the project page, open Tree for health and insights, HUD for the graph, or Ask for written Q&A.
After you edit code, ingest again. The graph is a snapshot of the last successful ingest, not a live file watcher.

First-time path: Ingest folder → project appears on Projects → Tree to confirm counts → HUD to click around → Ask “Find all unused code”.

Core concepts

Identity is the file path

Nodes are keyed by path inside the ingested folder (src/lib/utils.ts), not by component name. Two files named Button stay distinct. Compare and Ask citations use the same paths.

Public entries vs everything else

A public entry is how a user or client reaches the app: Next.js page.tsx / route.ts, SPA main / App / index, files under pages, routes, screens, or views, and JSX Route targets. Unused means nothing imports the file and it is not treated as a public entry. Tests and scripts can look unused even when you still want them.

Boundaries: client, server, shared

"use client" is client. "use server" and import "server-only" are server. Files with neither directive are shared (safe for client to import cn and most shadcn utils). The Client → server column only flags a client file importing a real server module.

Data flows vs import edges

Dashed edges are static imports. Solid/animated edges are runtime flows: props, action triggers, store subscriptions, Sanity queries and writes. Hide import edges when you only care how data moves.

Features

Projects home

Lists every project with codebase count, last ingest time, unused files, data flows, and skipped parses. Open a project to see each codebase’s health grid.

Ingest

Scan any folder this app can read. Build output (isolate, dist, hashed Vite chunks, .next, coverage) is skipped so vendor bundles do not pollute unused lists. You choose which scanned files to store. Skipped checker failures show in the ingest status and persist on the codebase.

Codebase tree

Health counts, a stale banner when files changed on disk since ingest, architecture insights (import cycles, hotspots, client → server), a watchlist (unused, TODOs / FIXMEs, recently changed, parse failures), and the route tree from public entries. Re-ingest from the stale banner prefills the same folder.

HUD

Overview starts from public entries and collapses utilities. Click a node to inspect; double-click to drill in. Breadcrumbs return to overview. Selecting a file writes filePath (and optional line) into the URL so you can share or reload the same focus.

Kind filter: all, public, unused, pages, components, hooks, utils, API.
Recency heatmap: git age on nodes (fresh / aging / stale).
Trace: pink path from the nearest public entry to the selected file.
Amber outline: the file sits on a static-import cycle.
Layout TB or LR. Hide artifacts, hide import edges, toggle flow types.
Inspector: copy path, Open in Cursor, Ask this file, source preview, last commit, blast radius (what would break / what this depends on).
Export report downloads a markdown summary of the current graph.

Ask

Free-form questions over the indexed graph plus live git blame when a line is cited. Suggestion chips are tailored to the project. Paths in an answer become chips: the path opens the HUD focused on that file; Cursor opens it in this editor (with line when the citation includes one).

Compare

On a project with two or more codebases, Compare diffs file paths: only left, only right, shared, unused counts, public entries, and data-flow counts. Useful for Studio vs Web, or two packages in one product. Explain this diff writes the same comparison in English.

Ask and HUD AI

Ask is a model with graph tools, not a dump of the repo. It ranks unused files, narrates routes, explains client→server, compares codebases, writes PR/incident briefs, and can return a HUD command (focus, filters, hide imports, tour). Tree insights, Compare, the stale banner, and the HUD inspector expose the same briefs as buttons. The HUD bar at the bottom of the canvas turns a sentence into those filters without leaving the graph. Splits are proposals — Open in Cursor, then re-ingest to verify.

Worked examples

Let Ask drive the canvas

Ask “Show unused, hide import edges, layout LR”. When a HUD command card appears, apply it. Or type the same sentence in the bar at the bottom of the HUD.

Rank unused before a cleanup

Tree → Rank unused files, or Ask the same. Inspect likely app paths; ignore tests, shadcn, and scripts unless you meant them.

See how a helper is reached

HUD search for cn or utils.ts. Leave Trace on. The pink outline is the path from a page or layout. The inspector caption names that entry and hop count.

Blame a line from a written answer

Ask “Who last touched HomePage?” If the answer cites src/app/page.tsx:12, click the path for the HUD with the blamed hunk, or Cursor to jump to line 12.

Catch a Next.js boundary mistake

Open the codebase Tree. If Client → server lists CheckoutButton → chargeUser, that client file is importing a "use server" or server-only module. Click through to the HUD.

Keep the graph honest after local edits

If the Tree shows files changed since ingest, open Re-ingest. The folder is prefilled. Scan and ingest again, then return to the HUD.

Less-obvious recipes

Share a focused graph instead of a screenshot

Click the file in the HUD, copy the browser URL. Anyone with the app open gets the same codebase, file, and line. Public HUD (/hud?project=… without a slug) is the shared surface across codebases.

Review a PR as an architecture report

HUD → Export report. You get markdown totals, public entries, unused files, skipped parses, endpoints, and flow types. Paste into a PR description or incident note.

Decide if a refactor is blast radius or a leaf

Select the module, read Incoming vs Would break. High incoming plus a fresh heatmap ring is a hotspot — change it last, or add tests first. Insights → Hotspots ranks the same idea for the whole codebase.

Prove a missing file is a parse failure, not a forgotten ingest

Search the HUD for the path. Skipped files appear in the dropdown even without a node. The amber banner explains the checker reason. Re-ingest after fixing the file.

See runtime architecture without import noise

Hide import edges, leave prop pass / action trigger / Sanity flows on. SPA and Next apps often look empty of “architecture” until imports are hidden.

Studio vs Web as two graphs

Ingest each folder into the same project with different codebase names. Compare shows paths that exist only on one side — useful when you thought a utility was shared.

Stand-up from the watchlist

Tree → TODOs / FIXMEs and Recently changed. Those lists are git- and marker-backed, not a kanban. Click through to HUD or Cursor.

Orient a new teammate on one route

HUD → kind Pages (or search a route). Drill into the page, expand utilities only if needed, keep Trace on. They see the route’s neighborhood instead of 150 nodes.

Keyboard shortcuts

Where	Keys	Action
HUD	/ or search box	Jump by name, route, or file (includes skipped parses)
HUD	⌘K / Ctrl+K	Command palette: files, layout, filters, export, Ask, Help
HUD	?	HUD legend
HUD	Esc	Close search, legend, palette, or selection
HUD	Click node	Select and inspect
HUD	Double-click node	Drill into that neighborhood
HUD	Click edge	Inspect flow type and payload contract
HUD	Click pane	Clear selection

Glossary

HUD: Heads-up display — the interactive architecture graph.
Ingest: Parse a folder and write the graph to Sanity. Repeat after meaningful code changes.
Codebase: One ingested folder under a project, with its own HUD, Ask scope, and health stats.
Hotspot: A file with many incoming imports and recent git activity — expensive to change casually.
Blast radius: Immediate neighbors: files that depend on this one, and files this one depends on.
Skipped parse: The file was on disk at ingest but the checker or parser failed, so it has no node.
Stale: Source files on disk differ from last ingest (committed or uncommitted).
Artifact: Build or bundler output (isolate, dist, hashed chunks). Hidden in HUD and watchlist by default.

FAQ & troubleshooting

The HUD only shows a handful of files.

Overview is capped on purpose. Search, kind filters, drill-down, or Expand utilities. Public HUD without a codebase slug shows public entries across the project.

A file I know exists is not on the graph.

It may have failed parse (search skipped files), been deselected at ingest, live under a skipped directory, or look like a build artifact. Check the Tree watchlist and ingest skipped list.

Unused count looks too high.

Generated files, shadcn pieces, and scripts often have no importers. Public entries are not counted unused. Isolate/hashed bundles are hidden from the unused watchlist even on old data.

Client → server is empty, or I expected cn to appear.

Shared utils without "use server" or server-only are not violations. Re-ingest if you just added those markers; the disk check also reads current files under the saved folder.

Open in Cursor does nothing.

The codebase must have a folder path from ingest. Relative paths like . are resolved on the server. Cursor must be installed and allowed to handle cursor:// links.

Ask falls back to a raw list, or briefs fail.

The model needs OPENAI_API_KEY (or an AI Gateway key) in web/.env.local and a restart of the Next.js app. Graph facts still work without a model; judgment, tours, and prose reports do not.

Scan failed or ingest skipped many files.

Checker failures are per-file; others still ingest. Fix the listed modules and re-ingest. The app must be running on the machine that has the folder.

Compare looks wrong.

It diffs ingested paths, not git. Ingest both sides the same way (both src, or both repo roots) or paths will not line up.

Limits, privacy, and accuracy

Ingest and Open in Cursor / source preview read folders on the computer running this Next.js app. That graph is stored in your Sanity project.
The HUD is not a live language server. After you commit or refactor, ingest again.
Dynamic import() is indexed when the path is a string literal. Fully computed paths will not resolve.
Unused and reachability are graph heuristics, not proof it is safe to delete.
Import cycles use static imports only. Data-flow edges are not part of cycle detection.

Need the graph itself? Ingest a folder, open the HUD, or Ask the graph. Press ? inside the HUD for the on-canvas legend.