first-tree 0.0.2 → 0.0.4

package/skills/first-tree/references/about.md

@@ -0,0 +1,36 @@
+---
+title: "About Context Tree"
+owners: []
+---
+
+# About Context Tree
+
+**context-tree.ai** — The living source of truth for your organization.
+
+---
+
+## The Problem
+
+Organizations generate decisions constantly — in PRs, meetings, Slack threads, documents. But none of these systems stay current. PRs get merged, issues get closed, documents decay. The knowledge that produced them scatters and disappears.
+
+When an agent — or a new teammate — needs to understand *why* something was built a certain way, there's nowhere to look. The information existed once, but no system kept it alive.
+
+---
+
+## The Idea
+
+Context Tree is the **living source of truth** for an organization — a tree-structured knowledge base that agents and humans build and maintain together.
+
+Every node represents a domain, decision, or design. Every node has an **owner**. When a decision is made, it is written to the tree. When things change, the tree updates. The tree is never a snapshot — it's the current state.
+
+The result is an organization where:
+
+- Every agent and every human reads from the same, always-current source
+- Decisions are traceable — the *what*, the *why*, and who owns it
+- Knowledge compounds over time instead of evaporating
+
+---
+
+## Who It's For
+
+Agent-centric teams — founders, engineers, and product builders who work alongside AI agents every day and want their organizational knowledge to grow with them, not against them.

package/skills/first-tree/references/maintainer-architecture.md

@@ -0,0 +1,59 @@
+# Maintainer Architecture
+
+This reference explains how to maintain the `first-tree` source repo itself.
+
+## What This Repo Ships
+
+- One canonical skill: `skills/first-tree/`
+- One thin CLI package: the `context-tree` command distributed by the `first-tree`
+  npm package
+- The published package carries that canonical skill directly; normal install
+  and upgrade flows should not depend on cloning this source repo
+
+This repo is not a user context tree. User decision content lives in the repos
+that install the framework.
+
+## Canonical Layers
+
+1. `SKILL.md` defines when to use the skill and the maintainer workflow.
+2. `references/` stores the knowledge an agent needs to maintain the framework
+   and the thin CLI without reading repo-local prose.
+3. `assets/framework/` stores the runtime payload that gets installed into user
+   repos.
+4. `engine/` stores the canonical framework and CLI behavior.
+5. `tests/` store the canonical skill validation surface.
+6. The root repo may also keep maintainer-only developer tooling such as
+   `evals/` when that tooling should not ship with the skill.
+7. The root CLI/package files are implementation shell code. They should call
+   into the skill-owned engine and validation surface, not become a second
+   source of framework knowledge.
+
+## Non-Negotiables
+
+- Treat `skills/first-tree/` as the only canonical source.
+- If a maintainer needs information to safely change behavior, move that
+  information into `references/`; do not leave it only in root `README.md`,
+  `AGENTS.md`, CI comments, or PR descriptions.
+- Keep runtime assets generic. They are copied into every user tree.
+- Keep the CLI thin. Command semantics, upgrade rules, layout contracts, and
+  maintainer guidance should belong to the skill.
+- Keep the user tree decision-focused. Execution detail stays in source systems.
+
+## Change Discipline
+
+- Path or layout changes: update `references/upgrade-contract.md`, task text,
+  validators, and tests together.
+- Shipped payload changes: update `assets/framework/`, the maintainer references
+  that describe the contract, and the validation surface together.
+- Thin shell changes: update the relevant maintainer reference before or during
+  the code change so the skill remains self-sufficient.
+
+## End-State Target
+
+- skill owns knowledge, runtime payload, framework engine, and the canonical
+  framework test surface
+- root owns only the light CLI/bootstrap/build shell plus maintainer-only
+  developer tooling such as `evals/`
+
+When deciding where a new file should live, bias toward the skill unless the
+file is purely package-tooling shell code.

package/skills/first-tree/references/maintainer-build-and-distribution.md

