Drop bin/cua, fold DESIGN.md into architecture.md, delete .cursor

README.md

@@ -85,12 +85,16 @@ flowchart LR
 git clone https://github.com/kernel/cua
 cd cua
 npm install
-npm run build
 
-# put `cua` on PATH (creates ~/.local/bin/cua → bin/cua):
-mkdir -p ~/.local/bin
-ln -s "$(pwd)/bin/cua" ~/.local/bin/cua
-# make sure ~/.local/bin is on $PATH (most distros already do)
+# run the CLI directly from source (no global install required):
+npx tsx packages/cli/src/cli.ts --help
+
+# if you want `cua` on $PATH from any directory, add a shell function to
+# your rc that pins the repo location while preserving the caller's cwd
+# (so `--out`, transcript bucketing, and `.agents/skills` discovery use
+# the directory you invoked from), e.g. in ~/.bashrc:
+#   CUA_REPO=/absolute/path/to/cua
+#   cua() { "$CUA_REPO/node_modules/.bin/tsx" "$CUA_REPO/packages/cli/src/cli.ts" "$@"; }
 
 # set API keys via env vars
 export OPENAI_API_KEY=sk-...                 # for gpt-5.5
@@ -318,8 +322,6 @@ ln -s "$(pwd)/skills/cua-cli" ~/.agents/skills/cua-cli
 ## Project layout
 
 ```
-bin/
-└── cua              # POSIX wrapper script (symlink into your $PATH)
 skills/
 └── cua-cli/SKILL.md # skill aimed at OTHER agents driving cua via shell
 packages/

docs/architecture.md

@@ -3,6 +3,47 @@
 This document explains how `cua` is wired together. It's aimed at
 someone who wants to read the code, contribute, or fork.
 
+## Product principles
+
+These are the evergreen product principles for Kernel's computer-use SDK
+packages. They explain the *why* behind the technical invariants below.
+
+### Package the boring plumbing
+
+Kernel's SDK packages should make the common browser-control work disappear:
+
+- Kernel browser session wiring
+- screenshots and screenshot reinjection
+- coordinate normalization
+- provider-specific computer-tool schemas
+- tool execution against Kernel browser APIs
+- provider registration
+- context and payload quirks
+- sensible default prompts
+
+These details are common to most CUA agents and are easy to get subtly wrong.
+
+### Do not over-own the agent
+
+The SDK should not hide the agent architecture from users. Builders keep
+control over:
+
+- system prompts
+- context and memory strategy
+- custom tools
+- streaming UI
+- orchestration policy
+- transport hooks and payload inspection
+
+The default path stays pleasant, but pi's primitives remain visible and
+replaceable.
+
+### Keep model refs explicit
+
+CUA model refs are provider-qualified — for example `openai:gpt-5.5` or
+`yutori:n1.5-latest`. This keeps examples, logs, persisted config, and
+transcripts unambiguous. The SDK does not export a default CUA model.
+
 ## Design goals and invariants
 
 - `@onkernel/cua-ai` owns provider-specific policy: the curated

docs/cua-cli-harness-migration.md

@@ -1,6 +1,6 @@
 # cua-cli → CuaAgentHarness migration plan
 
-Status: approved, in progress.
+Status: completed.
 
 `@onkernel/cua-cli` predates the public SDK packages. It hand-assembles a
 pi 0.67 (`@mariozechner/*`) `Agent` from the deprecated provider packages
@@ -202,12 +202,9 @@ Strictly ordered; each PR merges before the next starts.
   update root `package.json` workspaces, root tsconfig references, CI, README
   workspace table + mermaid diagram, and any references under `docs/` and
   `skills/`.
-- Out of scope (manual follow-up, requires npm publish rights):
-  `npm deprecate` of the published `@onkernel/cua-*` provider packages.
 - Acceptance: clean `npm install` + build + tests from a fresh checkout.
 
 ## Manual follow-ups after the migration
 
-- `npm deprecate` the published deprecated packages.
 - Decide on auto-compaction trigger and proper context-file injection.
 - Release a new `@onkernel/cua-cli` version per `docs/npm-releases.md`.

packages/cli/README.md

@@ -10,10 +10,17 @@ coding tools for workspace access.
 ## Install (from the monorepo)
 
 ```bash
+# from the repo root:
 npm install
-npm run build
-ln -s "$(pwd)/bin/cua" ~/.local/bin/cua    # put `cua` on your $PATH
-cua --help
+# run directly from source via tsx (no global install required):
+npx tsx packages/cli/src/cli.ts --help
+
+# optional: pin a shell function in your rc so `cua` works from any cwd
+# while preserving the caller's directory (so `--out`, transcript
+# bucketing, and `.agents/skills` discovery use the directory you
+# invoked from):
+#   CUA_REPO=/absolute/path/to/cua
+#   cua() { "$CUA_REPO/node_modules/.bin/tsx" "$CUA_REPO/packages/cli/src/cli.ts" "$@"; }
 ```
 
 ## Usage