### Platform Installation Instructions

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/specs/2026-03-18-multi-platform-simple-design.md

Provides examples of INSTALL.md files for different platforms, detailing the mechanism for installing skills.

```markdown
| File | Platform | Install Mechanism |
|------|----------|-------------------|
| .codex/INSTALL.md | Codex | `git clone` + symlink to `~/.agents/skills/` |
| .opencode/INSTALL.md | OpenCode | Plugin config in `opencode.json` |
| .openclaw/INSTALL.md | OpenClaw | `git clone` + symlink to `~/.openclaw/skills/` |
| .cursor/INSTALL.md | Cursor | `git clone` + symlink to `.cursor/plugins/` |
```

--------------------------------

### Implement Onboarding Guide Builder

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/plans/2026-03-14-phase4-implementation.md

This function generates a markdown-formatted onboarding guide from a provided KnowledgeGraph. It structures the output to include project overview, architecture layers, key concepts, getting started tour, complexity hotspots, and a file map.

```typescript
// packages/skill/src/onboard-builder.ts
import type { KnowledgeGraph } from "@understand-anything/core";

/**
 * Generate a structured onboarding guide from the knowledge graph.
 * Output is standalone markdown suitable for a README, wiki, or docs.
 */
export function buildOnboardingGuide(graph: KnowledgeGraph): string {
  const { project, nodes, edges, layers, tour } = graph;
  const lines: string[] = [];

  // --- Project Overview ---
  lines.push(`# ${project.name}`);
  lines.push("");
  lines.push(`> ${project.description}`);
  lines.push("");
  lines.push(`| | |`);

```

--------------------------------

### Initialize Astro Project

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/plans/2026-03-15-homepage-implementation.md

Scaffolds a new Astro project with the minimal template and strict TypeScript settings. Use this command to start the project setup.

```bash
cd /Users/yuxianglin/Desktop/opensource/Understand-Anything
mkdir -p homepage
cd homepage
pnpm create astro@latest . -- --template minimal --no-install --no-git --typescript strict
```

--------------------------------

### Verify Full Build and Tests

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/plans/2026-03-14-phase2-implementation.md

Execute a series of commands to install dependencies, build specific packages, run tests, and start the dashboard development server to ensure everything functions correctly.

```bash
pnpm install
pnpm --filter @understand-anything/core build
pnpm --filter @understand-anything/skill build
pnpm --filter @understand-anything/core test
pnpm --filter @understand-anything/skill test
pnpm dev:dashboard
```

--------------------------------

### Generate Onboarding Guide Markdown

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/plans/2026-03-14-phase4-implementation.md

This TypeScript code generates a markdown-formatted onboarding guide from a project's knowledge graph data. It structures information about languages, frameworks, architecture, key concepts, getting started steps, file maps, and complexity hotspots.

```typescript
lines.push(`|---|---|`);
  lines.push(`| **Languages** | ${project.languages.join(", ")} |`);
  lines.push(`| **Frameworks** | ${project.frameworks.join(", ")} |`);
  lines.push(`| **Components** | ${nodes.length} nodes, ${edges.length} relationships |`);
  lines.push(`| **Last Analyzed** | ${project.analyzedAt} |`);
  lines.push("");

  // --- Architecture ---
  if (layers.length > 0) {
    lines.push("## Architecture");
    lines.push("");
    lines.push("The project is organized into the following layers:");
    lines.push("");
    for (const layer of layers) {
      const memberNames = layer.nodeIds
        .map((id) => nodes.find((n) => n.id === id)?.name)
        .filter(Boolean);
      lines.push(`### ${layer.name}`);
      lines.push("");
      lines.push(layer.description);
      lines.push("");
      if (memberNames.length > 0) {
        lines.push(`Key components: ${memberNames.join(", ")}`);
        lines.push("");
      }
    }
  }

  // --- Key Concepts ---
  const conceptNodes = nodes.filter((n) => n.type === "concept");
  if (conceptNodes.length > 0) {
    lines.push("## Key Concepts");
    lines.push("");
    lines.push("Important architectural and domain concepts to understand:");
    lines.push("");
    for (const concept of conceptNodes) {
      lines.push(`### ${concept.name}`);
      lines.push("");
      lines.push(concept.summary);
      lines.push("");
    }
  }

  // --- Getting Started (Tour) ---
  if (tour.length > 0) {
    lines.push("## Getting Started");
    lines.push("");
    lines.push("Follow this guided tour to understand the codebase:");
    lines.push("");
    for (const step of tour) {
      const stepNodes = step.nodeIds
        .map((id) => nodes.find((n) => n.id === id))
        .filter(Boolean);
      lines.push(`### ${step.order}. ${step.title}`);
      lines.push("");
      lines.push(step.description);
      lines.push("");
      if (stepNodes.length > 0) {
        lines.push("**Files to look at:**");
        for (const node of stepNodes) {
          if (node!.filePath) {
            lines.push(`- lexible${node!.filePath}lexible — ${node!.summary}`);
          }
        }
        lines.push("");
      }
      if (step.languageLesson) {
        lines.push(`> **Language Tip:** ${step.languageLesson}`);
        lines.push("");
      }
    }
  }

  // --- File Map ---
  const fileNodes = nodes.filter((n) => n.type === "file" && n.filePath);
  if (fileNodes.length > 0) {
    lines.push("## File Map");
    lines.push("");
    lines.push("| File | Purpose | Complexity |");
    lines.push("|------|---------|------------|");
    for (const node of fileNodes) {
      lines.push(`| lexible${node.filePath}lexible | ${node.summary} | ${node.complexity} |`);
    }
    lines.push("");
  }

  // --- Complexity Hotspots ---
  const complexNodes = nodes.filter((n) => n.complexity === "complex");
  if (complexNodes.length > 0) {
    lines.push("## Complexity Hotspots");
    lines.push("");
    lines.push("These components are the most complex and deserve extra attention:");
    lines.push("");
    for (const node of complexNodes) {
      lines.push(`- **${node.name}** (${node.type}): ${node.summary}`);
    }
    lines.push("");
  }

  // --- Footer ---
  lines.push("---");
  lines.push("");
  lines.push(`*Generated by [Understand Anything](https://github.com/anthropics/understand-anything) from knowledge graph v${graph.version}*`);
  lines.push("");

  return lines.join("\n");
}