@@ -0,0 +1,59 @@
+# Build And Distribution
+
+Use this reference when touching package wiring, release behavior, or the
+distributable contract of `first-tree`.
+
+## Fast Validation
+
+Run these commands from the repo root:
+
+```bash
+pnpm validate:skill
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+## Packaging Checks
+
+When changing package contents, build wiring, or install/upgrade behavior, also
+run:
+
+```bash
+pnpm pack
+```
+
+Inspect the tarball contents before merging packaging changes. The distribution
+must be able to carry the canonical skill and the thin CLI shell without
+requiring repo-local prose.
+
+## Build Responsibilities
+
+- `package.json` defines package metadata, scripts, and import aliases.
+- `tsconfig.json` defines TypeScript compile boundaries.
+- `tsdown.config.ts` defines the build entry and asset loaders.
+- `vitest.config.ts` defines unit-test entrypoints, and
+  `vitest.eval.config.ts` defines the repo-only maintainer eval entrypoint.
+- `.github/workflows/ci.yml` is the thin CI shell for repo validation.
+
+These files are shell surfaces. Their meaning must be documented here or in
+another skill reference, not only in the files themselves.
+
+## Distribution Rules
+
+- Do not introduce a second copy of the framework outside the skill.
+- `package.json` must ship `skills/first-tree/` in the published
+  package alongside the thin CLI build output.
+- Keep repo-only developer tooling such as root `evals/` out of the published
+  package unless it becomes part of the user-facing framework contract.
+- If the CLI needs bundled knowledge or payload files, ship the canonical skill
+  with the package rather than copying that information into root docs.
+- Normal `context-tree init` / `context-tree upgrade` flows must install from
+  the skill bundled in the running package, not by cloning the source repo.
+- Default dedicated-tree-repo creation must stay local-only. It may create a
+  sibling git repo on disk, but it must not require remote repo creation or
+  source-repo cloning.
+- If you change anything that gets copied into user repos, bump
+  `assets/framework/VERSION` and keep the upgrade task text in sync.
+- If packaging changes alter what gets installed into user repos, update
+  `references/upgrade-contract.md`, tests, and validation commands together.

package/skills/first-tree/references/maintainer-testing.md

@@ -0,0 +1,58 @@
+# Testing
+
+Use this reference when validating framework behavior or changing the testing
+surface.
+
+## Core Checks
+
+```bash
+pnpm validate:skill
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+### What Each Check Covers
+
+- `pnpm validate:skill` verifies the canonical skill structure and sync rules.
+- `pnpm typecheck` catches TypeScript boundary and import issues.
+- `pnpm test` runs unit tests plus repo-local helper tests that support
+  maintainer tooling.
+- `pnpm build` checks the thin CLI bundle.
+
+## Targeted Unit Tests
+
+Examples:
+
+```bash
+pnpm test -- skills/first-tree/tests/rules.test.ts
+pnpm test -- skills/first-tree/tests/verify.test.ts
+pnpm test -- skills/first-tree/tests/skill-artifacts.test.ts
+pnpm test -- skills/first-tree/tests/thin-cli.test.ts
+```
+
+If a future refactor changes these paths again, keep the command semantics and
+coverage expectations documented here.
+
+## Packaging Check
+
+```bash
+pnpm pack
+```
+
+Inspect the tarball when package contents or install/upgrade behavior changes.
+The published package should include the thin CLI shell and canonical skill, but
+not repo-only developer tooling such as root `evals/`.
+
+## Repo-Only Evals
+
+The end-to-end eval harness is intentionally not part of the distributed skill.
+It lives under root `evals/` for `first-tree` maintainers working in this
+source repo. Use `evals/README.md` when you need to run or update it.
+
+## Change Discipline
+
+- Update this reference whenever core test entrypoints or packaging boundaries
+  change.
+- If a maintainer would need oral history to know which checks matter, that
+  knowledge belongs here.

package/skills/first-tree/references/maintainer-thin-cli.md

@@ -0,0 +1,38 @@
+# Thin CLI Shell
+
+Use this reference when changing the root CLI/package shell.
+
+## Shell Responsibilities
+
+The root shell should do only a few things:
+
+- parse commands and flags
+- expose version/help
+- load canonical framework behavior
+- build, validate, and package the distributable
+
+If a change requires non-trivial framework knowledge, put that knowledge in the
+skill and have the shell call it.
+
+## Shell Surface
+
+These root files are shell code, not canonical knowledge stores:
+
+- `src/cli.ts`
+- `src/md.d.ts`
+- `package.json`
+- `tsconfig.json`
+- `tsdown.config.ts`
+- `vitest.config.ts`
+- `vitest.eval.config.ts` (repo-only maintainer eval entrypoint)
+- `.github/workflows/ci.yml`
+- root `README.md` and `AGENTS.md`
+
+## Rules For Shell Changes
+
+- Keep root prose short. It should point to the skill, not duplicate the skill.
+- Keep command semantics, install layout rules, and maintainer guidance in the
+  skill references.
+- If the shell gains behavior that is not obviously mechanical, move that
+  behavior or its contract into the skill.
+- When in doubt, prefer adding a skill reference over expanding root docs.

