@first-tree-ai/context-tree 0.1.6-alpha.202608310559 → 0.1.7

package/README.md

@@ -1,179 +1,209 @@
 # Context Tree
 
-`@first-tree-ai/context-tree` gives agents durable project context: decisions,
-constraints, and relationships stored as Markdown in a private GitHub
-repository. It supports Codex and Claude Code through a portable Agent Plugins
-v1 package and includes a CLI for shell automation.
+`@first-tree-ai/context-tree` provides durable, structured project context for
+coding agents. It ships a portable core, CLI, templates, and six
+framework-neutral skills.
 
-Each project is explicitly linked to a verified local checkout. Future sessions
-resolve that checkout from the project's credential-free Git origin, or from its
-real directory when the project is not a Git repository. Context Tree currently
-supports repositories on GitHub.com only; GitHub Enterprise Server and other
-forges are not supported.
+A Context Tree records current decisions, constraints, relationships, and their
+rationale. Source repositories still own implementation detail, task history,
+and credentials.
+
+## Requirements
+
+- Node.js 22.13 or newer
+- Git
+- GitHub CLI (`gh`) only for connecting a GitHub tree or publishing
+
+Git and GitHub authentication remain owned by the host tools. Repository inputs
+are credential-free `OWNER/REPO` identities, never URLs containing credentials.
 
 ## Install
 
-Node.js 22.13 or newer and npm are required. Git is also required to initialize
-trees and use Git-backed workflows.
+```bash
+npm install --global @first-tree-ai/context-tree
+```
+
+That installs the `context-tree` command and copies the six skills into the
+skill directory of every agent you already have:
+
+```text
+✓ claude  → ~/.claude/skills/   (6 skills)
+✓ codex   → ~/.codex/skills/    (6 skills)
+```
+
+Restart your agent so it discovers them, then try asking:
 
-### Codex or Claude Code plugin (recommended)
+> Set up a Context Tree for this project, then read the relevant context.
 
-Install the marketplace and plugin, then start a new session so the host can
-discover the skills and lifecycle hook.
+> Write this architectural decision to the Context Tree.
 
-For Codex:
+Skill installation is a normal command, so you can re-run it after installing a
+new agent, or scope it to one project:
 
 ```bash
-codex plugin marketplace add first-tree-ai/context-tree
-codex plugin add context-tree@context-tree
+context-tree install                       # every agent you have
+context-tree install --host codex          # one agent
+context-tree install --project .           # ./.claude/skills and ./.codex/skills
 ```
 
-For Claude Code:
+Installing only ever writes `context-tree-*` skill directories, never touches
+skills it does not own, and never creates a configuration directory for an agent
+that is not present. Adding support for another agent is one entry in the host
+table in `src/core/install.ts`.
+
+Once a project is connected, `create` and `connect` record the tree in the
+project's own `AGENTS.md`, so any agent that reads instruction files knows the
+tree exists without host-specific configuration.
+
+## Six skills
+
+### Setup
+
+`context-tree-setup` orchestrates lifecycle setup for projects with no
+connection. It asks whether to create a new tree or connect an existing one,
+then delegates to the create or connect workflow rather than duplicating
+lifecycle policy. Read and write invoke setup when the current project has no
+connection. Setup never publishes without explicit confirmation.
+
+### Create
 
 ```bash
-claude plugin marketplace add first-tree-ai/context-tree
-claude plugin install context-tree@context-tree
+context-tree create --project-path ./service
 ```
 
-Marketplace installation requires repository access to
-`first-tree-ai/context-tree`. These selectors resolve the npm `latest` package,
-which must contain the plugin manifests, hook, four skills and launchers, and
-`dist/cli/index.mjs`. Review and trust the session-start hook if your host asks.
+`create` derives `<normalized-project-directory>-context-tree`, scaffolds and
+commits it under `~/.context-tree/trees`, then connects it atomically. It is
+idempotent only while the project remains connected to that managed tree.
 
-The plugin uses its own packaged CLI, so plugin users do not need a global CLI
-installation. Try asking:
+### Connect
 
-> Link this project to my Context Tree, then read the relevant context.
+Connect to an existing managed tree by exact name:
 
-> Publish this architectural decision to the Context Tree.
+```bash
+context-tree connect shared-context-tree --project-path ./service
+```
+
+Or reuse or clone a GitHub tree by repository identity:
 
-### Global CLI (optional)
+```bash
+context-tree connect OWNER/REPO --project-path ./service
+```
 
-Install the package globally only when scripts or terminal workflows need a
-`context-tree` command on `PATH`:
+Or connect an existing checkout in place by exact disk path:
 
 ```bash
-npm install --global @first-tree-ai/context-tree
-context-tree --help
+context-tree connect --tree-path /path/to/a/tree --project-path ./service
 ```
 
