Skip to main content
Agent skill

Engram

any input (code, docs, papers, images) -> knowledge graph -> clustered communities -> static Ontology Studio + JSON + audit report. Use when user asks any question about a codebase, project content, architecture, or file relationships, especially if .engram/ exists. Provides persistent graph with god nodes, community detection, and BFS/DFS query tools.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Engram when an AI agent needs a reusable SKILL.md workflow for this job: any input (code, docs, papers, images) -> knowledge graph -> clustered communities -> static Ontology Studio + JSON + audit report. Use when user asks any question about a codebase, project content, architecture, or file relationships, especially if .engram/ exists. Provides persistent graph with god nodes, community detection, and BFS/DFS query tools.

When not to use it

Skip Engram when the task is outside the analysis category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/engram
# Save SKILL.md to ~/.claude/skills/engram/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/engram/SKILL.md. For a shared project, commit the folder at .claude/skills/engram/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Engram skill for this task: Use Engram when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

69/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
55/100
Source signals
70/100
Model compatibility evidence
  • claudeinferred

    The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.

  • chatgptinferred

    The skill text mentions ChatGPT or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.

  • geminiinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • copilotinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • llamainferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • perplexityinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • mistralinferred

    The skill text mentions Mistral or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.

  • grokinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# /engram

> Alias: `/graphify` still triggers this skill (deprecated alias for `/engram`).

Turn any folder of files into a navigable knowledge graph with community detection, a verifiable audit trail, and three outputs: a static Ontology Studio, GraphRAG-ready JSON, and a plain-language GRAPH_REPORT.md.

## Usage

``` /engram # full pipeline on current directory → Obsidian vault /engram <path> # full pipeline on specific path /engram https://github.com/<owner>/<repo> # clone repo locally, then run the full pipeline /engram https://github.com/<owner>/<repo> --branch <branch> # clone a specific branch before graphing /engram <path> --scope auto # safe default for code/review repos /engram <path> --scope tracked # include newly staged files too /engram <path> --all # full recursive folder walk for knowledge bases /engram <path> --directed # build directed graph (preserves source→target) /engram <path> --mode deep # thorough extraction, richer INFERRED edges /engram <path> --pdf-ocr auto # preflight PDFs; OCR scanned/low-text PDFs with mistral-ocr when needed /engram <path> --update # incremental - re-extract only new/changed files /engram <path> --cluster-only # rerun clustering on existing graph engram studio export .engram/studio # build the self-contained static Ontology Studio (open by serving it with any static file server) /engram <path> --svg # also export graph.svg (embeds in Notion, GitHub) /engram <path> --graphml # export graph.graphml (Gephi, yEd) /engram <path> --neo4j # generate .engram/cypher.txt for Neo4j /engram <path> --neo4j-push bolt://localhost:7687 # push directly to Neo4j /engram <path> --mcp # start MCP stdio server for agent access /engram <path> --watch # watch folder, auto-rebuild on code changes (no LLM needed) /engram <path> --wiki # build agent-crawlable wiki (index.md + one article per community) engram wiki describe --graph .engram/graph.json --mode assistant --targets all # opt-in description sidecars engram export wiki --graph .engram/graph.json --descriptions .engram/wiki/descriptions.json engram export obsidian --graph .engram/graph.json --descriptions .engram/wiki/descriptions.json /engram <path> --obsidian --obsidian-dir ~/vaults/my-project # write vault to custom path (e.g. existing vault) /engram add <url> # fetch URL, save to ./raw, update graph /engram add <url> --author "Name" # tag who wrote it /engram add <url> --contributor "Name" # tag who added it to the corpus /engram migrate-state --dry-run # plan graphify-out -> .engram migration /engram query "<question>" # BFS traversal - broad context /engram query "<question>" --dfs # DFS - trace a specific path /engram query "<question>" --budget 1500 # cap answer at N tokens /engram summary --graph .engram/graph.json # compact first-hop orientation before deep traversal /engram minimal-context --task "review PR" --graph .engram/graph.json # first review call /engram review-delta --files src/auth.ts --graph .engram/graph.json # review impact for changed files /engram review-analysis --files src/auth.ts --graph .engram/graph.json # blast radius + review views /engram recommend-commits --files src/auth.ts,src/session.ts --graph .engram/graph.json # advisory commit grouping /engram scope inspect <path> --scope auto # inspect the resolved file inventory first /engram path "AuthModule" "Database" # shortest path between two concepts /engram explain "SwinTransformer" # plain-language explanation of a node ```

## Input scope policy

- Default to `--scope auto` for codebase and review work. In Git repos this means committed files plus `.engram/memory/*`. - Use `--scope tracked` when newly staged files must influence the graph before commit. - Use `--all` only when the user clearly wants a knowledge-base style crawl of docs, notes, papers, screenshots, audio, or video. - If the repo is dirty or the right scope is unclear, run `engram scope inspect <path> --scope auto` first and summarize what will be included or excluded.

## What engram is for

Engram is built around Andrej Karpathy's /raw folder workflow: drop anything into a folder - papers, tweets, screenshots, code, notes - and get a structured knowledge graph that shows you what you didn't know was connected.

Three things it does that Claude alone cannot: 1. **Persistent graph** - relationships are stored in `.engram/graph.json` and survive across sessions. Ask questions weeks later without re-reading everything. 2. **Verifiable audit trail** - every edge is tagged EXTRACTED, INFERRED, or AMBIGUOUS. You know what was found vs invented. 3. **Cross-document surprise** - community detection finds connections between concepts in different files that you would never think to ask about directly.

Use it for: - A codebase you're new to (understand architecture before touching anything) - A reading list (papers + tweets + notes → one navigable graph) - A research corpus (citation graph + concept graph in one) - Your personal /raw folder (drop everything in, let it grow, query it)

## What You Must Do When Invoked

If no path was given, use `.` (current directory). Do not ask the user for a path.

If the path argument starts with `https://github.com/` or `http://github.com/`, treat it as a GitHub URL and run Step 0 before anything else. Replace the target path for all later steps with the resolved local clone path.

Follow these steps in order. Do not skip steps.