```

--------------------------------

### Start Dashboard

Source: https://github.com/lum1104/understand-anything/blob/main/CONTRIBUTING.md

Optionally, start the development dashboard using pnpm.

```bash
pnpm dev:dashboard
```

--------------------------------

### Install Understand-Anything Plugin

Source: https://github.com/lum1104/understand-anything/blob/main/README.md

Use these commands to install the plugin via the marketplace. This is the initial step for using the plugin's features.

```bash
/plugin marketplace add Lum1104/Understand-Anything
/plugin install understand-anything
```

--------------------------------

### Generate Onboarding Guide

Source: https://context7.com/lum1104/understand-anything/llms.txt

Create an onboarding guide for new team members to help them understand the project structure and key components.

```bash
/understand-onboard
```

--------------------------------

### Install Dependencies

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/plans/2026-03-28-understand-anything-extension-impl.md

Installs necessary dependencies for the Understand Anything core package. Ensure you are in the correct directory before running.

```bash
cd understand-anything-plugin/packages/core
pnpm add yaml @iarna/toml jsonc-parser
```

--------------------------------

### Install Dependencies

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/plans/2026-05-03-graph-layout-scaling.md

Run this command from the repository root to install all project dependencies, including the newly added ones.

```bash
pnpm install
```

--------------------------------

### Verify Format Guides Presence

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/plans/2026-04-09-understand-knowledge.md

List the format guide files in the specified directory to ensure all expected format guides are present.

```bash
ls understand-anything-plugin/skills/understand-knowledge/formats/
```

--------------------------------

### One-line Install Script (Windows PowerShell)

Source: https://github.com/lum1104/understand-anything/blob/main/README.md

Execute this PowerShell command to download and run the installer on Windows systems. It automates the installation process.

```powershell
iwr -useb https://raw.githubusercontent.com/Lum1104/Understand-Anything/main/install.ps1 | iex
```

--------------------------------

### Add Phase 0.5 for .understandignore Setup

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/plans/2026-04-10-understandignore-impl.md

Insert a new 'Phase 0.5 — Ignore Configuration' section into the /understand skill's SKILL.md. This phase handles the setup and verification of the .understandignore file, including generating a starter file if it doesn't exist and waiting for user confirmation.

```markdown
## Phase 0.5 — Ignore Configuration

Set up and verify the `.understandignore` file before scanning.

1. Check if `$PROJECT_ROOT/.understand-anything/.understandignore` exists.
2. **If it does NOT exist**, generate a starter file:
   - Run a Node.js script (or inline logic) that scans `$PROJECT_ROOT` for common directories (`__tests__/`, `test/`, `tests/`, `fixtures/`, `testdata/`, `docs/`, `examples/`, `scripts/`, `migrations/`, `.storybook/`) and generates a `.understandignore` file with commented-out suggestions.
   - Write the generated content to `$PROJECT_ROOT/.understand-anything/.understandignore`.
   - Report to the user:
     > "Generated `.understand-anything/.understandignore` with suggested exclusions based on your project structure. Please review it and uncomment any patterns you'd like to exclude from analysis. When ready, confirm to continue."
   - **Wait for user confirmation before proceeding.**