-## CLI workflows
+`connect --tree-path` requires an exact, clean, fully valid Git root with no
+symlink components. Trees without an origin connect as local state;
+credential-free GitHub origins connect as GitHub state. External disk trees
+are never copied, moved, or deleted.
+
+An identical connection is idempotent. An explicit connect automatically
+switches the project. GitHub checkouts use the repository's lowercase name in
+the same flat managed namespace as created trees.
 
-### Initialize or link a tree
+`context-tree list` reports valid, clean managed trees as
+`{ schemaVersion: 1, trees: [{ name, tree }] }`; a missing managed directory
+is an empty list.
 
-Create a new tree and record a local link for the current project:
+### Read
 
 ```bash
-context-tree init --repository acme/context --tree-path ./context-tree
+context-tree sync --project-path ./service
+context-tree read product/runtime.md --tree-path /path/from/sync
 ```
 
-Or link a project to an existing, verified checkout:
+Local trees report their checked-out branch and exact `HEAD` without network
+access. GitHub trees perform one fast-forward-only pull of the checked-out
+branch. Reads navigate from indexes to narrow, task-relevant children.
+
+### Write
 
 ```bash
-context-tree link --project-path ./service --tree-path ./context-tree
+context-tree prepare-write --project-path ./service
+# Edit only the returned worktreePath.
+context-tree finish-write --project-path ./service \
+  --worktree-path /path/from/prepare \
+  --message "Record runtime constraint"
 ```
 
-If `init` omits `--tree-path`, it creates `./REPO`, using the repository name
-verbatim as the directory and tree title. Scaffolding is create-only. It runs
-ordinary `git init`, configures a credential-free GitHub origin, and creates a
-validation workflow pinned to the package version and selected initial branch.
-The init skill, rather than the CLI, owns the initial commit and any publication.
+Preparation synchronizes first and creates a random isolated worktree at that
+exact commit. Finishing validates the worktree, stages every pending change,
+creates one unsigned commit using the host identity, and attempts one
+fast-forward merge for local trees or one non-force push for GitHub trees.
+
+If the destination advanced, `finish-write` returns `WRITE_OUTDATED` and
+preserves the worktree. Prepare again and reapply the intended semantic change
+once; there is no automatic rebase, retry loop, or pull-request fallback.
 
-### Resolve, refresh, read, and verify
+A preserved or abandoned write leaves its temporary worktree on disk and a
+`context-tree/write/<name>` branch in the tree. The next `prepare-write` reclaims
+one of these only when it holds no commit your checkout lacks, has no pending
+change, and has gone untouched for twenty-four hours, so a worktree you are still
+editing and a `WRITE_OUTDATED` worktree awaiting its retry are both left alone.
+Those keep their pending edits until you clear them with
+`git worktree remove <path>` and `git branch -D <branch>` in the connected tree.
+
+### Publish
 
 ```bash
-context-tree resolve --project-path ./service
-context-tree refresh --project-path ./service
-context-tree read --tree-path ./context-tree
-context-tree read product --tree-path ./context-tree
-context-tree verify --tree-path ./context-tree
+context-tree publish --project-path ./service
+# or: context-tree publish OWNER/REPO --project-path ./service
 ```
 
-`resolve` checks the recorded checkout, origin, cleanliness, and root
-`NODE.md`; it does not scan the whole semantic tree. `refresh` discovers the
-live default branch, requires it to match the checked-out branch, and
-fast-forwards before reads. Agent reads refresh and fully verify the tree, then
-report the exact commit SHA. If GitHub is unavailable, a stale read requires
-explicit authorization, is clearly labeled, and can never be used as a write
-base.
+Publishing requires a clean, valid local tree with no `origin`. It creates one
+new private GitHub repository, pushes the checkout, and then changes the stored
+connection to GitHub state. Those external and local changes are not atomic;
+uncertain or partial outcomes are reported as `PUBLISH_INCOMPLETE` and are not
+automatically inspected or repaired.
 
-Directory reads return the selected `NODE.md` body and metadata plus summaries
-of immediate children. Leaf reads return the leaf body without children.
+## Project identity
 
-### Prepare and inspect a write
+Git project paths resolve to the exact root of that checkout. A clone or Git
+worktree is independent even if it shares an origin or Git common directory.
+Non-Git projects match only the exact connected directory; nested directories
+do not inherit the connection.
 
