better-dsh 0.2.5 → 0.3.0-a

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/pi-and-omp/pi/development.md

@@ -1,96 +0,0 @@
-<!--
-source: https://pi.dev/docs/latest/development
-fetched: 2026-09-06
--->
-
-# Development
-
-See [AGENTS.md](https://github.com/earendil-works/pi-mono/blob/main/AGENTS.md) for additional guidelines.
-
-## Setup
-
-```
-git clone https://github.com/earendil-works/pi-mono
-cd pi-mono
-npm install
-npm run build
-```
-
-Run from source:
-
-```
-/path/to/pi-mono/pi-test.sh
-```
-
-The script can be run from any directory. Pi keeps the caller's current working directory.
-
-### Experimental remote harness
-
-The remote harness server/client integration is development-only. Run it from the repository with:
-
-```
-PI_EXPERIMENTAL=1 ./pi-test.sh server
-PI_EXPERIMENTAL=1 ./pi-test.sh client
-```
-
-`PI_SERVER_DIR` overrides the server profile and socket directory (default: `~/.pi/server`). `PI_SERVER_ID` selects the logical server ID when `--server-id` is omitted.
-
-The `client` and `experimental/plugin` package subpaths resolve only under the `source` condition in a checkout. Their implementations and the server/client commands are excluded from npm packages and standalone binaries. `pi-client`, `pi-protocol`, and `pi-server` are development dependencies of coding-agent, not runtime dependencies. The local SDK and stdio RPC API are unchanged.
-
-## Forking / Rebranding
-
-Configure via `package.json`:
-
-```
-{
-  "piConfig": {
-    "name": "pi",
-    "configDir": ".pi"
-  }
-}
-```
-
-Change `name`, `configDir`, and `bin` field for your fork. Affects CLI banner, config paths, and environment variable names.
-
-## Path Resolution
-
-Three execution modes: npm install, standalone binary, tsx from source.
-
-**Always use `src/config.ts`** for package assets:
-
-```
-import { getPackageDir, getThemeDir } from "./config.js";
-```
-
-Never use `__dirname` directly for package assets.
-
-## Debug Command
-
-`/debug` (hidden) writes to `~/.pi/agent/pi-debug.log`:
-
-- Rendered TUI lines with ANSI codes
-- Last messages sent to the LLM
-
-## Testing
-
-```
-./test.sh                         # Run non-LLM tests (no API keys needed)
-npm test                          # Run all tests
-npm test -- test/specific.test.ts # Run specific test
-```
-
-### Published package smoke test
-
-After building, run `npm run check:package-install`. It packs the public packages and installs only coding-agent as a direct dependency in a temporary directory outside the repository. Local tarball overrides select declared transitive dependencies without installing development-only packages. The check verifies SDK imports and CLI startup without credentials or model requests.
-
-`npm run check` also checks runtime dependency declarations and rejects excluded development sources pulled into a package's build through imports.
-
-## Project Structure
-
-```
-packages/
-  ai/           # LLM provider abstraction
-  agent/        # Agent loop and message types  
-  tui/          # Terminal UI components
-  coding-agent/ # CLI and interactive mode
-```

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/pi-and-omp/pi/environment-variables.md

@@ -1,104 +0,0 @@
-<!--
-source: https://pi.dev/docs/latest/environment-variables
-fetched: 2026-09-06
--->
-
-# Environment Variables
-
-Pi uses environment variables in three ways:
-
-- Variables such as `PI_OFFLINE` configure the Pi process.
-- Pi sets process markers so child processes can identify Pi as the launching agent.
-- Commands run by the LLM-callable shell tools receive `PI_*` variables describing the current session.
-
-Provider API-key variables are documented separately in [Providers](/docs/latest/providers#environment-variables-or-auth-file).
-
-## Process Marker
-
-The CLI and RPC entry points set two process markers:
-
-- `AI_AGENT=pi` is a generic marker that lets tooling identify Pi as the agent that launched the process.
-- `PI_CODING_AGENT=true` is Pi-specific and lets child processes detect that they run inside Pi.
-
-Child processes inherit both markers. They are not session-specific and are not set automatically when Pi is embedded through the SDK.
-
-## Shell Tool Session Environment
-
-Commands run by the `bash` and `powershell` tools receive the current Pi session state:
-
-| Variable | Description |
-| --- | --- |
-| `PI_SESSION_ID` | Current session ID |
-| `PI_SESSION_FILE` | Absolute path to the current session JSONL file; unset for ephemeral sessions |
-| `PI_PROVIDER` | Currently selected model provider |
-| `PI_MODEL` | Currently selected model ID |
-| `PI_REASONING_LEVEL` | Current effective reasoning level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` |
-
-The values are resolved when each command starts. Switching models or changing the reasoning level therefore affects the next shell command without restarting Pi. `PI_PROVIDER` and `PI_MODEL` identify the selected Pi model, not a different upstream model that a router may choose internally.
-
-When asked which model or provider is running, inspect these variables instead of inferring the answer from the system prompt:
-
-```
-printf '%s/%s\n' "$PI_PROVIDER" "$PI_MODEL"
-printf 'reasoning=%s session=%s\n' "$PI_REASONING_LEVEL" "$PI_SESSION_ID"
-```
-
-The session file can be inspected directly when the session is persistent:
-
-```
-if [ -n "$PI_SESSION_FILE" ]; then
-  tail -n 1 "$PI_SESSION_FILE"
-fi
-```
-
-These variables are injected into the LLM-callable `bash` and `powershell` tools. They are not injected into user-entered `!` or `!!` commands.
-
-### Custom Shell Tools
-
-Tools created with `createBashTool()` or `createPowerShellTool()` expose the session environment by default when registered with Pi. Injection happens before `spawnHook`, so a hook receives the variables in `ctx.env`:
-
-```
-const bashTool = createBashTool(cwd, {
-  spawnHook: (ctx) => ({
-    ...ctx,
-    env: { ...ctx.env, CI: "1" },
-  }),
-});
-```
-
-Disable session metadata independently of the spawn hook:
-
-```
-const powershellTool = createPowerShellTool(cwd, {
-  exposeSessionEnvironment: false,
-  spawnHook: (ctx) => ctx,
-});
-```
-
-When disabled, Pi removes inherited values for these variables so nested Pi processes do not expose stale parent-session metadata.
-
-## Pi Process Configuration
-
-These variables are read by Pi itself:
-
-| Variable | Description |
-| --- | --- |
-| `PI_CODING_AGENT_DIR` | Override the config directory; default is `~/.pi/agent` |
-| `PI_CODING_AGENT_SESSION_DIR` | Override session storage; overridden by `--session-dir` |
-| `PI_PACKAGE_DIR` | Override the package directory, useful for Nix/Guix store paths |
-| `PI_OFFLINE` | Disable startup network operations, including update checks, package updates, and install/update telemetry |
-| `PI_SKIP_VERSION_CHECK` | Disable the `pi.dev` latest-version request |
-| `PI_TELEMETRY` | Override install/update telemetry and provider attribution headers: `1`/`true`/`yes` or `0`/`false`/`no` |
-| `PI_CACHE_RETENTION` | Set to `long` for extended provider prompt caching where supported |
-| `PI_SHARE_VIEWER_URL` | Override the base URL used by `/share` |
-| `PI_HARDWARE_CURSOR` | Set to `1` to show the hardware cursor; see [Terminal setup](/docs/latest/terminal-setup) |
-| `PI_HYPERLINKS` | Override OSC 8 hyperlink detection with `1`, `0`, or `auto` |
-| `PI_IMAGE_PROTOCOL` | Override inline image detection with `kitty`, `iterm2`, `none`, or `auto` |
-| `PI_TRUE_COLOR` | Override truecolor detection with `1`, `0`, or `auto` |
-| `PI_TUI_ESC_TIMEOUT` | How long to wait after a lone ESC before treating it as Escape, in milliseconds; defaults to `100` over SSH and `10` otherwise. Increase if Alt-key input is misread as Escape |
-| `VISUAL`, `EDITOR` | External editor fallback when `externalEditor` is unset |
-| `HTTP_PROXY`, `HTTPS_PROXY` | Proxy outbound HTTP requests |
-
-Provider credentials such as `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and cloud-provider configuration are listed in [Providers](/docs/latest/providers#environment-variables-or-auth-file).
-
-`PI_SERVER_DIR` and `PI_SERVER_ID` apply only to the source-only [experimental remote harness](/docs/latest/development#experimental-remote-harness), not distributed builds.