@bastani/atomic 0.9.19-alpha.1 → 0.9.19-alpha.10

package/docs/development.md

@@ -8,18 +8,20 @@ See [AGENTS.md](https://github.com/bastani-inc/atomic/blob/main/AGENTS.md) for a
 git clone https://github.com/bastani-inc/atomic
 cd atomic
 npm ci --ignore-scripts
-npm run typecheck
+npm run build
 ```
 
-This monorepo runs a hybrid toolchain matching upstream pi: npm installs, builds, checks, and runs the vitest suites, while Bun compiles the release binaries and runs `scripts/*.ts`. Avoid yarn and pnpm. Run package scripts from the monorepo root or a package directory, for example:
+Use npm for installs, builds, checks, and Vitest suites. Bun compiles standalone binaries and runs repository TypeScript scripts. Do not use yarn, pnpm, or `bun install`.
+
+Atomic keeps the caller's current working directory when launched from development wrappers.
+
+Run package scripts from the monorepo root or a package directory, for example:
 
 ```bash
 npm run test:unit
 npm run build --workspace=@bastani/atomic
 ```
 
-Atomic keeps the caller's current working directory when launched from development wrappers.
-
 ## Forking / Rebranding
 
 Configure via `package.json`:
@@ -33,7 +35,9 @@ Configure via `package.json`:
 }
 ```
 
-Change `name`, `configDir`, and the `bin` field for your fork. The app-specific `<appName>Config` key is preferred; legacy `piConfig` remains a backwards-compatible shim. Atomic sets these to `atomic`, `.atomic`, and the `atomic` executable. Affects CLI banner, config paths, and environment variable names.
+Change `name`, `configDir`, and the `bin` field for your fork. These control the CLI banner, config paths, and environment variable names. Legacy `piConfig` remains a compatibility fallback.
+
+The app-specific `<appName>Config` key is preferred. Atomic sets these to `atomic`, `.atomic`, and the `atomic` executable.
 
 ## Path Resolution
 
@@ -53,8 +57,23 @@ Never use `__dirname` directly for package assets.
 - Rendered TUI lines with ANSI codes
 - Last messages sent to the LLM
 
+For startup measurements, see the [Windows startup benchmark](https://github.com/bastani-inc/atomic/blob/main/scripts/perf/windows-startup/README.md). Internal timing marks do not prove terminal first paint.
+
+## PDF and engine diagnostics
+
+PDF conversion and engine diagnostics appear as status messages in interactive sessions
+and console output otherwise. Conversion failures also include diagnostic details in
+their error result. Long or noisy diagnostics may be truncated. Interactive sessions keep
+only recent diagnostics; older diagnostics are discarded without removing normal chat.
+
+Diagnostics are displayed as text, not terminal commands. RPC clients receive diagnostics
+separately from JSON responses. No `atomic-engine-stderr.log` file is written; include the
+displayed diagnostic and conversion error when reporting a PDF problem.
+
 ## Startup timing probes
 
+Use the [current startup benchmark instructions](https://github.com/bastani-inc/atomic/blob/main/scripts/perf/windows-startup/README.md).
+
 Use `scripts/perf/windows-startup/benchmark.ts` for Windows startup claims. It launches the ordinary bare `atomic` command through a real 120x40 ConPTY, feeds ordered output into `@xterm/headless`, and timestamps each receive with `process.hrtime.bigint()`. Complete first paint requires the final `Atomic v<version>` identity, the focused `❯ ` editor, and two identical settled frames at least one 80 ms animation interval apart. `dispatchMs` runs from the Enter write to the first byte observed by a raw TCP loopback provider. The headline `spawnToDispatchMs` is exactly `startupCompleteMs + dispatchMs`; `launchToProviderFirstByteMs` separately retains the contiguous launch-to-provider interval that also contains nonce typing and editor-echo wait. The provider request must contain the nonce and the normal tool schemas, and every accepted sample must pass `/workflow list` after the timed response. See [the benchmark README](https://github.com/bastani-inc/atomic/blob/main/scripts/perf/windows-startup/README.md) for artifact preparation, cache profiles, raw records, and summary commands.
 
 Do not use `time-to-first-frame` as settled-paint evidence, and do not substitute `launchToProviderFirstByteMs` for the contract sum. The first-frame mark records the host's first requested identity frame after the header is mounted; it does not prove terminal receipt, animation settlement, engine resource readiness, or provider readiness. `ATOMIC_STARTUP_BENCHMARK=1`, `--no-extensions`, and `--no-tools` are attribution controls only. They do not run the accepted full CLI path with bundled workflows, normal extensions, tools, and provider dispatch.
@@ -80,41 +99,45 @@ The header and editor are mounted before the host waits for `engine-bound`; the
 
 For package-manager installs under Node 22, Atomic enables Node's persistent module compile cache in both the host and isolated child and flushes the host cache before spawning the child. Explicit `NODE_COMPILE_CACHE` and `NODE_DISABLE_COMPILE_CACHE` settings pass through unchanged. This preserves Node's coverage opt-out and avoids forcing a new cache directory or a first-run-only precompile step. SEA, V8 snapshots, and package-install precompilation were not adopted because Atomic's dynamic ESM, native modules, workers, and first-run requirements do not provide a safe portable boundary.
 
-Compiled releases syntax-minify the shared CJS `app.js` sidecar without identifier minification and compile launchers with bytecode on all eight supported targets, including Windows x64 and ARM64. `bun run scripts/probe-windows-bytecode.ts` pins Bun 1.4.0, cross-compiles `bun-windows-x64-baseline` and `bun-windows-arm64` launchers, and verifies their PE machine types. Atomic observed a Bun 1.3.14 Windows startup crash in `llint_entry`, but Bun 1.4.0 already contains the embedded-bytecode alignment fix ([#26299](https://github.com/oven-sh/bun/pull/26299)) and integrity fallback ([#31961](https://github.com/oven-sh/bun/pull/31961)); the separate Bun 1.4.0 Windows report ([#40302](https://github.com/oven-sh/bun/issues/40302)) concerns a general standalone/JIT segfault and has not been shown to be bytecode-specific. Cross-compilation is not runtime validation: release candidates still require full-archive target-machine coverage of the TUI, workflows, tools, extensions, workers, and native add-ons, with Windows ARM64 validated on ARM64 hardware.
-
 Set `ATOMIC_TIMING=1` only for the older human-readable phase diagnostics. Normal interactive launches print that initial timing group before `interactiveMode.run()` starts the TUI loop, so later marks are not printed during ordinary sessions.
 
+For the current Bun version, Windows-hosted bytecode requirement, and archive-validation caveats, see [Windows interactive startup](/windows#interactive-startup).
+
 ## Testing
 
 ```bash
-npm run typecheck                 # Type-check the monorepo
-npm run test:unit                 # Run unit tests
-npm run test:integration          # Run integration tests
-npm run test:all                  # Run all tests
-npm run test:scripts              # Run the repository script tests under node --test
-# Run the package Vitest suite (Node-hosted)
+npm run check                    # Typechecks and published-shrinkwrap validation
+npm run test:unit                # Root unit tests
+npm run test:integration         # Root integration tests
+npm run test:all                 # All root test projects
+npm run test:scripts             # Repository script tests under Node
 npm run test --workspace=@bastani/atomic -- test/specific.test.ts
 ```
 
-Root Vitest projects install a fresh in-memory durable backend before every test.
-Durability initialization imports the backend and its process owner rather than
-preloading the DBOS factory or the Atomic host. A test that needs host prototype
-installers must import those real modules explicitly rather than depend on a
-side effect of shared setup. Test-local backend overrides still use the factory's
-injection seam, and the next test receives a fresh backend without resetting
-unrelated initialization or warning state. Keep the global artifact/native setups,
-default isolation, worker sizing and timeout budgets unchanged when measuring
-test cost. See the [CI measurements](https://github.com/bastani-inc/atomic/blob/main/docs/ci.md#current-critical-path-measured-september-5-2026)
-for local gains and the remaining hosted Linux/Windows validation.
-
-CI runs the complete root unit and integration suites in independent Linux and
-Windows jobs. Each builds its own native and package prerequisites; both required
-result gates wait for every work job and reject failures, cancellations and skips.
-This trades duplicated setup for earlier integration feedback without changing
-test isolation, coverage or retries.
+CI runs root unit and integration suites on Linux and Windows. See [CI documentation](https://github.com/bastani-inc/atomic/blob/main/docs/ci.md) for job details and release procedures.
+
+To run only the typechecks:
+
+```bash
+npm run typecheck                 # Type-check the monorepo
+```
+
+### Installed package smoke test
+
+After building, run:
+
+```bash
+ATOMIC_REQUIRE_INSTALLED_NODE_SMOKE=1 npx vitest --run --project integration test/integration/installed-package-node-extensions.test.ts
+```
+
+This checks Node startup and builtin extension loading outside the checkout.
+
+Atomic ships an npm shrinkwrap. After dependency changes, regenerate it with `npm run shrinkwrap:coding-agent` and validate with `npm run check`.
 
 ## Deterministic installs
 
+See [Testing](#testing) for the current shrinkwrap commands.
+
 `@bastani/atomic` ships `packages/coding-agent/npm-shrinkwrap.json` so package-manager installs resolve the same dependency tree every time. Contributors working from a source checkout can validate that the checked-in shrinkwrap is up to date with:
 
 ```bash
@@ -123,10 +146,25 @@ bun run scripts/generate-coding-agent-shrinkwrap.mjs --check
 
 ## Release security boundary
 
-Atomic's release bases remain at the `0.0.0` placeholder. `scripts/cut-release.ts` stamps the real version only on a detached tagged release commit. Tag creation runs an inert signal workflow; a separate `workflow_run` publisher loaded from protected `main` validates the exact upstream repository, source workflow/event/run, tag/SHA, immutable release-base trailers, and deterministic release tree. The privileged trigger checks out only protected workflow code: it treats the tag tree as data, exports it only after deterministic verification, and makes every read-only build verify the protected job's source checksum instead of checking out tag-selected code. Same-run artifact transport failures receive at most one retry after partial-download cleanup and still fail explicitly on the second error; verified source archives are streamed to tar over stdin for portable Windows drive-letter handling. Preparation restores the digest-verified source after documentation validation before producing artifacts. Release-source jobs configure no dependency cache, npm publication has OIDC without repository write, and GitHub Release creation has repository write without OIDC. Never move or recreate a failed release tag or dispatch the privileged publisher. See the repository's [CI/CD pipeline](https://github.com/bastani-inc/atomic/blob/main/docs/ci.md#release-pipeline) for trusted-publisher configuration.
+Follow the [current release pipeline](https://github.com/bastani-inc/atomic/blob/main/docs/ci.md#release-pipeline).
+
+Atomic's release bases remain at the `0.0.0` placeholder. `scripts/cut-release.ts` stamps the real version only on a detached tagged release commit.
 
 ## Project Structure
 
+```text
+packages/
+  ai/           # Atomic's LLM provider fork
+  coding-agent/ # CLI, interactive mode, and core runtime
+  workflows/    # Workflow execution
+  subagents/    # Subagent orchestration
+  mcp/          # MCP adapter
+  web-access/   # Web search and content extraction
+  intercom/     # Cross-session coordination
+```
+
+The bundled companion-package roles are:
+
 ```
 packages/
   coding-agent/ # Atomic CLI, agent loop, providers, TUI, and core runtime

package/docs/docs.json

@@ -10,95 +10,221 @@
     "dark": "#1D4ED8"
   },
   "navigation": {
-    "groups": [
+    "tabs": [
       {
-        "group": "Start here",
-        "pages": [
-          "index",
-          "quickstart",
-          "usage",
-          "providers",
-          "environment-variables",
-          "llama-cpp",
-          "containerization",
-          "security",
-          "settings",
-          "keybindings",
-          "sessions",
-          "compaction"
+        "tab": "Learn",
+        "groups": [
+          {
+            "group": "Overview",
+            "pages": [
+              "index"
+            ]
+          },
+          {
+            "group": "Quickstart",
+            "pages": [
+              "quickstart",
+              "getting-started/installation",
+              "getting-started/authentication",
+              "getting-started/first-session",
+              "getting-started/project-instructions"
+            ]
+          },
+          {
+            "group": "Start here",
+            "pages": [
+              "guides"
+            ]
+          },
+          {
+            "group": "Everyday use",
+            "pages": [
+              "usage",
+              "guides/non-interactive",
+              "sessions",
+              "compaction",
+              "guides/configuration"
+            ]
+          },
+          {
+            "group": "Running work for you",
+            "pages": [
+              "guides/workflows",
+              "guides/subagents",
+              "background-tasks",
+              "guides/intercom",
+              "computer-use"
+            ]
+          },
+          {
+            "group": "Models and providers",
+            "pages": [
+              "providers",
+              "llama-cpp"
+            ]
+          },
+          {
+            "group": "Safety and isolation",
+            "pages": [
+              "security",
+              "containerization"
+            ]
+          }
         ]
       },
       {
-        "group": "Customization",
-        "pages": [
-          "extensions",
-          "skills",
-          "subagents",
-          "intercom",
-          {
-            "group": "Workflows",
-            "pages": [
-              "workflows",
-              "workflows/builtins",
-              "workflows/authoring",
-              "workflows/reliable-design",
-              "workflows/verification",
-              "workflows/operations",
-              "workflows/api-reference"
+        "tab": "Build",
+        "groups": [
+          {
+            "group": "Build with Atomic",
+            "pages": [
+              "build"
             ]
           },
-          "prompt-templates",
-          "themes",
-          "packages",
           {
-            "group": "Models",
+            "group": "Extend a session",
+            "pages": [
+              {
+                "group": "Skills",
+                "pages": [
+                  "skills",
+                  "skills/authoring"
+                ]
+              },
+              "prompt-templates",
+              "themes",
+              {
+                "group": "Extensions",
+                "pages": [
+                  "extensions",
+                  "extensions/authoring",
+                  "extensions/events",
+                  "extensions/ui",
+                  "extensions/examples"
+                ]
+              }
+            ]
+          },
+          {
+            "group": "Orchestrate work",
+            "pages": [
+              {
+                "group": "Workflows",
+                "pages": [
+                  "workflows",
+                  "workflows/builtins",
+                  "workflows/authoring",
+                  "workflows/reliable-design",
+                  "workflows/verification",
+                  "workflows/operations",
+                  "workflows/api-reference"
+                ]
+              },
+              {
+                "group": "Subagents",
+                "pages": [
+                  "subagents",
+                  "subagents/authoring"
+                ]
+              },
+              {
+                "group": "Intercom",
+                "pages": [
+                  "intercom",
+                  "intercom/operations"
+                ]
+              }
+            ]
+          },
+          {
+            "group": "Distribute",
+            "pages": [
+              "packages",
+              "packages/authoring"
+            ]
+          },
+          {
+            "group": "Models and providers",
             "pages": [
               "models",
               "models/model-selection",
               "models/pareto-efficiency",
-              "models/evals"
+              "models/evals",
+              "custom-provider",
+              "custom-provider/override",
+              "custom-provider/registration",
+              "custom-provider/oauth",
+              "custom-provider/streaming"
             ]
           },
-          "custom-provider"
-        ]
-      },
-      {
-        "group": "Reference",
-        "pages": [
-          "tools",
-          "tools/edit",
-          "session-format"
-        ]
-      },
-      {
-        "group": "Programmatic Usage",
-        "pages": [
-          "sdk",
-          "rpc",
-          "json",
-          "tui"
-        ]
-      },
-      {
-        "group": "Platform Setup",
-        "pages": [
-          "windows",
-          "termux",
-          "tmux",
-          "terminal-setup",
-          "shell-aliases"
-        ]
-      },
-      {
-        "group": "Development",
-        "pages": [
-          "development"
+          {
+            "group": "Programmatic use",
+            "pages": [
+              "programmatic",
+              "sdk",
+              "rpc",
+              "rpc/extension-ui",
+              "rpc/examples",
+              "json",
+              "tui"
+            ]
+          }
         ]
       },
       {
-        "group": "Changelog",
-        "pages": [
-          "changelog"
+        "tab": "Reference",
+        "groups": [
+          {
+            "group": "Reference",
+            "pages": [
+              "reference",
+              "reference/cli",
+              "settings",
+              "environment-variables",
+              "keybindings",
+              "tools",
+              "tools/edit",
+              "web-access",
+              "session-format"
+            ]
+          },
+          {
+            "group": "Domain reference",
+            "pages": [
+              "providers/reference",
+              "models/reference",
+              "compaction/reference",
+              "skills/reference",
+              "subagents/reference",
+              "intercom/reference",
+              "packages/reference",
+              "themes/reference",
+              "extensions/api-reference",
+              "custom-provider/api-reference",
+              "sdk/reference",
+              "rpc/protocol",
+              "tui/reference"
+            ]
+          },
+          {
+            "group": "Platform setup",
+            "pages": [
+              "windows",
+              "termux",
+              "terminal-setup",
+              "tmux",
+              "herdr",
+              "shell-aliases"
+            ]
+          },
+          {
+            "group": "Project",
+            "pages": [
+              "development",
+              "changelog",
+              "models/artificial-analysis-index"
+            ]
+          }
         ]
       }
     ]

package/docs/environment-variables.md

@@ -13,7 +13,7 @@ Atomic accepts environment variables for configuration, provider credentials, an
 | `ATOMIC_SKIP_VERSION_CHECK` | `PI_SKIP_VERSION_CHECK` | Skip automatic startup version checks; explicit self-update still checks |
 | `ATOMIC_TELEMETRY` | `PI_TELEMETRY` | Enable/disable install/update telemetry |
 | `ATOMIC_REDUCED_MOTION` | `PI_REDUCED_MOTION` | Use static reduced-motion presentation |
-| `ATOMIC_EXPERIMENTAL` | `PI_EXPERIMENTAL` | Set to `1` to enable experimental features: built-in tool definitions request strict JSON-schema constrained sampling (`prefer`), and the footer shows an `xp` badge |
+| `ATOMIC_EXPERIMENTAL` | `PI_EXPERIMENTAL` | Set to `1` to enable experimental features and preferred strict JSON-schema constrained sampling for additional built-in tools; `read`, `edit`, `write`, `bash`, and PowerShell already prefer strict sampling by default. The footer shows an `xp` badge |
 
 `PI_CACHE_RETENTION=long` is a provider/upstream prompt-cache option and intentionally has no Atomic-prefixed alias. `VISUAL` and `EDITOR` select the Ctrl+G external editor when `externalEditor` is unset.
 
@@ -43,4 +43,4 @@ Every built-in, factory-created, direct, workflow-stage, and isolated bash or Po
 
 Atomic clears these ten reserved names before overlaying the current snapshot, preventing stale metadata from another session or workflow stage. Unrelated inherited/caller variables remain intact. The snapshot is taken when execution begins, so a resumed session or later model change is reflected. SDK `createBashTool()` and `createPowerShellTool()` expose it by default; set `exposeSessionEnvironment: false` to opt out.
 
-See [Using Atomic](/usage#environment-variables) and [RPC direct bash](/rpc#bash) for execution and streaming behavior.
+See [Using Atomic](/reference/cli#environment-variables) and [RPC direct bash](/rpc/protocol#bash) for execution and streaming behavior.