agenttwin 0.3.6 → 0.3.7

package/README.md

@@ -10,10 +10,15 @@ Node.js 22.12+ is required. Run discovery from your project; npx installs the CL
 
 ```sh
 npx agenttwin init
-npx agenttwin example --out ./agenttwin-example
 ```
 
-`init` writes the inventory, workflow candidates, `agenttwin.config.json`, `ENVIRONMENT.md`, `REPLICATION.md`, and an offline browser report. Discovery is evidence, not an automatically executable environment. It never uploads source. `init --json --dry-run` writes nothing.
+`init` discovers your repository and opens a persistent control menu. Bare `npx agenttwin` opens the same entry point. Select a reviewed world, inspect every service's support, run correctness checks, explore seeded faults, replay a failure, verify a source-only patch, save a regression, import an incident, or connect your account—all from this menu, without remembering flags or separate command names. `npx agenttwin refresh` updates discovery without executing application code. Existing advanced commands remain available to CI and coding agents.
+
+Discovery writes the inventory, workflow candidates, `agenttwin.config.json`, `ENVIRONMENT.md`, `REPLICATION.md`, and an offline browser report. A discovered candidate is not an executable specification: the menu accepts a reviewed `agenttwin.world.json` with explicit bundled Node files, synthetic services, invocation and required outcomes. The optional demo is clearly labeled as synthetic. Redirected input and `--yes` only perform discovery; they never start the interactive execution loop. `init --json --dry-run` writes nothing. Account sharing is explicit; having an existing token does not automatically upload evidence during init.
+
+Seeded exploration includes an unfaulted control and up to 31 timeout-after-write trials. A seed controls the selected service/path and delay, not OS scheduling or arbitrary application randomness. Each trial uses fresh service state. Captured application files, checks, fault cases and receipts stay under `.agenttwin/explorations/`. Replay uses the captured application; patch verification uses current application files with the captured checks and fault cases. Hash mismatches reject accidental snapshot edits. This is local evidence, not a tamper-proof security boundary; protected CI anchors saved regression checks in a trusted Git baseline. Unexercised fault targets and unsupported provider operations remain incomplete.
+
+This guided entry point describes the current source checkout. It reaches public `npx` users only after this package is published; verify the installed version when using a registry release.
 
 Installed packages and source references are clues, not proof that an integration is active. Credentials, environment keys and deployment configuration are kept separately. Unmatched `.env` entries do not require setup and are never turned into services by an interactive prompt.
 
@@ -34,7 +39,7 @@ Run from your original repository so receipts stay in its `.agenttwin/runs/` dir
 
 ## Optional cloud execution through an AgentTwin API
 
