first-tree 0.0.6 → 0.0.8

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

@@ -10,8 +10,6 @@ import {
   LEGACY_PROGRESS,
   LEGACY_REPO_SKILL_PROGRESS,
   LEGACY_REPO_SKILL_VERSION,
-  LEGACY_SKILL_PROGRESS,
-  LEGACY_SKILL_VERSION,
   LEGACY_VERSION,
   agentInstructionsFileCandidates,
   installedSkillRoots,
@@ -220,9 +218,6 @@ export class Repo {
     if (layout === "legacy") {
       return LEGACY_PROGRESS;
     }
-    if (layout === "legacy-skill") {
-      return LEGACY_SKILL_PROGRESS;
-    }
     if (layout === "legacy-repo-skill") {
       return LEGACY_REPO_SKILL_PROGRESS;
     }
@@ -237,9 +232,6 @@ export class Repo {
     if (layout === "legacy") {
       return LEGACY_VERSION;
     }
-    if (layout === "legacy-skill") {
-      return LEGACY_SKILL_VERSION;
-    }
     if (layout === "legacy-repo-skill") {
       return LEGACY_REPO_SKILL_VERSION;
     }

package/skills/first-tree/engine/runtime/adapters.ts

@@ -4,7 +4,6 @@ import {
   CLAUDE_FRAMEWORK_HELPERS_DIR,
   FRAMEWORK_EXAMPLES_DIR,
   LEGACY_REPO_SKILL_EXAMPLES_DIR,
-  LEGACY_SKILL_EXAMPLES_DIR,
   LEGACY_EXAMPLES_DIR,
 } from "#skill/engine/runtime/asset-loader.js";
 
@@ -16,7 +15,6 @@ export function claudeCodeExampleCandidates(): string[] {
     join(CLAUDE_FRAMEWORK_EXAMPLES_DIR, "claude-code"),
     join(FRAMEWORK_EXAMPLES_DIR, "claude-code"),
     join(LEGACY_REPO_SKILL_EXAMPLES_DIR, "claude-code"),
-    join(LEGACY_SKILL_EXAMPLES_DIR, "claude-code"),
     join(LEGACY_EXAMPLES_DIR, "claude-code"),
   ];
 }

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

@@ -18,6 +18,7 @@ export const FRAMEWORK_PROMPTS_DIR = join(FRAMEWORK_ASSET_ROOT, "prompts");
 export const FRAMEWORK_EXAMPLES_DIR = join(FRAMEWORK_ASSET_ROOT, "examples");
 export const FRAMEWORK_HELPERS_DIR = join(FRAMEWORK_ASSET_ROOT, "helpers");
 export const INSTALLED_PROGRESS = join(SKILL_ROOT, "progress.md");
+export const BOOTSTRAP_STATE = join(SKILL_ROOT, "bootstrap.json");
 export const AGENT_INSTRUCTIONS_FILE = "AGENTS.md";
 export const LEGACY_AGENT_INSTRUCTIONS_FILE = "AGENT.md";
 export const AGENT_INSTRUCTIONS_TEMPLATE = "agents.md.template";
@@ -115,32 +116,6 @@ export const LEGACY_REPO_SKILL_PROGRESS = join(
   "progress.md",
 );
 
-export const LEGACY_SKILL_NAME = "first-tree-cli-framework";
-export const LEGACY_SKILL_ROOT = join("skills", LEGACY_SKILL_NAME);
-export const LEGACY_SKILL_ASSET_ROOT = join(
-  LEGACY_SKILL_ROOT,
-  "assets",
-  "framework",
-);
-export const LEGACY_SKILL_VERSION = join(LEGACY_SKILL_ASSET_ROOT, "VERSION");
-export const LEGACY_SKILL_TEMPLATES_DIR = join(
-  LEGACY_SKILL_ASSET_ROOT,
-  "templates",
-);
-export const LEGACY_SKILL_WORKFLOWS_DIR = join(
-  LEGACY_SKILL_ASSET_ROOT,
-  "workflows",
-);
-export const LEGACY_SKILL_PROMPTS_DIR = join(
-  LEGACY_SKILL_ASSET_ROOT,
-  "prompts",
-);
-export const LEGACY_SKILL_EXAMPLES_DIR = join(
-  LEGACY_SKILL_ASSET_ROOT,
-  "examples",
-);
-export const LEGACY_SKILL_PROGRESS = join(LEGACY_SKILL_ROOT, "progress.md");
-
 export const LEGACY_FRAMEWORK_ROOT = ".context-tree";
 export const LEGACY_VERSION = join(LEGACY_FRAMEWORK_ROOT, "VERSION");
 export const LEGACY_PROGRESS = join(LEGACY_FRAMEWORK_ROOT, "progress.md");
@@ -153,7 +128,6 @@ export type FrameworkLayout =
   | "skill"
   | "claude-skill"
   | "legacy-repo-skill"
-  | "legacy-skill"
   | "legacy";
 
 function pathExists(root: string, relPath: string): boolean {
@@ -180,7 +154,6 @@ export function frameworkVersionCandidates(): string[] {
     FRAMEWORK_VERSION,
     CLAUDE_FRAMEWORK_VERSION,
     LEGACY_REPO_SKILL_VERSION,
-    LEGACY_SKILL_VERSION,
     LEGACY_VERSION,
   ];
 }
@@ -190,7 +163,6 @@ export function progressFileCandidates(): string[] {
     INSTALLED_PROGRESS,
     CLAUDE_INSTALLED_PROGRESS,
     LEGACY_REPO_SKILL_PROGRESS,
-    LEGACY_SKILL_PROGRESS,
     LEGACY_PROGRESS,
   ];
 }
@@ -204,7 +176,6 @@ export function frameworkTemplateDirCandidates(): string[] {
     FRAMEWORK_TEMPLATES_DIR,
     CLAUDE_FRAMEWORK_TEMPLATES_DIR,
     LEGACY_REPO_SKILL_TEMPLATES_DIR,
-    LEGACY_SKILL_TEMPLATES_DIR,
     LEGACY_TEMPLATES_DIR,
   ];
 }