### Step 0 - Clone GitHub repos when the input is a GitHub URL

```bash GRAPHIFY_BRANCH_FLAG="" if the original invocation included --branch <name>, set GRAPHIFY_BRANCH_FLAG="--branch <name>"

LOCAL_PATH=$(engram clone "INPUT_GITHUB_URL" $GRAPHIFY_BRANCH_FLAG) ```

Use `LOCAL_PATH` as the input path for all subsequent commands.

### Step 1 - Ensure engram is installed

```bash command -v engram >/dev/null 2>&1 || command -v graphify >/dev/null 2>&1 || npm install -g @sentropic/engram 2>&1 | tail -3 mkdir -p .engram ```

If the install succeeds, print nothing and move straight to Step 2.

### Step 2 - Detect files

```bash engram detect "INPUT_PATH" --scope auto --out .engram/.graphify_detect.json ```

Replace INPUT_PATH with the actual path the user provided. Do NOT cat or print the JSON - read it silently and present a clean summary instead:

``` Corpus: X files · ~Y words code: N files (.py .ts .go ...) docs: N files (.md .txt ...) papers: N files (.pdf ...) images: N files video: N files (.mp4 .mp3 ...) ```

Then act on it: - If `total_files` is 0: stop with "No supported files found in [path]." - If `skipped_sensitive` is non-empty: mention file count skipped, not the file names. - If the user asked for a knowledge-base style crawl, rerun detection with `--all`. - If newly staged files should count, rerun with `--scope tracked`. - If `total_words` > 2,000,000 OR `total_files` > 200: show the warning and the top 5 subdirectories by file count, then ask which subfolder to run on. Wait for the user's answer before proceeding. - Otherwise: proceed to Step 2.5. It is a safe no-op if no video or PDF files need preprocessing.

### Step 2.5 - Prepare semantic detection, including audio/video transcripts and PDF preflight/OCR when needed

Always run this step. It transcribes audio/video when present, runs local PDF preflight for papers, and converts text-layer PDFs locally. For scanned/low-text PDFs, keep two OCR paths explicit: the assistant vision model may interpret the original PDF or extracted image chunks during semantic extraction, and `mistral-ocr` may be used when OCR is explicitly requested or when a configured `MISTRAL_API_KEY` is available and preflight detects a scanned/low-text PDF. Do not call Mistral blindly. In `auto` mode, if no key/provider is available, leave the source PDF in semantic inputs so the assistant path can still handle it. Generated transcripts, PDF Markdown sidecars, and relevant PDF-extracted images are treated as semantic inputs in Step 3.

```bash node -e " (async () => { const fs = require('fs'); const { prepareSemanticDetection } = require('@sentropic/engram');

const detect = JSON.parse(fs.readFileSync('.engram/.graphify_detect.json', 'utf-8')); const analysis = fs.existsSync('.engram/.graphify_analysis.json') ? JSON.parse(fs.readFileSync('.engram/.graphify_analysis.json', 'utf-8')) : null;

const { detection: semanticDetect, transcriptPaths, pdfArtifacts } = await prepareSemanticDetection(detect, { transcriptOutputDir: '.engram/transcripts', pdfOutputDir: '.engram/converted/pdf', godNodes: (analysis && analysis.gods) || [], });

fs.writeFileSync('.engram/.graphify_detect_semantic.json', JSON.stringify(semanticDetect, null, 2)); fs.writeFileSync('.engram/.graphify_transcripts.json', JSON.stringify(transcriptPaths, null, 2)); fs.writeFileSync('.engram/.graphify_pdf_ocr.json', JSON.stringify(pdfArtifacts, null, 2)); console.log('Prepared semantic inputs: ' + transcriptPaths.length + ' transcript(s), ' + pdfArtifacts.filter((item) => item.markdownPath).length + ' PDF sidecar(s)'); )().catch((error) => { console.error(error instanceof Error ? error.message : String(error)); process.exit(1); }); " ```

After semantic preparation: - use `.engram/.graphify_detect_semantic.json` for semantic cache and semantic extraction - keep `.engram/.graphify_detect.json` for corpus summary, manifest, and final reporting

### Step 3 - Extract entities and relationships

**Before starting:** note whether `--mode deep` and `--directed` were given. You must pass `DEEP_MODE=true` to every subagent in Step B2 if it was. Track both flags from the original invocation - do not lose them.

This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (Claude, costs tokens).

**Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.**

Note: Parallelizing AST + semantic saves 5-15s on large corpora. AST is deterministic and fast; start it while subagents are processing docs/papers.

#### Part A - Structural extraction for code files

For any code files detected, run AST extraction in parallel with Part B subagents:

```bash node -e "(async () => { const fs = require('fs'); const { collectFiles, extract } = require('@sentropic/engram');

const detect = JSON.parse(fs.readFileSync('.engram/.graphify_detect.json', 'utf-8')); let codeFiles = []; for (const f of (detect.files || {}).code || []) { codeFiles = codeFiles.concat(collectFiles(f)); }

if (codeFiles.length > 0) { const result = await extract(codeFiles); fs.writeFileSync('.engram/.graphify_ast.json', JSON.stringify(result, null, 2)); console.log(\`AST: \${result.nodes.length} nodes, \${result.edges.length} edges\`); } else { fs.writeFileSync('.engram/.graphify_ast.json', JSON.stringify({nodes:[],edges:[],input_tokens:0,output_tokens:0})); console.log('No code files - skipping AST extraction'); } })()" ```

#### Part B - Semantic extraction (parallel subagents)

**Fast path:** If semantic detection found zero docs, papers, images, and transcripts (code-only corpus), skip Part B entirely and go straight to Part C. AST handles code - there is nothing for semantic subagents to do.

**MANDATORY: You MUST use the Agent tool here. Reading files yourself one-by-one is forbidden - it is 5-10x slower. If you do not use the Agent tool you are doing this wrong.**

