first-tree 0.0.5 → 0.0.6

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

@@ -20,13 +20,17 @@ import {
   frameworkVersionCandidates,
   progressFileCandidates,
   resolveFirstExistingPath,
+  SOURCE_INTEGRATION_FILES,
+  SOURCE_INTEGRATION_MARKER,
 } from "#skill/engine/runtime/asset-loader.js";
 
 const FRONTMATTER_RE = /^---\s*\n(.*?)\n---/s;
 const OWNERS_RE = /^owners:\s*\[([^\]]*)\]/m;
 const TITLE_RE = /^title:\s*['"]?(.+?)['"]?\s*$/m;
 const EMPTY_REPO_ENTRY_ALLOWLIST = new Set([
+  ".agents",
   ".DS_Store",
+  ".claude",
   ".editorconfig",
   ".gitattributes",
   ".github",
@@ -273,6 +277,23 @@ export class Repo {
     return text.includes(FRAMEWORK_BEGIN_MARKER) && text.includes(FRAMEWORK_END_MARKER);
   }
 
+  hasSourceIntegrationFile(relPath: string): boolean {
+    return this.fileContains(relPath, SOURCE_INTEGRATION_MARKER);
+  }
+
+  hasSourceWorkspaceIntegration(): boolean {
+    return SOURCE_INTEGRATION_FILES.some((file) => this.hasSourceIntegrationFile(file));
+  }
+
+  hasTreeContent(): boolean {
+    return (
+      this.progressPath() !== null
+      || this.hasAgentInstructionsMarkers()
+      || this.pathExists("members/NODE.md")
+      || this.frontmatter("NODE.md") !== null
+    );
+  }
+
   hasMembers(): boolean {
     const membersDir = join(this.root, "members");
     try {
@@ -338,13 +359,19 @@ export class Repo {
       return false;
     }
 
-    return (
-      this.progressPath() !== null
-      || this.hasFramework()
-      || this.hasAgentInstructionsMarkers()
-      || this.pathExists("members/NODE.md")
-      || this.frontmatter("NODE.md") !== null
-    );
+    if (this.hasTreeContent()) {
+      return true;
+    }
+
+    if (this.hasFramework() && this.hasSourceWorkspaceIntegration()) {
+      return false;
+    }
+
+    if (this.hasFramework()) {
+      return !this.hasLikelySourceRepoSignals();
+    }
+
+    return false;
   }
 
   isLikelyEmptyRepo(): boolean {
@@ -359,6 +386,10 @@ export class Repo {
       return false;
     }
 
+    return this.hasLikelySourceRepoSignals();
+  }
+
+  private hasLikelySourceRepoSignals(): boolean {
     const entries = this.topLevelEntries().filter(
       (entry) => !EMPTY_REPO_ENTRY_ALLOWLIST.has(entry),
     );

package/skills/first-tree/engine/runtime/asset-loader.ts

@@ -21,6 +21,12 @@ export const INSTALLED_PROGRESS = join(SKILL_ROOT, "progress.md");
 export const AGENT_INSTRUCTIONS_FILE = "AGENTS.md";
 export const LEGACY_AGENT_INSTRUCTIONS_FILE = "AGENT.md";
 export const AGENT_INSTRUCTIONS_TEMPLATE = "agents.md.template";
+export const CLAUDE_INSTRUCTIONS_FILE = "CLAUDE.md";
+export const SOURCE_INTEGRATION_MARKER = "FIRST-TREE-SOURCE-INTEGRATION:";
+export const SOURCE_INTEGRATION_FILES = [
+  AGENT_INSTRUCTIONS_FILE,
+  CLAUDE_INSTRUCTIONS_FILE,
+] as const;
 
 export const CLAUDE_SKILL_AGENTS_DIR = join(CLAUDE_SKILL_ROOT, "agents");
 export const CLAUDE_SKILL_REFERENCES_DIR = join(CLAUDE_SKILL_ROOT, "references");

package/skills/first-tree/engine/runtime/source-integration.ts

@@ -0,0 +1,80 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  SOURCE_INTEGRATION_FILES,
+  SOURCE_INTEGRATION_MARKER,
+} from "#skill/engine/runtime/asset-loader.js";
+
+export type SourceIntegrationFile = (typeof SOURCE_INTEGRATION_FILES)[number];
+
+export interface SourceIntegrationUpdate {
+  action: "created" | "updated" | "unchanged";
+  file: SourceIntegrationFile;
+}
+
+export function buildSourceIntegrationLine(treeRepoName: string): string {
+  return (
+    `${SOURCE_INTEGRATION_MARKER} Use the installed \`first-tree\` skill here;`
+    + ` keep all Context Tree files only in the sibling dedicated`
+    + ` \`${treeRepoName}\` repo/submodule and update that tree when decisions`
+    + " or constraints change."
+  );
+}
+
+export function hasSourceIntegrationMarker(text: string | null): boolean {
+  if (text === null) {
+    return false;
+  }
+  return text
+    .replaceAll("\r\n", "\n")
+    .split("\n")
+    .some((line) => line.startsWith(SOURCE_INTEGRATION_MARKER));
+}
+
+export function upsertSourceIntegrationFiles(
+  root: string,
+  treeRepoName: string,
+): SourceIntegrationUpdate[] {
+  return SOURCE_INTEGRATION_FILES.map((file) =>
+    upsertSourceIntegrationFile(root, file, treeRepoName),
+  );
+}
+
+function upsertSourceIntegrationFile(
+  root: string,
+  file: SourceIntegrationFile,
+  treeRepoName: string,
+): SourceIntegrationUpdate {
+  const fullPath = join(root, file);
+  const exists = existsSync(fullPath);
+  const nextLine = buildSourceIntegrationLine(treeRepoName);
+  const current = exists ? readFileSync(fullPath, "utf-8") : null;
+  const normalized = current?.replaceAll("\r\n", "\n") ?? "";
+  const lines = normalized === "" ? [] : normalized.split("\n");
+  const markerIndex = lines.findIndex((line) =>
+    line.startsWith(SOURCE_INTEGRATION_MARKER),
+  );
+
+  if (markerIndex >= 0) {
+    if (lines[markerIndex] === nextLine) {
+      return { action: "unchanged", file };
+    }
+    lines[markerIndex] = nextLine;
+  } else {
+    if (lines.length > 0 && lines.at(-1) !== "") {
+      lines.push("");
+    }
+    lines.push(nextLine);
+  }
+
+  let nextText = lines.join("\n");
+  if (nextText !== "" && !nextText.endsWith("\n")) {
+    nextText += "\n";
+  }
+  writeFileSync(fullPath, nextText);
+
+  return {
+    action: exists ? "updated" : "created",
+    file,
+  };
+}

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

@@ -4,6 +4,7 @@ import { Repo } from "#skill/engine/repo.js";
 import {
   AGENT_INSTRUCTIONS_FILE,
   AGENT_INSTRUCTIONS_TEMPLATE,
+  CLAUDE_INSTRUCTIONS_FILE,
   CLAUDE_SKILL_ROOT,
   FRAMEWORK_WORKFLOWS_DIR,
   FRAMEWORK_TEMPLATES_DIR,
@@ -14,6 +15,7 @@ import {
   LEGACY_REPO_SKILL_ROOT,
   LEGACY_SKILL_ROOT,
   SKILL_ROOT,
+  SOURCE_INTEGRATION_MARKER,
   installedSkillRootsDisplay,
   type FrameworkLayout,
 } from "#skill/engine/runtime/asset-loader.js";
@@ -21,6 +23,7 @@ import {
   copyCanonicalSkill,
   resolveBundledPackageRoot,
 } from "#skill/engine/runtime/installer.js";
+import { upsertSourceIntegrationFiles } from "#skill/engine/runtime/source-integration.js";
 import {
   compareFrameworkVersions,
   readSourceVersion,
@@ -121,8 +124,10 @@ export interface UpgradeOptions {
 
 export function runUpgrade(repo?: Repo, options?: UpgradeOptions): number {
   const workingRepo = repo ?? new Repo();
+  const workspaceOnlyIntegration =
+    workingRepo.hasSourceWorkspaceIntegration() && !workingRepo.looksLikeTreeRepo();
 
-  if (workingRepo.isLikelySourceRepo() && !workingRepo.looksLikeTreeRepo()) {
+  if (workingRepo.isLikelySourceRepo() && !workingRepo.looksLikeTreeRepo() && !workspaceOnlyIntegration) {
     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 upgrade an existing tree repo.",
     );
@@ -178,6 +183,68 @@ export function runUpgrade(repo?: Repo, options?: UpgradeOptions): number {
   }
 
   const missingInstalledRoots = workingRepo.missingInstalledSkillRoots();
+  const sourceRepoTreePathHint = `../${workingRepo.repoName()}-context`;
+
+  if (workspaceOnlyIntegration) {
+    if (
+      layout === "skill" &&
+      missingInstalledRoots.length === 0 &&
+      packagedVersion === localVersion
+    ) {
+      const updates = upsertSourceIntegrationFiles(
+        workingRepo.root,
+        `${workingRepo.repoName()}-context`,
+      );
+      const changedFiles = updates
+        .filter((update) => update.action !== "unchanged")
+        .map((update) => update.file);
+      if (changedFiles.length === 0) {
+        console.log(
+          `Already up to date with the bundled skill (${FRAMEWORK_VERSION} = ${localVersion}).`,
+        );
+        console.log(
+          `This repo only carries source/workspace integration. Upgrade the dedicated tree repo separately with \`context-tree upgrade --tree-path ${sourceRepoTreePathHint}\`.`,
+        );
+        return 0;
+      }
+      console.log(
+        `Already up to date with the bundled skill (${FRAMEWORK_VERSION} = ${localVersion}).`,
+      );
+      console.log(
+        `Updated the ${SOURCE_INTEGRATION_MARKER} marker lines in ${changedFiles.map((file) => `\`${file}\``).join(" and ")}.`,
+      );
+      console.log(
+        `This repo only carries source/workspace integration. Upgrade the dedicated tree repo separately with \`context-tree upgrade --tree-path ${sourceRepoTreePathHint}\`.`,
+      );
+      return 0;
+    }
+
+    copyCanonicalSkill(sourceRoot, workingRepo.root);
+    const updates = upsertSourceIntegrationFiles(
+      workingRepo.root,
+      `${workingRepo.repoName()}-context`,
+    );
+    const changedFiles = updates
+      .filter((update) => update.action !== "unchanged")
+      .map((update) => update.file);
+    console.log(
+      `Refreshed ${installedSkillRootsDisplay()} in this source/workspace repo.`,
+    );
+    if (changedFiles.length > 0) {
+      console.log(
+        `Updated the ${SOURCE_INTEGRATION_MARKER} marker lines in ${changedFiles.map((file) => `\`${file}\``).join(" and ")}.`,
+      );
+    } else {
+      console.log(
+        `The ${SOURCE_INTEGRATION_MARKER} marker lines in ${AGENT_INSTRUCTIONS_FILE} and ${CLAUDE_INSTRUCTIONS_FILE} were already current.`,
+      );
+    }
+    console.log(
+      `This repo is not the Context Tree. Upgrade the dedicated tree repo separately with \`context-tree upgrade --tree-path ${sourceRepoTreePathHint}\`.`,
+    );
+    return 0;
+  }
+
   if (
     layout === "skill" &&
     missingInstalledRoots.length === 0 &&

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
@@ -90,6 +92,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 +138,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 +177,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` 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. |
@@ -178,6 +197,11 @@ context-tree upgrade
 `first-tree` npm package, preserves your tree content, and generates follow-up
 tasks in `.agents/skills/first-tree/progress.md`.
 
+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/`,
 `skills/first-tree-cli-framework/`, or `.context-tree/` layouts,
 `context-tree upgrade` will migrate it to the current installed layout first.
@@ -191,5 +215,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 |