@@ -214,7 +185,6 @@ export function frameworkWorkflowDirCandidates(): string[] {
     FRAMEWORK_WORKFLOWS_DIR,
     CLAUDE_FRAMEWORK_WORKFLOWS_DIR,
     LEGACY_REPO_SKILL_WORKFLOWS_DIR,
-    LEGACY_SKILL_WORKFLOWS_DIR,
     LEGACY_WORKFLOWS_DIR,
   ];
 }
@@ -224,7 +194,6 @@ export function frameworkPromptDirCandidates(): string[] {
     FRAMEWORK_PROMPTS_DIR,
     CLAUDE_FRAMEWORK_PROMPTS_DIR,
     LEGACY_REPO_SKILL_PROMPTS_DIR,
-    LEGACY_SKILL_PROMPTS_DIR,
     LEGACY_PROMPTS_DIR,
   ];
 }
@@ -234,7 +203,6 @@ export function frameworkExampleDirCandidates(): string[] {
     FRAMEWORK_EXAMPLES_DIR,
     CLAUDE_FRAMEWORK_EXAMPLES_DIR,
     LEGACY_REPO_SKILL_EXAMPLES_DIR,
-    LEGACY_SKILL_EXAMPLES_DIR,
     LEGACY_EXAMPLES_DIR,
   ];
 }