package/skills/first-tree/references/onboarding.md

@@ -0,0 +1,185 @@
+# Context Tree Onboarding
+
+You are setting up a **Context Tree** — the living source of truth for an organization. This document tells you what it is and how to bootstrap one.
+
+---
+
+## What Is a Context Tree
+
+A Context Tree is a Git repository where every directory is a **domain** and every file is a **node**. Each node captures decisions, designs, and cross-domain relationships — the knowledge that would otherwise scatter across PRs, documents, and people's heads.
+
+Key properties:
+
+- **Nodes are markdown files.** Each directory has a `NODE.md` that describes the domain. Leaf `.md` files capture specific decisions or designs.
+- **Every node has an owner.** Declared in YAML frontmatter. Owners approve changes to their nodes.
+- **Organized by concern, not by repo or team.** An agent working on "add SSO" finds all auth context in one place — not split across 4 repos.
+- **The tree is never a snapshot — it's the current state.** When decisions change, the tree updates. Stale nodes are bugs.
+
+### Frontmatter Format
+
+Every node has frontmatter:
+
+```yaml
+---
+title: "Auth Architecture"
+owners: [alice, bob]
+soft_links: [/infrastructure/deployments]
+---
+```
+
+- `owners` — who can approve changes. `owners: []` inherits from parent. `owners: [*]` means anyone.
+- `soft_links` — cross-references to related nodes in other domains.
+
+### What Belongs in the Tree
+
+Information an agent needs to **decide** on an approach — not to execute it.
+
+**Yes:** "Auth spans 4 repos: backend issues JWTs, frontend uses Better Auth, extension uses OAuth popup, desktop uses localhost callback."
+
+**No:** The function signature of `auth_service.verify()` — that's in the code.
+
+---
+
+## Four Principles
+
+1. **Source of truth for decisions, not execution.** The tree captures the *what* and *why*. Execution details stay in source systems.
+2. **Agents are first-class participants.** The tree is designed for agents to navigate and update.
+3. **Transparency by default.** Reading is open to all. Writing requires owner approval.
+4. **Git-native.** Nodes are files, domains are directories. History, ownership, and review follow Git conventions.
+
+---
+
+## How to Set Up a Context Tree
+
+### Prerequisites
+
+- A source/workspace Git repository, or an already-created dedicated tree repo
+- Node.js 18+
+- The npm package is `first-tree`, the installed CLI command is
+  `context-tree`, and the installed skill directory in the tree is
+  `skills/first-tree/`
+- Use `npx first-tree init` for one-off runs, or `npm install -g first-tree`
+  to add the `context-tree` command to your PATH
+
+### Step 1: Initialize
+
+Recommended workflow: run `context-tree init` from your source or workspace repo.
+The CLI will create a sibling dedicated tree repo named `<repo>-context` by
+default and install the framework there.
+
+```bash
+cd my-org
+context-tree init
+cd ../my-org-context
+```
+
+If you already created a dedicated tree repo manually, initialize it in place:
+
+```bash
+mkdir my-org-context && cd my-org-context
+git init
+context-tree init --here
+```
+
+Either way, the framework installs into `skills/first-tree/`, renders
+scaffolding (`NODE.md`, `AGENTS.md`, `members/NODE.md`), and generates a task
+list in `skills/first-tree/progress.md`.
+
+Publishing tip: keep the tree repo in the same GitHub organization as the
+source repo unless you have a reason not to.
+
+### Step 2: Work Through the Task List
+
+Read `skills/first-tree/progress.md`. It contains a checklist tailored to the current state of the repo. Complete each task:
+
+- Fill in `NODE.md` with your organization name, owners, and domains
+- Add project-specific instructions to `AGENTS.md` below the framework markers
+- Create member nodes under `members/`
+- Optionally configure agent integration (e.g., Claude Code session hooks)
+- Copy validation workflows from `skills/first-tree/assets/framework/workflows/` to `.github/workflows/`
+
+As you complete each task, check it off in `skills/first-tree/progress.md` by changing `- [ ]` to `- [x]`.
+
+### Step 3: Verify
+
+```bash
+context-tree verify
+```
+
+Or, from your source/workspace repo:
+
+```bash
+context-tree verify --tree-path ../my-org-context
+```
+
+This fails if any items in `skills/first-tree/progress.md` remain unchecked, and runs deterministic checks (valid frontmatter, node structure, member nodes exist).
+
+### Step 4: Design Your Domains
+
+Create top-level directories for your organization's primary concerns. Each needs a `NODE.md`:
+
+```
+my-org-tree/
+  NODE.md              # root — lists all domains
+  engineering/
+    NODE.md            # decisions about architecture, infra, tooling
+  product/
+    NODE.md            # strategy, roadmap, user research
+  marketing/
+    NODE.md            # positioning, campaigns
+  members/
+    NODE.md            # team members and agents
+    alice/
+      NODE.md          # individual member node
+```
+
+### Step 5: Populate from Existing Work
+
+For each domain, extract knowledge from existing repos, docs, and systems:
+
+- Decisions and their rationale
+- Cross-domain relationships and dependencies
+- Constraints that aren't obvious from the code
+
+The tree doesn't duplicate source code — it captures what connects things and why they were built that way.
+
+---
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `context-tree init` | Create or refresh a dedicated tree repo. By default, running in a source/workspace repo creates a sibling `<repo>-context`; use `--here` to initialize the current repo in place. |
+| `context-tree verify` | Check the installed progress file for unchecked items + run deterministic validation. Use `--tree-path` when invoking from another working directory. |
+| `context-tree upgrade` | Refresh the installed framework skill from the currently running `first-tree` npm package and generate follow-up tasks. Use `--tree-path` when invoking from another working directory. |
+| `context-tree help onboarding` | Print this onboarding guide. |
+
+---
+
+## Upgrading the Framework
+
+When the framework updates:
+
+```bash
+context-tree upgrade
+```
+
+`context-tree upgrade` refreshes `skills/first-tree/` from the
+skill bundled with the currently running `first-tree` npm package, preserves your
+tree content, and generates follow-up tasks in
+`skills/first-tree/progress.md`.
+
+If your repo still uses the older `skills/first-tree-cli-framework/` path,
+`context-tree upgrade` will migrate it to `skills/first-tree/` first.
+
+To pick up a newer framework release, first run a newer package version, for
+example `npx first-tree@latest upgrade`, or update your global `first-tree`
+install before running `context-tree upgrade`.
+
+---
+
+## Further Reading
+
+- `skills/first-tree/references/principles.md` — Core principles with detailed examples
+- `skills/first-tree/references/ownership-and-naming.md` — How nodes are named and owned
+- `AGENTS.md` in your tree — The before/during/after workflow for every task

