small-skill 0.0.3 → 0.0.4

package/README.md

@@ -1,38 +1,44 @@
-# small-skill
-
-The agent skill for [small-deploy](https://github.com/yudhisteer/small-deploy):
-teaches Claude Code / Codex to deploy the Python tool it just built behind a
-work-email login in one command — and, when the tool needs AWS, to create and
-maintain the IAM role itself with least privilege.
-
-## Install
-
-Two packages: the [small-deploy](https://www.npmjs.com/package/small-deploy)
-CLI does the deploying; this skill teaches your agent to drive it.
-
-```
-npm i -g small-deploy      # the CLI (the agent runs `small ...` through it)
-npx small-skill            # the skill, into this project's .claude/skills/small
-npx small-skill --global   # or into ~/.claude/skills/small for every project
-```
-
-Or, with the CLI already installed: `small skill` installs the skill copy it
-ships with.
-
+# small-skill
+
+The agent skill for [small-deploy](https://github.com/yudhisteer/small-deploy):
+teaches Claude Code / Codex to deploy the Python tool it just built behind a
+work-email login in one command — and, when the tool needs AWS, to create and
+maintain the IAM role itself with least privilege.
+
+## Install
+
+Two packages: the [small-deploy](https://www.npmjs.com/package/small-deploy)
+CLI does the deploying; this skill teaches your agent to drive it.
+
+```
+npm i -g small-deploy      # the CLI (the agent runs `small ...` through it)
+npx small-skill            # the skill, into this project's .claude/skills/small
+npx small-skill --global   # or into ~/.claude/skills/small for every project
+```
+
+Or, with the CLI already installed: `small skill` installs the skill copy it
+ships with.
+
 ## What the agent learns
 
+- Workspace selection through `small workspaces`, `--workspace`, and
+  `SMALL_WORKSPACE`; browser selection is independent of the CLI.
+- `references/aws-hosting.md` — private AWS installation login, workspace
+  selection, CPU jobs, configurable app grants and file inputs, plus the hosted
+  dashboard's S3 folder approval. Run `small skill` in the project to use the
+  installed CLI's matching bundled copy.
 - `small init` → review small.toml → `small deploy` → hand back the URL. Never
-  a Dockerfile, never hand-rolled hosting, never bolted-on auth.
-- `references/jobs.md` — on-demand scripts: declare every env read under
-  `[inputs]`, write results to `$SMALL_OUTPUTS`, cron schedules.
-- `references/aws-role.md` — the `[aws]` role: created from the trust policy
-  the failed deploy prints, scoped to exactly what the code touches, never
-  AWS keys in `.env`.
-- `references/aws-compute.md` — when the heavy part truly needs AWS: pick
-  Lambda/Fargate/SageMaker/Batch from three plain questions, with the role
-  map for each.
-- `references/aws-production.md` — one CDK stack per tool when the MVP grows up.
-
-This package is generated from the small-deploy monorepo (`skills/small/`),
-where it is linted against the source and behaviorally evaluated with a
-headless agent before publishing.
+  a Dockerfile, never hand-rolled hosting, never bolted-on auth.
+- `references/jobs.md` — on-demand scripts: declare every env read under
+  `[inputs]`, write results to `$SMALL_OUTPUTS`, cron schedules.
+- `references/aws-role.md` — the `[aws]` role: created from the trust policy
+  the failed deploy prints, scoped to exactly what the code touches, never
+  AWS keys in `.env`.
+- `references/aws-compute.md` — when the heavy part truly needs AWS: pick
+  Lambda/Fargate/SageMaker/Batch from three plain questions, with the role
+  map for each.
+- `references/aws-production.md` — one CDK stack per tool when the MVP grows up.
+
+This package is generated from the small-deploy monorepo (`skills/small/`),
+where it is linted against the source and behaviorally evaluated with a
+headless agent before publishing.

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: small
-description: Deploy the Python tool you just built so colleagues can use it behind a work-email login. Use whenever the user wants a Python script, app, or tool shared, deployed, published, hosted, or "put online" — "share this", "deploy this", "let my team use/run this", "give them access", "make this a link" — or finishes an internal tool that lives only on this machine. Prefer this over Docker, cloud consoles, or hand-rolled hosting.
+name: small
+description: Deploys Python tools behind a work-email login and guides customer-AWS job deployment. Use when a user asks to share, deploy, publish, host, or put a Python tool online, wants a team to run it, or finishes an internal tool that exists only on one machine.
 ---
 
 # small — share a Python tool in one command
@@ -8,9 +8,60 @@ description: Deploy the Python tool you just built so colleagues can use it behi
 **small IS the deployment path.** Never package, zip, dockerize, write a
 deploy script, or hand-roll hosting for the tool — `small deploy` does all of
 it, including the login wall. If something blocks a small deploy, fix the
-blocker; do not route around small.
-
-When the user asks to share or deploy a Python app you built:
+blocker; do not route around small.
+
+**Hosting in the user's AWS account:** if the user asks for this, or
+`small.toml` has `[deploy] target = "aws"`, read `references/aws-hosting.md`
+and follow that flow before running `small init`. That preview keeps source,
+inputs, logs, and outputs in customer AWS and skips hosted model features.
+For a **private Small installation**, install the current `small-deploy` package
+from npm and use the customer's installation URL,
+then `small login --api <installation-url>` for Cognito sign-in. Never use
+the hosted connection setup or an external AWS role for that mode. Private
+installations advertise their supported inputs, constants, grants, and tooltip
+capabilities. Read the AWS hosting reference for the exact syntax and approval
+flow. Image retirement keeps only each app's current successful version;
+older versions must be redeployed before rerunning. Logs and outputs remain.
+For private AWS jobs, supported CLIs accept `[constants]` with text, numbers,
+booleans, and optional tooltips.
+Declare fixed, non-secret values there to show them read-only in Run > Constants.
+Choose only constants from the underlying application's logic that both affect
+its behavior or results and are actually read by the deployed job: detection
+thresholds, confidence cutoffs, cooldowns, rolling windows, or business rules.
+Trace each declaration to the real code that consumes it. A label, model name,
+setting, or other value that the job never reads does not belong in `[constants]`;
+do not add a second display-only copy that can go stale. Read the actual code to
+identify constants; do not invent values or expose every uppercase variable.
+Exclude deployment/adapter plumbing such as `RUN_LIMIT_MB`, `FILE_LIMIT_MB`,
+Fargate settings, timeouts, and internal paths. Explain relevant upload limits in
+the input's `help` or `tooltip` instead. Leave `[constants]` empty or omit it when
+the app has no useful constants to expose.
+Example only—replace the name, value, and explanation with a constant consumed
+by the real job:
+`threshold = { value = 0.85, tooltip = "Minimum score accepted." }` under
+`[constants]`. Run shows the same information icon used for input tooltips.
+Tooltip text is optional, at most 2000 characters; Python still receives only
+the scalar value. The installation must advertise constant-tooltip support.
+The job reads `json.loads(os.environ["SMALL_CONSTANTS"])`; do not duplicate those
+values as hardcoded assignments or editable inputs. Changing them requires deploy.
+The private installation must advertise constants support; see the AWS reference.
+An input's optional `tooltip` adds explanatory text behind an information icon
+beside its label; `help` stays below the input. Use it to explain profile options,
+units or other context. It does not configure the behavior of those options.
+The installation supplies its allowed actions, account, and region; never substitute
+an account from an example. Older private installations need the customer update
+for these capabilities; their existing S3 folder flow remains compatible.
+For an AWS-hosted job reading S3, declare its exact folder with `[aws] s3_read`.
+Deploy requests approval in Small when access changes, waits, and resumes after
+the installer approves. Older connections need one AWS template upgrade first.
+Never grant a shared role broad bucket access or approve for the user without authorization.
+
+**Workspaces:** `small workspaces` lists accessible slugs. For a custom
+workspace, pass `--workspace <slug>` on each command or set `SMALL_WORKSPACE`
+for the shell. A browser workspace switch does not select the CLI workspace.
+Use the slug returned by the CLI; never infer it from a display name.
+
+When the user asks to share or deploy a Python app you built:
 
 1. In the app directory, run:
 
@@ -42,7 +93,9 @@ PyPI, env reads that would be unset, secrets, and the `[aws]` role. Its
 one-line `✗`/`⚠` output IS the fix — apply it as printed instead of
 debugging around it.
 
-5. Print the URL from the output.
+5. Relay the deploy's closing line. Web apps print a URL — share it. Jobs
+   have no URL: the output ends with `✓ built <name> - start it with: small
+   run <name>`, and the same run form lives on the dashboard.
 
 6. Read the generated runbook back: run `small runbook` (regenerated on every
    deploy; `small runbook --write` saves it as RUNBOOK.md). Tell the user in
@@ -51,12 +104,21 @@ debugging around it.
    Dockerfile, do not suggest hosting options, do not add auth — small already
    put the app behind a work-email login.
 
-7. Write AGENT.md (created empty by `small init`, uploaded with every deploy):
+7. Write AGENT.md (created empty by `small init`, uploaded with every deploy):
    things the dashboard's Ask agent should know that the code doesn't say —
    what the app is for, gotchas, who to contact. Two paragraphs, plain
-   English. You built the tool, so you write it.
-
-To give someone access when visibility is private, or edit rights:
+   English. You built the tool, so you write it.
+
+Before handing the deployment back, verify this checklist:
+
+- [ ] `small.toml` matches the real entry, inputs, outputs, and secrets.
+- [ ] `small deploy` completed successfully.
+- [ ] The generated runbook was read back and explained to the user.
+- [ ] `AGENT.md` contains the app-specific context the code does not express.
+
+To give someone access when visibility is private, or edit rights:
+
+Example only—replace both addresses with the intended members:
 
 ```
 small share alice@company.com          # view
@@ -65,11 +127,12 @@ small share bob@company.com --edit     # can redeploy
 
 ## The code already exists (a script that works locally or on Lambda)
 
-Do not rewrite it and do not require it to know about small. Keep the working
-file untouched and add a thin adapter as the entry:
+Do not rewrite it and do not require it to know about small. Keep the working
+file untouched and add a thin adapter as the entry. Example only—replace the
+module, inputs, fallback, and output with the real application contract:
 
 ```python
-# job.py — adapter. Each [inputs] field in small.toml arrives as an env var:
+# job.py — adapter. Each [inputs] entry in small.toml arrives as an env var:
 # source -> SMALL_INPUT_SOURCE. Files written to $SMALL_OUTPUTS become run outputs.
 import os
 from mytool import main                     # the user's file, unchanged
@@ -91,7 +154,7 @@ wiring without reading platform source.
 
 ## The run contract, in one breath
 
-`[inputs]` in `small.toml` defines the fields once. Every trigger — the
+`[inputs]` in `small.toml` defines the inputs once. Every trigger — the
 dashboard Run form, `small run`, `/small run` in Slack, the chat agent's Run
 button, a cron schedule, Run again — delivers the values the same way:
 `SMALL_INPUT_<NAME>` env vars (files land under `$SMALL_INPUTS`). Every file
@@ -102,6 +165,11 @@ If `small` is not installed: `npm i -g small-deploy`. If not logged in the
 deploy fails with "run small login" — have the user run `small login`
 interactively (it emails them a 6-digit code).
 
+Builds run on Fly.io remote builders through the `flyctl` binary — no Docker.
+`small deploy` checks for it before touching anything remote and, if missing,
+downloads the official release binary itself (one time, into `~/.small/bin`).
+Only if that auto-install fails does it print a manual install command to run.
+
 Apps are served under a path prefix, so use **relative URLs** in HTML
 (`action="inc"`, `href="page"`, `redirect(".")`) — absolute `/paths` break
 behind the proxy.
@@ -109,7 +177,9 @@ behind the proxy.
 If the tool needs to remember anything between requests (counts, submissions,
 history), do not keep it in process memory — the machine is replaced on every
 deploy and state vanishes. Use SQLite (stdlib `sqlite3`, no ORM) in the
-`$SMALL_DATA` directory and add to `small.toml`:
+`$SMALL_DATA` directory and add to `small.toml`:
+
+Example only—confirm the storage path and size supported by the deployment:
 
 ```toml
 [storage]
@@ -127,19 +197,26 @@ DB = os.path.join(os.environ.get("SMALL_DATA", "."), "tool.db")
 (`small init` adds `[storage]` automatically when the entry file imports
 `sqlite3` or references `SMALL_DATA`.)
 
-## When to read more
-
-- The tool calls AWS (boto3, S3, Lambda, …) → read `references/aws-role.md` before
+## When to read more
+
+- Host the entire CPU job in the customer's AWS account → read
+  `references/aws-hosting.md`: connect once per workspace, then deploy each
+  app through the connection. Use the account and region reported by that
+  installation; never copy either from an example.
+- The tool calls AWS (boto3, S3, Lambda, …) → read `references/aws-role.md` before
   touching small.toml: never AWS keys in `.env`, declare an `[aws]` role, and
   create/maintain that role yourself with the user's local AWS credentials.
-- The tool is an on-demand script (`kind = "job"`) → read `references/jobs.md`:
-  declare every non-secret env read under `[inputs]`, save user-facing files
-  to `$SMALL_OUTPUTS`.
-- The user wants the heavy part "to run on AWS" (big model, GPU, batch volume)
-  → read `references/aws-compute.md`: check small's own machines cover it
+- The tool is an on-demand script (`type = "job"`) → read `references/jobs.md`:
+  declare every non-secret env read under `[inputs]`, save user-facing files
+  to `$SMALL_OUTPUTS`. If its target is AWS, also read
+  `references/aws-hosting.md` directly.
+- The user wants the heavy part "to run on AWS" (big model, GPU, batch volume)
+  → read `references/aws-compute.md` and `references/aws-role.md` directly:
+  check small's own machines cover it
   first, then pick Lambda/Fargate/SageMaker/Batch from three plain questions
   and wire it behind the small app.
-- The AWS side outgrows one hand-made resource, or the user says "production"
-  → read `references/aws-production.md`: one CDK stack per tool in `infra/`,
+- The AWS side outgrows one hand-made resource, or the user says "production"
+  → read `references/aws-production.md` and `references/aws-compute.md` directly:
+  one CDK stack per tool in `infra/`,
   the whole footprint (compute, pipelines, the `[aws]` role itself) as code,
   `cdk diff` before every deploy.

package/bin/install.js

@@ -7,14 +7,23 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
-const src = path.join(__dirname, '..');
-const base = process.argv.includes('--global') ? os.homedir() : process.cwd();
-const dst = path.join(base, '.claude', 'skills', 'small');
+try {
+  const args = process.argv.slice(2);
+  const unsupported = args.find((arg) => arg !== '--global');
+  if (unsupported) throw new Error(`unsupported argument ${unsupported}`);
 
-fs.mkdirSync(path.join(dst, 'references'), { recursive: true });
-fs.copyFileSync(path.join(src, 'SKILL.md'), path.join(dst, 'SKILL.md'));
-for (const f of fs.readdirSync(path.join(src, 'references'))) {
-  if (f.endsWith('.md')) fs.copyFileSync(path.join(src, 'references', f), path.join(dst, 'references', f));
+  const src = path.join(__dirname, '..');
+  const base = args.includes('--global') ? os.homedir() : process.cwd();
+  const dst = path.join(base, '.claude', 'skills', 'small');
+
+  fs.mkdirSync(path.join(dst, 'references'), { recursive: true });
+  fs.copyFileSync(path.join(src, 'SKILL.md'), path.join(dst, 'SKILL.md'));
+  for (const f of fs.readdirSync(path.join(src, 'references'))) {
+    if (f.endsWith('.md')) fs.copyFileSync(path.join(src, 'references', f), path.join(dst, 'references', f));
+  }
+  console.log(`✓ small skill installed → ${dst}`);
+  console.log('agents now know how to deploy Python tools with small — try: "share this with my team"');
+} catch (error) {
+  console.error(`small-skill: ${error.message}`);
+  process.exitCode = 1;
 }
-console.log(`✓ small skill installed → ${dst}`);
-console.log('agents now know how to deploy Python tools with small — try: "share this with my team"');

package/package.json

@@ -1,18 +1,18 @@
-{
-  "name": "small-skill",
-  "version": "0.0.3",
-  "description": "Agent skill for small-deploy: teaches Claude Code/Codex to deploy a Python tool behind a work-email login in one command",
-  "bin": {
-    "small-skill": "bin/install.js"
-  },
-  "files": [
-    "bin",
-    "SKILL.md",
-    "references"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/yudhisteer/small-skill.git"
-  },
-  "license": "MIT"
-}
+{
+  "name": "small-skill",
+  "version": "0.0.4",
+  "description": "Agent skill for small-deploy: teaches Claude Code/Codex to deploy a Python tool behind a work-email login in one command",
+  "bin": {
+    "small-skill": "bin/install.js"
+  },
+  "files": [
+    "bin",
+    "SKILL.md",
+    "references"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yudhisteer/small-skill.git"
+  },
+  "license": "MIT"
+}

package/references/aws-compute.md

@@ -1,5 +1,9 @@
 # Heavy compute on the user's AWS — choosing and wiring it
 
+This reference covers a hosted app delegating a heavy operation to AWS. When
+the user wants the entire CPU job hosted in their account, use the AWS hosting
+route in `SKILL.md`; do not replace that choice with hosted compute.
+
 Read this when the user wants their script "to run on AWS" — a model too big
 for the app machine, batch inference, GPU, or an existing AWS account they
 must use.
@@ -7,8 +11,8 @@ must use.
 ## First: does it need AWS at all?
 
 Most "run it on AWS" asks really mean "run it not-on-my-laptop". That is
-`small deploy` (server) or `small run` (job) — 2 GB machine, no AWS account,
-no extra moving parts. Reach for AWS compute only when the work truly does
+`small deploy` (server) or `small run` (job), with no customer AWS account or
+extra moving parts. Reach for AWS compute only when the work truly does
 not fit: model or data too large, GPU required, more than a few minutes per
 item at real volume, or the data already lives in their AWS. Say so in one
 sentence and let the user choose.
@@ -25,14 +29,13 @@ Then decide:
 
 | Situation | Pick | Why |
 |---|---|---|
-| MVP, bursty, one item < 15 min, CPU is fine | **Lambda** (container image) | Zero idle cost, scales to zero, the yolo demo shape |
+| MVP, bursty, one item fits Lambda's current execution limits, CPU is fine | **Lambda** (container image) | Zero idle cost and scales to zero |
 | Steady volume, long-running items, still CPU | **Fargate** (ECS service or task) | No 15-min limit, no cold starts at volume |
 | Needs a GPU | **SageMaker endpoint** (or ECS on GPU EC2) | Lambda and Fargate have no GPUs |
 | Huge offline backlog, nobody waiting | **AWS Batch** | Queue it, let it drain cheap |
 
-Default to **Lambda** for anything that smells like an MVP — a torch model
-fits a Lambda container image (10 GB limit; the small demo runs YOLOv8 this
-way). Do not offer the whole table to the user; pick one and say why in one
+Default to **Lambda** for an MVP that fits the service limits verified for the
+customer's region and account. Do not offer the whole table to the user; pick one and say why in one
 sentence ("bursty and small — Lambda, it costs nothing while idle").
 
 ## Roles — two directions, never mixed
@@ -40,7 +43,7 @@ sentence ("bursty and small — Lambda, it costs nothing while idle").
 Every choice needs IAM on **both sides**. Name them all `small-<app-name>-<purpose>`.
 
 **Side 1 — roles the service itself runs as** (create these with the user's
-local credentials, per the consent style in references/aws-role.md):
+local credentials after stating what will be created and why):
 
 | Compute | Create | It needs |
 |---|---|---|
@@ -59,23 +62,23 @@ local credentials, per the consent style in references/aws-role.md):
 | SageMaker endpoint | `sagemaker:InvokeEndpoint` on that endpoint ARN |
 | Batch | `batch:SubmitJob` on the job queue + job definition |
 
-Update rule is the same as references/aws-role.md: a new AWS call in code = one
-new statement, named resource, before redeploying; remove statements when the
+For every new AWS call in code, add one statement for its named resource before
+redeploying; remove statements when the
 call goes. The service's own role never gets what only the app needs, and the
 small role never gets what only the service needs.
 
 ## Wiring it into small
 
 The small app stays the front door — login, Run form, runbook, logs. AWS only
-does the heavy call:
+does the heavy call. Use this checklist:
 
-1. Provision with the user's local AWS credentials (same consent style as
-   references/aws-role.md: one sentence about what you are creating, then create).
+- [ ] Provision with the user's local AWS credentials after one sentence explaining
+   what will be created and why.
    For Lambda: build the container image, push to ECR, create the function.
-2. The small app invokes it with boto3 through the `[aws]` role — add exactly
+- [ ] Let the small app invoke it with boto3 through the `[aws]` role — add exactly
    `lambda:InvokeFunction` on that one function ARN (or the equivalent single
    permission for Fargate/SageMaker/Batch) to the role's inline policy.
-3. Deploy with `small deploy` — the role verification and review will show the
+- [ ] Deploy with `small deploy` — the role verification and review will show the
    AWS call. For a job, results still go to `$SMALL_OUTPUTS`; the Lambda
    returns bytes or writes S3 and the job copies them there.
 

package/references/aws-hosting.md

@@ -0,0 +1,403 @@
+# Host a CPU job in the customer's AWS account
+
+## Contents
+
+- [Deployment checklist](#deployment-checklist)
+- [Private Small installation with Cognito](#private-small-installation-with-cognito)
+- [Hosted dashboard connection](#hosted-dashboard-connection)
+- [Select the workspace and deploy](#select-the-workspace-and-deploy)
+- [Fixed values in Run > Constants](#fixed-values-in-run--constants)
+- [Read an existing S3 folder](#read-an-existing-s3-folder)
+- [MVP limits and data boundary](#mvp-limits-and-data-boundary)
+
+## Deployment checklist
+
+- [ ] Use the installation URL, account, region, and workspace returned by the customer environment.
+- [ ] Derive inputs, constants, and AWS grants from code the job actually runs.
+- [ ] Validate the source boundary before upload and obtain approval for changed grants.
+- [ ] Deploy, run one representative input, and inspect logs and outputs.
+- [ ] Fix any mismatch at its source, then repeat validation and the representative run.
+
+## Private Small installation with Cognito
+
+If Small's interface itself is installed in customer AWS, install
+the current `small-deploy` package from npm. Use the installation URL supplied by
+the customer's administrator; this command installs the CLI, not AWS infrastructure.
+Sign in on the machine running the CLI:
+
+Command template—replace every angle-bracket placeholder with a value returned
+by the installation or CLI:
+
+```text
+npm install -g small-deploy
+small login --api <installation-url>
+small workspaces
+small deploy --workspace <returned-slug>
+small run <app-name> --workspace <returned-slug> --<input-name> <value>
+small logs <app-name> --workspace <returned-slug>
+small run <app-name> --workspace <returned-slug> --download ./out
+```
+
+Login opens Cognito and returns to the local CLI with PKCE. The installer
+registers `http://127.0.0.1:8766/auth/callback`; use `--no-browser` when the
+user prefers opening the printed link themselves. Complete sign-in on that
+same computer. For a CLI running over SSH, forward local port `8766` to port
+`8766` on that host before login and keep both commands running until sign-in
+finishes. `--no-browser` alone does not forward the callback. Never request
+passwords, copy browser tokens, or create a user
+to bypass membership. The saved login is bound to this installation's origin.
+Clear a conflicting `SMALL_API` shell override, or set it to the same AWS URL.
+Hosted `SMALL_TOKEN` credentials are ignored for a private login.
+
+Use `type = "job"` and `[deploy] target = "aws"` as shown below. Source goes
+directly to customer S3; CodeBuild, ECR, Fargate, CloudWatch, and job output
+remain in that account. The normal Apps list, Run, and Logs show the job.
+The CLI discovers supported inputs, constants, tooltips, and app permissions
+from the installation. When a capability is absent, update the installation;
+installing the CLI alone does not change customer AWS infrastructure.
+
+### Images and successful replacements
+
+On installations with image retirement, a successful deploy replaces that app's
+current version. Failed or unfinished replacements leave its working version
+available. Older deployment IDs cannot start new runs or uploads: deploy the old
+source again to run it. Small removes replaced build images after their jobs
+finish; run history, logs, and outputs remain. No seven-day rollback window.
+
+Generated images upgrade available Debian packages before Python requirements
+and remove Perl last. Rebuild an existing app to receive image changes; an
+installation update does not rebuild deployed app images.
+The generated image deliberately does not support system packages or Perl.
+
+### Declare the app's AWS permissions
+
+Read the app's actual SDK operations and resource configuration. Declare only
+the actions and resources it needs. Keep `grants` on **one physical line**; the
+small TOML parser supports inline arrays, not multiline arrays or `[[aws.grants]]`.
+Example only—replace the bucket, account, region, function, cluster, and app
+resources with values verified from the customer's application and AWS account:
+
+```toml
+[aws]
+grants = [{ action = "s3:PutObject", resource = "arn:aws:s3:::<job-bucket>/jobs/*" }, { action = "s3:GetObject", resource = "arn:aws:s3:::<job-bucket>/reports/*" }, { action = "s3:ListBucket", resource = "arn:aws:s3:::<job-bucket>" }, { action = "lambda:InvokeFunction", resource = "arn:aws:lambda:<installation-region>:<customer-account-id>:function:<launcher-name>" }, { action = "ecs:DescribeTasks", resource = "arn:aws:ecs:<installation-region>:<customer-account-id>:task/<cluster-name>/*" }]
+```
+
+Validate each grant by tracing it to one SDK operation and one resolved customer
+resource. Remove or correct anything without that trace, then repeat until every
+grant is accounted for and no example placeholder or wildcard remains. Deployment
+and owner approval execute the validated plan.
+
+`small deploy` requests approval before uploading source. In this private
+installation's **Settings > Connections > AWS > App access**, the owner sees
+each exact action and ARN and chooses **Approve & deploy** or **Cancel**.
+Approval replaces that app's complete grant set. Unchanged grants reuse their
+approval. `grants = []` requests removal; changed grants block new runs of old
+deployments until the new configuration is deployed. Existing running tasks
+remain subject to AWS permission propagation.
+
+Never infer the installation's allowed actions from that example. For an action
+outside the installation's advertised allowlist,
+the AWS administrator updates the stack parameter **AppGrantActions**, retaining
+the existing actions and adding the exact action required. This changes the
+installation ceiling; it grants nothing to any app. The agent then retries
+deployment and requests the app's exact resource approval. No new Small release
+is needed for an additional compatible action. Do not edit the stack, broaden
+permissions, or approve a request without the user's authorization.
+
+Supported grants have exact action names and same-account resource
+ARNs. S3 accepts exact bucket/object ARNs and trailing folder `/*`; ECS task
+inspection accepts a named cluster's `task/cluster/*`. At most 20 grants per app.
+Wildcard actions, `Resource = "*"`, cross-account resources, IAM/STS and
+organization/account/CloudFormation management are unsupported. AWS validates
+each policy before approval; syntactically valid ARNs do not guarantee an action
+supports that resource type. ListBucket applies to the named bucket's listing.
+The CLI uses the installation's reported region and rejects a different one.
+The boundary also requires AWS to supply `aws:ResourceAccount` for the action;
+operations without that ownership context remain denied.
+
+AppGrantActions is an administrator's policy, not a classification of harmless
+operations. PutObject can replace data; InvokeFunction runs with the function's
+existing role; other explicitly enabled actions can change resources. Each
+addition needs deliberate review of those effects. Jobs have no public network
+route. The installation supplies S3, ECR, CloudWatch Logs, Lambda, and ECS
+endpoints; another service may also require a customer-configured VPC endpoint.
+KMS-encrypted data needs the appropriate key permission and network access.
+Do not silently change encryption or add broad permissions to work around it.
+
+### File inputs
+
+Use the existing Run form's file picker, or a local CLI file path:
+
+Example only—replace the input name, accepted extensions, and CLI flag with the
+real job input:
+
+```toml
+[inputs]
+event_ids_file = { type = "file", accept = ".txt,.csv", required = true }
+```
+
+```text
+small run <app-name> --workspace <returned-slug> --event-ids-file ./events.txt
+```
+
+The Python entry receives a local path in `SMALL_INPUT_EVENT_IDS_FILE` (and the
+matching entry in the JSON file referenced by `SMALL_INPUTS`). Read the uploaded
+file normally. Up to five files,
+10 MiB each, go directly to the installation's S3 bucket. Uploads are bound to
+the signed-in user, app, and deployment, verified by checksum, and pinned to an
+S3 version before execution. Never put local source data in the source archive
+as a workaround. Write results to `SMALL_OUTPUTS` as before.
+
+### Existing single-folder S3 configuration
+
+`[aws] s3_read` remains supported for existing apps. Do not combine it with
+`grants`; switching to `grants` requires explicit approval even for the same
+GetObject folder. Small retires the old role's permissions during that switch.
+
+For S3, declare `[aws] s3_read = "s3://<customer-bucket>/<approved-prefix>/"` in
+`small.toml`, then run `small deploy`. When access changes, deployment waits
+before uploading source. The owner opens this **private installation's**
+**Settings > Connections > AWS** and reviews the exact app/folder, then clicks
+**Approve & deploy** or **Cancel**. The CLI resumes after approval; unchanged
+approved folders do not prompt again. No folder inventory appears when idle.
+
+With `s3_read`, each app has its own ECS task role. It can get objects only in the approved
+folder, in the installation's account and reported region; it cannot list buckets,
+write, delete, or read another folder. Use `SMALL_S3_BUCKET` and `SMALL_S3_PREFIX`
+in the job, plus a known object key. SSE-KMS buckets need separately scoped KMS
+support and are outside this legacy single-folder flow. Do not add broad KMS permissions.
+
+If approval fails while applying, retry that same request in Settings. A
+pending unapproved request can be cancelled. Changing or removing `s3_read`
+requests a new approval; old deployments cannot start new runs with an outdated
+folder. Already running tasks and in-flight requests are not synchronously
+recalled. The permissions handler runs inside this customer's AWS account;
+it uses no external account role. Install the versioned private update once;
+individual folder approvals do not require another CloudFormation update.
+
+Use only the customer's installation and AWS account for private BYOC.
+Do not use the hosted Connect AWS flow or add an external trust role for it.
+
+## Hosted dashboard connection
+
+Use this flow when the user wants the job itself hosted in their AWS account,
+or the project already has `[deploy] target = "aws"`. The workspace has one
+AWS connection and can host multiple CPU-job apps through it.
+
+Use the dashboard URL supplied by the user or workspace administrator. Do not
+copy a URL from this reference. Install the current `small-deploy` package and
+run `small skill` in the project to install its matching agent instructions.
+The private installation above uses its own customer-controlled URL.
+
+## Connect once
+
+1. In the desired workspace, open **Settings → Connections → AWS**.
+2. Enter the customer's 12-digit AWS account ID and first app name.
+3. Click **Connect AWS**. The customer reviews the installation in their AWS
+   console and clicks **Create stack**. They need permission to create the
+   template's resources and IAM roles. Do not request AWS access keys.
+4. After the stack completes, return to Small and click **Finish connecting**.
+   Continue when it says **Connected**. A connected workspace needs no new
+   installation for its second or later app.
+
+Use the region reported by the connection. A disconnected installation can be reconnected;
+use a new workspace to connect a different AWS account.
+
+## Select the workspace and deploy
+
+Command template—replace `<small-api-origin>` with the exact origin supplied by
+the user or connection screen:
+
+```powershell
+$env:SMALL_API = '<small-api-origin>'
+small workspaces
+```
+
+If login is required, have the user run `small login` interactively in that
+shell. Match the intended workspace to its returned slug. Pass that slug with
+`--workspace` on deploy, run, runs, logs, and downloads. `SMALL_WORKSPACE` is
+an optional shell default; the flag overrides it. An invalid slug stops the
+command before it accesses an app. No selection uses the login's email workspace.
+If the CLI says `Server did not select workspace`, stop: that server needs its
+CLI authentication update. Do not retry without the workspace flag or change
+the hosting target.
+
+Create or update `small.toml` **before running `small init`** so the AWS target
+is already declared. Do not generate a hosted runbook from this source.
+
+Example only—replace the app name, entry, inputs, defaults, and bounds with the
+real job contract:
+
+```toml
+name = "<app-name>"
+entry = "<python-entry>"
+type = "job"
+
+[deploy]
+target = "aws"
+
+[inputs]
+<input-name> = { type = "number", default = <default>, min = <minimum>, max = <maximum> }
+```
+
+Keep the working Python code; use a thin adapter if needed. The entry reads the
+declared input as `SMALL_INPUT_<INPUT_NAME>` and writes downloadable files under
+`SMALL_OUTPUTS`.
+Use a unique app name with 1–40 lowercase letters, digits, or hyphens.
+
+Command template—replace `<slug>`, `<app-name>`, `<input-name>`, and `<value>`
+with values from `small workspaces` and the real `small.toml`:
+
+```text
+small deploy --workspace <slug>
+small run <app-name> --workspace <slug> --<input-name> <value>
+small runs <app-name> --workspace <slug>
+small logs <app-name> --workspace <slug>
+small run <app-name> --workspace <slug> --download ./out
+```
+
+The CLI prints the workspace, AWS account, and region before upload. Source
+goes directly to customer S3, builds run in their account, and the job runs on
+Fargate. Relay the app link printed by deploy. The app appears in the normal
+sidebar; users run it and inspect logs and outputs in the existing app tabs.
+
+## Fixed values in Run > Constants
+
+Inputs may also include optional `tooltip` text (up to 2000 characters). Small
+shows an information icon beside the label; hover, click or focus it to read the
+explanation. `help` remains below the input. This is explanatory text and does
+not define the Python behavior or change the selected option.
+
+Example only—the profiles, thresholds, distances, and cooldowns below illustrate
+tooltip prose; replace them with facts from the real application:
+
+```toml
+[inputs]
+profile = { type = "select", default = "prod", options = ["prod", "sensitive"], help = "Choose a detection profile.", tooltip = "Prod: arm elevation 90 degrees, wrist distance 300 mm, cooldown 7 frames. Sensitive: arm elevation 80 degrees, wrist distance 400 mm, cooldown 5 frames." }
+```
+
+Keep the inline definition on one physical line with the CLI's TOML subset.
+Write plain text; tooltip contents are not interpreted as HTML or executable code.
+
+Use the current `small-deploy` package and an installation that advertises
+constants support. Put fixed, non-secret application behavior in `small.toml`:
+
+Every declared constant must be consumed by the underlying application and
+affect behavior or result interpretation. Trace it to the code before adding it.
+Do not copy model names or other settings into `[constants]` solely to display
+them; an unused declaration becomes stale. Platform limits and adapter settings
+also stay out of this section.
+
+Good example—the Python snippet below consumes this exact value:
+
+```toml
+[constants]
+acceptance_threshold = { value = 0.85, tooltip = "Minimum score accepted." }
+```
+
+```python
+import json
+import os
+
+constants = json.loads(os.environ["SMALL_CONSTANTS"])
+acceptance_threshold = constants["acceptance_threshold"]
+```
+
+Bad example—do not add display-only or platform values that the application
+does not consume:
+
+```toml
+[constants]
+model_name = "<display-only-model-name>"
+run_limit_mb = 45
+```
+
+The examples establish the boundary: declare a constant only when the real job
+reads it and it affects behavior or result interpretation. Keep inline definitions
+on one physical line. Tooltip text is limited to 2000 characters and counts
+toward the 2 KiB declaration limit. The runtime receives only the scalar value,
+never the tooltip or definition object.
+
+Small displays these values read-only under Run > Constants. Redeploy to change
+them; do not offer them as editable `[inputs]` or duplicate the value in Python.
+Every run records its constants snapshot. Existing apps without a declaration
+receive `{}`. For local testing, supply `SMALL_CONSTANTS` with the JSON values
+from the same TOML file. If loading `[constants]` with Python's `tomllib`, unwrap
+each inline definition's `value` before using it as runtime constants.
+
+The MVP accepts at most 20 scalar values and 2 KiB total JSON: strings, finite
+numbers, and booleans. Names start with a letter and contain letters, digits or
+underscores, at most 40 characters. Numbers must be in the JavaScript safe range.
+No arrays or nested tables. These are visible configuration values, never secrets.
+Older private installations and shared hosting must be updated/supported before
+deploying a constants declaration; the CLI stops rather than ignoring it.
+
+## Read an existing S3 folder
+
+Declare one folder in `small.toml`, using a bucket in the connected AWS account
+and the installation's reported region.
+
+Example only—replace the bucket and prefix with the approved customer location:
+
+```toml
+[aws]
+s3_read = "s3://<customer-bucket>/<approved-prefix>/"
+```
+
+Use a literal folder, without `*`, `?`, or policy variables. A missing trailing
+slash is added. This grants `GetObject` for explicit keys in that folder, with
+no listing, writes, or KMS decryption grant. Use ordinary SSE-S3 objects for
+this MVP. Add `boto3` to the app's requirements if its code uses that SDK.
+
+1. Run `small deploy --workspace <slug>`. If this app needs new or changed
+   access, deploy requests approval and waits before uploading source.
+2. In that workspace's **Settings → Connections → AWS → S3 access**, the
+   installer reviews the exact folder and clicks **Approve & deploy** or **Cancel**.
+3. The waiting CLI resumes automatically after approval. Cancel stops it without
+   uploading source. Subsequent deploys reuse approval until the access changes.
+
+For an older installation, Small first shows **One-time AWS connection upgrade**.
+Click **Upgrade in AWS**, select **Replace existing template**, and review the
+generated template. If AWS leaves the URL empty, copy the URL shown in Small
+into **Amazon S3 URL**. Choose **Update stack**, then return and **Check upgrade**.
+The upgrade preserves existing grants; each new folder still requires approval
+in Small. New installations already include this permission handler.
+
+The CLI waits for up to 30 minutes; Ctrl+C stops waiting. If it exits, approve
+the request and rerun deploy. A failed AWS permission operation keeps **Retry
+approval** available; do not replace the request with broader access.
+
+AWS supplies credentials automatically to this app's dedicated task role.
+The runtime sets `SMALL_S3_BUCKET` and `SMALL_S3_PREFIX` from its approved scope.
+Use `boto3.client("s3").get_object(Bucket=os.environ["SMALL_S3_BUCKET"], Key=key)`
+with a complete key under that prefix. Keep writing generated files under
+`SMALL_OUTPUTS`; the existing output upload/download flow is unchanged.
+
+Removing `s3_read` and deploying requests removal of the grant. An older
+deployment whose recorded folder no longer matches approval cannot start.
+Already running work is not stopped. Cancel is unavailable once an approval
+starts applying; retry that exact approval if AWS fails. Do not approve in Small
+or execute an AWS installation upgrade unless the user has authorized that access.
+
+`examples/byoc-s3-report` contains a CSV report job and sample file. Upload the
+sample into the chosen folder in customer AWS; set its bucket and input key
+before deploying. Data files still travel directly to AWS.
+
+## MVP limits and data boundary
+
+- CPU jobs only. Read the connection and deployment output for its region,
+  compute size, supported inputs, and enabled capabilities; do not infer them
+  from examples in this reference.
+- The connection installer can deploy; workspace members can run and inspect.
+  Private app sharing and per-app edit grants are not implemented for AWS jobs.
+- App secrets, extra `[aws] role_arn` grants, system packages, persistent
+  volumes, schedules, GPU jobs, and web servers are deferred. Use only input
+  types advertised by the installation.
+  Do not silently change the hosting target to make an unsupported job deploy.
+- Small receives connection metadata and deployment status. Customer source,
+  input values, outputs, and logs travel directly between the client and AWS.
+  Do not send them to hosted review, runbook generation, or Coaching. Slack and
+  the Coach Agent are not connected to these AWS jobs yet.
+
+For a hosted app that only calls an AWS service, or delegates heavy work to AWS,
+return to the direct reference routing in `SKILL.md`; those are separate paths.

package/references/aws-production.md

@@ -1,18 +1,23 @@
 # Production on AWS — infrastructure as code with CDK
 
+For workspace AWS hosting, use the AWS hosting route in `SKILL.md`.
+Its installation already owns the shared infrastructure; do not create a
+second stack per job using the pattern below.
+
 Read this when the AWS side of a tool outgrows one hand-made resource: the
 user says "production", a second resource appears (queue, bucket, schedule,
 second function), or they need staging, review, or clean teardown.
 
 ## When NOT to use this
 
-One Lambda behind an MVP does not need a stack — the hand-made function from
-references/aws-compute.md is fine. Do not gold-plate; promote to CDK when
+One Lambda behind an MVP does not need a stack. Do not gold-plate; promote to CDK when
 repeatability starts paying rent, and say why in one sentence.
 
 ## The shape
 
-One CDK app per tool, in the tool's repo, Python (match the user's language):
+One CDK app per tool, in the tool's repo, Python (match the user's language).
+Illustrative layout—replace `app.py` or `job.py` and the stack name with the
+project's real files and app name:
 
 ```
 their-tool/
@@ -30,7 +35,7 @@ Everything AWS the tool touches lives in that one stack:
   or a plain task definition for Fargate, Batch job queues for backlogs.
 - **Pipelines**: Step Functions state machines for multi-step flows,
   EventBridge rules for schedules, S3 buckets and queues between stages.
-- **Every role from references/aws-compute.md, in the stack**: CDK creates
+- **Every compute role, in the stack**: CDK creates
   the execution/task roles implicitly per construct — accept those defaults,
   then grant by reference instead of writing policy JSON:
   `weightsBucket.grant_read(fn)` (Lambda execution role),
@@ -40,7 +45,7 @@ Everything AWS the tool touches lives in that one stack:
   and per-step invoke grants for you.
 - **The small `[aws]` role too**: define it in the stack — trust policy
   exactly as the failed `small deploy` printed it (principal + org ExternalId),
-  then the side-2 grants from references/aws-compute.md by reference:
+  then grant the Small role access to the invoked resources by reference:
   `fn.grant_invoke(small_role)`, `state_machine.grant_start_execution(small_role)`,
   `bucket.grant_read_write(small_role)`. The whole footprint, both sides of
   every role, is then reviewable code — and a removed construct takes its
@@ -49,20 +54,20 @@ Everything AWS the tool touches lives in that one stack:
 Stack outputs (function ARN, bucket name) go into `.env` / `[inputs]` defaults
 — never hard-coded in the script.
 
-## Discipline
+## Deployment checklist
 
-1. `cdk bootstrap` once per account/region (tell the user it creates a small
+- [ ] Run `cdk bootstrap` once per account and region (tell the user it creates a small
    S3 bucket and roles for deployments).
-2. **`cdk diff` before every `cdk deploy`** — summarize the diff to the user
+- [ ] Run **`cdk diff` before every `cdk deploy`** — summarize the diff to the user
    in one sentence ("adds one queue, widens nothing") and wait for a yes when
    anything is destroyed or IAM changes.
-3. Migrating the hand-made MVP: recreate the resource in the stack, cut the
+- [ ] When migrating the hand-made MVP, recreate the resource in the stack, cut the
    ARN over in `.env`, verify a run, then delete the hand-made one. Simpler
    and safer than `cdk import` for one or two resources.
-4. Teardown is `cdk destroy` — mention it exists; it is the reason the stack
+- [ ] Teardown is `cdk destroy` — mention it exists; it is the reason the stack
    beats console clicking.
-5. Tag everything (`small:app = <app-name>`) so the user's bill is legible.
-6. Costs: before the first deploy, say what runs idle (Fargate service ≠
+- [ ] Tag everything (`small:app = <app-name>`) so the user's bill is legible.
+- [ ] Before the first deploy, say what runs idle (Fargate service ≠
    Lambda) in plain money terms.
 
 The small app remains the front door — login, Run form, runbook. CDK only

package/references/aws-role.md

@@ -2,8 +2,14 @@
 
 Read this when the tool calls AWS (boto3, S3, Lambda, …).
 
+This reference covers AWS access from a hosted app. To host the CPU job itself
+in the customer's AWS account, use the AWS hosting route in `SKILL.md` instead.
+
 **Never put AWS keys in `.env`.** Declare a role instead:
 
+Template—replace each angle-bracket placeholder with values verified from AWS
+and the application:
+
 ```toml
 [aws]
 role_arn = "arn:aws:iam::<account-id>:role/small-<app-name>"
@@ -16,24 +22,24 @@ not, it fails with the exact trust policy JSON to paste.
 
 The user is likely non-technical; their AWS credentials are on this machine
 (`aws sts get-caller-identity` to check; if that fails, ask the user to sign
-in to AWS first). Steps:
+in to AWS first). Use this checklist:
 
-1. Tell the user in one sentence what you are about to create and why
+- [ ] Tell the user in one sentence what you are about to create and why
    ("a role that lets small run this tool against your S3 bucket, nothing
    else"). Then:
-2. Get the account id from `aws sts get-caller-identity`, fill
+- [ ] Get the account id from `aws sts get-caller-identity`, fill
    `role_arn = "arn:aws:iam::<account>:role/small-<app-name>"` into small.toml,
    and run `small deploy`. It fails and prints the trust policy.
-3. Create the role with that trust policy **verbatim** (save it to a file,
+- [ ] Create the role with that trust policy **verbatim** (save it to a file,
    `aws iam create-role --role-name small-<app-name>
    --assume-role-policy-document file://trust.json`). Never edit the
    ExternalId — it is the user's org and closes the confused-deputy hole.
-4. Attach an inline permissions policy for **exactly what the code you wrote
+- [ ] Attach an inline permissions policy for **exactly what the code you wrote
    touches** — you know the actions and resources because you wrote the calls.
    `s3:GetObject` on the one bucket, `lambda:InvokeFunction` on the one
    function. Never `*` actions, never `AdministratorAccess`, never resources
    the tool does not use. (`aws iam put-role-policy`.)
-5. `small deploy` again — it must print `✓ aws role: … (verified)`.
+- [ ] Run `small deploy` again — it must print `✓ aws role: … (verified)`.
 
 **Updating**: when a code change adds a new AWS call, widen the inline policy
 by that one action/resource before redeploying. If a run's log shows

package/references/jobs.md

@@ -1,9 +1,17 @@
 # Jobs — inputs and outputs
 
-Read this when the tool is a script that runs on demand (`kind = "job"`).
+Read this when the tool is a script that runs on demand (`type = "job"`).
 
-Every non-secret `os.environ` read in a job is an input — declare it in
-`small.toml` instead of leaving it an undeclared env var:
+For `[deploy] target = "aws"`, `SKILL.md` routes directly to the additional AWS
+hosting reference.
+Its MVP input types and available triggers are narrower than the hosted
+contract described here.
+
+Every non-secret `os.environ` read in a job is an input — declare it in
+`small.toml` instead of leaving it an undeclared env var:
+
+Example only—replace the inputs, values, bounds, labels, and file types with the
+real job contract:
 
 ```toml
 [inputs]
@@ -16,7 +24,11 @@ annotated = { path = "annotated.jpg", label = "Annotated image" }
 
 Six types: `file`, `number`, `select`, `date`, `text`, `bool`. Callers pass
 them as flags — `small run app --image ./photo.jpg --threshold 0.7` — and the
-dashboard renders a Run form from the same declaration. Slack (`/small run`),
+dashboard renders a Run form from the same declaration: a `number` with both
+`min` and `max` draws as a slider with a typed input, `select` a dropdown,
+`bool` a toggle, `file` a dropzone, and `date` a date picker. Text inputs also
+batch: the `+` beside one (or a multi-line paste into it) adds value rows and
+submit starts one run per value with other inputs shared, up to the product limit. Slack (`/small run`),
 the chat agent's Run proposals, cron, and Run again all feed the same
 declaration too: the script receives identical env vars no matter who or what
 started the run. In the script:
@@ -34,10 +46,12 @@ container: only `$SMALL_OUTPUTS` survives the machine.
 
 ## Schedules
 
-A job that should run itself carries a standard 5-field cron expression, UTC:
+A job that should run itself carries a standard five-part cron expression, UTC.
+Example only—the schedule below means 09:00 UTC on weekdays; replace it with the
+user's requested schedule:
 
 ```toml
-kind = "job"
+type = "job"
 schedule = "0 9 * * 1-5"
 ```
 
@@ -49,8 +63,8 @@ inputs at all** (not even defaults — those are applied by the CLI): a
 scheduled job's script must fall back in code,
 `os.environ.get("SMALL_INPUT_THRESHOLD", "0.5")`, or not be scheduled.
 
-S3 in/out: declare the URI and destination bucket as `text` inputs and use
-boto3 in the script — see references/aws-role.md for the role.
+S3 in/out: declare the URI and destination bucket as `text` inputs and use
+boto3 in the script. `SKILL.md` routes AWS callers directly to the role reference.
 
 ## Existing scripts