overlane 0.0.0-stage → 0.1.12

package/README.md

@@ -1,3 +1,117 @@
-# Temporary Holding Version
+# Overlane
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Overlane connects a GitHub project to your coding agents. One connection gives Claude Code, Codex and background bots project memory, tasks, a code map, guardrails and evidence that work is really done.
+
+This package is the `overlane` command line: connect and doctor, tasks and runs, releases, the code indexer (`overlane index`), the local code shim (`overlane shim`, off by default) and the Claude Code and Codex plugin (`overlane plugin install`).
+
+Node 22 or later. No runtime dependencies: the package is one bundled file plus its assets, and works offline after install. The hosted service is not in the package. Docs: https://docs.overlane.dev.
+
+## Install
+
+    npm i -g overlane
+
+Or from a GitHub release tarball (every release attaches `overlane-<version>.tgz`):
+
+    npm i -g https://github.com/owenob1/mvrx-harness/releases/download/v<version>/overlane-<version>.tgz
+
+Check it:
+
+    overlane --version
+    overlane help
+
+The binary is `overlane`; `ol` is the short alias. The old `mvrx` command still works for now (it prints a one-line notice on stderr in a terminal, never when output is JSON) and will be removed in a later release. The previous package `@mvrx/harness` is deprecated; use `overlane`.
+
+The package version is the plugin release version, so the plugin you install always matches the binary.
+
+## Quick start
+
+In a git repository:
+
+    overlane connect            # sign in, bind the project to the service, register the plugin for this project
+    overlane plugin install     # install the embedded plugin for Claude Code (and Codex, when `codex` is on PATH)
+    overlane doctor             # check that each agent is ready
+
+`overlane connect` reads the plugin marketplace from a stable folder under your data directory (`$XDG_DATA_HOME/mvrx-harness/marketplace`, default `~/.local/share/mvrx-harness/marketplace`; `MVRX_DATA_DIR` overrides the base). The package writes that folder from its embedded release the first time `connect`, `doctor` or `release` runs, so no separate step is needed before `connect`. The folder and the plugin id `mvrx-harness` keep their names for now so existing installs keep working (ADR 0034).
+
+`overlane plugin install [--scope project|user] [--client claude|codex]`:
+
+1. verifies every embedded plugin file against the embedded release manifest (sha256 per file and the release digest) and refuses to install if anything differs;
+2. copies the tree into the stable marketplace folder and verifies the copy;
+3. runs the clients' native commands: `claude plugin marketplace add`, `claude plugin marketplace update`, `claude plugin install mvrx-harness@mvrx-local --scope <scope>`, and for Codex `codex plugin marketplace add` and `codex plugin add` (Codex only when `codex` is on PATH).
+
+The default scope is `user`. Use `--scope project` to write the plugin into the current project's `.claude/settings.json`. The signature on a release is checked by `overlane release update` against the service key; the embedded manifest is checked for integrity only.
+
+Credentials: the npm package has no OS keychain module, so `overlane connect` keeps tokens in a 0600 file under `$XDG_CONFIG_HOME/mvrx-harness` (default `~/.config/mvrx-harness`). Nothing is written to the repository.
+
+## For AI agents
+
+`overlane` is built to be driven by an agent. Start here:
+
+    overlane context                 # one JSON briefing: auth, project, release, task, run, policy, next task, suggested commands
+    overlane search "<task>"         # local, no credentials: the 5 best commands for a task, as JSON
+    overlane schema <command>        # parameters (type, required, description), safety flags, result shape
+    overlane commands                # every command, with its effect: read, write or destructive
+
+- **Output.** JSON on stdout when stdout is not a terminal or with `--json`; text in a terminal or with `--text`. Messages go to stderr (`--verbose` keeps progress in JSON mode). A write with nothing to return prints `{"ok":true}`.
+- **Errors** are `{"error":{"code","message","hint","retryable"}}` on stderr; `hint` is the exact next command. Exit codes: 0 ok, 1 failure, 2 usage, 3 auth required, 4 not found, 5 conflict or precondition, 6 blocked by policy or budget, 7 service unreachable. Messages never contain a credential.
+- **Safety.** Every write takes `--dry-run`, which prints the requests it would send (method, path, body) and the files it would change, and needs no credentials. Destructive commands (`disconnect`, `release rollback`) need `--force` when stdin is not a terminal. Nothing prompts without a terminal.
+- **Auth.** `HARNESS_TOKEN` is used before stored credentials; `overlane auth status` reports the state without revealing the token. Browser sign-in stays for humans (`overlane connect`).
+- **Unknown commands** suggest the closest matches.
+
+Add this block to AGENTS.md or CLAUDE.md (`overlane agents-md` prints it):
+
+    <!-- overlane:cli:begin -->
+    ## Overlane
+
+    Agents: run `overlane context`, then `overlane search "<task>"`. `overlane schema <command>` gives exact flags; output is JSON when piped; exit codes: 0 ok, 2 usage, 3 auth, 4 not found, 5 conflict, 6 blocked by policy or budget, 7 unreachable; use `--dry-run` before a write.
+    <!-- overlane:cli:end -->
+
+## Cloud sessions
+
+The plugin hooks are Node scripts inside the installed plugin (`node ${CLAUDE_PLUGIN_ROOT}/scripts/...`); they need Node 22 and the plugin, not network access at install time. The `overlane` binary installs and updates the plugin and is what the agent calls for `overlane task ...`. Pin the version so a cloud session installs the same release every time.
+
+### Claude Code on the web
+
+In the environment's setup script:
+
+    npm i -g overlane@<version>
+    overlane plugin install --client claude --scope user
+
+Authentication to the service for cloud runs comes from the `HARNESS_TOKEN` environment secret that the plugin hooks and the CLI read; keep it in the environment's secrets, never in files in the repository.
+
+### Codex cloud
+
+In the environment's setup script (the setup phase has network access; the agent phase can then work offline):
+
+    npm i -g overlane@<version>
+    overlane plugin install --client codex
+
+Without the package manager, `npx -y overlane@<version> plugin install --client codex` does the same.
+
+### Background bots
+
+Bots that you message (chat or scheduled agents) do not need the CLI. They connect to Overlane through the remote MCP endpoint of the service, with a token held in the bot platform's secrets. The CLI and plugin are for sessions that have a shell and a working copy.
+
+## Code indexer and shim
+
+    overlane index build --scip FILE --out DIR --tenant ID
+    overlane index upload --service URL --tenant ID --repo owner/name --commit SHA
+
+`overlane index` parses TypeScript, TSX, JavaScript, Python and Zig with tree-sitter. The grammars ship in the package under `assets/` and are found relative to the installed bundle; `MVRX_ASSET_DIR` points at another folder.
+
+`overlane shim` serves the local code tools over MCP on stdio. The code layer is off by default (ADR 0018); nothing starts it unless a project configures it.
+
+## Environment
+
+| Variable | Effect |
+|---|---|
+| `HARNESS_TOKEN` | Service token, used before stored credentials |
+| `MVRX_DATA_DIR` | Base folder for the stable marketplace (default `$XDG_DATA_HOME/mvrx-harness`) |
+| `MVRX_ASSET_DIR` | Folder holding the tree-sitter wasm files (default `assets/` inside the package) |
+| `XDG_CONFIG_HOME` | Base for the user config folder `mvrx-harness` (credential fallback file, approvals) |
+
+The `MVRX_*` and `HARNESS_*` variable names and the `mvrx-harness` folder names are internal and stay until a later migration (ADR 0034).
+
+## Releases
+
+Releases are built by the repository's release workflow: it packs `overlane-<version>.tgz`, installs it into a clean prefix, runs a smoke test, attaches it to the GitHub release `v<version>`, and publishes to npm with provenance when the repository has an npm token.

package/dist/mvrx.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+globalThis.__OVERLANE_INVOKED_AS__ = "mvrx";
+await import("./overlane.mjs");