@@ -261,9 +229,6 @@ export function detectFrameworkLayout(root: string): FrameworkLayout | null {
   if (pathExists(root, LEGACY_REPO_SKILL_VERSION)) {
     return "legacy-repo-skill";
   }
-  if (pathExists(root, LEGACY_SKILL_VERSION)) {
-    return "legacy-skill";
-  }
   if (pathExists(root, LEGACY_VERSION)) {
     return "legacy";
   }

package/skills/first-tree/engine/runtime/bootstrap.ts

@@ -0,0 +1,40 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { BOOTSTRAP_STATE } from "#skill/engine/runtime/asset-loader.js";
+
+export interface BootstrapState {
+  sourceRepoName: string;
+  sourceRepoPath: string;
+  treeRepoName: string;
+}
+
+export function bootstrapStatePath(root: string): string {
+  return join(root, BOOTSTRAP_STATE);
+}
+
+export function readBootstrapState(root: string): BootstrapState | null {
+  const path = bootstrapStatePath(root);
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8")) as Partial<BootstrapState>;
+    if (
+      typeof parsed.sourceRepoName !== "string"
+      || typeof parsed.sourceRepoPath !== "string"
+      || typeof parsed.treeRepoName !== "string"
+    ) {
+      return null;
+    }
+    return {
+      sourceRepoName: parsed.sourceRepoName,
+      sourceRepoPath: parsed.sourceRepoPath,
+      treeRepoName: parsed.treeRepoName,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function writeBootstrapState(root: string, state: BootstrapState): void {
+  const path = bootstrapStatePath(root);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`);
+}

package/skills/first-tree/engine/runtime/installer.ts

@@ -5,7 +5,6 @@ import {
   BUNDLED_SKILL_ROOT,
   INSTALLED_SKILL_ROOTS,
   LEGACY_REPO_SKILL_ROOT,
-  LEGACY_SKILL_ROOT,
 } from "#skill/engine/runtime/asset-loader.js";
 
 export function resolveBundledPackageRoot(startUrl = import.meta.url): string {
@@ -57,7 +56,6 @@ export function copyCanonicalSkill(sourceRoot: string, targetRoot: string): void
   for (const relPath of [
     ...INSTALLED_SKILL_ROOTS,
     LEGACY_REPO_SKILL_ROOT,
-    LEGACY_SKILL_ROOT,
   ]) {
     const fullPath = join(targetRoot, relPath);
     if (existsSync(fullPath)) {

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

@@ -13,7 +13,6 @@ import {
   LEGACY_AGENT_INSTRUCTIONS_FILE,
   LEGACY_FRAMEWORK_ROOT,
   LEGACY_REPO_SKILL_ROOT,
-  LEGACY_SKILL_ROOT,
   SKILL_ROOT,
   SOURCE_INTEGRATION_MARKER,
   installedSkillRootsDisplay,
@@ -73,12 +72,6 @@ function formatUpgradeTaskList(
     );
   }
 
-  if (layout === "legacy-skill") {
-    migrationTasks.push(
-      `- [ ] Remove any stale \`${LEGACY_SKILL_ROOT}/\` references from repo-specific docs, scripts, workflow files, or agent config`,
-    );
-  }
-
   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`,
@@ -269,10 +262,6 @@ export function runUpgrade(repo?: Repo, options?: UpgradeOptions): number {
     console.log(
       `Migrated legacy ${LEGACY_REPO_SKILL_ROOT}/ layout to ${installedSkillRootsDisplay()}.`,
     );
-  } else if (layout === "legacy-skill") {
-    console.log(
-      `Migrated ${LEGACY_SKILL_ROOT}/ to ${installedSkillRootsDisplay()}.`,
-    );
   } else {
     if (missingInstalledRoots.length > 0) {
       console.log(

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/references/maintainer-build-and-distribution.md

@@ -53,6 +53,9 @@ another skill reference, not only in the files themselves.
 - 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.
+- `context-tree publish` is the explicit networked second-stage command for
+  GitHub repo creation, submodule add-back, and optional source-repo PR
+  opening. Keep that remote behavior there instead of expanding default `init`.
 - 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

@@ -33,7 +33,7 @@ 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
+- If init/publish/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

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

@@ -55,6 +55,8 @@ Information an agent needs to **decide** on an approach — not to execute it.
 
 - A source/workspace Git repository, or an already-created dedicated tree repo
 - Node.js 18+
+- GitHub CLI (`gh`) if you want `context-tree publish` to create the remote
+  `*-context` repo and open the source-repo PR for you
 - The npm package is `first-tree`, the installed CLI command is
   `context-tree`.
 - `context-tree init` installs the framework skill into
@@ -74,6 +76,7 @@ files are scaffolded only in the dedicated tree repo.
 cd my-org
 context-tree init
 cd ../my-org-context
+context-tree publish --open-pr
 ```
 
 If you already created a dedicated tree repo manually, initialize it in place:
@@ -84,26 +87,29 @@ 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
 `.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.
-
 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.
+1. Draft the initial tree version in the dedicated `*-context` repo.
+2. Run `context-tree publish --open-pr` from that dedicated tree repo. It will
+   create or reuse the GitHub `*-context` repo in the same owner/org as the
+   source repo, add it back to the source/workspace repo as a `git submodule`,
+   and open the source-repo PR.
+3. After publish succeeds, treat the source repo's submodule checkout as the
+   canonical local working copy for the tree. The temporary sibling bootstrap
+   checkout can be deleted when you no longer need it.
 
 ### Step 2: Work Through the Task List
 
@@ -177,7 +183,8 @@ The tree doesn't duplicate source code — it captures what connects things and
 
 | Command | Description |
 |---------|-------------|
-| `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 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 publish` | Publish a dedicated tree repo to GitHub, add it back to the source/workspace repo as a submodule, and optionally open the source-repo PR. |
 | `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. |
@@ -202,8 +209,7 @@ 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,
+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

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

@@ -42,12 +42,13 @@ 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/init.ts` / `engine/publish.ts` / `engine/verify.ts` / `engine/upgrade.ts` | Command implementations for install, publish, verify, and upgrade |
 | `engine/onboarding.ts` | Canonical onboarding text loader |
 | `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 |
+| `engine/runtime/bootstrap.ts` | Dedicated-tree bootstrap metadata for the publish workflow |
 | `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 |
@@ -74,6 +75,7 @@ not become the only place important maintainer knowledge lives.
 | Path | Coverage |
 | --- | --- |
 | `tests/init.test.ts` | Init scaffolding behavior |
+| `tests/publish.test.ts` | Publish workflow orchestration |
 | `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 |

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

@@ -21,25 +21,37 @@ existing source or workspace repository.
   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
+1. Run `context-tree init` from the current source/workspace repo.
+2. Switch into the sibling dedicated tree repo named `<repo>-context`.
+3. 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.
+4. Run `context-tree publish --open-pr` from the dedicated tree repo. It will:
+   create or reuse the GitHub `*-context` repo in the same owner/org as the
+   source repo, push the tree, add it back to the source/workspace repo as a
+   `git submodule`, and open the source-repo PR.
+5. After publish succeeds, treat the source repo's submodule checkout as the
+   canonical local working copy for the tree. The temporary sibling bootstrap
+   checkout can be deleted when you no longer need it.
+
+If the dedicated tree repo was initialized manually with `context-tree init --here`
+and publish cannot infer the source repo, pass `--source-repo PATH`.
 
 ## Verification And Upgrade
 

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
 
@@ -60,6 +59,9 @@ For a dedicated tree repo, the tree content still lives outside the skill:
 - `NODE.md`
 - `AGENTS.md`
 - `members/`
+- `.agents/skills/first-tree/bootstrap.json` when `context-tree init` was run
+  from a separate source/workspace repo and the publish workflow needs to
+  remember that source repo path
 
 The repo-owned `.agents/skills/first-tree/` path is the primary installed root
 for progress state, workflow references, and helper scripts. The matching
@@ -84,6 +86,14 @@ skill discovery and hooks.
   - validates root/frontmatter/agent markers
   - runs node and member validators
   - must reject source/workspace repos that carry only local integration
+- `context-tree publish`
+  - is the explicit second-stage command for publishing a dedicated tree repo
+    to GitHub after local bootstrap
+  - reads dedicated-tree bootstrap metadata from
+    `.agents/skills/first-tree/bootstrap.json` when available
+  - may create or reuse the GitHub `*-context` repo, push tree commits, add it
+    back to the source/workspace repo as a git submodule, and optionally open
+    the source-repo PR
 - `context-tree upgrade`
   - compares the installed skill payload version to the skill bundled with the
     currently running `first-tree` package
@@ -92,9 +102,6 @@ skill discovery and hooks.
     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`
 
@@ -111,9 +118,9 @@ skill discovery and hooks.
 - 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

@@ -91,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 });

package/skills/first-tree/tests/init.test.ts

@@ -3,6 +3,7 @@ import { basename, dirname, join } from "node:path";
 import { describe, expect, it } from "vitest";
 import {
   formatTaskList,
+  INIT_USAGE,
   parseInitArgs,
   writeProgress,
   runInit,
@@ -10,6 +11,7 @@ import {
 import { Repo } from "#skill/engine/repo.js";
 import {
   AGENT_INSTRUCTIONS_FILE,
+  BOOTSTRAP_STATE,
   CLAUDE_INSTRUCTIONS_FILE,
   FRAMEWORK_VERSION,
   INSTALLED_PROGRESS,
@@ -79,6 +81,17 @@ describe("formatTaskList", () => {
     expect(output).toContain("# Context Tree Init");
     expect(output).toContain("## Verification");
   });
+
+  it("documents the publish workflow for dedicated tree repos", () => {
+    const output = formatTaskList([], {
+      dedicatedTreeRepo: true,
+      sourceRepoName: "ADHD",
+      sourceRepoPath: "../ADHD",
+    });
+
+    expect(output).toContain("context-tree publish --open-pr");
+    expect(output).toContain("canonical local working copy");
+  });
 });
 
 // --- writeProgress ---
@@ -233,6 +246,13 @@ describe("runInit", () => {
     expect(existsSync(join(treeRepo, AGENT_INSTRUCTIONS_FILE))).toBe(true);
     expect(existsSync(join(treeRepo, "members", "NODE.md"))).toBe(true);
     expect(existsSync(join(treeRepo, INSTALLED_PROGRESS))).toBe(true);
+    expect(
+      JSON.parse(readFileSync(join(treeRepo, BOOTSTRAP_STATE), "utf-8")),
+    ).toEqual({
+      sourceRepoName: basename(sourceRepoDir.path),
+      sourceRepoPath: `../${basename(sourceRepoDir.path)}`,
+      treeRepoName: basename(treeRepo),
+    });
     expect(existsSync(join(sourceRepoDir.path, "NODE.md"))).toBe(false);
     expect(existsSync(join(sourceRepoDir.path, "members", "NODE.md"))).toBe(false);
     expect(existsSync(join(sourceRepoDir.path, INSTALLED_PROGRESS))).toBe(false);
@@ -302,6 +322,11 @@ describe("runInit", () => {
 });
 
 describe("parseInitArgs", () => {
+  it("documents that --here is only for dedicated tree repos", () => {
+    expect(INIT_USAGE).toContain("Do not use `--here` inside a source/workspace repo");
+    expect(INIT_USAGE).toContain("already in the dedicated tree repo");
+  });
+
   it("parses dedicated repo options", () => {
     expect(parseInitArgs(["--tree-name", "acme-context"])).toEqual({
       treeName: "acme-context",