Before dispatching subagents, print a timing estimate: - Load `total_words` and file counts from `.engram/.graphify_detect.json` - Estimate agents needed: `ceil(uncached_non_code_files / 22)` (chunk size is 20-25) - Estimate time: ~45s per agent batch (they run in parallel, so total ≈ 45s × ceil(agents/parallel_limit)) - Print: "Semantic extraction: ~N files → X agents, estimated ~Ys"

**Step B0 - Check extraction cache first**

Before dispatching any subagents, check which files already have cached extraction results:

```bash node -e " const fs = require('fs'); const { checkSemanticCache } = require('@sentropic/engram');

const detect = JSON.parse(fs.readFileSync('.engram/.graphify_detect_semantic.json', 'utf-8')); const allFiles = [ ...((detect.files || {}).document || []), ...((detect.files || {}).paper || []), ...((detect.files || {}).image || []), ];

const [cachedNodes, cachedEdges, cachedHyperedges, uncached] = checkSemanticCache(allFiles);

if (cachedNodes.length || cachedEdges.length || cachedHyperedges.length) { fs.writeFileSync('.engram/.graphify_cached.json', JSON.stringify({nodes: cachedNodes, edges: cachedEdges, hyperedges: cachedHyperedges})); } fs.writeFileSync('.engram/.graphify_uncached.txt', uncached.join('\n')); console.log(\`Cache: \${allFiles.length - uncached.length} files hit, \${uncached.length} files need extraction\`); " ```

Only dispatch subagents for files listed in `.engram/.graphify_uncached.txt`. If all files are cached, skip to Part C directly.

**Step B1 - Split into chunks**

Load files from `.engram/.graphify_uncached.txt`. Split into chunks of 20-25 files each. Each image gets its own chunk (vision needs separate context). PDF sidecar Markdown can reference extracted image artifacts under `.engram/converted/pdf/*_images/`; when those images contain diagrams, tables, captions, or embedded text that carry meaning, include them as image chunks or describe the delegated OCR/vision output with provenance back to the source PDF. When splitting, group files from the same directory together so related artifacts land in the same chunk and cross-file relationships are more likely to be extracted.

**Step B2 - Dispatch ALL subagents in a single message**

Call the Agent tool multiple times IN THE SAME RESPONSE - one call per chunk. This is the only way they run in parallel. If you make one Agent call, wait, then make another, you are doing it sequentially and defeating the purpose.

Concrete example for 3 chunks: ``` [Agent tool call 1: files 1-15] [Agent tool call 2: files 16-30] [Agent tool call 3: files 31-45] ``` All three in one message. Not three separate messages.

Each subagent receives this exact prompt (substitute FILE_LIST, CHUNK_NUM, TOTAL_CHUNKS, and DEEP_MODE):

``` You are an engram extraction subagent. Read the files listed and extract a knowledge graph fragment. Output ONLY valid JSON matching the schema below - no explanation, no markdown fences, no preamble.

Files (chunk CHUNK_NUM of TOTAL_CHUNKS): FILE_LIST

Rules: - EXTRACTED: relationship explicit in source (import, call, citation, "see §3.2") - INFERRED: reasonable inference (shared data structure, implied dependency) - AMBIGUOUS: uncertain - flag for review, do not omit - Node IDs must stay stable across chunks and reruns. Base them on the entity label or file-relative identity only. Never append chunk counters like `_c1`, `_c2`, `_chunk3`, or similar suffixes.

Code files: focus on semantic edges AST cannot find (call relationships, shared data, arch patterns). Do not re-extract imports - AST already has those. Doc/paper files: extract named concepts, entities, citations. For rationale (WHY decisions were made, trade-offs, design intent): store it as a `rationale` attribute on the relevant concept node. Do not create a separate rationale node or fragment node unless it is itself a named concept. Code files: when adding `calls` edges, source MUST be the caller and target MUST be the callee. Never reverse the direction. Image files: use vision to understand what the image IS - do not just OCR. For images extracted from PDFs, decode figures, tables, diagrams, captions, and embedded text when they carry meaning; use the assistant vision model by default, or a delegated OCR/vision model when configured, and keep provenance to the source PDF and sidecar. UI screenshot: layout patterns, design decisions, key elements, purpose. Chart: metric, trend/insight, data source. Tweet/post: claim as node, author, concepts mentioned. Diagram: components and connections. Research figure: what it demonstrates, method, result. Handwritten/whiteboard: ideas and arrows, mark uncertain readings AMBIGUOUS.

DEEP_MODE (if --mode deep was given): be aggressive with INFERRED edges - indirect deps, shared assumptions, latent couplings. Mark uncertain ones AMBIGUOUS instead of omitting.

Semantic similarity: if two concepts in this chunk solve the same problem or represent the same idea without any structural link (no import, no call, no citation), add a `semantically_similar_to` edge marked INFERRED with a confidence_score reflecting how similar they are (0.6-0.95). Examples: - Two functions that both validate user input but never call each other - A class in code and a concept in a paper that describe the same algorithm - Two error types that handle the same failure mode differently Only add these when the similarity is genuinely non-obvious and cross-cutting. Do not add them for trivially similar things.

Hyperedges: if 3 or more nodes clearly participate together in a shared concept, flow, or pattern that is not captured by pairwise edges alone, add a hyperedge to a top-level `hyperedges` array. Examples: - All classes that implement a common protocol or interface - All functions in an authentication flow (even if they don't all call each other) - All concepts from a paper section that form one coherent idea Use sparingly — only when the group relationship adds information beyond the pairwise edges. Maximum 3 hyperedges per chunk.

If a file has YAML frontmatter (--- ... ---), copy source_url, captured_at, author, contributor onto every node from that file.

confidence_score is REQUIRED on every edge - never omit it, never use 0.5 as a default: - EXTRACTED edges: confidence_score = 1.0 always - INFERRED edges: reason about each edge individually. Direct structural evidence (shared data structure, clear dependency): 0.8-0.9. Reasonable inference with some uncertainty: 0.6-0.7. Weak or speculative: 0.4-0.5. Most edges should be 0.6-0.9, not 0.5. - AMBIGUOUS edges: 0.1-0.3

Output exactly this JSON (no other text): {"nodes":[{"id":"filestem_entityname","label":"Human Readable Name","file_type":"code|document|paper|image|concept|rationale","source_file":"relative/path","source_location":null,"source_url":null,"captured_at":null,"author":null,"contributor":null,"rationale":null}],"edges":[{"source":"node_id","target":"node_id","relation":"calls|implements|references|cites|conceptually_related_to|shares_data_with|semantically_similar_to|rationale_for","confidence":"EXTRACTED|INFERRED|AMBIGUOUS","confidence_score":1.0,"source_file":"relative/path","source_location":null,"weight":1.0}],"hyperedges":[{"id":"snake_case_id","label":"Human Readable Label","nodes":["node_id1","node_id2","node_id3"],"relation":"participate_in|implement|form","confidence":"EXTRACTED|INFERRED","confidence_score":0.75,"source_file":"relative/path"}],"input_tokens":0,"output_tokens":0} ```

