@oddington/cli 0.1.52 → 0.1.53

package/README.md

@@ -22,28 +22,41 @@ Run `os --help` or add `--help` to any command for the full command list.
 Commands print readable output by default. Add `--json` when another program
 will consume the result.
 
-Dropbox setup uses an offline OAuth URL and hidden one-time code entry:
+Dropbox connection setup uses an offline OAuth URL and hidden one-time code entry:
 
 ```sh
-os connection create dropbox --workspace example --name os-files
-os connection create dropbox --workspace example --name business --access full-dropbox --root "/Business"
+os connection create dropbox --workspace example --name business --root "/Business"
 os connection list --workspace example --all
 os connection inspect --workspace example --id <returned-id>
 os connection test --workspace example --connection dropbox/business
 ```
 
-The default is App Folder, privately available to Files. Full Dropbox requires a
-separate saved connection, OAuth application and grant, plus an explicit existing
-folder; setup and testing only read provider state. Neither create command selects
-File storage. Full Dropbox cannot be a File store. Its declared root is the base
-path trusted routines must use, not provider-enforced token containment. Routine
-Dropbox calls change provider data immediately, independently of publication.
-Disconnect prevents new delivery but does not revoke an already delivered token.
-The operator must register and configure separate App Folder and Full Dropbox
-applications on the OS service. The application mode is that verified backend
-registration, never an inference from Dropbox account namespace metadata.
-Missing Full Dropbox setup refuses only that setup path; it does not disable App
-Folder authorization.
+A Dropbox connection lets routines work with an existing Dropbox folder. Its
+root is the base path trusted routines must use, not provider-enforced token
+containment. Setup and testing only read provider state; routine calls change
+Dropbox immediately, independently of publication. Disconnect prevents new
+delivery but does not revoke an already delivered token.
+
+Dropbox storage backs the OS Files capability with a separate dedicated folder:
+
+```sh
+os files storage connect dropbox --workspace example --name os-files
+os files storage select --workspace example --connection dropbox/os-files
+```
+
+Connecting authorizes storage; selecting it separately changes placement for new
+remote Files. A routine connection cannot be selected as File storage, and
+routines never receive storage credentials. OS uses separate company-owned OAuth
+applications for these purposes. Members authorize their own accounts; they do
+not register applications or handle OS app keys. Missing service setup names
+either Dropbox connection authorization or Dropbox storage authorization.
+
+The old `--access full-dropbox --root ...` connection flag remains a compatibility
+alias. A connection command without `--root`, or with `--access app-folder`, now
+points to the explicit Files storage command; it never silently changes purpose.
+Older installed clients retain their explicit authorization semantics on the API.
+Deployment operators must complete the credential-name cutover in
+`server/dropbox-authorization-rollout.md` before deploying this server version.
 
 Sign-in and session operations use `https://auth.oddington.ai`. Connection
 management, repository targets, local app repository context, Dropbox authorization,
@@ -60,6 +73,40 @@ Data and shared Files go directly to their OS owners. Local publication validate
 the whole captured set before applying Records, retaining Files and publishing
 Asks/Digests; retry resumes the same retained identities and receipts.
 
+## Repository schema types
+
+Inside a TypeScript code repository with a GitHub origin and named branch, run:
+
+```sh
+os data schema general
+```
+
+Your ordinary CLI login resolves the worktree to one member workspace. `general`
+is a Data repository alias there. The command reads only its published normalized
+schema and writes the marked root `os-data.generated.d.ts`. It reports that path
+and the TypeScript project files it integrates. Review and commit those files;
+a fresh clone uses the types without signing in or regenerating them.
+
+Keep importing `data` from `@oddington/sdk`. A known repository literal now gains
+schema-aware `records.select`, `pages` and `all` queries and projected values.
+No source import, app declaration, build or launch is needed. Other operations
+and dynamic repository names retain their generic types. Types grant no access;
+runtime Data validation and membership remain authoritative.
+
+Run the same command explicitly after a published schema changes, then review
+and commit its diff. Other aliases in the declaration are preserved. An unchanged
+refresh leaves generated and project bytes untouched. App build/launch never
+refreshes this file. The command does not retrieve Records or commit anything.
+
+Project integration preserves JSONC comments and authored settings, including
+confined local inheritance, source includes and project references. Unsupported
+or ambiguous layouts (including package-based/external inheritance, symlinks,
+nested Git repositories and incompatible referenced build projects) are refused
+before writing. Access, parsing, transport or write failures preserve the prior
+complete declaration and project configuration. Generation is serialized within
+the worktree; after a process interruption, check that no generation is running
+before removing a stale `.os-data-schema.lock` directory and refreshing again.
+
 ## Local apps
 
 From anywhere inside the app’s Git worktree, run:
@@ -346,6 +393,22 @@ and other CLI output never reveal saved credentials.
 `OS_CONNECTION_CREDENTIAL`. Only run trusted code, and do not print or
 retain that value.
 
