first-tree 0.0.7 → 0.0.8

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";

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/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:
@@ -93,21 +96,20 @@ Either way, the framework installs into `.agents/skills/first-tree/` and
 `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
 
@@ -182,6 +184,7 @@ 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` 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. |

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

@@ -38,20 +38,20 @@ existing source or workspace repository.
 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

@@ -59,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
@@ -83,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

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

@@ -11,6 +11,7 @@ import {
 import { Repo } from "#skill/engine/repo.js";
 import {
   AGENT_INSTRUCTIONS_FILE,
+  BOOTSTRAP_STATE,
   CLAUDE_INSTRUCTIONS_FILE,
   FRAMEWORK_VERSION,
   INSTALLED_PROGRESS,
@@ -80,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 ---
@@ -234,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);

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

@@ -0,0 +1,248 @@
+import { join, relative } from "node:path";
+import { writeFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+import { Repo } from "#skill/engine/repo.js";
+import {
+  PUBLISH_USAGE,
+  parsePublishArgs,
+  runPublish,
+  type CommandRunner,
+} from "#skill/engine/publish.js";
+import { writeBootstrapState } from "#skill/engine/runtime/bootstrap.js";
+import {
+  AGENT_INSTRUCTIONS_FILE,
+  CLAUDE_INSTRUCTIONS_FILE,
+  SOURCE_INTEGRATION_MARKER,
+} from "#skill/engine/runtime/asset-loader.js";
+import {
+  makeAgentsMd,
+  makeFramework,
+  makeGitRepo,
+  makeMembers,
+  makeNode,
+  makeSourceRepo,
+  useTmpDir,
+} from "./helpers.js";
+
+interface RecordedCommand {
+  args: string[];
+  command: string;
+  cwd: string;
+}
+
+function makeTreeRepo(root: string): void {
+  makeGitRepo(root);
+  makeFramework(root, "0.2.0");
+  makeNode(root);
+  makeAgentsMd(root, { markers: true });
+  makeMembers(root);
+}
+
+function makeSourceIntegration(root: string): void {
+  writeFileSync(
+    join(root, AGENT_INSTRUCTIONS_FILE),
+    `${SOURCE_INTEGRATION_MARKER} installed\n`,
+  );
+  writeFileSync(
+    join(root, CLAUDE_INSTRUCTIONS_FILE),
+    `${SOURCE_INTEGRATION_MARKER} installed\n`,
+  );
+}
+
+function createRunner(
+  sourceRoot: string,
+  treeRoot: string,
+): { calls: RecordedCommand[]; runner: CommandRunner } {
+  const calls: RecordedCommand[] = [];
+  let treeOriginExists = false;
+  const runner: CommandRunner = (command, args, options) => {
+    calls.push({ command, args, cwd: options.cwd });
+
+    if (command === "git" && args[0] === "remote" && args[1] === "get-url") {
+      if (options.cwd === sourceRoot) {
+        return "git@github.com:acme/ADHD.git";
+      }
+      if (!treeOriginExists) {
+        throw new Error("missing origin");
+      }
+      return "git@github.com:acme/ADHD-context.git";
+    }
+
+    if (command === "gh" && args[0] === "repo" && args[1] === "view") {
+      if (args[2] === "acme/ADHD") {
+        return JSON.stringify({
+          defaultBranchRef: { name: "main" },
+          nameWithOwner: "acme/ADHD",
+          visibility: "PRIVATE",
+        });
+      }
+      throw new Error("not found");
+    }
+
+    if (
+      command === "git"
+      && args[0] === "rev-parse"
+      && args[1] === "--verify"
+      && args[2] === "HEAD"
+      && options.cwd === treeRoot
+    ) {
+      throw new Error("missing HEAD");
+    }
+
+    if (
+      command === "git"
+      && args[0] === "diff"
+      && args[1] === "--cached"
+      && args[2] === "--quiet"
+    ) {
+      throw new Error("changes present");
+    }
+
+    if (command === "git" && args[0] === "branch" && args[1] === "--show-current") {
+      return "main";
+    }
+
+    if (
+      command === "git"
+      && args[0] === "rev-parse"
+      && args[1] === "--verify"
+      && args[2] === "refs/remotes/origin/main"
+    ) {
+      return "origin/main";
+    }
+
+    if (
+      command === "git"
+      && args[0] === "rev-parse"
+      && args[1] === "--verify"
+      && args[2].startsWith("refs/heads/")
+    ) {
+      throw new Error("missing local branch");
+    }
+
+    if (command === "git" && args[0] === "ls-files") {
+      return "";
+    }
+
+    if (command === "gh" && args[0] === "pr" && args[1] === "create") {
+      return "https://github.com/acme/ADHD/pull/123";
+    }
+
+    if (command === "gh" && args[0] === "repo" && args[1] === "create") {
+      treeOriginExists = true;
+      return "";
+    }
+
+    if (command === "git" && args[0] === "remote" && args[1] === "add") {
+      treeOriginExists = true;
+      return "";
+    }
+
+    return "";
+  };
+
+  return { calls, runner };
+}
+
+describe("parsePublishArgs", () => {
+  it("documents the publish command", () => {
+    expect(PUBLISH_USAGE).toContain("context-tree publish");
+    expect(PUBLISH_USAGE).toContain("--open-pr");
+    expect(PUBLISH_USAGE).toContain("--source-repo PATH");
+  });
+
+  it("parses supported publish flags", () => {
+    expect(
+      parsePublishArgs([
+        "--open-pr",
+        "--tree-path",
+        "../ADHD-context",
+        "--source-repo",
+        "../ADHD",
+        "--submodule-path",
+        "ADHD-context",
+        "--source-remote",
+        "origin",
+      ]),
+    ).toEqual({
+      openPr: true,
+      sourceRemote: "origin",
+      sourceRepoPath: "../ADHD",
+      submodulePath: "ADHD-context",
+      treePath: "../ADHD-context",
+    });
+  });
+});
+
+describe("runPublish", () => {
+  it("publishes the tree repo, adds the submodule, and opens the source PR", () => {
+    const rootDir = useTmpDir();
+    const sourceRoot = join(rootDir.path, "ADHD");
+    const treeRoot = join(rootDir.path, "ADHD-context");
+
+    makeSourceRepo(sourceRoot);
+    makeFramework(sourceRoot, "0.2.0");
+    makeSourceIntegration(sourceRoot);
+    makeTreeRepo(treeRoot);
+    writeBootstrapState(treeRoot, {
+      sourceRepoName: "ADHD",
+      sourceRepoPath: relative(treeRoot, sourceRoot),
+      treeRepoName: "ADHD-context",
+    });
+
+    const { calls, runner } = createRunner(sourceRoot, treeRoot);
+    const result = runPublish(new Repo(treeRoot), {
+      commandRunner: runner,
+      openPr: true,
+    });
+
+    expect(result).toBe(0);
+    expect(
+      calls.some(
+        (call) =>
+          call.command === "gh"
+          && call.args[0] === "repo"
+          && call.args[1] === "create"
+          && call.args[2] === "acme/ADHD-context",
+      ),
+    ).toBe(true);
+    expect(
+      calls.some(
+        (call) =>
+          call.command === "git"
+          && call.args[0] === "submodule"
+          && call.args[1] === "add"
+          && call.args[2] === "git@github.com:acme/ADHD-context.git"
+          && call.args[3] === "ADHD-context",
+      ),
+    ).toBe(true);
+    expect(
+      calls.some(
+        (call) =>
+          call.command === "git"
+          && call.args[0] === "switch"
+          && call.args[1] === "-c"
+          && call.args[2] === "chore/connect-adhd-context",
+      ),
+    ).toBe(true);
+    expect(
+      calls.some(
+        (call) =>
+          call.command === "gh"
+          && call.args[0] === "pr"
+          && call.args[1] === "create"
+          && call.args.includes("--repo")
+          && call.args.includes("acme/ADHD"),
+      ),
+    ).toBe(true);
+  });
+
+  it("errors when the source repo cannot be inferred", () => {
+    const treeRoot = useTmpDir();
+    makeTreeRepo(treeRoot.path);
+
+    const result = runPublish(new Repo(treeRoot.path));
+
+    expect(result).toBe(1);
+  });
+});

package/skills/first-tree/tests/skill-artifacts.test.ts

@@ -230,6 +230,8 @@ describe("skill artifacts", () => {
     expect(read("README.md")).toContain("dedicated tree repo");
     expect(read("README.md")).toContain("FIRST-TREE-SOURCE-INTEGRATION:");
     expect(read("README.md")).toContain("`first-tree` skill");
+    expect(read("README.md")).toContain("context-tree publish --open-pr");
+    expect(read("README.md")).toContain("canonical local working copy");
     expect(read("README.md")).toContain("Only use `--here` after you have already switched into the dedicated tree repo.");
     expect(read("AGENTS.md")).toContain("references/source-map.md");
     expect(read("AGENTS.md")).toContain("source-workspace-installation.md");
@@ -249,6 +251,7 @@ describe("skill artifacts", () => {
     expect(onboarding).toContain(".agents/skills/first-tree/");
     expect(onboarding).toContain(".claude/skills/first-tree/");
     expect(onboarding).toContain("FIRST-TREE-SOURCE-INTEGRATION:");
+    expect(onboarding).toContain("context-tree publish --open-pr");
     expect(onboarding).toContain("source/workspace repo");
     expect(onboarding).toContain("git submodule");
     expect(onboarding).toContain("Only use `--here` after you have already switched into the dedicated tree repo.");
@@ -266,6 +269,7 @@ describe("skill artifacts", () => {
     expect(skillMd).toContain(".claude/skills/first-tree/");
     expect(skillMd).toContain("source-workspace-installation.md");
     expect(skillMd).toContain("FIRST-TREE-SOURCE-INTEGRATION:");
+    expect(skillMd).toContain("context-tree publish --open-pr");
     expect(skillMd).toContain("Never run `context-tree init --here` in a source/workspace repo");
     expect(skillMd).not.toContain("canonical eval harness");
 
@@ -277,6 +281,8 @@ describe("skill artifacts", () => {
     expect(sourceMap).toContain("maintainer-thin-cli.md");
     expect(sourceMap).toContain("maintainer-build-and-distribution.md");
     expect(sourceMap).toContain("maintainer-testing.md");
+    expect(sourceMap).toContain("engine/publish.ts");
+    expect(sourceMap).toContain("tests/publish.test.ts");
     expect(sourceMap).toContain("engine/commands/");
     expect(sourceMap).toContain("engine/runtime/asset-loader.ts");
     expect(sourceMap).toContain("tests/init.test.ts");
@@ -291,6 +297,7 @@ describe("skill artifacts", () => {
     );
     expect(sourceWorkspaceInstall).toContain("FIRST-TREE-SOURCE-INTEGRATION:");
     expect(sourceWorkspaceInstall).toContain("git submodule");
+    expect(sourceWorkspaceInstall).toContain("context-tree publish --open-pr");
     expect(sourceWorkspaceInstall).toContain("Do not run `context-tree verify`");
     expect(sourceWorkspaceInstall).toContain("Do not run `context-tree init --here` in the source/workspace repo");
 
@@ -300,6 +307,11 @@ describe("skill artifacts", () => {
     expect(maintainerArchitecture).toContain("maintainer-only developer tooling");
     expect(maintainerArchitecture).toContain("`evals/`");
     expect(maintainerArchitecture).not.toContain("tests, and evals");
+
+    const buildAndDistribution = read(
+      "skills/first-tree/references/maintainer-build-and-distribution.md",
+    );
+    expect(buildAndDistribution).toContain("context-tree publish");
   });
 
   it("keeps public OSS entrypoints and package metadata in place", () => {

package/skills/first-tree/tests/thin-cli.test.ts

@@ -41,6 +41,7 @@ afterEach(() => {
 describe("thin CLI shell", () => {
   it("documents the dedicated-repo meaning of --here", () => {
     expect(USAGE).toContain("git init && context-tree init --here");
+    expect(USAGE).toContain("context-tree publish --open-pr");
     expect(USAGE).toContain("`--here` is for when the current repo is already the dedicated tree repo.");
   });
 

package/dist/onboarding-BS8btkG4.js

@@ -1,2 +0,0 @@
-import { t as runOnboarding } from "./onboarding-D3hnxIie.js";
-export { runOnboarding };

package/dist/onboarding-D3hnxIie.js

@@ -1,10 +0,0 @@
-//#region skills/first-tree/references/onboarding.md
-var onboarding_default = "# Context Tree Onboarding\n\nYou are setting up a **Context Tree** — the living source of truth for an organization. This document tells you what it is and how to bootstrap one.\n\n---\n\n## What Is a Context Tree\n\nA Context Tree is a Git repository where every directory is a **domain** and every file is a **node**. Each node captures decisions, designs, and cross-domain relationships — the knowledge that would otherwise scatter across PRs, documents, and people's heads.\n\nKey properties:\n\n- **Nodes are markdown files.** Each directory has a `NODE.md` that describes the domain. Leaf `.md` files capture specific decisions or designs.\n- **Every node has an owner.** Declared in YAML frontmatter. Owners approve changes to their nodes.\n- **Organized by concern, not by repo or team.** An agent working on \"add SSO\" finds all auth context in one place — not split across 4 repos.\n- **The tree is never a snapshot — it's the current state.** When decisions change, the tree updates. Stale nodes are bugs.\n\n### Frontmatter Format\n\nEvery node has frontmatter:\n\n```yaml\n---\ntitle: \"Auth Architecture\"\nowners: [alice, bob]\nsoft_links: [/infrastructure/deployments]\n---\n```\n\n- `owners` — who can approve changes. `owners: []` inherits from parent. `owners: [*]` means anyone.\n- `soft_links` — cross-references to related nodes in other domains.\n\n### What Belongs in the Tree\n\nInformation an agent needs to **decide** on an approach — not to execute it.\n\n**Yes:** \"Auth spans 4 repos: backend issues JWTs, frontend uses Better Auth, extension uses OAuth popup, desktop uses localhost callback.\"\n\n**No:** The function signature of `auth_service.verify()` — that's in the code.\n\n---\n\n## Four Principles\n\n1. **Source of truth for decisions, not execution.** The tree captures the *what* and *why*. Execution details stay in source systems.\n2. **Agents are first-class participants.** The tree is designed for agents to navigate and update.\n3. **Transparency by default.** Reading is open to all. Writing requires owner approval.\n4. **Git-native.** Nodes are files, domains are directories. History, ownership, and review follow Git conventions.\n\n---\n\n## How to Set Up a Context Tree\n\n### Prerequisites\n\n- A source/workspace Git repository, or an already-created dedicated tree repo\n- Node.js 18+\n- The npm package is `first-tree`, the installed CLI command is\n  `context-tree`.\n- `context-tree init` installs the framework skill into\n  `.agents/skills/first-tree/` and `.claude/skills/first-tree/`.\n- Use `npx first-tree init` for one-off runs, or `npm install -g first-tree`\n  to add the `context-tree` command to your PATH\n\n### Step 1: Initialize\n\nRecommended workflow: run `context-tree init` from your source or workspace repo.\nThe CLI will install the bundled skill in the current repo, update root\n`AGENTS.md` and `CLAUDE.md` with a `FIRST-TREE-SOURCE-INTEGRATION:` line, and\ncreate a sibling dedicated tree repo named `<repo>-context` by default. Tree\nfiles are scaffolded only in the dedicated tree repo.\n\n```bash\ncd my-org\ncontext-tree init\ncd ../my-org-context\n```\n\nIf you already created a dedicated tree repo manually, initialize it in place:\n\n```bash\nmkdir my-org-context && cd my-org-context\ngit init\ncontext-tree init --here\n```\n\nOnly use `--here` after you have already switched into the dedicated tree repo.\nDo not use it inside the source/workspace repo unless you intentionally want\nthat repo itself to become the Context Tree.\n\nEither way, the framework installs into `.agents/skills/first-tree/` and\n`.claude/skills/first-tree/`, renders scaffolding (`NODE.md`, `AGENTS.md`,\n`members/NODE.md`), and generates a task list in\n`.agents/skills/first-tree/progress.md`.\n\nPublishing tip: keep the tree repo in the same GitHub organization as the\nsource repo unless you have a reason not to.\n\nHard boundary: do **not** create `NODE.md`, `members/`, or tree-scoped\n`AGENTS.md` in the source/workspace repo. Those files belong only in the\ndedicated `*-context` repo.\n\nDefault agent workflow after initialization:\n\n1. Create and push the dedicated `*-context` repo in the same GitHub\n   organization as the source repo.\n2. Add the dedicated tree repo back to the source/workspace repo as a `git submodule`.\n3. Open a PR against the source/workspace repo's default branch for the local\n   skill integration plus the new submodule pointer. Do not merge it\n   automatically.\n\n### Step 2: Work Through the Task List\n\nRead `.agents/skills/first-tree/progress.md`. It contains a checklist tailored\nto the current state of the repo. Complete each task:\n\n- Fill in `NODE.md` with your organization name, owners, and domains\n- Add project-specific instructions to `AGENTS.md` below the framework markers\n- Create member nodes under `members/`\n- Optionally configure agent integration (for Claude Code, the installed hook\n  assets live under `.claude/skills/first-tree/`)\n- Copy validation workflows from\n  `.agents/skills/first-tree/assets/framework/workflows/` to\n  `.github/workflows/`\n\nAs you complete each task, check it off in\n`.agents/skills/first-tree/progress.md` by changing `- [ ]` to `- [x]`.\n\n### Step 3: Verify\n\n```bash\ncontext-tree verify\n```\n\nOr, from your source/workspace repo:\n\n```bash\ncontext-tree verify --tree-path ../my-org-context\n```\n\nThis fails if any items in `.agents/skills/first-tree/progress.md` remain\nunchecked, and runs deterministic checks (valid frontmatter, node structure,\nmember nodes exist).\n\nDo not run `context-tree verify` in the source/workspace repo itself. That repo\nonly carries the installed skill plus the\n`FIRST-TREE-SOURCE-INTEGRATION:` line.\n\n### Step 4: Design Your Domains\n\nCreate top-level directories for your organization's primary concerns. Each needs a `NODE.md`:\n\n```\nmy-org-tree/\n  NODE.md              # root — lists all domains\n  engineering/\n    NODE.md            # decisions about architecture, infra, tooling\n  product/\n    NODE.md            # strategy, roadmap, user research\n  marketing/\n    NODE.md            # positioning, campaigns\n  members/\n    NODE.md            # team members and agents\n    alice/\n      NODE.md          # individual member node\n```\n\n### Step 5: Populate from Existing Work\n\nFor each domain, extract knowledge from existing repos, docs, and systems:\n\n- Decisions and their rationale\n- Cross-domain relationships and dependencies\n- Constraints that aren't obvious from the code\n\nThe tree doesn't duplicate source code — it captures what connects things and why they were built that way.\n\n---\n\n## CLI Reference\n\n| Command | Description |\n|---------|-------------|\n| `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. |\n| `context-tree verify` | Check the installed progress file for unchecked items + run deterministic validation. Use `--tree-path` when invoking from another working directory. |\n| `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. |\n| `context-tree help onboarding` | Print this onboarding guide. |\n\n---\n\n## Upgrading the Framework\n\nWhen the framework updates:\n\n```bash\ncontext-tree upgrade\n```\n\n`context-tree upgrade` refreshes `.agents/skills/first-tree/` and\n`.claude/skills/first-tree/` from the skill bundled with the currently running\n`first-tree` npm package, preserves your tree content, and generates follow-up\ntasks in `.agents/skills/first-tree/progress.md`.\n\nIf you run `context-tree upgrade` in the source/workspace repo, it refreshes\nonly the local installed skill plus the `FIRST-TREE-SOURCE-INTEGRATION:` lines.\nRun `context-tree upgrade --tree-path ../my-org-context` to upgrade the\ndedicated tree repo itself.\n\nIf your repo still uses the older `skills/first-tree/` or `.context-tree/` layouts,\n`context-tree upgrade` will migrate it to the current installed layout first.\n\nTo pick up a newer framework release, first run a newer package version, for\nexample `npx first-tree@latest upgrade`, or update your global `first-tree`\ninstall before running `context-tree upgrade`.\n\n---\n\n## Further Reading\n\n- `.agents/skills/first-tree/references/principles.md` — Core principles with detailed examples\n- `.agents/skills/first-tree/references/source-workspace-installation.md` — Source/workspace install contract\n- `.agents/skills/first-tree/references/ownership-and-naming.md` — How nodes are named and owned\n- `AGENTS.md` in your tree — The before/during/after workflow for every task\n";
-//#endregion
-//#region skills/first-tree/engine/onboarding.ts
-function runOnboarding(output = console.log) {
-	output(onboarding_default);
-	return 0;
-}
-//#endregion
-export { onboarding_default as n, runOnboarding as t };