**Step B3 - Collect, cache, and merge**

Wait for all subagents. For each result: - If a subagent returned valid JSON with `nodes` and `edges`, include it and save each file's nodes/edges to the cache - If a subagent failed or returned invalid JSON, print a warning and skip that chunk - do not abort

If more than half the chunks failed, stop and tell the user.

Save new results to cache. The `saveSemanticCache` call is wrapped in `validateSemanticFragment` + `sanitizeSemanticFragment` so a malformed agent response cannot poison the per-file semantic cache: ```bash node -e " const fs = require('fs'); const { saveSemanticCache, validateSemanticFragment, sanitizeSemanticFragment } = require('@sentropic/engram');

const raw = fs.existsSync('.engram/.graphify_semantic_new.json') ? JSON.parse(fs.readFileSync('.engram/.graphify_semantic_new.json', 'utf-8')) : {nodes:[],edges:[],hyperedges:[]}; const errors = validateSemanticFragment(raw); if (errors.length > 0) { console.error('Refusing to cache invalid semantic fragment: ' + errors.slice(0, 3).join('; ')); process.exit(1); } const clean = sanitizeSemanticFragment(raw); const saved = saveSemanticCache(clean.nodes || [], clean.edges || [], clean.hyperedges || []); console.log(\`Cached \${saved} files\`); " ```