3. **If it already exists**, report:
   > "Found `.understand-anything/.understandignore`. Review it if needed, then confirm to continue."
   - **Wait for user confirmation before proceeding.**
4. After confirmation, proceed to Phase 1.

**Note:** The `.understandignore` file uses `.gitignore` syntax. The user can add patterns to exclude files from analysis, or use `!` prefix to force-include files excluded by built-in defaults (e.g., `!dist/` to analyze dist/ files).

---
```

--------------------------------

### Install fuse.js

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/plans/2026-03-14-phase2-implementation.md

Navigate to the core package directory and install fuse.js using pnpm.

```bash
cd packages/core && pnpm add fuse.js
```

--------------------------------

### Install Understand Anything via Claude Code Plugin Marketplace

Source: https://context7.com/lum1104/understand-anything/llms.txt

Use these commands to install the plugin directly from the Claude Code plugin marketplace.

```bash
# Install from the Claude Code plugin marketplace
/plugin marketplace add Lum1104/Understand-Anything
/plugin install understand-anything
```

--------------------------------

### Write Failing Tests for Onboarding Guide Generation

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/plans/2026-03-14-phase4-implementation.md

These tests define the expected output for the `buildOnboardingGuide` function, ensuring it correctly includes project overview, architecture layers, key concepts, getting started tour, complexity hotspots, and file map sections. They also verify graceful handling of graphs with missing layers or tour information.

```typescript
// packages/skill/src/__tests__/onboard-builder.test.ts
import { describe, it, expect } from "vitest";
import { buildOnboardingGuide } from "../onboard-builder.js";
import type { KnowledgeGraph } from "@understand-anything/core";

const sampleGraph: KnowledgeGraph = {
  version: "1.0.0",
  project: {
    name: "test-project",
    languages: ["typescript", "python"],
    frameworks: ["express", "prisma"],
    description: "A test REST API",
    analyzedAt: "2026-03-14T00:00:00Z",
    gitCommitHash: "abc123",
  },
  nodes: [
    { id: "file:src/index.ts", type: "file", name: "index.ts", filePath: "src/index.ts", summary: "Entry point", tags: ["entry"], complexity: "simple" },
    { id: "file:src/service.ts", type: "file", name: "service.ts", filePath: "src/service.ts", summary: "Core service", tags: ["service"], complexity: "complex" },
    { id: "concept:auth", type: "concept", name: "Auth Flow", summary: "JWT-based authentication", tags: ["concept", "auth"], complexity: "complex" },
  ],
  edges: [
    { source: "file:src/index.ts", target: "file:src/service.ts", type: "imports", direction: "forward", weight: 0.8 },
  ],
  layers: [
    { id: "layer:api", name: "API Layer", description: "Routes and handlers", nodeIds: ["file:src/index.ts"] },
    { id: "layer:service", name: "Service Layer", description: "Business logic", nodeIds: ["file:src/service.ts"] },
  ],
  tour: [
    { order: 1, title: "Start Here", description: "Begin with index.ts", nodeIds: ["file:src/index.ts"] },
    { order: 2, title: "Core Logic", description: "Service layer", nodeIds: ["file:src/service.ts"] },
  ],
};

describe("onboard-builder", () => {
  it("includes project overview section", () => {
    const guide = buildOnboardingGuide(sampleGraph);
    expect(guide).toContain("# test-project");
    expect(guide).toContain("A test REST API");
  });

  it("lists languages and frameworks", () => {
    const guide = buildOnboardingGuide(sampleGraph);
    expect(guide).toContain("typescript");
    expect(guide).toContain("express");
  });

  it("includes architecture layers section", () => {
    const guide = buildOnboardingGuide(sampleGraph);
    expect(guide).toContain("## Architecture");
    expect(guide).toContain("API Layer");
    expect(guide).toContain("Service Layer");
  });

  it("includes key concepts section", () => {
    const guide = buildOnboardingGuide(sampleGraph);
    expect(guide).toContain("## Key Concepts");
    expect(guide).toContain("Auth Flow");
  });

  it("includes getting started / tour section", () => {
    const guide = buildOnboardingGuide(sampleGraph);
    expect(guide).toContain("## Getting Started");
    expect(guide).toContain("Start Here");
  });

  it("includes complexity hotspots", () => {
    const guide = buildOnboardingGuide(sampleGraph);
    expect(guide).toContain("## Complexity Hotspots");
    expect(guide).toContain("service.ts");
  });

  it("includes file map section", () => {
    const guide = buildOnboardingGuide(sampleGraph);
    expect(guide).toContain("## File Map");
  });

  it("handles graph with no layers gracefully", () => {
    const noLayers = { ...sampleGraph, layers: [] };
    const guide = buildOnboardingGuide(noLayers);
    expect(guide).toContain("# test-project");
  });

  it("handles graph with no tour gracefully", () => {
    const noTour = { ...sampleGraph, tour: [] };
    const guide = buildOnboardingGuide(noTour);
    expect(guide).toContain("# test-project");
  });
});

