@cydm/pie 1.0.5 → 1.0.7

package/README.md

@@ -4,8 +4,6 @@
 
 It gives you a terminal-first agent experience out of the box, while staying modular enough to embed into other runtimes and products. Pie is designed for teams that want a small surface area, strong defaults, persistent sessions, tool use, and a clean path from CLI usage to deeper integration.
 
-Pie is heavily inspired by `pi`, while evolving in its own direction around modularity, embeddability, and a compact developer-facing workflow.
-
 Pie is developed by [cydream](https://cydream.tech).
 
 ## Why Pie
@@ -22,6 +20,8 @@ Pie is developed by [cydream](https://cydream.tech).
 npm install -g @cydm/pie
 ```
 
+Pie supports Node.js 20 and newer. Release builds are validated with npm's lockfile workflow (`npm ci`) so dependency resolution is reproducible.
+
 ## Quick Start
 
 Set an API key for the provider you want to use:
@@ -38,6 +38,71 @@ You can also configure defaults in:
 - `~/.pie/models.json`
 - `~/.pie/config.json` for legacy-compatible defaults
 
+Minimal `~/.pie/models.json`:
+
+```json
+{
+  "profiles": {
+    "cy-gpt": {
+      "api": "openai-completions",
+      "baseUrl": "https://token.magicshell.ai/v1",
+      "apiKey": "YOUR_API_KEY",
+      "models": [
+        {
+          "id": "gpt-5.4",
+          "name": "GPT 5.4",
+          "reasoning": true,
+          "input": ["text", "image"],
+          "contextWindow": 128000,
+          "maxTokens": 16384,
+          "cost": {
+            "input": 0,
+            "output": 0,
+            "cacheRead": 0,
+            "cacheWrite": 0
+          }
+        }
+      ]
+    }
+  },
+  "defaults": {
+    "provider": "cy-gpt",
+    "modelId": "gpt-5.4"
+  }
+}
+```
+
+Required profile fields:
+
+- `api`
+- `baseUrl`
+- `apiKey` or `apiKeyEnv`
+- `models`
+
+Required model fields:
+
+- `id`
+- `input`
+- `cost`
+- `contextWindow`
+- `maxTokens`
+
+Validate the file explicitly:
+
+```bash
+pie models validate
+pie models validate --path /abs/path/to/models.json
+```
+
+Generate a starter template:
+
+```bash
+pie models init
+pie models init --stdout
+```
+
+For editor auto-complete and validation, you can also point the optional `"$schema"` field in your local `models.json` at your installed `@cydm/pie/models.schema.json` file.
+
 Start Pie in interactive mode:
 
 ```bash
@@ -67,6 +132,17 @@ Pie is not just a chat CLI. It is a compact agent suite with a terminal UI on to
 
 If you want an agent that feels lightweight but still has serious capability, that is the design target for Pie.
 
+## Architecture Position
+
+`@cydm/pie` is the CLI product layer in the repo architecture.
+
+- `@pie/agent-core` provides runtime semantics and the agent loop
+- `@pie/agent-framework` provides shared application infrastructure such as sessions, skills, and extension protocols
+- `@pie/shared-headless-capabilities` provides shared headless capabilities used across hosts
+- `products/cli` adds terminal bindings, CLI workflows, and host-specific capabilities such as shell execution
+
+The CLI should consume shared capability and framework contracts; it should not redefine shared runtime or extension semantics locally.
+
 ## Interactive Experience
 
 Run:
@@ -102,6 +178,10 @@ Pie uses a hierarchical slash-command menu. The current built-in commands includ
 
 | Command | Description |
 | --- | --- |
+| `pie doctor [--json]` | Diagnose local config, model setup, writable paths, browser automation, and Unity bridge hints |
+| `pie models init` | Create a starter `~/.pie/models.json` |
+| `pie models validate` | Validate `~/.pie/models.json` |
+| `pie permissions` | Explain tool and shell safety defaults |
 | `/sessions/compact` | Summarize history and create a compact checkpoint |
 | `/sessions/new` | Start a new session |
 | `/sessions/resume` | Resume a different session |
@@ -119,9 +199,9 @@ Pie uses a hierarchical slash-command menu. The current built-in commands includ
 | `/skills/use` | Use a skill |
 | `/skills/reload` | Reload skills from disk |
 | `/tools/subagent` | Spawn a subagent for a task |
-| `/debugs/cache-test` | Test context caching |
-| `/debugs/context` | Dump raw context for debugging |
-| `/debugs/package` | Dump raw request and response payloads |
+| `/debugs/cache-test` | Run provider cache diagnostics with a dedicated 2-request probe |
+| `/debugs/context` | Append a context summary to `~/.pie/logs/pie-cli.log` |
+| `/debugs/package` | Append a package summary to `~/.pie/logs/pie-cli.log` |
 
 Pie can also load extension-provided commands at runtime.
 
@@ -147,6 +227,55 @@ Pie supports Markdown-based skills and built-in extensions.
 
 That is part of what makes Pie embeddable: the CLI is only one interface on top of a broader agent toolkit.
 
+## Browser Tools
+
+The built-in `browser-tools` skill uses Microsoft's Playwright CLI for visible browser automation. Its runtime dependencies ship with the CLI; do not run `npm install` inside the skill directory.
+
+Resolve the skill resource and run Playwright commands:
+
+```bash
+node <resolvedPath for browser-tools/playwright-cli.js> open https://example.com
+node <resolvedPath for browser-tools/playwright-cli.js> snapshot
+node <resolvedPath for browser-tools/playwright-cli.js> screenshot
+node <resolvedPath for browser-tools/playwright-cli.js> console
+node <resolvedPath for browser-tools/playwright-cli.js> network
+```
+
+If Playwright's Chromium browser is not installed, run:
+
+```bash
+node <resolvedPath for browser-tools/playwright-cli.js> install-browser chromium
+```
+
+Run `pie doctor` to check whether Playwright CLI and its browser runtime are discoverable.
+
+## Web Search
+
+Pie exposes a canonical `web_search` tool for public web research, current information, online documentation, and internet inspiration. Workspace search remains separate: use `grep_text`, `find_files`, and `list_dir` for local repository content.
+
+`web_search` uses provider-native web search where supported. It does not scrape DuckDuckGo or fall back to `bash` with `curl` or Python HTTP scripts. If the current provider/model cannot perform native web search, the tool returns a clear unavailable result with provider/configuration details.
+
+Use `web_fetch` after search when the agent needs to read a specific URL, documentation page, changelog, issue, or PDF. `web_fetch` follows redirects, extracts readable text/markdown, returns citation anchors and extraction diagnostics, and reports `requires_browser` for JavaScript-heavy pages instead of pretending the content was read.
+
+## Permissions
+
+Pie's default tools operate from the current workspace. File tools are workspace-scoped, `~/.pie` is allowlisted for Pie configuration/session support, and shell commands return structured timeout/truncation/error details. The canonical shell tool is still named `bash` for compatibility; on Windows `shell:auto` uses PowerShell, and callers can explicitly request `bash`, `powershell`, or `cmd`. High-risk shell commands require confirmation outside YOLO mode. `/settings/yolo` relaxes filesystem sandbox directory restrictions and should only be used in trusted workspaces. `pie permissions` prints the current policy-derived safety summary.
+
+## Code Intelligence
+
+`code_intel` provides read-only JS/TS diagnostics, definition, references, symbols, and hover. CLI uses the TypeScript language service by default and falls back to lightweight text analysis only when the TypeScript service cannot start. Unity uses a Node sidecar contract for TypeScript intelligence so the PuerTS bundle does not import Node-only parser dependencies.
+
+## Diagnostics
+
+Use:
+
+```bash
+pie doctor
+pie doctor --json
+```
+
+Doctor checks Node/npm, model configuration, API key availability, writable Pie data paths, Playwright browser readiness, Unity bridge hints, and runtime log location. User-facing errors stay concise; detailed debugging goes to `~/.pie/logs/pie-cli.log` and session trace artifacts.
+
 ## Output Modes
 
 For non-interactive usage, Pie supports structured output options:
@@ -168,12 +297,36 @@ For the best multiline editing experience, use a terminal with good modified-key
 ## Development
 
 ```bash
-cd products/cli
-npm install
-npm run build
-npm run test:offline
+npm ci
+npm run verify:quality
+npm run verify:release
+npm run verify:browser
+npm run verify:terminal:matrix
+```
+
+Use `npm run verify:agent` when model credentials are available and you want the real daily agent gate.
+Use `npm run verify:agent:nightly` and `npm run verify:unity:reliability` before release candidates that claim real-provider or Unity reliability.
+Set `PIE_REAL_BROWSER=1` when you want `verify:browser` to open a real browser session instead of only checking the Playwright CLI contract.
+
+## Publishing
+
+Publish `@cydm/pie` from the monorepo root.
+
+Set the npm token first:
+
+```bash
+npm config set //registry.npmjs.org/:_authToken <YOUR_TOKEN>
 ```
 
+Then publish:
+
+```bash
+npm run verify:release
+npm publish --workspace products/cli --access public
+```
+
+If the package version already exists on npm, bump `products/cli/package.json` first.
+
 ## License
 
 MIT