first-tree 0.0.3 → 0.0.5

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

@@ -1,14 +1,20 @@
 import { mkdirSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { Repo } from "#skill/engine/repo.js";
 import {
+  AGENT_INSTRUCTIONS_FILE,
+  AGENT_INSTRUCTIONS_TEMPLATE,
+  CLAUDE_SKILL_ROOT,
   FRAMEWORK_WORKFLOWS_DIR,
   FRAMEWORK_TEMPLATES_DIR,
   FRAMEWORK_VERSION,
   INSTALLED_PROGRESS,
+  LEGACY_AGENT_INSTRUCTIONS_FILE,
   LEGACY_FRAMEWORK_ROOT,
+  LEGACY_REPO_SKILL_ROOT,
   LEGACY_SKILL_ROOT,
   SKILL_ROOT,
+  installedSkillRootsDisplay,
   type FrameworkLayout,
 } from "#skill/engine/runtime/asset-loader.js";
 import {
@@ -20,6 +26,13 @@ import {
   readSourceVersion,
 } from "#skill/engine/runtime/upgrader.js";
 
+export const UPGRADE_USAGE = `usage: context-tree upgrade [--tree-path PATH]
+
+Options:
+  --tree-path PATH   Upgrade a tree repo from another working directory
+  --help             Show this help message
+`;
+
 function writeProgress(repo: Repo, content: string): void {
   const progressPath = join(repo.root, repo.preferredProgressPath());
   mkdirSync(dirname(progressPath), { recursive: true });
@@ -35,32 +48,52 @@ function formatUpgradeTaskList(
   const lines: string[] = [
     `# Context Tree Upgrade — v${localVersion} -> v${packagedVersion}\n`,
     "## Installed Skill",
-    `- [ ] Review local customizations under \`${SKILL_ROOT}/\` and reapply them if needed`,
+    `- [ ] Review local customizations under ${installedSkillRootsDisplay()} and reapply them if needed`,
     `- [ ] Re-copy any workflow updates you want from \`${FRAMEWORK_WORKFLOWS_DIR}/\` into \`.github/workflows/\``,
-    `- [ ] Re-check any local agent setup that references \`${SKILL_ROOT}/assets/framework/examples/\` or \`${SKILL_ROOT}/assets/framework/helpers/\``,
+    `- [ ] Re-check any local agent setup that references \`${CLAUDE_SKILL_ROOT}/assets/framework/examples/\` or \`${CLAUDE_SKILL_ROOT}/assets/framework/helpers/\``,
+    `- [ ] Re-check any repo scripts or workflow files that reference \`${SKILL_ROOT}/assets/framework/\``,
     "",
   ];
 
+  const migrationTasks: string[] = [];
   if (layout === "legacy") {
+    migrationTasks.push(
+      "- [ ] Remove any stale `.context-tree/` references from repo-specific docs, scripts, or workflow files",
+    );
+  }
+
+  if (layout === "legacy-repo-skill") {
     lines.push(
       "## Migration",
-      "- [ ] Remove any stale `.context-tree/` references from repo-specific docs, scripts, or workflow files",
+      `- [ ] Remove any stale \`${LEGACY_REPO_SKILL_ROOT}/\` references from repo-specific docs, scripts, workflow files, or agent config`,
       "",
     );
   }
 
   if (layout === "legacy-skill") {
-    lines.push(
-      "## Migration",
+    migrationTasks.push(
       `- [ ] Remove any stale \`${LEGACY_SKILL_ROOT}/\` references from repo-specific docs, scripts, workflow files, or agent config`,
-      "",
     );
   }
 
-  if (repo.hasAgentMdMarkers()) {
+  if (repo.hasCanonicalAgentInstructionsFile() && repo.hasLegacyAgentInstructionsFile()) {
+    migrationTasks.push(
+      `- [ ] Merge any remaining user-authored content from \`${LEGACY_AGENT_INSTRUCTIONS_FILE}\` into \`${AGENT_INSTRUCTIONS_FILE}\`, then delete the legacy file`,
+    );
+  } else if (repo.hasLegacyAgentInstructionsFile()) {
+    migrationTasks.push(
+      `- [ ] Rename \`${LEGACY_AGENT_INSTRUCTIONS_FILE}\` to \`${AGENT_INSTRUCTIONS_FILE}\` to use the canonical agent instructions filename`,
+    );
+  }
+
+  if (migrationTasks.length > 0) {
+    lines.push("## Migration", ...migrationTasks, "");
+  }
+
+  if (repo.hasAgentInstructionsMarkers()) {
     lines.push(
       "## Agent Instructions",
-      `- [ ] Compare the framework section in \`AGENT.md\` with \`${FRAMEWORK_TEMPLATES_DIR}/agent.md.template\` and update the content between the markers if needed`,
+      `- [ ] Compare the framework section in \`${AGENT_INSTRUCTIONS_FILE}\` with \`${FRAMEWORK_TEMPLATES_DIR}/${AGENT_INSTRUCTIONS_TEMPLATE}\` and update the content between the markers if needed`,
       "",
     );
   }
@@ -89,6 +122,13 @@ export interface UpgradeOptions {
 export function runUpgrade(repo?: Repo, options?: UpgradeOptions): number {
   const workingRepo = repo ?? new Repo();
 
+  if (workingRepo.isLikelySourceRepo() && !workingRepo.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 upgrade an existing tree repo.",
+    );
+    return 1;
+  }
+
   if (!workingRepo.hasFramework()) {
     console.error(
       "Error: no installed framework skill found. Run `context-tree init` first.",
@@ -137,7 +177,12 @@ export function runUpgrade(repo?: Repo, options?: UpgradeOptions): number {
     return 1;
   }
 
-  if (layout === "skill" && packagedVersion === localVersion) {
+  const missingInstalledRoots = workingRepo.missingInstalledSkillRoots();
+  if (
+    layout === "skill" &&
+    missingInstalledRoots.length === 0 &&
+    packagedVersion === localVersion
+  ) {
     console.log(
       `Already up to date with the bundled skill (${FRAMEWORK_VERSION} = ${localVersion}).`,
     );
@@ -151,16 +196,26 @@ export function runUpgrade(repo?: Repo, options?: UpgradeOptions): number {
       force: true,
     });
     console.log(
-      "Migrated legacy .context-tree/ layout to skills/first-tree/.",
+      `Migrated legacy .context-tree/ layout to ${installedSkillRootsDisplay()}.`,
     );
-  } else if (layout === "legacy-skill") {
+  } else if (layout === "legacy-repo-skill") {
     console.log(
-      "Migrated skills/first-tree-cli-framework/ to skills/first-tree/.",
+      `Migrated legacy ${LEGACY_REPO_SKILL_ROOT}/ layout to ${installedSkillRootsDisplay()}.`,
     );
-  } else {
+  } else if (layout === "legacy-skill") {
     console.log(
-      "Refreshed skills/first-tree/ from the bundled first-tree package.",
+      `Migrated ${LEGACY_SKILL_ROOT}/ to ${installedSkillRootsDisplay()}.`,
     );
+  } else {
+    if (missingInstalledRoots.length > 0) {
+      console.log(
+        `Repaired missing installed skill roots (${missingInstalledRoots.map((root) => `${root}/`).join(", ")}) and refreshed ${installedSkillRootsDisplay()} from the bundled first-tree package.`,
+      );
+    } else {
+      console.log(
+        `Refreshed ${installedSkillRootsDisplay()} from the bundled first-tree package.`,
+      );
+    }
   }
 
   const output = formatUpgradeTaskList(
@@ -174,3 +229,32 @@ export function runUpgrade(repo?: Repo, options?: UpgradeOptions): number {
   console.log(`Progress file written to ${workingRepo.preferredProgressPath()}`);
   return 0;
 }
+
+export function runUpgradeCli(args: string[] = []): number {
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(UPGRADE_USAGE);
+    return 0;
+  }
+
+  let treePath: string | undefined;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--tree-path") {
+      const value = args[index + 1];
+      if (!value) {
+        console.error("Missing value for --tree-path");
+        console.log(UPGRADE_USAGE);
+        return 1;
+      }
+      treePath = value;
+      index += 1;
+      continue;
+    }
+
+    console.error(`Unknown upgrade option: ${arg}`);
+    console.log(UPGRADE_USAGE);
+    return 1;
+  }
+
+  return runUpgrade(treePath ? new Repo(resolve(process.cwd(), treePath)) : undefined);
+}

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

@@ -1,5 +1,13 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 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";
 
 const FRONTMATTER_RE = /^---\s*\n(.*?)\n---/s;
 const OWNERS_RE = /^owners:\s*\[([^\]]*)\]/m;
@@ -11,7 +19,11 @@ const MD_LINK_RE = /\[.*?\]\(([^)]+\.md)\)/g;
 const DOMAIN_LINK_RE = /\[(\w[\w-]*)\/?\]\((\w[\w-]*)\/NODE\.md\)/g;
 
 const SKIP = new Set(["node_modules", "__pycache__"]);
-const SKIP_FILES = new Set(["AGENT.md", "CLAUDE.md"]);
+const SKIP_FILES = new Set([
+  AGENT_INSTRUCTIONS_FILE,
+  LEGACY_AGENT_INSTRUCTIONS_FILE,
+  "CLAUDE.md",
+]);
 const MIN_BODY_LENGTH = 20;
 
 export class Findings {
@@ -75,9 +87,42 @@ function rel(path: string): string {
   return relative(treeRoot, path);
 }
 
+function isInstalledSkillPath(relPath: string): boolean {
+  return (
+    relPath === SKILL_ROOT ||
+    relPath.startsWith(`${SKILL_ROOT}/`) ||
+    relPath === LEGACY_SKILL_ROOT ||
+    relPath.startsWith(`${LEGACY_SKILL_ROOT}/`)
+  );
+}
+
+function isFrameworkContainerDir(relPath: string, fullPath: string): boolean {
+  if (relPath !== "skills") {
+    return false;
+  }
+
+  try {
+    const entries = readdirSync(fullPath).filter((entry) => !entry.startsWith("."));
+    if (entries.length === 0) {
+      return false;
+    }
+    return entries.every(
+      (entry) => entry === SKILL_NAME || entry === LEGACY_SKILL_NAME,
+    );
+  } catch {
+    return false;
+  }
+}
+
 function shouldSkip(path: string): boolean {
-  const parts = relative(treeRoot, path).split("/");
-  return parts.some((part) => SKIP.has(part) || part.startsWith("."));
+  const relPath = relative(treeRoot, path);
+  const parts = relPath.split("/");
+
+  if (parts.some((part) => SKIP.has(part) || part.startsWith("."))) {
+    return true;
+  }
+
+  return isInstalledSkillPath(relPath) || isFrameworkContainerDir(relPath, path);
 }
 
 function readText(path: string): string | null {

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

@@ -1,8 +1,19 @@
+import { resolve } from "node:path";
 import { Repo } from "#skill/engine/repo.js";
+import {
+  AGENT_INSTRUCTIONS_FILE,
+  LEGACY_AGENT_INSTRUCTIONS_FILE,
+} from "#skill/engine/runtime/asset-loader.js";
 import { runValidateMembers } from "#skill/engine/validators/members.js";
 import { runValidateNodes } from "#skill/engine/validators/nodes.js";
 
 const UNCHECKED_RE = /^- \[ \] (.+)$/gm;
+export const VERIFY_USAGE = `usage: context-tree verify [--tree-path PATH]
+
+Options:
+  --tree-path PATH   Verify a tree repo from another working directory
+  --help             Show this help message
+`;
 
 export function check(label: string, passed: boolean): boolean {
   const icon = passed ? "\u2713" : "\u2717";
@@ -38,6 +49,14 @@ function defaultNodeValidator(root: string): ValidateNodesResult {
 export function runVerify(repo?: Repo, nodeValidator?: NodeValidator): number {
   const r = repo ?? new Repo();
   const validate = nodeValidator ?? defaultNodeValidator;
+
+  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.",
+    );
+    return 1;
+  }
+
   let allPassed = true;
   const progressPath = r.progressPath() ?? r.preferredProgressPath();
   const frameworkVersionPath = r.frameworkVersionPath();
@@ -73,10 +92,20 @@ export function runVerify(repo?: Repo, nodeValidator?: NodeValidator): number {
     hasValidNode,
   ) && allPassed;
 
-  // 3. AGENT.md exists with framework markers
+  // 3. AGENTS.md is canonical and contains framework markers
+  const hasCanonicalAgentInstructions = r.hasCanonicalAgentInstructionsFile();
+  const hasLegacyAgentInstructions = r.hasLegacyAgentInstructionsFile();
+  if (hasLegacyAgentInstructions) {
+    const followUp = hasCanonicalAgentInstructions
+      ? `Remove legacy \`${LEGACY_AGENT_INSTRUCTIONS_FILE}\` after confirming its contents are in \`${AGENT_INSTRUCTIONS_FILE}\`.`
+      : `Rename \`${LEGACY_AGENT_INSTRUCTIONS_FILE}\` to \`${AGENT_INSTRUCTIONS_FILE}\`.`;
+    console.log(`  Legacy agent instructions detected. ${followUp}\n`);
+  }
   allPassed = check(
-    "AGENT.md exists with framework markers",
-    r.hasAgentMdMarkers(),
+    `${AGENT_INSTRUCTIONS_FILE} is the only agent instructions file and has framework markers`,
+    hasCanonicalAgentInstructions &&
+      !hasLegacyAgentInstructions &&
+      r.hasAgentInstructionsMarkers(),
   ) && allPassed;
 
   // 4. Node validation
@@ -95,3 +124,32 @@ export function runVerify(repo?: Repo, nodeValidator?: NodeValidator): number {
   }
   return allPassed ? 0 : 1;
 }
+
+export function runVerifyCli(args: string[] = []): number {
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(VERIFY_USAGE);
+    return 0;
+  }
+
+  let treePath: string | undefined;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--tree-path") {
+      const value = args[index + 1];
+      if (!value) {
+        console.error("Missing value for --tree-path");
+        console.log(VERIFY_USAGE);
+        return 1;
+      }
+      treePath = value;
+      index += 1;
+      continue;
+    }
+
+    console.error(`Unknown verify option: ${arg}`);
+    console.log(VERIFY_USAGE);
+    return 1;
+  }
+
+  return runVerify(treePath ? new Repo(resolve(process.cwd(), treePath)) : undefined);
+}

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

@@ -33,7 +33,7 @@ that install the framework.
 - 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`,
-  `AGENT.md`, CI comments, or PR descriptions.
+  `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.

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

@@ -50,6 +50,9 @@ another skill reference, not only in the files themselves.
   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

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

@@ -26,7 +26,7 @@ These root files are shell code, not canonical knowledge stores:
 - `vitest.config.ts`
 - `vitest.eval.config.ts` (repo-only maintainer eval entrypoint)
 - `.github/workflows/ci.yml`
-- root `README.md` and `AGENT.md`
+- root `README.md` and `AGENTS.md`
 
 ## Rules For Shell Changes
 

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

@@ -53,35 +53,59 @@ Information an agent needs to **decide** on an approach — not to execute it.
 
 ### Prerequisites
 
-- A Git repository for your tree (separate from your code repos)
+- 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/`
+  `context-tree`.
+- `context-tree init` installs the framework skill into
+  `.agents/skills/first-tree/` and `.claude/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
-mkdir my-org-tree && cd my-org-tree
-git init
+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
 ```
 
-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`.
+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
+`.agents/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:
+Read `.agents/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
+- 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/`
+- Optionally configure agent integration (for Claude Code, the installed hook
+  assets live under `.claude/skills/first-tree/`)
+- Copy validation workflows from
+  `.agents/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]`.
+As you complete each task, check it off in
+`.agents/skills/first-tree/progress.md` by changing `- [ ]` to `- [x]`.
 
 ### Step 3: Verify
 
@@ -89,7 +113,15 @@ As you complete each task, check it off in `skills/first-tree/progress.md` by ch
 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).
+Or, from your source/workspace repo:
+
+```bash
+context-tree verify --tree-path ../my-org-context
+```
+
+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).
 
 ### Step 4: Design Your Domains
 
@@ -126,9 +158,9 @@ The tree doesn't duplicate source code — it captures what connects things and
 
 | 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 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. |
 
 ---
@@ -141,13 +173,14 @@ When the framework updates:
 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`.
+`context-tree upgrade` refreshes `.agents/skills/first-tree/` and
+`.claude/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 `.agents/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.
+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.
 
 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`
@@ -157,6 +190,6 @@ 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
+- `.agents/skills/first-tree/references/principles.md` — Core principles with detailed examples
+- `.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/source-map.md

@@ -43,7 +43,7 @@ These skill-owned files implement the framework behavior.
 | `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/repo.ts` | Repo inspection, source-vs-tree heuristics, and worktree-aware git-root 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 |
@@ -66,7 +66,7 @@ not become the only place important maintainer knowledge lives.
 | `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 |
+| `AGENTS.md` | Thin maintainer pointer for agent sessions |
 
 ## Validation
 
@@ -89,6 +89,6 @@ not become the only place important maintainer knowledge lives.
 - 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
+- Root `README.md` and `AGENTS.md` are intentionally brief. Important
   information must live in the skill references instead.
 - If you change `references/` or `assets/framework/`, run `pnpm validate:skill`.

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

@@ -1,8 +1,8 @@
 # Upgrade Contract
 
 This file describes the current installed-layout contract and the compatibility
-rules we keep for legacy `skills/first-tree-cli-framework/` and
-`.context-tree/` repos.
+rules we keep for legacy `skills/first-tree/`,
+`skills/first-tree-cli-framework/`, and `.context-tree/` repos.
 
 ## Canonical Source
 
@@ -19,34 +19,56 @@ rules we keep for legacy `skills/first-tree-cli-framework/` and
 The current installed layout in a user repo is:
 
 ```text
-skills/
-  first-tree/
-    SKILL.md
-    progress.md
-    references/
-    assets/
-      framework/
-        manifest.json
-        VERSION
-        templates/
-        workflows/
-        prompts/
-        examples/
-        helpers/
+.agents/
+  skills/
+    first-tree/
+      SKILL.md
+      progress.md
+      references/
+      assets/
+        framework/
+          manifest.json
+          VERSION
+          templates/
+          workflows/
+          prompts/
+          examples/
+          helpers/
+.claude/
+  skills/
+    first-tree/
+      SKILL.md
+      references/
+      assets/
+        framework/
+          manifest.json
+          VERSION
+          templates/
+          workflows/
+          prompts/
+          examples/
+          helpers/
 ```
 
 The tree content still lives outside the skill:
 
 - `NODE.md`
-- `AGENT.md`
+- `AGENTS.md`
 - `members/`
 
+The repo-owned `.agents/skills/first-tree/` path is the primary installed root
+for progress state, workflow references, and helper scripts. The matching
+`.claude/skills/first-tree/` path mirrors the same payload for Claude-facing
+skill discovery and hooks.
+
 ## Command Intent
 
 - `context-tree init`
-  - installs the skill into the target repo
+  - when run in a source/workspace repo, creates or reuses a sibling dedicated
+    tree repo by default
+  - installs the skill into the target tree repo
   - renders top-level tree scaffolding from the skill templates
-  - writes progress state to `skills/first-tree/progress.md`
+  - writes progress state to `.agents/skills/first-tree/progress.md`
 - `context-tree verify`
   - checks progress state from the installed skill
   - validates root/frontmatter/agent markers
@@ -55,23 +77,36 @@ The tree content still lives outside the skill:
   - 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
+  - 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 `skills/first-tree/`
+    `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 `AGENT.md`
+  - preserves user-authored sections such as the editable part of `AGENTS.md`
 
 ## Compatibility Rules For Legacy Trees
 
-- `context-tree init` only installs the skill layout; it never creates a new
-  `.context-tree/`.
+- `context-tree init` never creates a new `.context-tree/`.
+- `context-tree init --here` preserves the explicit in-place bootstrap path for
+  already-created tree repos.
+- 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.
 - 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
-  `skills/first-tree-cli-framework/...` or `.context-tree/...` layout in an
-  existing user repo so the repo can be upgraded in place.
+  `.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.
 - `context-tree upgrade` must migrate either legacy layout onto
-  `skills/first-tree/` and remove the old directory afterward.
-- When both layouts are present, prefer the installed skill layout.
+  `.agents/skills/first-tree/` and `.claude/skills/first-tree/`, and remove
+  old skill directories afterward.
+- When both current and legacy layouts are present, prefer the
+  `.agents/skills/first-tree/` layout.
+- Existing repos may still have a legacy `AGENT.md`; `init` and `upgrade`
+  must not silently overwrite it, and follow-up tasks should direct users to
+  rename or merge it into `AGENTS.md`.
 
 ## Invariants