first-tree 0.0.2 → 0.0.4

package/README.md

@@ -1,68 +1,144 @@
-# seed-tree
+# first-tree
 
-Template source and CLI for [Context Tree](https://context-tree.ai) — the living source of truth for your organization.
+`first-tree` publishes the `context-tree` CLI and bundles the canonical
+`first-tree` skill used to bootstrap and maintain Context Tree repos.
 
-## What is Context Tree?
+## Install And Run
 
-A tree-structured knowledge base that agents and humans build and maintain together. Every node represents a domain, decision, or design. Every node has an owner. When things change, the tree updates. See [docs/about.md](docs/about.md) for the full story.
+- One-off use without installing globally:
+
+  ```bash
+  npx first-tree init
+  ```
+
+- Global install:
+
+  ```bash
+  npm install -g first-tree
+  context-tree init
+  ```
+
+- Show the installed CLI version:
+
+  ```bash
+  context-tree --version
+  ```
+
+- Show the command list:
+
+  ```bash
+  context-tree --help
+  ```
+
+Although the npm package is named `first-tree`, the installed CLI command is
+`context-tree`.
 
 ## Quick Start
 
+Recommended workflow: start from your source or workspace repo and let
+`context-tree init` create a sibling dedicated tree repo.
+
 ```bash
-npx context-tree init
+cd my-app
+npx first-tree init
+cd ../my-app-context
 ```
 
-Run this inside a git repo. It clones the framework, renders scaffolding, and generates a task list for your agent to work through.
+If you already created a dedicated tree repo yourself, initialize it in place:
+
+```bash
+mkdir my-org-context && cd my-org-context
+git init
+context-tree init --here
+```
+
+- `context-tree init` installs `skills/first-tree/`, creates `NODE.md`,
+  `AGENTS.md`, `members/NODE.md`, and writes a checklist to
+  `skills/first-tree/progress.md`.
+- `context-tree verify` checks both the progress checklist and deterministic
+  tree validation. It is expected to fail until the required onboarding tasks
+  are complete.
+- `context-tree upgrade` refreshes the installed skill from the currently
+  running `first-tree` npm package. To force the newest published package for a
+  one-off upgrade, run `npx first-tree@latest upgrade`.
+
+The package carries the bundled canonical skill, so `init` and `upgrade`
+install from the package payload instead of cloning this source repo at
+runtime.
 
 ## Commands
 
 | Command | What it does |
-|---------|-------------|
-| `context-tree init` | Bootstrap a new context tree in the current git repo |
-| `context-tree verify` | Run checks against the tree, report pass/fail |
-| `context-tree upgrade` | Compare local framework version to upstream, generate upgrade tasks |
+| --- | --- |
+| `context-tree init` | Create or refresh a dedicated context tree repo; use `--here` to initialize the current repo in place |
+| `context-tree verify` | Run verification checks against the current tree |
+| `context-tree upgrade` | Refresh the installed skill from the current `first-tree` npm package and write follow-up tasks |
+| `context-tree help onboarding` | Print the onboarding guide |
+| `context-tree --help` | Show the available commands |
+| `context-tree --version` | Print the installed CLI version |
 
-## What `init` creates
+## Package Name vs Command
 
-```
-your-tree/
-  .context-tree/           # framework (upgradable from seed-tree)
-    VERSION
-    principles.md
-    ownership-and-naming.md
-    templates/
-    workflows/
-    examples/
-  NODE.md                  # root node — your domains (from template)
-  AGENT.md                 # agent instructions with framework markers (from template)
-  members/
-    NODE.md                # members domain (from template)
-```
+- npm package name: `first-tree`
+- installed CLI command: `context-tree`
+- installed skill directory inside a user tree: `skills/first-tree/`
+- when maintainer docs mention "the `first-tree` skill", they mean that
+  bundled skill directory, not the npm package name
 
-## Upgrades
+## Runtime And Maintainer Prerequisites
 
-After init, seed-tree is added as a git remote (`context-tree-upstream`). To upgrade the framework:
+- User trees: the onboarding guide targets Node.js 18+.
+- This source repo: use Node.js 22 and pnpm 10 to match CI and the checked-in
+  package manager version.
 
-```bash
-context-tree upgrade      # shows what changed and what to do
-```
+## What This Repo Ships
 
-## Documentation
+- `src/` keeps the thin CLI shell that parses commands and dispatches to the
+  bundled skill.
+- `skills/first-tree/` is the canonical source for framework behavior, shipped
+  templates, maintainer references, and validation logic.
+- `evals/` is maintainer-only developer tooling for the source repo. It is
+  intentionally not part of the published package.
 
-- [docs/onboarding.md](docs/onboarding.md) — Onboarding guide for setting up a context tree (for agents)
-- [docs/about.md](docs/about.md) — What is Context Tree and who it's for
-- [.context-tree/principles.md](.context-tree/principles.md) — Core principles with examples
-- [.context-tree/ownership-and-naming.md](.context-tree/ownership-and-naming.md) — Node naming and ownership model
+## Developing This Repo
+
+Run these commands from the repo root:
+
+```bash
+pnpm install --frozen-lockfile
+pnpm validate:skill
+pnpm typecheck
+pnpm test
+pnpm build
+```
 
-## Development
+When package contents or install/upgrade behavior changes, also run:
 
 ```bash
-pnpm install
-pnpm test              # run tests
-pnpm typecheck         # type check
-pnpm build             # build CLI
+pnpm pack
 ```
 
+## Canonical Documentation
+
+All framework documentation, maintainer guidance, and shipped runtime assets
+live in `skills/first-tree/`.
+
+- User-facing overview: `skills/first-tree/references/about.md`
+- User onboarding: `skills/first-tree/references/onboarding.md`
+- Maintainer entrypoint: `skills/first-tree/references/source-map.md`
+
+If you are maintaining this repo, start with the source map instead of relying
+on root-level prose.
+
+## Contributing And Security
+
+- Use the GitHub issue forms for bug reports and feature requests so maintainers
+  get reproducible context up front.
+- See `CONTRIBUTING.md` for local setup, validation expectations, and where
+  changes should live.
+- See `CODE_OF_CONDUCT.md` for community expectations.
+- See `SECURITY.md` for vulnerability reporting guidance.
+
 ## License
 
 Apache 2.0

package/dist/cli.js

@@ -1,41 +1,70 @@
 #!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 //#region src/cli.ts
 const USAGE = `usage: context-tree <command>
 
+  New to context-tree? Run \`context-tree help onboarding\` first.
+
 Commands:
-  init      Bootstrap a new context tree (clones seed-tree, copies framework files)
-  verify    Run verification checks against the current tree
-  upgrade   Generate an upgrade task list from upstream changes
+  init      Create or refresh a dedicated context tree repo
+  verify    Run verification checks against a tree repo
+  upgrade   Refresh the installed skill in a tree repo
+  help      Show help for a topic (e.g. \`help onboarding\`)
 
 Options:
-  --help    Show this help message
+  --help       Show this help message
+  --version    Show version number
+
+Common examples:
+  context-tree init
+  context-tree init --here
+  context-tree verify --tree-path ../my-org-context
+  context-tree upgrade --tree-path ../my-org-context
 `;
-async function main() {
-	const args = process.argv.slice(2);
+function isDirectExecution(argv1, metaUrl = import.meta.url) {
+	if (argv1 === void 0) return false;
+	try {
+		return realpathSync(argv1) === realpathSync(fileURLToPath(metaUrl));
+	} catch {
+		return false;
+	}
+}
+async function runCli(args, output = console.log) {
+	const write = (text) => output(text);
 	if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
-		console.log(USAGE);
+		write(USAGE);
+		return 0;
+	}
+	if (args[0] === "--version" || args[0] === "-v") {
+		const { createRequire } = await import("node:module");
+		write(createRequire(import.meta.url)("../package.json").version);
 		return 0;
 	}
 	const command = args[0];
 	switch (command) {
 		case "init": {
-			const { runInit } = await import("./init-CE_944sb.js");
-			return runInit();
+			const { runInit } = await import("./init--VepFe6N.js");
+			return runInit(args.slice(1));
 		}
 		case "verify": {
-			const { runVerify } = await import("./verify-CSRIkuoM.js");
-			return runVerify();
+			const { runVerify } = await import("./verify-mC9ZTd1f.js");
+			return runVerify(args.slice(1));
 		}
 		case "upgrade": {
-			const { runUpgrade } = await import("./upgrade-Chr7z0CY.js");
-			return runUpgrade();
+			const { runUpgrade } = await import("./upgrade-Cgx_K2HM.js");
+			return runUpgrade(args.slice(1));
 		}
+		case "help": return (await import("./help-Dtdj91HJ.js")).runHelp(args.slice(1), write);
 		default:
-			console.log(`Unknown command: ${command}`);
-			console.log(USAGE);
+			write(`Unknown command: ${command}`);
+			write(USAGE);
 			return 1;
 	}
 }
-main().then((code) => process.exit(code));
+async function main() {
+	return runCli(process.argv.slice(2));
+}
+if (isDirectExecution(process.argv[1])) main().then((code) => process.exit(code));
 //#endregion
-export {};
+export { USAGE, isDirectExecution, runCli };

package/dist/help-Dtdj91HJ.js

@@ -0,0 +1,25 @@
+//#region skills/first-tree/engine/commands/help.ts
+const HELP_USAGE = `usage: context-tree help <topic>
+
+Topics:
+  onboarding   How to set up a context tree from scratch
+`;
+async function runHelp(args, output = console.log) {
+	const topic = args[0];
+	if (!topic || topic === "--help" || topic === "-h") {
+		output(HELP_USAGE);
+		return 0;
+	}
+	switch (topic) {
+		case "onboarding": {
+			const { runOnboarding } = await import("./onboarding-C9cYSE6F.js");
+			return runOnboarding(output);
+		}
+		default:
+			output(`Unknown help topic: ${topic}`);
+			output(HELP_USAGE);
+			return 1;
+	}
+}
+//#endregion
+export { runHelp };