```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/lum1104/understand-anything/blob/main/CONTRIBUTING.md

Clone the project repository and install necessary dependencies using pnpm.

```bash
git clone https://github.com/YOUR_USERNAME/Understand-Anything.git
cd Understand-Anything
pnpm install
```

--------------------------------

### One-line Install for macOS/Linux

Source: https://context7.com/lum1104/understand-anything/llms.txt

Install or update the plugin on macOS or Linux using a single curl command. Specify the platform for installation.

```bash
# Install for a specific platform (codex | gemini | opencode | vscode | pi | openclaw | antigravity | vibe)
curl -fsSL https://raw.githubusercontent.com/Lum1104/Understand-Anything/main/install.sh | bash -s codex

# Update an existing installation
./install.sh --update

# Uninstall from a platform
./install.sh --uninstall codex
```

--------------------------------

### Install Script Options

Source: https://github.com/lum1104/understand-anything/blob/main/README.md

These are common options for the install script. Use `--update` to update the plugin and `--uninstall` to remove it for a specific platform.

```bash
# Update later: ./install.sh --update
# Uninstall: ./install.sh --uninstall <platform>
```

--------------------------------

### Install Understand Anything Claude Code Plugin

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/specs/2026-03-15-homepage-design.md

Commands to install and activate the Understand Anything plugin from the marketplace. Ensure you have Claude Code installed.

```bash
/plugin marketplace add Lum1104/Understand-Anything
/plugin install understand-anything
/understand
```

--------------------------------

### Start Vite Development Server

Source: https://github.com/lum1104/understand-anything/blob/main/understand-anything-plugin/skills/understand-dashboard/SKILL.md

Starts the Vite development server, configured to host on 127.0.0.1 and serve the knowledge graph from the specified directory. This command should be executed in the dashboard directory.

```bash
cd <dashboard-dir> && GRAPH_DIR=<project-dir> npx vite --host 127.0.0.1
```

--------------------------------

### Build and Run Dashboard

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/plans/2026-05-03-graph-layout-scaling.md

Commands to build the dashboard package and start the development server for manual testing.

```bash
pnpm --filter @understand-anything/dashboard build
pnpm dev:dashboard
```

--------------------------------

### One-line Install Script (macOS/Linux)

Source: https://github.com/lum1104/understand-anything/blob/main/README.md

Use this curl command to download and execute the installation script for macOS and Linux. It supports specifying a platform to skip prompts.

```bash
curl -fsSL https://raw.githubusercontent.com/Lum1104/Understand-Anything/main/install.sh | bash
# or skip the prompt by passing the platform:
curl -fsSL https://raw.githubusercontent.com/Lum1104/Understand-Anything/main/install.sh | bash -s codex
```

--------------------------------

### Start Dashboard Dev Server

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/plans/2026-03-26-theme-system-implementation.md

Command to start the development server for the dashboard using pnpm. This allows for visual verification of theme changes.

```bash
cd understand-anything-plugin && pnpm dev:dashboard
```

--------------------------------

### Install Dependencies and Build Project

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/plans/2026-03-15-homepage-implementation.md

Installs project dependencies and builds the Astro project. This step verifies that the project configuration is correct and the build process succeeds.

```bash
cd /Users/yuxianglin/Desktop/opensource/Understand-Anything/homepage
pnpm install
pnpm build
```

--------------------------------

### Install Dagre Package

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/plans/2026-03-14-phase2-implementation.md

Install the Dagre library using pnpm. This command should be run from the dashboard package directory.

```bash
cd packages/dashboard && pnpm add @dagrejs/dagre
```

--------------------------------

### Add Knowledge Graph Guide Agent

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/plans/2026-03-18-multi-platform-simple-implementation.md

Stages the new knowledge graph guide agent definition file for commit.

```bash
git add understand-anything-plugin/agents/knowledge-graph-guide.md
git commit -m "feat: add knowledge-graph-guide agent for graph navigation and querying"
```

--------------------------------

### Copilot CLI Plugin Installation

Source: https://github.com/lum1104/understand-anything/blob/main/README.md

Install the plugin using the Copilot CLI. This command registers the plugin for use within the Copilot environment.

```bash
copilot plugin install Lum1104/Understand-Anything:understand-anything-plugin
```

--------------------------------

### Run Dashboard Development Server

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/plans/2026-03-14-phase1-implementation.md

Command to start the Vite development server for the dashboard. Assumes pnpm is used as the package manager.

```bash
pnpm --filter @understand-anything/dashboard dev
```

--------------------------------

### Create README.md

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/plans/2026-03-14-phase1-implementation.md

This markdown file serves as the primary README for the project, detailing its purpose, features, quick start guide, project structure, and tech stack.

```markdown
# Understand Anything