package/skills/first-tree/references/ownership-and-naming.md

@@ -0,0 +1,94 @@
+---
+title: "Node Naming and Ownership Model"
+owners: []
+---
+
+# Node Naming and Ownership Model
+
+## Summary
+
+This proposal defines how nodes are structured, named, and owned in a Context Tree repository.
+
+## NODE.md as the Parent Node
+
+Every folder in the tree **must** contain a `NODE.md` file. This file serves two purposes:
+
+1. **Description** — it is the human- and agent-readable explanation of the domain that folder represents.
+2. **Ownership** — its frontmatter declares who owns all content within the folder.
+
+Example:
+
+```yaml
+# backend/NODE.md
+---
+title: Backend Architecture
+owners: [alice, bob]
+soft_links: [/infrastructure/deployments]
+---
+
+This subtree covers the backend service architecture, including API design,
+data access patterns, and service-to-service communication.
+```
+
+## Ownership Rules
+
+1. **NODE.md is the folder-level authority.** Its owners can approve changes to any file within the folder.
+
+2. **Leaf files can declare their own owners.** These owners can approve changes to that specific file. This is additive — `NODE.md` owners retain full authority over all files in the folder.
+
+3. **Multiple owners are allowed.** On both `NODE.md` and leaf files.
+
+4. **Inheritance with override.** Every node must declare an `owners` field. To inherit from the nearest parent `NODE.md` that declares owners, use `owners: []`. Omitting `owners` entirely is not permitted. When a `NODE.md` explicitly declares owners, it fully overrides the parent — the parent folder's owners have no implicit authority over child folders.
+
+5. **Every folder requires a NODE.md.** Creating a subfolder means someone must think about ownership — either declare owners explicitly or inherit from the parent.
+
+6. **Wildcard owner.** `owners: [*]` means anyone can approve changes to that file or folder. When a NODE.md declares `owners: [*]`, anyone can add or edit leaf nodes in that folder without approval. The parent NODE.md owners still retain authority (per rule 1). Use this for open-contribution areas like tips, FAQs, proposals, or community-editable content.
+
+## Example
+
+```
+/backend/
+  NODE.md          <- owners: [alice]
+  auth.md          <- owners: [carol]
+  storage.md       <- owners: [] (inherits from NODE.md)
+  tips.md          <- owners: [*]
+
+/proposals/
+  NODE.md          <- owners: [*]
+  new-feature.md   <- owners: [] (inherits from NODE.md)
+```
+
+- **backend/auth.md** — both Alice and Carol can approve changes
+- **backend/storage.md** — only Alice can approve changes (owners: [] inherits from NODE.md)
+- **backend/tips.md** — anyone can approve changes; Alice also retains authority (governed by NODE.md)
+- **backend/NODE.md** — only Alice can approve changes
+- **proposals/new-feature.md** — anyone can approve changes (owners: [] inherits wildcard from NODE.md)
+- **proposals/NODE.md** — anyone can approve changes; parent NODE.md owners still retain authority
+
+## Leaf Files
+
+Any `.md` file in a folder other than `NODE.md` is a leaf node. Leaf nodes:
+
+- Contain content with optional frontmatter (title, owners, soft_links, etc.)
+- Are always governed by the folder's `NODE.md` ownership in addition to any owners they declare
+
+## CODEOWNERS Generation
+
+The CLI can generate a GitHub `CODEOWNERS` file from all `NODE.md` and leaf file frontmatter in the tree. This gives teams PR-level enforcement of the ownership model without custom tooling.
+
+Example generated output:
+
+```
+# Auto-generated from Context Tree. Do not edit manually.
+/backend/          @alice
+/backend/auth.md   @alice @carol
+/frontend/         @dana @eli
+```
+
+## Why This Design
+
+- **Simple to resolve ownership** — `NODE.md` owners always apply; leaf file owners are additive.
+- **Tree structure enforces clarity** — ownership disagreements at the folder level are resolved by splitting into subtrees.
+- **Folder creation is deliberate** — requiring `NODE.md` with owners prevents folder sprawl.
+- **Flexible without complexity** — leaf files can have specialized owners without introducing override semantics.
+- **Git-native** — everything is a file, versioned, reviewable in PRs.

