first-tree 0.0.5 → 0.0.7

package/skills/first-tree/engine/validators/nodes.ts

@@ -3,8 +3,6 @@ import { join, relative, posix } from "node:path";
 import {
   AGENT_INSTRUCTIONS_FILE,
   LEGACY_AGENT_INSTRUCTIONS_FILE,
-  LEGACY_SKILL_NAME,
-  LEGACY_SKILL_ROOT,
   SKILL_NAME,
   SKILL_ROOT,
 } from "#skill/engine/runtime/asset-loader.js";
@@ -88,12 +86,7 @@ function rel(path: string): string {
 }
 
 function isInstalledSkillPath(relPath: string): boolean {
-  return (
-    relPath === SKILL_ROOT ||
-    relPath.startsWith(`${SKILL_ROOT}/`) ||
-    relPath === LEGACY_SKILL_ROOT ||
-    relPath.startsWith(`${LEGACY_SKILL_ROOT}/`)
-  );
+  return relPath === SKILL_ROOT || relPath.startsWith(`${SKILL_ROOT}/`);
 }
 
 function isFrameworkContainerDir(relPath: string, fullPath: string): boolean {
@@ -106,9 +99,7 @@ function isFrameworkContainerDir(relPath: string, fullPath: string): boolean {
     if (entries.length === 0) {
       return false;
     }
-    return entries.every(
-      (entry) => entry === SKILL_NAME || entry === LEGACY_SKILL_NAME,
-    );
+    return entries.every((entry) => entry === SKILL_NAME);
   } catch {
     return false;
   }

package/skills/first-tree/engine/verify.ts

@@ -50,6 +50,13 @@ export function runVerify(repo?: Repo, nodeValidator?: NodeValidator): number {
   const r = repo ?? new Repo();
   const validate = nodeValidator ?? defaultNodeValidator;
 
+  if (r.hasSourceWorkspaceIntegration() && !r.looksLikeTreeRepo()) {
+    console.error(
+      `Error: this repo only has the first-tree source/workspace integration installed. Verify the dedicated tree repo instead, for example \`context-tree verify --tree-path ../${r.repoName()}-context\`.`,
+    );
+    return 1;
+  }
+
   if (r.isLikelySourceRepo() && !r.looksLikeTreeRepo()) {
     console.error(
       "Error: no installed framework skill found here. This looks like a source/workspace repo. Run `context-tree init` to create a dedicated tree repo, or pass `--tree-path` to verify an existing tree repo.",

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

@@ -13,6 +13,10 @@ This reference explains how to maintain the `first-tree` source repo itself.
 This repo is not a user context tree. User decision content lives in the repos
 that install the framework.
 
+When a source/workspace repo installs first-tree, that repo should keep only
+the local skill integration and marker lines. Tree content still belongs only
+in a dedicated `*-context` repo.
+
 ## Canonical Layers
 
 1. `SKILL.md` defines when to use the skill and the maintainer workflow.

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

@@ -33,6 +33,9 @@ These root files are shell code, not canonical knowledge stores:
 - 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 init/upgrade semantics change for source/workspace repos versus dedicated
+  tree repos, update `references/source-workspace-installation.md` and
+  `references/upgrade-contract.md` instead of expanding root shell prose.
 - 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

@@ -65,8 +65,10 @@ Information an agent needs to **decide** on an approach — not to execute it.
 ### 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.
+The CLI will install the bundled skill in the current repo, update root
+`AGENTS.md` and `CLAUDE.md` with a `FIRST-TREE-SOURCE-INTEGRATION:` line, and
+create a sibling dedicated tree repo named `<repo>-context` by default. Tree
+files are scaffolded only in the dedicated tree repo.
 
 ```bash
 cd my-org
@@ -82,6 +84,10 @@ git init
 context-tree init --here
 ```
 
+Only use `--here` after you have already switched into the dedicated tree repo.
+Do not use it inside the source/workspace repo unless you intentionally want
+that repo itself to become the Context Tree.
+
 Either way, the framework installs into `.agents/skills/first-tree/` and
 `.claude/skills/first-tree/`, renders scaffolding (`NODE.md`, `AGENTS.md`,
 `members/NODE.md`), and generates a task list in
@@ -90,6 +96,19 @@ Either way, the framework installs into `.agents/skills/first-tree/` and
 Publishing tip: keep the tree repo in the same GitHub organization as the
 source repo unless you have a reason not to.
 
+Hard boundary: do **not** create `NODE.md`, `members/`, or tree-scoped
+`AGENTS.md` in the source/workspace repo. Those files belong only in the
+dedicated `*-context` repo.
+
+Default agent workflow after initialization:
+
+1. Create and push the dedicated `*-context` repo in the same GitHub
+   organization as the source repo.
+2. Add the dedicated tree repo back to the source/workspace repo as a `git submodule`.
+3. Open a PR against the source/workspace repo's default branch for the local
+   skill integration plus the new submodule pointer. Do not merge it
+   automatically.
+
 ### Step 2: Work Through the Task List
 
 Read `.agents/skills/first-tree/progress.md`. It contains a checklist tailored
@@ -123,6 +142,10 @@ This fails if any items in `.agents/skills/first-tree/progress.md` remain
 unchecked, and runs deterministic checks (valid frontmatter, node structure,
 member nodes exist).
 
+Do not run `context-tree verify` in the source/workspace repo itself. That repo
+only carries the installed skill plus the
+`FIRST-TREE-SOURCE-INTEGRATION:` line.
+
 ### Step 4: Design Your Domains
 
 Create top-level directories for your organization's primary concerns. Each needs a `NODE.md`:
@@ -158,7 +181,7 @@ The tree doesn't duplicate source code — it captures what connects things and
 
 | 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 init` | Install local source/workspace integration and create or refresh a dedicated tree repo. By default, running in a source/workspace repo creates a sibling `<repo>-context`; use `--here` only when you are already inside the dedicated tree repo. |
 | `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. |
@@ -178,8 +201,12 @@ context-tree upgrade
 `first-tree` npm package, preserves your tree content, and generates follow-up
 tasks in `.agents/skills/first-tree/progress.md`.
 
-If your repo still uses the older `skills/first-tree/`,
-`skills/first-tree-cli-framework/`, or `.context-tree/` layouts,
+If you run `context-tree upgrade` in the source/workspace repo, it refreshes
+only the local installed skill plus the `FIRST-TREE-SOURCE-INTEGRATION:` lines.
+Run `context-tree upgrade --tree-path ../my-org-context` to upgrade the
+dedicated tree repo itself.
+
+If your repo still uses the older `skills/first-tree/` or `.context-tree/` layouts,
 `context-tree upgrade` will migrate it to the current installed layout first.
 
 To pick up a newer framework release, first run a newer package version, for
@@ -191,5 +218,6 @@ install before running `context-tree upgrade`.
 ## Further Reading
 
 - `.agents/skills/first-tree/references/principles.md` — Core principles with detailed examples
+- `.agents/skills/first-tree/references/source-workspace-installation.md` — Source/workspace install contract
 - `.agents/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/principles.md

@@ -5,25 +5,26 @@ owners: []
 
 # Tree Principles
 
-This document explains the core principles of Context Tree with concrete examples.
+This document explains the four core principles of Context Tree and how to
+apply them in practice. Read them in order: principle 1 defines what the tree
+is for, principle 2 explains how to organize it, principle 3 clarifies access
+and ownership, and principle 4 explains why the structure is tree-shaped and
+Git-native.
 
 ---
 
 ## 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.
+The tree captures the *what* and *why* - strategic choices, cross-domain
+relationships, and constraints. An agent should be able to read the tree and
+decide on the right approach before consulting source systems for
+implementation details.
 
-### Workflow
+### The decision test
 
-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.
+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.
 
 ### What belongs in the tree
 
@@ -32,82 +33,121 @@ This applies to all tasks — features, campaigns, hiring decisions, refactors.
 - "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
+### 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 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
+### Good node examples
 
-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.
+**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.
 
-### When inconsistency is found
+**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.
 
-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.
+**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.
 
----
+### Bad node examples
 
-## 2. Agents are first-class participants
+- 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.
 
-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.
+### Use judgment, not a checklist
 
-### Why organize by concern?
+Not every task needs a tree update. A pure UI bug fix probably does not. But
+do not 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 each task in context.
 
-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.
+### How this works during a task
+
+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 did not capture, update the
+   tree, revisit with the human, then proceed.
+7. After execution is complete, update the tree to reflect any new decisions.
 
-### Domain placement
+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.
 
-A feature or decision lives in the domain that owns the primary concern, with soft links to other domains for discoverability:
+### When the tree and source systems disagree
 
-- "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
+If an agent reads the tree, makes a decision, then discovers a source system
+contradicts the tree, that is 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.
 
-### 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.
+## 2. Agents are first-class participants
 
-### Whether something belongs in the tree is a judgment call
+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.
 
-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.
+### Organize by concern
 
----
+An agent working on "add SSO support" does not think in terms of repos
+(backend, frontend, extension, desktop) or org structure (engineering vs.
+product). It needs all auth context - the why, the how, and the cross-domain
+implications - in one place. Organizing by concern puts that context together.
 
-## 3. Transparency by default
+### Place work in the domain of the primary concern
 
-All information in the tree is readable by everyone — humans and agents alike. Writing requires owner approval; reading is open.
+A feature or decision lives in the domain that owns the primary concern, with
+soft links to other domains for discoverability:
 
-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.
+- "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 the
+  product domain (feature positioning)
+- "Agent remembers user preferences" -> `agent/` (memory)
+- "Hire a frontend engineer" -> `people/hiring/` (role decision), soft link to
+  the team they would join
 
----
+### Start flat, then split when needed
 
-## 4. Git-native tree structure
+Start flat. Split when an agent cannot 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.
 
-Each node is a file; each domain is a directory. The tree is a Git repository.
+---
 
-### Why a tree?
+## 3. Transparency by default
 
-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.
+All information in the tree is readable by everyone - humans and agents alike.
+Reading is open; writing requires owner approval.
 
-### Why Git?
+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.
 
-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
+## 4. Git-native tree structure
 
-**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.
+Each node is a file, each domain is a directory, and the tree itself is a Git
+repository. The tree shape gives predictable navigation; Git provides history,
+review, and ownership workflows.
 
-**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.
+### Why a tree
 
-**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.
+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.
 
-### Examples of bad nodes
+### Why Git
 
-- 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.
+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.

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

@@ -11,6 +11,7 @@ information should be discoverable from this file.
 | `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/source-workspace-installation.md` | Contract for source/workspace installs vs dedicated tree repos |
 | `references/principles.md` | Decision-model reference |
 | `references/ownership-and-naming.md` | Ownership contract |
 | `references/upgrade-contract.md` | Installed layout and upgrade semantics |

package/skills/first-tree/references/source-workspace-installation.md

@@ -0,0 +1,64 @@
+---
+title: "Source/Workspace Installation Contract"
+owners: []
+---
+
+# Source/Workspace Installation Contract
+
+This reference defines what it means to "install and use first-tree" in an
+existing source or workspace repository.
+
+## Core Boundary
+
+- The current source/workspace repo is **not** the Context Tree.
+- The current source/workspace repo should carry only the installed
+  `.agents/skills/first-tree/` and `.claude/skills/first-tree/` skill roots
+  plus a single `FIRST-TREE-SOURCE-INTEGRATION:` line in root `AGENTS.md` and
+  `CLAUDE.md`.
+- `NODE.md`, `members/`, and tree-scoped `AGENTS.md` content belong only in a
+  dedicated `*-context` repo.
+- If a task changes decisions, rationale, ownership, or constraints, update
+  the dedicated tree repo rather than copying that material into the source
+  repo.
+
+## Agent Decision Rule
+
+- Treat "install and use first-tree" in a source/workspace repo as a two-repo
+  workflow: local integration in the current repo plus tree bootstrap in a
+  sibling `*-context` repo.
+- Do not run `context-tree init --here` in the source/workspace repo unless the
+  user explicitly says that repo itself should become the Context Tree.
+- If you cannot create the sibling repo locally, cannot push it to GitHub, or
+  cannot add the submodule yet, pause and report the blocker. Do not fall back
+  to creating `NODE.md`, `members/`, or tree-scoped `AGENTS.md` in the
+  source/workspace repo.
+
+## Default Agent Workflow
+
+When an agent is asked to install first-tree for a source/workspace repo, the
+default workflow is:
+
+1. Install the bundled first-tree skill into the current repo.
+2. Upsert the `FIRST-TREE-SOURCE-INTEGRATION:` line in root `AGENTS.md` and
+   `CLAUDE.md`.
+3. Create a sibling dedicated tree repo named `<repo>-context`.
+4. Prefer creating and pushing that repo in the same GitHub organization as
+   the source repo, matching the source repo's default visibility unless the
+   user asks for something else.
+5. Add the dedicated tree repo back to the source/workspace repo as a `git submodule`.
+6. Run `context-tree init --here` inside the dedicated tree repo.
+7. Draft the first tree version from the real codebase, docs, and ownership
+   signals.
+8. Open a PR against the source/workspace repo's default branch for the local
+   skill integration plus the new submodule pointer. Do not merge it
+   automatically.
+
+## Verification And Upgrade
+
+- Do not run `context-tree verify` in the source/workspace repo. Verify the
+  dedicated tree repo instead, for example
+  `context-tree verify --tree-path ../my-repo-context`.
+- Running `context-tree upgrade` in the source/workspace repo refreshes only
+  the local installed skill plus the `FIRST-TREE-SOURCE-INTEGRATION:` lines.
+- Run `context-tree upgrade --tree-path ../my-repo-context` to upgrade the
+  dedicated tree repo itself.

package/skills/first-tree/references/upgrade-contract.md

@@ -1,8 +1,7 @@
 # Upgrade Contract
 
 This file describes the current installed-layout contract and the compatibility
-rules we keep for legacy `skills/first-tree/`,
-`skills/first-tree-cli-framework/`, and `.context-tree/` repos.
+rules we keep for legacy `skills/first-tree/` and `.context-tree/` repos.
 
 ## Canonical Source
 
@@ -16,7 +15,8 @@ rules we keep for legacy `skills/first-tree/`,
 
 ## Installed Layout
 
-The current installed layout in a user repo is:
+The current installed layout in a source/workspace repo or dedicated tree repo
+is:
 
 ```text
 .agents/
@@ -50,7 +50,11 @@ The current installed layout in a user repo is:
           helpers/
 ```
 
-The tree content still lives outside the skill:
+For a source/workspace repo, the local integration stops there. It should also
+carry a single `FIRST-TREE-SOURCE-INTEGRATION:` line in root `AGENTS.md` and
+`CLAUDE.md`, but it must not contain tree content.
+
+For a dedicated tree repo, the tree content still lives outside the skill:
 
 - `NODE.md`
 - `AGENTS.md`
@@ -66,22 +70,27 @@ skill discovery and hooks.
 - `context-tree init`
   - when run in a source/workspace repo, creates or reuses a sibling dedicated
     tree repo by default
+  - installs the skill into the source/workspace repo without creating tree
+    files there
+  - upserts the `FIRST-TREE-SOURCE-INTEGRATION:` line in root `AGENTS.md` and
+    `CLAUDE.md`
   - installs the skill into the target tree repo
-  - renders top-level tree scaffolding from the skill templates
-  - writes progress state to `.agents/skills/first-tree/progress.md`
+  - renders top-level tree scaffolding only in the target tree repo
+  - writes progress state only to the dedicated tree repo at
+    `.agents/skills/first-tree/progress.md`
 - `context-tree verify`
   - checks progress state from the installed skill
   - validates root/frontmatter/agent markers
   - runs node and member validators
+  - must reject source/workspace repos that carry only local integration
 - `context-tree upgrade`
   - compares the installed skill payload version to the skill bundled with the
     currently running `first-tree` package
   - refreshes the installed skill payload without overwriting tree content
+  - when run in a source/workspace repo, refreshes only the local installed
+    skill plus the `FIRST-TREE-SOURCE-INTEGRATION:` lines
   - migrates repos that still use the previous `skills/first-tree/` path onto
     `.agents/skills/first-tree/` and `.claude/skills/first-tree/`
-  - migrates repos that still use the previous
-    `skills/first-tree-cli-framework/` path onto `.agents/skills/first-tree/`
-    and `.claude/skills/first-tree/`
   - migrates legacy `.context-tree/` repos onto the installed skill layout
   - preserves user-authored sections such as the editable part of `AGENTS.md`
 
@@ -93,12 +102,14 @@ skill discovery and hooks.
 - Default dedicated-tree-repo creation is local-only. The CLI may create a new
   sibling git repo on disk, but it must not clone the source repo or depend on
   network access.
+- Source/workspace repos must never receive `NODE.md`, `members/`, or
+  tree-scoped `AGENTS.md` from default init flows.
 - Normal `context-tree init` and `context-tree upgrade` flows do not clone the
   source repo or require network access.
 - `context-tree verify` may still read a legacy
-  `.claude/skills/first-tree/...`, `skills/first-tree/...`,
-  `skills/first-tree-cli-framework/...`, or `.context-tree/...` layout in an
-  existing user repo so the repo can be repaired or upgraded in place.
+  `.claude/skills/first-tree/...`, `skills/first-tree/...`, or
+  `.context-tree/...` layout in an existing user repo so the repo can be
+  repaired or upgraded in place.
 - `context-tree upgrade` must migrate either legacy layout onto
   `.agents/skills/first-tree/` and `.claude/skills/first-tree/`, and remove
   old skill directories afterward.

package/skills/first-tree/scripts/check-skill-sync.sh

@@ -39,6 +39,7 @@ require_file "$SOURCE_DIR/SKILL.md"
 require_file "$SOURCE_DIR/agents/openai.yaml"
 require_file "$SOURCE_DIR/references/about.md"
 require_file "$SOURCE_DIR/references/onboarding.md"
+require_file "$SOURCE_DIR/references/source-workspace-installation.md"
 require_file "$SOURCE_DIR/references/principles.md"
 require_file "$SOURCE_DIR/references/ownership-and-naming.md"
 require_file "$SOURCE_DIR/references/source-map.md"
@@ -59,6 +60,7 @@ require_file "$SOURCE_DIR/engine/commands/verify.ts"
 require_file "$SOURCE_DIR/engine/rules/index.ts"
 require_file "$SOURCE_DIR/engine/runtime/asset-loader.ts"
 require_file "$SOURCE_DIR/engine/runtime/installer.ts"
+require_file "$SOURCE_DIR/engine/runtime/source-integration.ts"
 require_file "$SOURCE_DIR/engine/runtime/upgrader.ts"
 require_file "$SOURCE_DIR/engine/runtime/adapters.ts"
 require_file "$SOURCE_DIR/engine/validators/members.ts"
@@ -89,7 +91,6 @@ for legacy_path in \
   ".claude" \
   ".context-tree" \
   "docs" \
-  "skills/first-tree-cli-framework" \
   "tests" \
   "skills/first-tree/references/repo-snapshot"
 do

package/skills/first-tree/tests/asset-loader.test.ts

@@ -7,8 +7,6 @@ import {
   INSTALLED_PROGRESS,
   LEGACY_REPO_SKILL_PROGRESS,
   LEGACY_REPO_SKILL_VERSION,
-  LEGACY_SKILL_PROGRESS,
-  LEGACY_SKILL_VERSION,
   LEGACY_PROGRESS,
   LEGACY_VERSION,
   detectFrameworkLayout,
@@ -57,37 +55,15 @@ describe("asset-loader", () => {
     ).toBe(LEGACY_REPO_SKILL_VERSION);
   });
 
-  it("detects the previous installed skill name before the .context-tree layout", () => {
-    const tmp = useTmpDir();
-    mkdirSync(
-      join(tmp.path, "skills", "first-tree-cli-framework", "assets", "framework"),
-      {
-        recursive: true,
-      },
-    );
-    mkdirSync(join(tmp.path, ".context-tree"), { recursive: true });
-    writeFileSync(join(tmp.path, LEGACY_SKILL_VERSION), "0.2.0\n");
-    writeFileSync(join(tmp.path, LEGACY_VERSION), "0.1.0\n");
-
-    expect(detectFrameworkLayout(tmp.path)).toBe("legacy-skill");
-    expect(
-      resolveFirstExistingPath(tmp.path, frameworkVersionCandidates()),
-    ).toBe(LEGACY_SKILL_VERSION);
-  });
-
   it("prefers the installed progress file candidate", () => {
     const tmp = useTmpDir();
     mkdirSync(join(tmp.path, ".agents", "skills", "first-tree"), { recursive: true });
     mkdirSync(join(tmp.path, ".claude", "skills", "first-tree"), { recursive: true });
     mkdirSync(join(tmp.path, "skills", "first-tree"), { recursive: true });
-    mkdirSync(join(tmp.path, "skills", "first-tree-cli-framework"), {
-      recursive: true,
-    });
     mkdirSync(join(tmp.path, ".context-tree"), { recursive: true });
     writeFileSync(join(tmp.path, INSTALLED_PROGRESS), "new");
     writeFileSync(join(tmp.path, CLAUDE_INSTALLED_PROGRESS), "claude");
     writeFileSync(join(tmp.path, LEGACY_REPO_SKILL_PROGRESS), "old-repo-skill");
-    writeFileSync(join(tmp.path, LEGACY_SKILL_PROGRESS), "old-skill");
     writeFileSync(join(tmp.path, LEGACY_PROGRESS), "old");
 
     expect(resolveFirstExistingPath(tmp.path, progressFileCandidates())).toBe(

package/skills/first-tree/tests/helpers.ts

@@ -9,7 +9,6 @@ import {
   FRAMEWORK_VERSION,
   LEGACY_AGENT_INSTRUCTIONS_FILE,
   LEGACY_REPO_SKILL_VERSION,
-  LEGACY_SKILL_VERSION,
   LEGACY_VERSION,
   SKILL_ROOT,
 } from "#skill/engine/runtime/asset-loader.js";
@@ -74,19 +73,6 @@ export function makeLegacyRepoFramework(root: string, version = "0.1.0"): void {
   writeFileSync(join(root, LEGACY_REPO_SKILL_VERSION), `${version}\n`);
 }
 
-export function makeLegacyNamedFramework(
-  root: string,
-  version = "0.1.0",
-): void {
-  mkdirSync(
-    join(root, "skills", "first-tree-cli-framework", "assets", "framework"),
-    {
-      recursive: true,
-    },
-  );
-  writeFileSync(join(root, LEGACY_SKILL_VERSION), `${version}\n`);
-}
-
 export function makeSourceSkill(root: string, version = "0.2.0"): void {
   const skillRoot = join(root, "skills", "first-tree");
   mkdirSync(join(skillRoot, "agents"), { recursive: true });