An open-source tool that combines LLM intelligence with static analysis to help anyone understand any codebase — from junior developers to product managers.

## Features

- **Knowledge Graph** — Automatically maps your codebase into an interactive graph of files, functions, classes, and their relationships
- **Multi-Panel Dashboard** — Graph view, code viewer, chat, and learn panels in a workspace layout
- **Natural Language Search** — Search your codebase with plain English: "which parts handle authentication?"
- **Tree-sitter Analysis** — Accurate structural analysis for TypeScript, JavaScript (more languages coming)
- **LLM-Powered Summaries** — Every node gets a plain-English description of what it does and why

## Quick Start

```bash
# Install dependencies
pnpm install

# Build the core package
pnpm --filter @understand-anything/core build

# Start the dashboard dev server
pnpm dev:dashboard
```

## Project Structure

```
packages/
  core/        — Analysis engine: types, persistence, tree-sitter, LLM prompts
  dashboard/   — React + TypeScript web dashboard
  skill/       — Claude Code skill (coming soon)
```

## Tech Stack

- TypeScript, pnpm workspaces
- React 18, Vite, TailwindCSS
- React Flow (graph visualization)
- Monaco Editor (code viewer)
- Zustand (state management)
- tree-sitter (static analysis)

## License

MIT

```

--------------------------------

### Generate .understandignore File

Source: https://github.com/lum1104/understand-anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md

Generates a starter .understandignore file by reading .gitignore and deduplicating against built-in defaults. This script should be run in the project root.

```bash
node -e "
const fs = require('fs');
const path = require('path');
const root = process.cwd();
const defaults = ['node_modules/','node_modules','.git/','vendor/','venv/','.venv/','__pycache__/','dist/','dist','build/','build','out/','coverage/','coverage','.next/','.cache/','.turbo/','target/','obj/','*.lock','package-lock.json','yarn.lock','pnpm-lock.yaml','*.png','*.jpg','*.jpeg','*.gif','*.svg','*.ico','*.woff','*.woff2','*.ttf','*.eot','*.mp3','*.mp4','*.pdf','*.zip','*.tar','*.gz','*.min.js','*.min.css','*.map','*.generated.*','.idea/','.vscode/','LICENSE','.gitignore','.editorconfig','.prettierrc','.eslintrc*','*.log'];
const norm = p => p.replace(///+$/, '');
const defaultSet = new Set(defaults.map(norm));
const header = '# .understandignore — patterns for files/dirs to exclude from analysis\n# Syntax: same as .gitignore (globs, # comments, ! negation, trailing / for dirs)\n# Lines below are suggestions — uncomment to activate.\n# Use ! prefix to force-include something excluded by defaults.\n#\n# Built-in defaults (always excluded unless negated):\n#   node_modules/, .git/, dist/, build/, obj/, *.lock, *.min.js, etc.\n#\n';
let body = '';
const gitignorePath = path.join(root, '.gitignore');
if (fs.existsSync(gitignorePath)) {
  const gi = fs.readFileSync(gitignorePath, 'utf-8').split('\n').map(l => l.trim()).filter(l => l && !l.startsWith('#')).filter(p => !defaultSet.has(norm(p)));
  if (gi.length) { body += '# --- From .gitignore (uncomment to exclude) ---\n\n' + gi.map(p => '# ' + p).join('\n') + '\n\n'; }
}
const dirs = ['__tests__','test','tests','fixtures','testdata','docs','examples','scripts','migrations','.storybook'];
const found = dirs.filter(d => fs.existsSync(path.join(root, d)));
if (found.length) { body += '# --- Detected directories (uncomment to exclude) ---\n\n' + found.map(d => '# ' + d + '/').join('\n') + '\n\n'; }
body += '# --- Test file patterns (uncomment to exclude) ---\n\n# *.test.*\n# *.spec.*\n# *.snap\n';
const outDir = path.join(root, '.understand-anything');
if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true });
fs.writeFileSync(path.join(outDir, '.understandignore'), header + body);
"

```

--------------------------------

### Generate Starter .understandignore File

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/plans/2026-04-10-understandignore-impl.md

Generates a starter .understandignore file by scanning the project root for common directories and suggesting them as commented-out exclusions. The user must uncomment suggestions to activate them.

```typescript
const HEADER = `# Built-in defaults (always excluded unless negated):
#   node_modules/, .git/, dist/, build/, bin/, obj/, *.lock, *.min.js, etc.
#
`;