-```bash
-context-tree stage --project-path ./service
-context-tree diff ./prepared-worktree --base HEAD
+Connection data is written atomically with mode `0600` at
+`~/.context-tree/connections.json`. Duplicate project records are corruption.
+Stored local/GitHub state is not reclassified from mutable remotes.
+
+Every command that touches a connected tree reports why it refused:
+`NO_CONNECTION` (nothing connected), `DIRTY_TREE` (your uncommitted edits —
+commit or discard them), `INVALID_TREE` (structure fails `verify`),
+`STALE_CONNECTION` (the stored path is gone; connect again), and
+`CORRUPT_CONNECTION` (unreadable or duplicated records).
+
+## CLI plumbing
+
+The public command inventory is:
+
+```text
+install  create  connect  list  resolve  sync  prepare-write
+finish-write  publish  read  verify
 ```
 
-`stage` fetches the live default branch and creates an isolated worktree at its
-exact commit. After edits, `diff` reports all pending changes against the given
-base (`HEAD` by default). These are preparation and inspection commands: there
-is no CLI publish command. The write skill edits, verifies, reviews, commits,
-rebases when necessary, and publishes the result.
+Setup, create, connect, read, write, and publish ship as six skills; setup
+orchestrates the five concrete workflows. `install` is the distribution
+entry point, run for you by `npm install`. `resolve`, `sync`, `prepare-write`,
+`finish-write`, and `verify` are plumbing or diagnostic commands rather than
+separate user intentions; `list` backs setup's connect-target discovery.
+All machine-readable responses use strict schema version `1`.
+
+`verify` is intended for CI and diagnostics. Normal skills invoke it only after
+an operation reports invalid tree content.
 
-### Retrieve the policy
+## Development
 
 ```bash
-context-tree policy
+pnpm install
+pnpm check
+pnpm typecheck
+pnpm test
+pnpm check:package
 ```
 
-This returns the canonical policy packaged with the installed version.
-
-## Command reference
-
-| Command | Purpose | Essential arguments and options |
-| --- | --- | --- |
-| `link` | Link a project to a verified checkout | `--project-path <path>`, `--tree-path <path>` |
-| `resolve` | Resolve a project's recorded link | `--project-path <path>` (default `.`) |
-| `refresh` | Fast-forward a linked tree to its live default branch | `--project-path <path>` (default `.`) |
-| `stage` | Prepare an isolated worktree for a write | `--project-path <path>` (default `.`) |
-| `diff` | Inspect changes in a prepared worktree | `[tree-path]` (default `.`), `--base <ref>` (default `HEAD`) |
-| `init` | Scaffold a new tree | `--repository <owner/repo>`, optional `--tree-path <path>` |
-| `policy` | Print the packaged Context Tree policy | None |
-| `read` | Read a node or Markdown leaf | `[path]` (default `.`), `--tree-path <path>` (default `.`) |
-| `verify` | Validate tree structure and safety | `--tree-path <path>` (default `.`) |
-
-Successful commands and runtime or argument failures emit one
-`schemaVersion: 1` JSON object on stdout. Help and version output are plain
-text. An invalid `verify` report is still emitted and exits with status 1. The
-strict Zod schemas are the source of truth for public wire contracts.
-
-Links are machine-local internal state in
-`~/.context-tree/connections.json`; do not edit this file manually. Managed
-clones default to `~/.context-tree/checkouts/OWNER/REPO`. Resolution does not
-search for moved checkouts, so use the link skill again to repair a stale link.
-
-## Safety and lifecycle
-
-- **Credentials:** The core and CLI neither manage credentials nor perform
-  authenticated GitHub operations. Repository URLs containing credentials are
-  rejected and never logged; host Git and GitHub CLI own authentication.
-- **Checkout validation:** Linking requires a clean, exact Git root with a safe
-  GitHub origin and a fully valid tree. Resolution fails closed for symlinks,
-  moved paths, dirty trees, origin mismatches, and invalid roots. `init` has a
-  narrow exception for its four new uncommitted scaffold files.
-- **Git operations:** Reads fast-forward only. Writes start from a freshly
-  fetched default-branch commit in an isolated worktree and never force-push.
-  Commit SHAs identify shared snapshots.
-- **Hooks:** Session and subagent hooks inject only a resolved tree identity and
-  path. They are silent when no link matches and never fetch, clone, or mutate.
-  They use only the plugin's packaged CLI and warn if it is unavailable.
-- **Write fallback:** The write skill retries bounded concurrent updates. If a
-  direct push is denied or retries are exhausted, it opens a conflict-free PR
-  from the latest default branch without merging it or requesting reviewers.
-  Each write and commit is scoped to one concrete source.
-
-For tree structure, link replacement rules, validation boundaries, memory
-selection, read/write lifecycle details, and exact public contracts, see the
-[Context Tree format specification](docs/specification.md).
-
-## Compatibility
-
-The package uses `.codex-plugin/plugin.json` and `.claude-plugin/plugin.json` as
-host adapters for installation and lifecycle integration. It intentionally
-omits a root `plugin.json`: Codex 0.151.0 treats that portable manifest as an
-alternate plugin shape and fails to discover bundled lifecycle hooks. Both
-marketplaces install the same npm package, and all plugin components use its
-private packaged CLI at the same version rather than a global `PATH` command.
+See [docs/specification.md](docs/specification.md) for contracts and safety
+invariants.