Merge cached + new results into `.engram/.graphify_semantic.json`. Each chunk is independently validated; invalid chunks are skipped with a warning rather than crashing the merge (mirrors upstream PR #825): ```bash node -e " const fs = require('fs'); const { validateSemanticFragment, sanitizeSemanticFragment } = require('@sentropic/engram');

function loadAndClean(path, label) { if (!fs.existsSync(path)) return {nodes:[],edges:[],hyperedges:[]}; let raw; try { raw = JSON.parse(fs.readFileSync(path, 'utf-8')); } catch (e) { console.warn(\`Skipping invalid \${label} fragment \${path}: \${e.message}\`); return {nodes:[],edges:[],hyperedges:[]}; } const errs = validateSemanticFragment(raw); if (errs.length > 0) { console.warn(\`Skipping invalid \${label} fragment \${path}: \` + errs.slice(0, 3).join('; ')); return {nodes:[],edges:[],hyperedges:[]}; } return sanitizeSemanticFragment(raw); }

const cached = loadAndClean('.engram/.graphify_cached.json', 'cached'); const raw = loadAndClean('.engram/.graphify_semantic_new.json', 'new');

const allNodes = (cached.nodes || []).concat(raw.nodes || []); const allEdges = (cached.edges || []).concat(raw.edges || []); const allHyperedges = (cached.hyperedges || []).concat(raw.hyperedges || []); const seen = new Set(); const deduped = []; for (const n of allNodes) { if (!seen.has(n.id)) { seen.add(n.id); deduped.push(n); } }

const merged = { nodes: deduped, edges: allEdges, hyperedges: allHyperedges, input_tokens: raw.input_tokens || 0, output_tokens: raw.output_tokens || 0, }; fs.writeFileSync('.engram/.graphify_semantic.json', JSON.stringify(merged, null, 2)); console.log(\`Extraction complete - \${deduped.length} nodes, \${allEdges.length} edges (\${(cached.nodes||[]).length} from cache, \${(raw.nodes||[]).length} new)\`); " ``` Clean up temp files: `rm -f .engram/.graphify_cached.json .engram/.graphify_uncached.txt .engram/.graphify_semantic_new.json .engram/.graphify_detect_semantic.json .engram/.graphify_transcripts.json .engram/.graphify_pdf_ocr.json`

#### Part C - Merge AST + semantic into final extraction

The AST side comes from Tree-sitter and is trusted as-is. The semantic side is LLM-generated and must be sanitized one more time before the final merge: ```bash node -e " const fs = require('fs'); const { sanitizeSemanticFragment } = require('@sentropic/engram');

const ast = JSON.parse(fs.readFileSync('.engram/.graphify_ast.json', 'utf-8')); const sem = sanitizeSemanticFragment(JSON.parse(fs.readFileSync('.engram/.graphify_semantic.json', 'utf-8')));

const seen = new Set(ast.nodes.map(n => n.id)); const mergedNodes = [...ast.nodes]; for (const n of sem.nodes) { if (!seen.has(n.id)) { mergedNodes.push(n); seen.add(n.id); } }

const mergedEdges = ast.edges.concat(sem.edges); const mergedHyperedges = sem.hyperedges || []; const merged = { nodes: mergedNodes, edges: mergedEdges, hyperedges: mergedHyperedges, input_tokens: sem.input_tokens || 0, output_tokens: sem.output_tokens || 0, }; fs.writeFileSync('.engram/.graphify_extract.json', JSON.stringify(merged, null, 2)); console.log(\`Merged: \${mergedNodes.length} nodes, \${mergedEdges.length} edges (\${ast.nodes.length} AST + \${sem.nodes.length} semantic)\`); " ```

### Step 4 - Build graph, cluster, analyze, generate outputs

**Before starting:** if `--directed` was given, replace each `buildFromJson(...)` call in the build/export steps below with `buildFromJson(..., { directed: true })`, and when manually reconstructing `graph.json`, use `new Graph({type: 'directed'})` instead of `undirected`.

```bash mkdir -p .engram node -e " const fs = require('fs'); const { buildFromJson } = require('@sentropic/engram'); const { cluster, scoreAll } = require('@sentropic/engram'); const { godNodes, surprisingConnections, suggestQuestions } = require('@sentropic/engram'); const { generateReport } = require('@sentropic/engram'); const { toJson } = require('@sentropic/engram');

const extraction = JSON.parse(fs.readFileSync('.engram/.graphify_extract.json', 'utf-8')); const detection = JSON.parse(fs.readFileSync('.engram/.graphify_detect.json', 'utf-8'));

const G = buildFromJson(extraction); const communities = cluster(G); const cohesion = scoreAll(G, communities); const tokens = {input: extraction.input_tokens || 0, output: extraction.output_tokens || 0}; const gods = godNodes(G); const surprises = surprisingConnections(G, communities); const labels = new Map(Array.from(communities.keys(), cid => [cid, 'Community ' + cid])); const questions = suggestQuestions(G, communities, labels);

const report = generateReport(G, communities, cohesion, labels, gods, surprises, detection, tokens, '.', {suggestedQuestions: questions}); fs.writeFileSync('.engram/GRAPH_REPORT.md', report); toJson(G, communities, '.engram/graph.json');

const analysis = { communities: Object.fromEntries(Array.from(communities.entries(), ([k, v]) => [String(k), v])), cohesion: Object.fromEntries(Array.from(cohesion.entries(), ([k, v]) => [String(k), v])), gods, surprises, questions, }; fs.writeFileSync('.engram/.graphify_analysis.json', JSON.stringify(analysis, null, 2)); if (G.order === 0) { console.log('ERROR: Graph is empty - extraction produced no nodes.'); console.log('Possible causes: all files were skipped, binary-only corpus, or extraction failed.'); process.exit(1); } console.log(\`Graph: \${G.order} nodes, \${G.size} edges, \${communities.size} communities\`); " ```

If this step prints `ERROR: Graph is empty`, stop and tell the user what happened - do not proceed to labeling or visualization.

Replace INPUT_PATH with the actual path.

### Step 5 - Label communities and node descriptions (no API key needed)

**`engram update` handles descriptions + labels automatically.** By default (no API key), it runs in assistant/skill mode:

1. It emits instruction files to `.engram/description-instructions/` (one per node batch) and `.engram/label-instructions/communities.md` for the host assistant to fill. 2. **You (the host assistant) read those files and write JSON answers** (see below). 3. A second `engram update` ingests the completed answers and stamps descriptions + labels onto `graph.json`.

**For community labels**, read `.engram/label-instructions/communities.md` which lists every community with representative node names. Write 2-5 word names to `.engram/label-instructions/communities.json`: ```json {"0": "Attention Mechanism", "1": "Training Pipeline", "2": "Data Loading"} ```

**For node descriptions**, each `.engram/description-instructions/batch-NNN.md` file lists nodes with their context. Write a one-sentence description per node to the corresponding `batch-NNN.json`: ```json { "some_node_id": "Resolves the configured ontology profile from graphify.yaml.", "another_id": "Colonel James Barclay, an antagonist introduced in The Crooked Man." } ```

Then re-run `engram update` to ingest: ```bash engram update . ```

**With an API key** (headless/automation), descriptions and labels are generated directly in the same `engram update` call — no two-step needed. To force assistant mode even with a key: `--description-mode assistant` / `--label-mode assistant`. To force direct mode: `--description-mode direct` / `--label-mode direct`.

**Opt out of either step**: `--no-description` / `--no-label`.

> **REQUIRED before the studio/wiki export — `describe` is NOT optional for a populated studio.** There is an asymmetry to know about: the default `engram update` flow wires the community-**labels** pass automatically, but the node-**descriptions** pass only fills `graph.json` when you actually complete the assistant two-step (or run with a key). If you skip it, every node ships with `description: null` and the **static studio / wiki export shows empty entity panels silently** (field report ia-aero: 620/620 null descriptions). The export now *warns* on ~0% description coverage and *provisionally* backfills entity panels from each node's extractor `rationale` (clearly marked "provisional" in the studio) — but that is a stop-gap, not a real description. > > So, for non-null descriptions, the explicit order is: > > 1. `engram update .` (emits `.engram/description-instructions/` + `.engram/label-instructions/`). > 2. Fill **both** the `batch-NNN.json` description answers **and** `communities.json` labels. > 3. `engram update .` again to ingest — OR, on an already-built/curated graph, `engram describe .` (descriptions) + `engram label .` (labels) + `engram cite .` (grounded `node.citations[]`) non-destructively. > 4. **Then** generate the static Ontology Studio (Step 6). Confirm descriptions landed: a 0%-description studio means Step 5 was skipped — go back and run `describe` (and `cite` for non-null citations).

**Language attention (per source).** Descriptions and community names are written in the **language of each node's SOURCE document**, detected per node from its label + citations (and the community's sampled node names). A 100%-French corpus yields French descriptions and French community names; a mixed corpus gets each node's description in its own source language — never a random FR/EN mix left to the backend's whim. The directive is injected into **every** prompt: the assistant `batch-NNN.md` files (look for the `Write every description in <Language>` line, or per-node `lang=` markers on a mixed batch) AND the direct API path. When you (the host assistant) fill an instruction file, **honor that language directive** — answer in the language the instruction states, per node.

- Default is `--description-lang auto` / `--label-lang auto` (detect per source). - Force one language for the whole run with a code: `--description-lang fr`, `--label-lang fr` (also `en`, `de`, `es`, `it`, `pt`, `nl`). A forced code overrides detection for every node. - The ontology profile `default_language` (graphify.yaml) is the fallback for nodes with no detectable signal (e.g. proper-noun-only nodes).

```bash # Force French descriptions + French community names on a French corpus: engram describe . --description-lang fr engram label . --label-lang fr engram update . --description-lang fr --label-lang fr # Default (auto) — detect each source's language: engram describe . ```

**To describe an existing curated graph without re-extraction** (e.g. after manual curation or corpus build), use `engram describe [path]` — the non-destructive counterpart to `engram label [path]`:

```bash # Non-destructive: stamps node.description onto graph.json without re-extracting engram describe . # Only fill missing descriptions (idempotent): engram describe . --fill-missing # Direct mode with API key: engram describe . --description-mode direct --description-backend anthropic ```

`engram describe` loads the existing `graph.json`, runs the same description pipeline as `engram update --description`, and writes back — without touching node IDs, edges, communities, or any other node attributes. Only `description` is added/updated. Use it when `engram update` would re-extract and destroy a curated graph.

**Ground citations into the graph — `engram cite` (alias `ground-citations`).** Symmetric to `describe`/`label`, and like them **opt-in** (NOT auto-run in the default pipeline): it loads the existing `graph.json`, scans the corpus, and grounds per-entity `node.citations[]` entries `{quote, source_file, source_location}` — populating **new** verbatim citations, not just projecting the ones already present. **Heuristic mode is the no-key DEFAULT**; `--mode heuristic|assistant|api` (assistant/api are opt-in recall boosters gated by the SAME verbatim check). It is **anti-hallucination by construction**: every emitted `quote` is a verified verbatim substring of the source text — a quote that cannot be relocated in the source is dropped, never invented. It UNIONS with existing citations (never clobbers) and re-runs the shipped aggregation (count + inline top-K + `.engram/ontology/citations.json`). **Run it BEFORE the studio/wiki export** so entity panels ship non-null citations.

```bash # No-key heuristic grounding (default): verbatim citations into node.citations[] engram cite . # Only fill nodes that have no citations yet (additive second pass): engram cite . --only-missing # Restrict to node types and cap per node: engram cite . --types person,concept,reference --top-k 6 # Report coverage without writing graph.json / citations.json: engram cite . --dry-run # Opt-in LLM recall boost (still verbatim-gated): engram cite . --mode assistant ```

**Citation density per corpus type (no key needed).** `describe`/`update`/`extract`/`watch` auto-tune two citation knobs from the corpus type they read out of `.engram/.graphify_detect.json` (no extra step): the **describe-prompt cap** (citation snippets grounding each description) and the **inline top-K** (citations kept per node in `graph.json`; the full per-entity tail always lands in `.engram/ontology/citations.json`). Resolution precedence is **CLI flag > corpus-type default > global default (cap 10, K 8)**. Corpus-type defaults:

| Corpus type | describe cap | inline K | |---|---|---| | code (code dominates, no docs/papers) | 3 | 3 | | mixed (the middle default) | 10 | 8 | | long-document (docs/papers, large word count) | all | 8 | | entity-corpus (ontology/profile mode) | all | 8 |

You normally rely on the auto-resolved policy. Override it explicitly per detected corpus type when needed — e.g. a long-form prose corpus should ground descriptions on many distinct sources, while a code project stays terse:

```bash # Long-document / entity corpus: ground on every distinct source. engram describe . --citation-cap all # Code project: keep descriptions terse. engram describe . --citation-cap 3 # Bound how many citations ride inline in graph.json (the full tail stays in citations.json): engram extract . --citations-top-k 8 engram update . --citation-cap all --citations-top-k 8 ```

`--citation-cap <n|all>` is on `describe`/`label`/`update`; `--citations-top-k <n>` is on `extract`/`update`/`watch`; `--description-lang <auto|code>` is on `describe`/`update` and `--label-lang <auto|code>` is on `label`/`update`. All are flag-only overrides (no key, no config file required) — absent, the corpus-type default (citations) or per-source detection (language) applies. To project a pre-feature graph into the new schema without re-extracting (lower-bound counts; re-extract for true exhaustive counts), run `engram backfill-citations .`.

**Legacy manual label approach** (still works; skip if using the CLI two-step above):

Read `.engram/.graphify_analysis.json`. For each community key, look at its node labels and write a 2-5 word name. Then regenerate the report:

```bash node -e " const fs = require('fs'); const { buildFromJson } = require('@sentropic/engram'); const { scoreAll } = require('@sentropic/engram'); const { godNodes, surprisingConnections, suggestQuestions } = require('@sentropic/engram'); const { generateReport } = require('@sentropic/engram');

const extraction = JSON.parse(fs.readFileSync('.engram/.graphify_extract.json', 'utf-8')); const detection = JSON.parse(fs.readFileSync('.engram/.graphify_detect.json', 'utf-8')); const analysis = JSON.parse(fs.readFileSync('.engram/.graphify_analysis.json', 'utf-8'));

const G = buildFromJson(extraction); const communities = Object.fromEntries(Object.entries(analysis.communities).map(([k, v]) => [Number(k), v])); const cohesion = Object.fromEntries(Object.entries(analysis.cohesion).map(([k, v]) => [Number(k), v])); const tokens = {input: extraction.input_tokens || 0, output: extraction.output_tokens || 0};

// LABELS - replace these with the names you chose above const labels = LABELS_DICT;

const questions = suggestQuestions(G, communities, labels);

const report = generateReport(G, communities, cohesion, labels, analysis.gods, analysis.surprises, detection, tokens, '.', {suggestedQuestions: questions}); fs.writeFileSync('.engram/GRAPH_REPORT.md', report); fs.writeFileSync('.engram/.graphify_labels.json', JSON.stringify(Object.fromEntries(Object.entries(labels).map(([k, v]) => [String(k), v])))); console.log('Report updated with community labels'); " ```

Replace `LABELS_DICT` with the actual dict you constructed (e.g. `{0: "Attention Mechanism", 1: "Training Pipeline"}`). Replace INPUT_PATH with the actual path.

### Step 6 - Generate Obsidian vault (opt-in) + static Ontology Studio

**Generate the static Ontology Studio always.** **Obsidian vault only if `--obsidian` was explicitly given** — skip it otherwise, it generates one file per node.

**Node descriptions from graph.json render automatically** — `engram update` fills `node.description` on each node (via the description pipeline), and `export wiki`, `export obsidian`, and the static studio export now render those descriptions by default with no extra step. You do NOT need `wiki describe` just to get descriptions in the output.

`engram wiki describe` is for RICHER multi-sentence, evidence-grounded descriptions generated by an LLM. It is optional and additive: the sidecar fills only the gaps where no `node.description` exists. When both exist, the graph.json `node.description` wins (canonical source of truth).

```bash # Opt-in: richer LLM-generated descriptions (fills gaps; does not override node.description) engram wiki describe --graph .engram/graph.json --mode assistant --targets all # Describe ALL nodes and communities (0 = unlimited): engram wiki describe --graph .engram/graph.json --mode assistant --targets all --max-nodes 0 --max-communities 0 # or, for direct mode: engram wiki describe --graph .engram/graph.json --mode direct --backend openai --targets all

# Export: descriptions from graph.json render automatically; pass --descriptions for sidecar enrichment engram export wiki --graph .engram/graph.json engram export wiki --graph .engram/graph.json --descriptions .engram/wiki/descriptions.json engram export obsidian --graph .engram/graph.json --descriptions .engram/wiki/descriptions.json ```

Sidecars live under `.engram/wiki/descriptions/` with an index at `.engram/wiki/descriptions.json`. They record per-node content hashes (unrelated graph.json changes no longer stale the sidecar), prompt/generator provenance, evidence refs, and cache keys; existing generated sidecars may be reused when a fresh generation does not complete. `insufficient_evidence` sidecars render no Description section. This never mutates `.engram/graph.json`.

If `--obsidian` was given:

- If `--obsidian-dir <path>` was also given, use that path as the vault directory. Otherwise default to `.engram/obsidian`.

```bash node -e " const fs = require('fs'); const { buildFromJson } = require('@sentropic/engram'); const { toWiki, toCanvas } = require('@sentropic/engram');

const extraction = JSON.parse(fs.readFileSync('.engram/.graphify_extract.json', 'utf-8')); const analysis = JSON.parse(fs.readFileSync('.engram/.graphify_analysis.json', 'utf-8')); const labelsRaw = fs.existsSync('.engram/.graphify_labels.json') ? JSON.parse(fs.readFileSync('.engram/.graphify_labels.json', 'utf-8')) : {};

const G = buildFromJson(extraction); const communities = Object.fromEntries(Object.entries(analysis.communities).map(([k, v]) => [Number(k), v])); const cohesion = Object.fromEntries(Object.entries(analysis.cohesion).map(([k, v]) => [Number(k), v])); const labels = Object.fromEntries(Object.entries(labelsRaw).map(([k, v]) => [Number(k), v]));

const obsidianDir = 'OBSIDIAN_DIR'; // replace with --obsidian-dir value, or '.engram/obsidian' if not given

const n = toWiki(G, communities, obsidianDir, {communityLabels: Object.keys(labels).length ? labels : undefined, cohesion}); console.log(\`Obsidian vault: \${n} notes in \${obsidianDir}/\`);

toCanvas(G, communities, \`\${obsidianDir}/graph.canvas\`, {communityLabels: Object.keys(labels).length ? labels : undefined}); console.log(\`Canvas: \${obsidianDir}/graph.canvas - open in Obsidian for structured community layout\`); console.log(); console.log(\`Open \${obsidianDir}/ as a vault in Obsidian.\`); console.log(' Graph view - nodes colored by community (set automatically)'); console.log(' graph.canvas - structured layout with communities as groups'); console.log(' _COMMUNITY_* - overview notes with cohesion scores and dataview queries'); " ```

Generate the static Ontology Studio (always). It bundles the prebuilt studio SPA (`index.html` + `assets/`) with the data artifacts the SPA reads next to it — `graph.json`, `scene.json` (with pre-computed force-layout positions), `entities.json`, `reconciliation-candidates.json`, and `class-hierarchies.json` (the latter only when a profile carries a `class_hierarchies` block):

```bash # Default state dir is .engram; pass --profile <path> to emit class-hierarchies.json for ontology profiles engram studio export .engram/studio ```

The studio scales to large graphs (WebGL render + pre-computed positions), so there is no node-count cap — even oversized graphs export to the studio. To open it, serve the export dir (`.engram/studio`) with any static file server and load `index.html` in a browser.

### Step 7 - Neo4j export (only if --neo4j or --neo4j-push flag)

**If `--neo4j`** - generate a Cypher file for manual import:

```bash node -e " const fs = require('fs'); const { buildFromJson, toCypher } = require('@sentropic/engram');

const G = buildFromJson(JSON.parse(fs.readFileSync('.engram/.graphify_extract.json', 'utf-8'))); toCypher(G, '.engram/cypher.txt'); console.log('cypher.txt written - import with: cypher-shell < .engram/cypher.txt'); " ```

**If `--neo4j-push <uri>`** - push directly to a running Neo4j instance. Ask the user for credentials if not provided:

```bash node -e " (async () => { const fs = require('fs'); const { buildFromJson, pushToNeo4j } = require('@sentropic/engram');

const extraction = JSON.parse(fs.readFileSync('.engram/.graphify_extract.json', 'utf-8')); const analysis = JSON.parse(fs.readFileSync('.engram/.graphify_analysis.json', 'utf-8')); const G = buildFromJson(extraction); const communities = Object.fromEntries(Object.entries(analysis.communities).map(([k, v]) => [Number(k), v]));

const result = await pushToNeo4j(G, {uri: 'NEO4J_URI', user: 'NEO4J_USER', password: 'NEO4J_PASSWORD', communities}); console.log(\`Pushed to Neo4j: \${result.nodes} nodes, \${result.edges} edges\`); })().catch((e) => { console.error(\`error: \${e.message}\`); process.exit(1); }); " ```

Replace `NEO4J_URI`, `NEO4J_USER`, `NEO4J_PASSWORD` with actual values. Default URI is `bolt://localhost:7687`, default user is `neo4j`. Uses MERGE - safe to re-run without creating duplicates.

### Step 7b - SVG export (only if --svg flag)

```bash node -e " const fs = require('fs'); const { buildFromJson, toSvg } = require('@sentropic/engram');

const extraction = JSON.parse(fs.readFileSync('.engram/.graphify_extract.json', 'utf-8')); const analysis = JSON.parse(fs.readFileSync('.engram/.graphify_analysis.json', 'utf-8')); const labelsRaw = fs.existsSync('.engram/.graphify_labels.json') ? JSON.parse(fs.readFileSync('.engram/.graphify_labels.json', 'utf-8')) : {};

const G = buildFromJson(extraction); const communities = Object.fromEntries(Object.entries(analysis.communities).map(([k, v]) => [Number(k), v])); const labels = Object.fromEntries(Object.entries(labelsRaw).map(([k, v]) => [Number(k), v]));

toSvg(G, communities, '.engram/graph.svg', {communityLabels: Object.keys(labels).length ? labels : undefined}); console.log('graph.svg written - embeds in Obsidian, Notion, GitHub READMEs'); " ```

### Step 7c - GraphML export (only if --graphml flag)

```bash node -e " const fs = require('fs'); const { buildFromJson, toGraphml } = require('@sentropic/engram');

const extraction = JSON.parse(fs.readFileSync('.engram/.graphify_extract.json', 'utf-8')); const analysis = JSON.parse(fs.readFileSync('.engram/.graphify_analysis.json', 'utf-8'));

const G = buildFromJson(extraction); const communities = Object.fromEntries(Object.entries(analysis.communities).map(([k, v]) => [Number(k), v]));

toGraphml(G, communities, '.engram/graph.graphml'); console.log('graph.graphml written - open in Gephi, yEd, or any GraphML tool'); " ```

### Step 7d - MCP server (only if --mcp flag)

```bash npx engram serve .engram/graph.json ```

This starts a stdio MCP server that exposes tools: `query_graph`, `get_node`, `get_neighbors`, `get_community`, `god_nodes`, `graph_stats`, `shortest_path`. Add to Claude Desktop or any MCP-compatible agent orchestrator so other agents can query the graph live.

To configure in Claude Desktop, add to `claude_desktop_config.json`: ```json { "mcpServers": { "engram": { "command": "npx", "args": ["engram", "serve", "/absolute/path/to/.engram/graph.json"] } } } ```

### Step 8 - Token reduction benchmark (only if total_words > 5000)

If `total_words` from `.engram/.graphify_detect.json` is greater than 5,000, run:

```bash node -e " const fs = require('fs'); const { runBenchmark, printBenchmark } = require('@sentropic/engram');

const detection = JSON.parse(fs.readFileSync('.engram/.graphify_detect.json', 'utf-8')); const result = runBenchmark('.engram/graph.json', {corpusWords: detection.total_words}); printBenchmark(result); " ```

Print the output directly in chat. If `total_words <= 5000`, skip silently - the graph value is structural clarity, not token compression, for small corpora.

---

### Step 9 - Save manifest, update cost tracker, clean up, and report

```bash node -e " const fs = require('fs'); const { saveManifest } = require('@sentropic/engram');

const detect = JSON.parse(fs.readFileSync('.engram/.graphify_detect.json', 'utf-8')); saveManifest(detect.files);

const extract = JSON.parse(fs.readFileSync('.engram/.graphify_extract.json', 'utf-8')); const inputTok = extract.input_tokens || 0; const outputTok = extract.output_tokens || 0;

const costPath = '.engram/cost.json'; const cost = fs.existsSync(costPath) ? JSON.parse(fs.readFileSync(costPath, 'utf-8')) : {runs: [], total_input_tokens: 0, total_output_tokens: 0};

cost.runs.push({ date: new Date().toISOString(), input_tokens: inputTok, output_tokens: outputTok, files: detect.total_files || 0, }); cost.total_input_tokens += inputTok; cost.total_output_tokens += outputTok; fs.writeFileSync(costPath, JSON.stringify(cost, null, 2));

console.log(\`This run: \${inputTok.toLocaleString()} input tokens, \${outputTok.toLocaleString()} output tokens\`); console.log(\`All time: \${cost.total_input_tokens.toLocaleString()} input, \${cost.total_output_tokens.toLocaleString()} output (\${cost.runs.length} runs)\`); " rm -f .engram/.graphify_detect.json .engram/.graphify_extract.json .engram/.graphify_ast.json .engram/.graphify_semantic.json .engram/.graphify_analysis.json rm -f .engram/needs_update 2>/dev/null || true ```

Tell the user (omit the obsidian line unless --obsidian was given): ``` Graph complete. Outputs in PATH_TO_DIR/.engram/

studio/ - static Ontology Studio, serve with any static file server and open index.html GRAPH_REPORT.md - audit report graph.json - raw graph data obsidian/ - Obsidian vault (only if --obsidian was given) ```

Replace PATH_TO_DIR with the actual absolute path of the directory that was processed.

Then paste these sections from GRAPH_REPORT.md directly into the chat: - God Nodes - Surprising Connections - Suggested Questions

Do NOT paste the full report - just those three sections. Keep it concise.

Then immediately offer to explore. Pick the single most interesting suggested question from the report - the one that crosses the most community boundaries or has the most surprising bridge node - and ask:

> "The most interesting question this graph can answer: **[question]**. Want me to trace it?"

If the user says yes, run `/engram query "[question]"` on the graph and walk them through the answer using the graph structure - which nodes connect, which community boundaries get crossed, what the path reveals. Keep going as long as they want to explore. Each answer should end with a natural follow-up ("this connects to X - want to go deeper?") so the session feels like navigation, not a one-shot report.

The graph is the map. Your job after the pipeline is to be the guide.

---

## For --update (incremental re-extraction)

Use when you've added or modified files since the last run. Only re-extracts changed files - saves tokens and time.

```bash node -e " const fs = require('fs'); const { detectIncremental } = require('@sentropic/engram');

const result = detectIncremental('INPUT_PATH'); const newTotal = result.new_total || 0; console.log(JSON.stringify(result, null, 2)); fs.writeFileSync('.engram/.graphify_incremental.json', JSON.stringify(result)); if (newTotal === 0) { console.log('No files changed since last run. Nothing to update.'); process.exit(0); } console.log(\`\${newTotal} new/

Intended uses

  • Use Engram when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.