/** Directories to check for and suggest excluding. */
const DETECTABLE_DIRS = [
  { dir: "__tests__", pattern: "__tests__/" },
  { dir: "test", pattern: "test/" },
  { dir: "tests", pattern: "tests/" },
  { dir: "fixtures", pattern: "fixtures/" },
  { dir: "testdata", pattern: "testdata/" },
  { dir: "docs", pattern: "docs/" },
  { dir: "examples", pattern: "examples/" },
  { dir: "scripts", pattern: "scripts/" },
  { dir: "migrations", pattern: "migrations/" },
  { dir: ".storybook", pattern: ".storybook/" },
];

/** Always-included generic suggestions. */
const GENERIC_SUGGESTIONS = [
  "*.test.*",
  "*.spec.*",
  "*.snap",
];

/**
 * Generates a starter .understandignore file by scanning the project root
 * for common directories and suggesting them as commented-out exclusions.
 *
 * All suggestions are commented out — the user must uncomment to activate.
 * Returns the file content as a string.
 */
export function generateStarterIgnoreFile(projectRoot: string): string {
  const sections: string[] = [HEADER];

  // Detected directory suggestions
  const detected: string[] = [];
  for (const { dir, pattern } of DETECTABLE_DIRS) {
    if (existsSync(join(projectRoot, dir))) {
      detected.push(pattern);
    }
  }

  if (detected.length > 0) {
    sections.push("# --- Detected directories (uncomment to exclude) ---\
");
    for (const pattern of detected) {
      sections.push(`# ${pattern}`);
    }
    sections.push("");
  }

  // Generic suggestions (always included)
  sections.push("# --- Test file patterns (uncomment to exclude) ---\
");
  for (const pattern of GENERIC_SUGGESTIONS) {
    sections.push(`# ${pattern}`);
  }
  sections.push("");

  return sections.join("\n");
}

```

--------------------------------

### Install Dashboard Dependencies

Source: https://github.com/lum1104/understand-anything/blob/main/understand-anything-plugin/skills/understand-dashboard/SKILL.md

Installs project dependencies using pnpm, falling back to a standard install if the frozen lockfile installation fails. This command should be run within the dashboard directory.

```bash
cd <dashboard-dir> && pnpm install --frozen-lockfile 2>/dev/null || pnpm install
```

--------------------------------

### Generated .understandignore File Format

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/specs/2026-04-10-understandignore-design.md

Example format of a generated `.understandignore` file. It includes a header explaining the syntax and usage, followed by commented-out suggestions for common exclusions.

```text
# .understandignore — patterns for files/dirs to exclude from analysis
# Syntax: same as .gitignore (globs, # comments, ! negation, trailing / for dirs)
# Lines below are suggestions — uncomment to activate.
# Use ! prefix to force-include something excluded by defaults.
#
# Built-in defaults (always excluded unless negated):
#   node_modules/, .git/, dist/, build/, bin/, obj/, *.lock, *.min.js, etc.
#

# --- Suggested exclusions (uncomment to activate) ---

# Test files
# __tests__/
# *.test.*
# *.spec.*

# Test data
# fixtures/
# testdata/

# Documentation
# docs/

# ... (more suggestions based on detection)
```

--------------------------------

### Install Tree-Sitter WASM Grammar Packages

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/plans/2026-03-21-language-agnostic-plan.md

This command installs multiple tree-sitter grammar packages for various programming languages. It's important to verify that each installed package includes a .wasm file.

```bash
cd understand-anything-plugin && pnpm --filter @understand-anything/core add \
  tree-sitter-python \
  tree-sitter-go \
  tree-sitter-java \
  tree-sitter-rust \
  tree-sitter-cpp \
  tree-sitter-c-sharp \
  tree-sitter-ruby \
  tree-sitter-php \
  tree-sitter-swift \
  tree-sitter-kotlin
```

--------------------------------

### Create Astro Project with Minimal Template

Source: https://github.com/lum1104/understand-anything/blob/main/homepage/README.md

Use this command to initialize a new Astro project using the minimal template. Ensure you have pnpm installed.

```sh
pnpm create astro@latest -- --template minimal
```

--------------------------------

### Install Tree-sitter Dependencies

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/plans/2026-03-14-phase1-implementation.md

Installs the tree-sitter, tree-sitter-javascript, and tree-sitter-typescript packages for the core package.

```bash
pnpm --filter @understand-anything/core add tree-sitter tree-sitter-javascript tree-sitter-typescript
```

--------------------------------

### Create Skill Directory and SKILL.md

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/plans/2026-04-01-business-domain-knowledge-impl.md

Create the directory structure and the main skill markdown file for the /understand-domain skill.

```bash
mkdir -p understand-anything-plugin/skills/understand-domain
```

```markdown
---
name: understand-domain
description: Extract business domain knowledge from a codebase and generate an interactive domain flow graph. Works standalone (lightweight scan) or derives from an existing /understand knowledge graph.
argument-hint: [--full]
---

