first-tree 0.0.1 → 0.0.3

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

@@ -0,0 +1,56 @@
+# 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.
+- 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 `AGENT.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,162 @@
+# 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 Git repository for your tree (separate from your code repos)
+- 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
+
+```bash
+mkdir my-org-tree && cd my-org-tree
+git init
+context-tree init
+```
+
+This installs the framework skill into `skills/first-tree/`, renders scaffolding (`NODE.md`, `AGENT.md`, `members/NODE.md`), and generates a task list in `skills/first-tree/progress.md`.
+
+### 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 `AGENT.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
+```
+
+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` | Bootstrap a new tree. Installs the framework skill, renders templates, generates a task list. |
+| `context-tree verify` | Check the installed progress file for unchecked items + run deterministic validation. |
+| `context-tree upgrade` | Refresh the installed framework skill from the currently running `first-tree` npm package and generate follow-up tasks. |
+| `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
+- `AGENT.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.

package/skills/first-tree/references/source-map.md

@@ -0,0 +1,94 @@
+# Context Tree Source Map
+
+This is the canonical reading index for the single-skill architecture. If a
+maintainer needs information to safely change the framework or thin CLI, that
+information should be discoverable from this file.
+
+## Read First
+
+| Path | Why it matters |
+| --- | --- |
+| `SKILL.md` | Trigger conditions, workflow, and validation contract |
+| `references/about.md` | Product framing for what Context Tree is and is not |
+| `references/onboarding.md` | The onboarding narrative that `help onboarding` and `init` surface |
+| `references/principles.md` | Decision-model reference |
+| `references/ownership-and-naming.md` | Ownership contract |
+| `references/upgrade-contract.md` | Installed layout and upgrade semantics |
+| `references/maintainer-architecture.md` | Source-repo architecture and invariants |
+| `references/maintainer-thin-cli.md` | Root shell contract and anti-duplication rules |
+| `references/maintainer-build-and-distribution.md` | Build, pack, and distribution contract |
+| `references/maintainer-testing.md` | Test workflow and maintainer validation expectations |
+
+## Runtime Payload
+
+The installed skill payload lives under `assets/framework/`.
+
+| Path | Purpose |
+| --- | --- |
+| `assets/framework/manifest.json` | Runtime asset contract |
+| `assets/framework/VERSION` | Version marker for installed payloads |
+| `assets/framework/templates/` | Generated scaffolds |
+| `assets/framework/workflows/` | CI templates |
+| `assets/framework/prompts/` | Review prompt payload |
+| `assets/framework/examples/` | Agent integration examples |
+| `assets/framework/helpers/` | Shipped helper scripts and TypeScript utilities |
+| `progress.md` | Generated in user repos to track unfinished setup or upgrade tasks |
+
+## Framework Engine Surface
+
+These skill-owned files implement the framework behavior.
+
+| Path | Purpose |
+| --- | --- |
+| `engine/commands/` | Stable command entrypoints that the thin CLI imports |
+| `engine/init.ts` / `engine/verify.ts` / `engine/upgrade.ts` | Command implementations for install, verify, and upgrade |
+| `engine/onboarding.ts` | Canonical onboarding text loader |
+| `engine/repo.ts` | Repo inspection and layout helpers |
+| `engine/rules/` | Situation-aware task generation after `init` |
+| `engine/validators/` | Deterministic tree and member validation |
+| `engine/runtime/asset-loader.ts` | Path constants plus legacy-layout detection |
+| `engine/runtime/installer.ts` | Bundled-package discovery, skill copy, and template-render helpers |
+| `engine/runtime/upgrader.ts` | Packaged-skill version comparison helpers |
+| `engine/runtime/adapters.ts` | Agent-integration path helpers |
+
+## Thin CLI Shell Surface
+
+These root files are distribution shell code. They should stay thin and should
+not become the only place important maintainer knowledge lives.
+
+| Path | Purpose |
+| --- | --- |
+| `src/cli.ts` | Thin command parser and dispatcher |
+| `src/md.d.ts` | Build-time markdown module typing |
+| `package.json` | Package metadata, import aliases, and scripts |
+| `tsconfig.json` | TypeScript compile boundaries |
+| `tsdown.config.ts` | Build entry and asset handling |
+| `vitest.config.ts` | Unit-test entrypoints |
+| `.github/workflows/ci.yml` | Thin CI shell |
+| `README.md` | Thin distribution overview |
+| `AGENT.md` | Thin maintainer pointer for agent sessions |
+
+## Validation
+
+| Path | Coverage |
+| --- | --- |
+| `tests/init.test.ts` | Init scaffolding behavior |
+| `tests/verify.test.ts` | Verification and progress gating |
+| `tests/rules.test.ts` | Task generation text |
+| `tests/asset-loader.test.ts` | Layout detection and path precedence |
+| `tests/generate-codeowners.test.ts` | Ownership helper behavior |
+| `tests/run-review.test.ts` | Review helper behavior |
+| `tests/skill-artifacts.test.ts` | Skill export and documentation integrity |
+| `tests/thin-cli.test.ts` | Thin CLI entrypoint smoke coverage |
+| `tests/upgrade.test.ts` | Installed-skill upgrade behavior |
+
+## Compatibility Notes
+
+- The source repo intentionally contains no root `.context-tree/`, `docs/`,
+  mirror skills, or bundled repo snapshot.
+- Legacy `.context-tree/...` paths still matter only for migrating existing
+  user repos; the compatibility logic lives in
+  `engine/runtime/asset-loader.ts` and `engine/upgrade.ts`.
+- Root `README.md` and `AGENT.md` are intentionally brief. Important
+  information must live in the skill references instead.
+- If you change `references/` or `assets/framework/`, run `pnpm validate:skill`.