package/skills/first-tree/references/principles.md

@@ -0,0 +1,113 @@
+---
+title: "Tree Principles: Explanation and Examples"
+owners: []
+---
+
+# Tree Principles
+
+This document explains the core principles of Context Tree with concrete examples.
+
+---
+
+## 1. Source of truth for decisions, not execution
+
+The tree captures the *what* and *why* — strategic choices, cross-domain relationships, constraints. An agent should be able to read the tree and produce a correct approach without consulting source systems.
+
+### Workflow
+
+1. Human says: "Let's add SSO to our product."
+2. Agent reads relevant tree nodes (e.g., `platform/`, `environment/`).
+3. Agent writes a top-level design based on tree context alone.
+4. Human reviews and approves.
+5. Agent explores source systems to build a detailed execution plan.
+6. If source systems reveal something the tree didn't capture — update the tree, revisit with the human, then proceed.
+7. After execution is complete, update the tree to reflect any new decisions.
+
+This applies to all tasks — features, campaigns, hiring decisions, refactors. Not every task requires a tree update, but the tree is always the starting point, and the question "does the tree need updating?" is always asked at the end.
+
+### What belongs in the tree
+
+- "Auth flows span four repos: backend issues JWTs, frontend uses Better Auth, browser extension authenticates via OAuth popup through the frontend, desktop app uses a localhost callback server."
+- "We chose MinerU for PDF parsing because it handles academic papers with complex layouts better than alternatives we tested."
+- "We target academic researchers and AI-native teams because they have the highest tolerance for an agent-centric workflow."
+- "Q3 campaign focuses on developer communities because enterprise sales cycle is too long for our current stage."
+
+### What does NOT belong in the tree
+
+- The function signature of `retrieval_service.search()` — read the code.
+- The database schema for the `chunk_embeddings` table — read the models.
+- The current ad copy for a campaign — read the campaign tool.
+- The current list of API endpoints — read the route files.
+- The exact interview questions for a role — read the hiring doc.
+
+### The test
+
+If an agent needs this information to *decide* on an approach, it belongs in the tree. If the agent only needs it to *execute*, it stays in the source system.
+
+### When inconsistency is found
+
+If an agent reads the tree, makes a decision, then discovers a source system contradicts the tree — that's a tree bug. The tree must be corrected before proceeding. This is how the tree stays accurate: every completed task is an opportunity to validate and update it.
+
+---
+
+## 2. Agents are first-class participants
+
+The tree is designed to be navigated and updated by agents, not just humans. Domains are organized by concern — what an agent needs to know to act — not by repo, team, or org chart.
+
+### Why organize by concern?
+
+An agent working on "add SSO support" doesn't think in terms of repos (backend, frontend, extension, desktop) or org structure (engineering vs. product). It needs all auth context — the why, the how, the cross-domain implications — in one place. Organizing by concern puts that context together.
+
+### Domain placement
+
+A feature or decision lives in the domain that owns the primary concern, with soft links to other domains for discoverability:
+
+- "Add SSO support" → `platform/` (auth decision), soft links to `environment/` (extension/desktop auth flows)
+- "Support PPTX parsing" → `knowledge/` (ingestion). Clear, single domain.
+- "Q3 developer campaign" → `marketing/` (go-to-market), soft link to product domain (feature positioning)
+- "Agent remembers user preferences" → `agent/` (memory)
+- "Hire a frontend engineer" → `people/hiring/` (role decision), soft link to the team they'd join
+
+### When to create subdomains
+
+Start flat. Split when an agent can't scan a NODE.md and quickly determine where to go next. If a domain accumulates enough leaf nodes on a single topic, that topic is ready to become a subdomain.
+
+### Whether something belongs in the tree is a judgment call
+
+Not every task needs a tree update. A pure UI bug fix probably doesn't. But don't assume — a "simple" feature like dark mode becomes a tree-worthy decision once it involves auto mode, cross-device persistence, or desktop app coordination. Evaluate per task.
+
+---
+
+## 3. Transparency by default
+
+All information in the tree is readable by everyone — humans and agents alike. Writing requires owner approval; reading is open.
+
+This means any agent can build full context by traversing the tree. No domain is hidden. The ownership model controls who can *change* the tree, not who can *read* it.
+
+---
+
+## 4. Git-native tree structure
+
+Each node is a file; each domain is a directory. The tree is a Git repository.
+
+### Why a tree?
+
+A tree structure keeps information organized and navigable. Soft links allow cross-references where needed without the complexity of a full graph. An agent can start at any node and traverse up (broader context) or down (more detail) predictably.
+
+### Why Git?
+
+History, ownership, and review follow the same model software engineering has refined for decades. Every change is a commit, every decision is reviewable in a PR, and the full history of how the tree evolved is preserved.
+
+### Examples of good nodes
+
+**Cross-domain relationships:** "Auth touches 4 repos: backend (JWT issuance), frontend (Better Auth client), browser extension (OAuth popup + device token), desktop (localhost callback server + JWT storage)." — An agent would need to search across all repos to piece this together.
+
+**Strategic decisions with rationale:** "We use Reciprocal Rank Fusion to combine vector and BM25 results because pure vector search missed keyword-heavy queries and pure BM25 missed semantic matches." — This is nowhere in the source systems.
+
+**Domain state summaries:** "The ingestion pipeline has 6 stages: download → extract → parse → chunk → embed → store. PDF extraction uses MinerU (cloud). PPTX uses python-pptx locally." — An agent could trace this through 6+ files, or read one node.
+
+### Examples of bad nodes
+
+- Restating what one source file already says clearly.
+- Documenting stable, well-known patterns (e.g., "we use FastAPI for the backend").
+- Listing things that change frequently without decision implications.