# /understand-domain

Extracts business domain knowledge — domains, business flows, and process steps — from a codebase and produces an interactive horizontal flow graph in the dashboard.

## How It Works

- If a knowledge graph already exists (.understand-anything/knowledge-graph.json), derives domain knowledge from it (cheap, no file scanning)
- If no knowledge graph exists, performs a lightweight scan: file tree + entry point detection + sampled files
- Use `--full` flag to force a fresh scan even if a knowledge graph exists

## Instructions

### Phase 1: Detect Existing Graph

1. Check if .understand-anything/knowledge-graph.json exists in the current project
2. If it exists AND `--full` was NOT passed → proceed to Phase 3 (derive from graph)
3. Otherwise → proceed to Phase 2 (lightweight scan)

### Phase 2: Lightweight Scan (Path 1)

1. Run the preprocessing script bundled with this skill:
   ```
   python understand-anything-plugin/skills/understand-domain/extract-domain-context.py <project-root>
   ```
   This outputs .understand-anything/intermediate/domain-context.json containing:
   - File tree (respecting .gitignore)
   - Detected entry points (HTTP routes, CLI commands, event handlers, cron jobs, exported handlers)
   - File signatures (exports, imports per file)
   - Code snippets for each entry point (signature + first few lines)
2. Read the generated domain-context.json as context for Phase 4
3. Proceed to Phase 4

### Phase 3: Derive from Existing Graph (Path 2)

1. Read .understand-anything/knowledge-graph.json
2. Format the graph data as structured context:
   - All nodes with their types, names, summaries, and tags
   - All edges with their types (especially `calls`, `imports`, `contains`)
   - All layers with their descriptions
   - Tour steps if available
3. This is the context for the domain analyzer — no file reading needed
4. Proceed to Phase 4

### Phase 4: Domain Analysis

1. Read the domain-analyzer agent prompt from agents/domain-analyzer.md
2. Dispatch a subagent with the domain-analyzer prompt + the context from Phase 2 or 3
3. The agent writes its output to .understand-anything/intermediate/domain-analysis.json

### Phase 5: Validate and Save

1. Read the domain analysis output
2. Validate using the standard graph validation pipeline (the schema now supports domain/flow/step types)
3. If validation fails, log warnings but save what's valid (error tolerance)
4. Save to .understand-anything/domain-graph.json
5. Clean up .understand-anything/intermediate/domain-analysis.json

### Phase 6: Launch Dashboard

1. Auto-trigger /understand-dashboard to visualize the domain graph
2. The dashboard will detect domain-graph.json and show the domain view by default

```

--------------------------------

### Commit Format Guides to Knowledge Base

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/plans/2026-04-09-understand-knowledge.md

Use these Git commands to stage and commit the newly added format guides for knowledge base parsing. Ensure the path accurately reflects the location of your format guides.

```bash
git add understand-anything-plugin/skills/understand-knowledge/formats/
git commit -m "feat(skill): add 7 research-backed format guides for knowledge base parsing"
```

--------------------------------

### Vitest Example Test Structure

Source: https://github.com/lum1104/understand-anything/blob/main/CONTRIBUTING.md

An example of how to structure tests using Vitest, including describe, it, and expect.

```typescript
import { describe, it, expect } from 'vitest';

describe('MyFeature', () => {
  it('should do something', () => {
    // Arrange
    const input = 'test';

    // Act
    const result = myFunction(input);

    // Assert
    expect(result).toBe('expected');
  });
});
```

--------------------------------

### Build and Test Skill Package

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/plans/2026-03-14-phase4-implementation.md

Navigate to the skill package directory and execute build and test commands using pnpm.

```bash
cd packages/skill && pnpm build && pnpm test
```

--------------------------------

### Generate Starter Ignore File Function

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/specs/2026-04-10-understandignore-design.md

Provides a function to generate the content of a starter `.understandignore` file. This function scans the project for common patterns and returns a string with commented-out suggestions.

```typescript
export function generateStarterIgnoreFile(projectRoot: string): string;
```

--------------------------------

### Install CTA Component in Astro

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/plans/2026-03-15-homepage-implementation.md

Astro component for the installation Call-to-Action. Includes styled preformatted code for Claude Code CLI commands.

```astro
<section class="install" id="install">
  <div class="install-inner reveal">
    <h2 class="install-title">Get started in 30 seconds</h2>
    <div class="install-code">
      <div class="install-code-header">
        <span class="install-code-dot"></span>
        <span class="install-code-label">Claude Code</span>
      </div>
      <pre><code><span class="cmd">/plugin marketplace add</span> Lum1104/Understand-Anything