+## Check routine requirements
+
+```sh
+os routine check invoice-import
+os routine check invoice-import --json
+```
+
+Checks the frozen authored definition, local runtimes, configured workspace
+capabilities and declared local Claude readiness. No business steps run, no
+provider operations or model requests are made, and no Run, first-use routine
+bookkeeping, Records, Files, Inbox items or publication intent are created.
+OS login and readiness metadata still require normal host access. Failure
+reports the same typed setup issues and recovery commands as pre-run checks;
+JSON includes `status`, `stepsRan: false`, and any error/issues. A check does not
+reserve access: running later checks current requirements again.
+
 ## Deploy routines
 
 From the customer Git worktree, a signed-in workspace member can run:
@@ -447,10 +510,11 @@ const captured = await inbox.readRecords({
 })
 ```
 
-OS uses the installed routine's repository grant, the managed target, and bounded
-data roots. A scheduler or another trusted runtime can launch without a human
-login. For a manual run, a signed-in workspace member uses the installed
-routine's name. OS supplies only the connections declared by its installation:
+OS intersects the routine's declared access with configured workspace
+capabilities. A new routine runs locally from a customer branch without
+registration, a merge to main, or deployment. The canonical ID is the `id` you
+author in `defineRoutine`; use that same ID in the command. Named connections
+must already be configured in the workspace; declaring a name does not create it:
 
 ```sh
 os routine run invoice-import --input input.json
@@ -480,10 +544,10 @@ detail, results and newest-first recent history use the same SDK handle contract
 The command executes once and accepts no workspace, version, command, environment
 or authority override.
 
-Before local execution, the command names installed connections and explains that
+Before local execution, the command names declared connections and explains that
 local filesystem changes, model calls and provider effects happen immediately.
 Only Record, File, Ask and Digest changes stay local for review. The child
-receives temporary installed authority, which is revoked when execution ends.
+receives temporary scoped authority, which is revoked when execution ends.
 Success reports concrete nonzero counts and the stable Run reference:
 
 ```sh
@@ -494,7 +558,7 @@ os routine publish <run> --json
 
 Declared records appear in the matched checkout; exact files, captured receipts,
 source/input and authored items stay in the private Run directory
-`.git/oddington-prepared/<run>` (under the worktree's actual Git directory).
+`~/.os/<workspace>/runs/<run>`.
 `execution.json` retains steps, optional result, redacted child output and known
 effect evidence. `complete.json` seals successful intent. Inspect these files and
 the bounded Git diff, then publish from the original root. Bare publish lists
@@ -508,7 +572,7 @@ Run evidence. Run output includes `runId`, `state`, `placement`, `changes`,
 the same Run reference, change state, confirmed receipts, Files, items and links.
 
 The SDK's `data.repository(name)` collection, selection and search calls also work in
-this mode, using only installed repository grants and the exact committed
+this mode, using only declared workspace repository access and the exact committed
 checkout version captured for the run. Dirty and untracked files are ignored;
 an OS cache outside the checkout reuses derived data without remote access.
 Accepted record effects advance later selections and searches to their exact
@@ -522,7 +586,7 @@ provider connections retain their normal network and authority requirements;
 local execution may contact OS or providers.
 
 For modern local execution, install the workspace separately with Bun 1.3.14.
-Keep `@oddington/sdk` exactly 0.1.17 in root `devDependencies`, compatible Node,
+Keep `@oddington/sdk` exactly 0.1.29 in root `devDependencies`, compatible Node,
 the selected private ESM manifest and the shared frozen lock. OS verifies only
 the selected installed graph, stages its confined bytes and builds the same
 executable unit used by deployment, preserving declared assets and SDK ownership.
@@ -531,6 +595,32 @@ packages report unavailable before business work. Local Python dependency
 provisioning is unsupported. Launch never repairs the workspace or falls back
 from a broken modern manifest to legacy execution.
 
+Global npm Bun is supported: `npm install --global bun@1.3.14`. Add the global
+executable directory to PATH. OS excludes executables owned by the customer
+checkout, while accepting host installations whose paths contain `node_modules`.
+
+Routine requirement failures name missing workspace resources and local AI
+setup together before any business step starts. For example, a declared
+`dropbox/documents` with no workspace connection is reported as a missing
+connection, with the Dropbox connection setup command and a placeholder for your
+existing folder. Inspect all configured connections with
+`os connection list --workspace <slug> --all`.
+
+Local AI supports signed-in Claude Code 2.1.259 and newer. An older unsupported
+version explains the required feature and prints `claude update`; a missing
+login prints `claude auth login`. Settings-policy failures point to `claude
+doctor`. Readiness never sends documents or makes a model request.
+
+Reuse ordinary customer source through relative imports from `routines/lib/`,
+without a package manifest in `lib/`. Each consuming routine declares any
+runtime packages that shared code imports. Importing another routine's package
+is rejected because its dependency boundary differs; copying its steps is not
+required.
+
+Business steps can also be tested with ordinary fixture inputs in the customer
+repository. A real local OS Run uses the configured workspace connections;
+fixtures do not require registering or deploying the routine.
+
 Routines without a selected package manifest retain the existing legacy path:
 native Node TypeScript stripping, a module `routines/package.json`, a matching
 `engines.node`, and an installed SDK. A workspace root alone does not cut over