-Your operator supplies the API URL and your individual token:
+Sign in with `npx agenttwin login`. For an operator-managed API, you can instead supply its URL and individual token:
 
 ```sh
 export AGENTTWIN_API_URL=https://your-agenttwin-api.example.com
@@ -87,7 +92,7 @@ MIT license.
 
 `agenttwin init --yes` detects project dependencies, tooling and available connector configuration, then writes `.agenttwin/dashboard/index.html`. Open that file to review the detected environment without selecting every connector or uploading inventory. The dashboard includes its assets and an allowlisted discovery payload; account records, credential values and evidence paths are excluded. It starts with no saved run receipts. Detection does not verify provider access or implement an adapter.
 
-The website starts empty and does not import this repository’s inventory automatically. Connect your individual API account in Settings and run `npx agenttwin sync` with `AGENTTWIN_TOKEN` configured, or import discovery JSON manually. Removed detected resources stay excluded until a fresh discovery revision. The generated project dashboard loads its own embedded discovery.
+The website starts empty and does not import this repository’s inventory automatically. Create an account on the website, connect your terminal with `npx agenttwin login`, and run `npx agenttwin sync`, or import discovery JSON manually. Removed detected resources stay excluded until a fresh discovery revision. The generated project dashboard loads its own embedded discovery.
 
 ## Prepare an actual discovered workflow
 
@@ -122,13 +127,19 @@ The output contains your unchanged source, a world spec, a SHA-256 manifest, and
 Supported mapping contracts: bounded Slack operations, PostgreSQL, Redis and custom JSON collections (`GET /path` / `POST /path`). Preparation rejects missing/unreviewed mappings and unsupported vendor SDK operations. Discovery and mappings remain user-reviewed declarations, not proof that every operation or dependency in arbitrary source was discovered. Hosted execution checks the declared assertions.
 
 
+### Updates
+
+Interactive `npx agenttwin` and `npx agenttwin init` check the official npm registry on startup and automatically install and run a newer stable release in the same repository. Offline startup continues with an explicit warning. Updates do not run in CI, noninteractive/JSON mode, dry runs, or advanced automation commands. Set `AGENTTWIN_AUTO_UPDATE=0` to retain an installed release; checkouts ahead of the published release are never downgraded.
+
+Older releases without this updater cannot update themselves. After the new release is published, bootstrap once with `npx --yes agenttwin@latest init`; normal guided use remains `npx agenttwin init`. npm can otherwise resolve a local or cached older package.
+
 ### Coding session and dashboard discovery
 
-Run `npx agenttwin init` inside your repository (Node.js 22.12+). Interactive init offers an OpenCode session when the CLI is installed; `npx agenttwin init --agent opencode` launches explicitly with your configured provider and its normal permission controls. Provider authentication and usage belong to your coding-agent account. Other coding agents can use `.agenttwin/AGENT-TASK.md`.
+Run `npx agenttwin init` inside your repository (Node.js 22.12+). Interactive init opens the guided repository menu and offers account connection and reviewed project sharing. It does not launch another coding agent automatically. `npx agenttwin init --agent opencode` launches OpenCode explicitly with your configured provider and its normal permission controls. Provider authentication and usage belong to your coding-agent account. Other coding agents can use `.agenttwin/AGENT-TASK.md`.
 
 The session traces workflows across files, records intents and production failure hypotheses in `.agenttwin/WORKFLOWS.md`, and writes metadata to `.agenttwin/agent-discovery.json`. Static candidates retain their original evidence. Agent candidates remain unverified until the workflow is explicitly prepared and executed. Static discovery preserves distinct exported side-effect entrypoints, including repositories with 100 candidates; it does not prove that every business workflow has been found.
 
-After reviewing discovery, configure `AGENTTWIN_TOKEN` using your individual account token (never paste it into an agent prompt) and run `npx agenttwin sync`. Optional `AGENTTWIN_API_URL` selects your API. The website loads account discovery after you connect in Settings, then refreshes while visible. Sync sends names, operations and relative entrypoint metadata; application source uploads happen separately through reviewed bundles. Avoid sensitive names or identifiers in discovery metadata.
+Create a workspace at https://agenttwin.si/signup/ or run `npx agenttwin login` from your repository. Run `npx agenttwin init`, review discovery, then choose account connection and approve sharing in the guided menu. Sign in in your browser and enter the code shown in the terminal when prompted. Terminal credentials are stored with owner-only permissions in `~/.agenttwin/credentials.json`, outside your repository. You can still supply `AGENTTWIN_TOKEN` for automation. Optional `AGENTTWIN_API_URL` selects your API. The website loads account discovery after you connect in Settings, then refreshes while visible. Sync sends names, operations and relative entrypoint metadata; application source uploads happen separately through reviewed bundles. Avoid sensitive names or identifiers in discovery metadata.
 
 To execute a workflow, supply an executable Node entrypoint, reviewed supported dependency mappings, synthetic fixtures and expected observable outcomes. Run `npx agenttwin prepare --file preparation.json`, review the bundle, and run it through your AgentTwin API or E2B account. Browser/desktop automation and arbitrary vendor SDKs require additional runtimes/adapters. The CLI is the default runner; select a hosted runner only when the workflow requires it. No local Docker is used.