<span class="cmd">/plugin install</span> understand-anything
<span class="cmd">/understand</span></code></pre>
    </div>
    <p class="install-note">Works with <strong>Claude Code</strong> — Anthropic's official CLI for Claude.</p>
  </div>
</section>

<style>
  .install {
    padding: 6rem 2rem;
    text-align: center;
  }

  .install-inner {
    max-width: 640px;
    margin: 0 auto;
  }

  .install-title {
    font-family: var(--font-heading);
    font-size: clamp(1.5rem, 3vw, 2.25rem);
    color: var(--text);
    margin-bottom: 2rem;
  }

  .install-code {
    background: var(--surface);
    border: 1px solid var(--border);
    border-radius: 12px;
    overflow: hidden;
    text-align: left;
    margin-bottom: 1.5rem;
  }

  .install-code-header {
    display: flex;
    align-items: center;
    gap: 0.5rem;
    padding: 0.75rem 1rem;
    border-bottom: 1px solid var(--border);
  }

  .install-code-dot {
    width: 8px;
    height: 8px;
    border-radius: 50%;
    background: var(--accent);
  }

  .install-code-label {
    font-size: 0.8rem;
    color: var(--text-muted);
    font-family: var(--font-code);
  }

  pre {
    padding: 1.25rem 1.5rem;
    margin: 0;
    overflow-x: auto;
  }

  code {
    font-family: var(--font-code);
    font-size: 0.95rem;
    line-height: 1.8;
    color: var(--text);
  }

  .cmd {
    color: var(--accent);
  }

  .install-note {
    font-size: 0.9rem;
    color: var(--text-muted);
  }

  .install-note strong {
    color: var(--text);
  }
</style>
```

--------------------------------

### Install ignore package for core

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/plans/2026-04-10-understandignore-impl.md

Installs the 'ignore' npm package as a dependency for the core package. This is a prerequisite for implementing .understandignore file parsing.

```bash
cd understand-anything-plugin && pnpm add --filter @understand-anything/core ignore
```

--------------------------------

### Understand-Anything CLI Commands

Source: https://github.com/lum1104/understand-anything/blob/main/README.md

A collection of commands for interacting with the Understand-Anything plugin. Use these for chat-based queries, diff analysis, code explanation, onboarding guide generation, domain knowledge extraction, and knowledge base analysis.

```bash
# Ask anything about the codebase
/understand-chat How does the payment flow work?

# Analyze impact of your current changes
/understand-diff

# Deep-dive into a specific file or function
/understand-explain src/auth/login.ts

# Generate an onboarding guide for new team members
/understand-onboard

# Extract business domain knowledge (domains, flows, steps)
/understand-domain

# Analyze a Karpathy-pattern LLM wiki knowledge base
/understand-knowledge ~/path/to/wiki
```

--------------------------------

### AI Agent Installation Command

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/specs/2026-03-18-multi-platform-simple-design.md

A one-line command that a user can provide to an AI agent to fetch and follow installation instructions from a remote INSTALL.md file.

```bash
Fetch and follow instructions from https://raw.githubusercontent.com/Lum1104/Understand-Anything/refs/heads/main/understand-anything-plugin/.codex/INSTALL.md
```

--------------------------------

### Create package.json for Skill Package

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/plans/2026-03-14-phase2-implementation.md

Defines the metadata, scripts, and dependencies for the `@understand-anything/skill` package. Includes build and test scripts, and workspace dependencies.

```json
{
  "name": "@understand-anything/skill",
  "version": "0.1.0",
  "type": "module",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "scripts": {
    "build": "tsc",
    "test": "vitest run"
  },
  "dependencies": {
    "@understand-anything/core": "workspace:*"
  },
  "devDependencies": {
    "@types/node": "^22.0.0",
    "typescript": "^5.7.0",
    "vitest": "^3.1.0"
  }
}
```

--------------------------------

### Build Dashboard Package

Source: https://github.com/lum1104/understand-anything/blob/main/docs/superpowers/plans/2026-03-14-phase3-implementation.md

Navigate to the dashboard package directory and execute the build command to compile the project.

```bash
cd packages/dashboard && pnpm build
```

--------------------------------

### Build All Packages

Source: https://github.com/lum1104/understand-anything/blob/main/CONTRIBUTING.md

Build all packages in the project using pnpm.

```bash
pnpm build
```

--------------------------------

### Find Installed Plugin Version

Source: https://github.com/lum1104/understand-anything/blob/main/CLAUDE.md

Locate the currently installed version of the plugin in the Claude Code cache. This version number is crucial for replacing the correct directory.

```bash
ls ~/.claude/plugins/cache/understand-anything/understand-anything/
```