@skillcdn/console 0.1.6 → 0.1.8

package/skills/building-a-console/references/the-default-console.md

@@ -0,0 +1,140 @@
+# The default console, as it is wired
+
+The four files of the default UI, `apps/console/web/` in the console's repository, quoted here so that an agent that has the skill and not the repository starts from the same shape: the page with its root, the script that composes the console with the brand's marks and the Korean face, the build that links the icons from the brand's package and sends the API to a running server, and the compiler's settings. The repository's check keeps them identical to the files; the package's sources under `src/` say what each import is.
+
+### `apps/console/web/index.html`
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="color-scheme" content="dark" />
+    <title>Console</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+```
+
+### `apps/console/web/src/main.tsx`
+
+```tsx
+// The marks of the brand come from the main repository's package, never from a copy here
+// (ADR-0013); the build gives back their addresses. The pages are dark, so the wordmark is white.
+import symbol from "@skillcdn/brand/symbol.svg";
+import wordmark from "@skillcdn/brand/wordmark-white.svg";
+import { createConsole } from "@skillcdn/console";
+// The styles ship with the package; the build bundles them next to the script.
+import "@skillcdn/console/console.css";
+// The Korean face of SkillCDN's own pages, Pretendard, in the subsets a browser fetches as it
+// needs them; the package's stylesheet names it first and falls through to the system's faces.
+import "pretendard/dist/web/variable/pretendardvariable-dynamic-subset.css";
+
+// The default UI the image serves: the package's composition, with the default configuration
+// (docs/architecture.md, "The package and custom consoles"). A custom console is this file,
+// with a configuration of its own, in a repository of its own.
+
+const container = document.getElementById("root");
+if (container === null) {
+  throw new Error("the page has no #root element");
+}
+createConsole({ brand: { symbol, wordmark } }).mount(container);
+```
+
+### `apps/console/web/vite.config.ts`
+
+```ts
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import react from "@vitejs/plugin-react";
+import { defineConfig, type Plugin } from "vite";
+
+/** Where the `api` role listens by default; what the development server sends the API to. */
+const API_URL = "http://127.0.0.1:11199";
+
+const here = fileURLToPath(new URL(".", import.meta.url));
+const resolve = createRequire(import.meta.url).resolve;
+
+/** A file of the brand package as an address relative to the page, which the build takes as an asset. */
+function brandFile(name: string): string {
+  return path
+    .relative(here, resolve(`@skillcdn/brand/${name}`))
+    .split(path.sep)
+    .join("/");
+}
+
+// The page's icons come from `@skillcdn/brand`, as the symbol and the wordmark do in main.tsx
+// (ADR-0013): linked here, before the build reads the page, so that it bundles them next to the
+// script like any other asset and never copies them into this repository.
+const icons: Plugin = {
+  name: "console:icons",
+  transformIndexHtml: {
+    order: "pre",
+    handler: () => [
+      {
+        tag: "link",
+        attrs: { rel: "icon", href: brandFile("favicon.ico"), sizes: "32x32" },
+        injectTo: "head",
+      },
+      {
+        tag: "link",
+        attrs: { rel: "icon", href: brandFile("favicon.svg"), type: "image/svg+xml" },
+        injectTo: "head",
+      },
+      {
+        tag: "link",
+        attrs: { rel: "apple-touch-icon", href: brandFile("apple-touch-icon.png") },
+        injectTo: "head",
+      },
+    ],
+  },
+};
+
+// `vite build` writes the default UI into web/dist, which the `api` role serves from WEB_ROOT.
+// `vite` serves the UI with its own reloading and sends everything else to a running `api`.
+export default defineConfig({
+  root: here,
+  plugins: [react(), icons],
+  publicDir: false,
+  server: {
+    // Next to the api role's 11199, so that every local port of the project is one block.
+    port: 11198,
+    proxy: {
+      "/api": { target: API_URL, changeOrigin: false },
+      "/auth": { target: API_URL, changeOrigin: false },
+      "/healthz": { target: API_URL, changeOrigin: false },
+      "/readyz": { target: API_URL, changeOrigin: false },
+    },
+  },
+  build: {
+    outDir: "dist",
+    emptyOutDir: true,
+    sourcemap: true,
+  },
+});
+```
+
+### `apps/console/web/tsconfig.json`
+
+```json
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["ES2024", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "noEmit": true,
+    "types": ["vite/client", "node"]
+  },
+  "include": ["src", "vite.config.ts"],
+  "references": [{ "path": "../../../packages/console/tsconfig.build.json" }]
+}
+```
+
+What a console of one's own changes. In the page: its `<title>` and `lang`, and its icons, linked directly in the page or through the plugin, for its own. In the script: the `title` it passes; the two `@skillcdn/brand` imports, for its own symbol and wordmark (a light one, since the pages are dark), or none; the face it loads, for its languages (`npm install pretendard` for Korean). In the build: the proxy's target, `http://127.0.0.1:11197` with `changeOrigin: true` for `console serve`; the default console's own proxy points at the `api` role's development port, which a console of one's own does not have, and its plugin reads the icons from the brand package, which a console of one's own replaces with files of its own. In the compiler's settings: `jsx`, `moduleResolution` and the `vite/client` types stay, which make an imported picture a module; `extends` and `references` are the repository's and go, with `"strict": true` of the console's own in their place.

package/skills/deploying-a-console/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: deploying-a-console
+description: "Deploys a SkillCDN Console for an organization on AWS behind Cloudflare, with an agent on the person's own machine and no developer needed: asks a few plain questions (how many people, the web address, how people sign in and who is in, where the organization's skills are), shows the monthly cost of the size that fits and of the next one before anything is made, creates the database, the bucket, the secrets, the tunnel and the containers, leaves a private repository that redeploys on every push, signs the first administrator in, makes the first project, connects an agent and proves it all with a file handed in and read back. Also grows a deployment to the next size, updates it to a new version of the console, adds a member or rotates a secret. Use when an agent is asked to deploy, set up, host, upgrade or resize a console for an organization. To build a console's pages, use building-a-console; to work tasks on a board, use working-the-board."
+license: MIT
+compatibility: Needs a shell with Node.js 24 or newer, git, curl, jq and the AWS CLI v2, the gh command signed in or an empty repository the person made, network access to AWS, Cloudflare, GitHub and npm, an AWS account and a domain on Cloudflare the person can create a key and a token for, and a browser on any device for the few steps only a signed-in person can take. Works in any agent that can run a shell and write files; on Windows, in Git Bash with path conversion off.
+metadata:
+  author: skillcdn
+  version: "1.0"
+skillcdn:
+  translations:
+    ko:
+      title: 조직의 콘솔 배포하기
+      description: "조직의 SkillCDN 콘솔을 AWS와 Cloudflare에 배포합니다. 개발자가 아니어도 됩니다: 에이전트가 쉬운 질문 몇 개(몇 명이 쓰는지, 주소, 로그인 방식과 구성원, 조직 스킬의 위치)를 묻고, 맞는 크기와 그 다음 크기의 월 비용을 먼저 보여준 뒤, 데이터베이스·버킷·비밀·터널·컨테이너를 만들고, 푸시할 때마다 다시 배포되는 비공개 저장소를 남기고, 첫 관리자를 로그인시키고 첫 프로젝트를 만들고 에이전트를 연결해 파일 제출과 되읽기로 증명합니다. 규모 키우기, 콘솔 새 버전으로 올리기, 구성원 추가, 비밀 교체도 합니다. 조직의 콘솔을 배포·설치·호스팅·업그레이드·확장하라고 할 때 쓰세요. 콘솔 페이지를 만들 때는 building-a-console, 보드의 작업을 할 때는 working-the-board를 쓰세요."
+---
+# Deploying a console for an organization
+
+What goes in: an AWS account, a domain on Cloudflare or one to buy, and the answers to a few plain questions. What comes out: the console at `https://<hostname>`, signed in by its first administrator, with a first project and an agent connected; running as containers on AWS next to a managed PostgreSQL and a bucket, reached only through Cloudflare, every secret in a parameter store; a private deployment repository whose every push rebuilds and redeploys; a budget alert; and a record, `DEPLOY.md`, of what exists and how it is run. The person never needs to know the cloud: every choice is derived from their answers, shown with its cost, and changed when they ask. The shape and why it was chosen are [ADR-0017](/docs/adr/0017-the-reference-deployment-is-the-image-on-aws-behind-cloudflare-written-as-a-skill.md); what the console asks of any platform is [deploy/README.md](/deploy/README.md).
+
+## How the person is involved
+
+- **Questions:** one message at the start, the ones under "Inputs" that the request leaves open, in plain words. Then a second message, so that the questions stay short: the order of cost for the size ([sizing.md](references/sizing.md)'s snapshot, named as such) and the two credentials to create ([access.md](references/access.md)), so that the person knows what it costs before an account or a key exists, and the credentials are ready when the plan is.
+- **Checkpoints:** the plan with today's cost, before anything is made; each purchase with its price (a domain); a secret only the person holds, asked with the exact steps once the address is known; the first push, which starts the first build and makes the address public once it serves; the record's push; the deletion of the secrets file and the token file. One short message each, with the recommendation, and "OK", in the person's language, continues.
+- **Go-ahead:** when the person says to go ahead alone, the reports between phases need no answer. The plan, a purchase, the first push and a deletion are confirmed in every mode.
+- **Waiting:** what only the person or the world can finish, the run waits for, in the open. A domain whose nameservers the person must change answers at Cloudflare minutes to hours later: the zone is made first, the steps go out in the second message, and from phase 5 the run checks the zone every ten minutes for up to an hour, saying so; still not there, it stops with the record saying what waits and resumes at phase 5 when the person says the nameservers are set. The only way of signing in answered `later` means nobody can sign in: the run stops at phase 5 the same way and resumes when the secret is in the secrets file.
+- **Changes mid-run:** applied from that point. What was created is kept and recorded, never silently deleted.
+- **Language:** messages to the person in the language they wrote in; the repository's files in English, its `README.md` and `DEPLOY.md` in the organization's language.
+
+## Requirements
+
+| What | Used for |
+|---|---|
+| A shell with Node.js 24 or newer, git, curl, jq and the AWS CLI v2 (`aws --version`); on Windows, Git Bash with `export MSYS_NO_PATHCONV=1`, since Git Bash otherwise rewrites an argument that starts with `/` (a log group, a parameter) into a Windows path before a program sees it | Every command of the run; the deployment repository |
+| The deployer's access key and the Cloudflare token, as [access.md](references/access.md) says they are made and reach the agent | Everything on AWS and at Cloudflare |
+| The `gh` command signed in (`gh auth status`), or an empty private repository the person made | The deployment repository, its first push, watching its runs |
+| The `console` command, `npm install -g @skillcdn/console` in phase 1 | The proof at the end: an agent connected, a file handed in; and this skill's two scripts, which the package carries at `$(npm root -g)/@skillcdn/console/skills/deploying-a-console/scripts/`, copied into the run's `scratch/` folder, or read through the connection and written there |
+| The person, with a browser on any device | The OAuth app, the first sign-in, approving the agent's code, a registrar's nameservers |
+| Network access to AWS, Cloudflare, GitHub and npm | |
+
+Check these before the first message. Without the AWS CLI, offer to install it (access.md); without `gh`, the person makes the repository; without network, stop. This skill's own pages ([access.md](references/access.md), [sizing.md](references/sizing.md), [resources.md](references/resources.md)) arrive with it through SkillCDN, in the package, and in a copy of its directory. `deploy/README.md` and the decisions are read through the repository connection or in a checkout of the console's repository; without them, this skill and its pages carry the shape.
+
+## Inputs
+
+| Input | Source |
+|---|---|
+| How many people | Asked: "How many people will use the console within a year: just you, up to 10, up to 30, or up to 100?" The answer picks the size ([sizing.md](references/sizing.md)). |
+| The board's name | Asked, with the organization's name as the suggestion when the request gives one: "What should the board be called? Usually the organization's name." |
+| The web address | Asked: "Which web address should the console have? A domain you already own, and where it is registered (I set it up on Cloudflare; you change its nameservers there once, and I give you the steps), or should I find one to buy (I show the price before buying)? I suggest `console.<domain>`." A domain is needed: the tunnel has no free hostname. |
+| How people sign in, and who | Asked: "How should people sign in: with GitHub, with Google (Workspace), or both? Who is in: everyone's GitHub login or Google address, and who among them configures the console (you, at least)? With a Google Workspace, everyone of the domain can be in." |
+| The organization's skills | Asked: "Where are your organization's skills on SkillCDN, if anywhere yet? An address like `/gh/<owner>/<repo>`." Default: none; a project names one later on its Settings page. |
+| The AWS account | Asked: "Do you have an AWS account for this, or should the console get an account of its own (the simplest to run and to read the bill of)?" A new account is made by the person, on the paid plan, with the order of cost already in front of them (the second message). |
+| The region | Asked when the organization's country does not say: "Which AWS region: the one nearest your people?" Default: the nearest to where the organization is (`ap-northeast-2`, Seoul, for Korea; `ap-northeast-1` for Japan; `eu-central-1` for central Europe; `us-east-1` for the eastern United States). |
+| The run's folder | Asked with a suggestion: "Which folder should the deployment live in on this machine? I suggest `console-deploy` under your home folder." It is made at once and becomes the deployment repository. |
+| The deployment repository | Asked: "Where should the deployment's files live on GitHub: a private repository under your account, or under an organization you name?" Its name is the folder's. |
+| Where alerts go | Asked: "Which email should the cost alert go to?" |
+| The console's version | Derived: the current commit of `main` of the console's repository (`git ls-remote https://github.com/skillcdn/console main`), pinned in the deployment repository; an update is a new commit there. |
+| Everything else | Derived and shown in the plan: the size's numbers, the names (`console` for the cluster and the database, `api` and `worker` for the services, `console-files-<account id>` for the bucket), the generated secrets (`AUTH_SECRET`, the database password), the variables of [deploy/README.md](/deploy/README.md) with the tunnel's settings (`TRUSTED_PROXIES=127.0.0.1`, `CLIENT_IP_HEADER=cf-connecting-ip`, `HTTP_KEEP_ALIVE_SECONDS=100`), the estimate of this size and the next, the budget alert at one and a half times the estimate, the rate limiting rule on the sign-in paths, and what the person does once. |
+
+## Workflow
+
+Each phase produces a named artifact and ends with one line to the person. The procedure of each, its commands, its checks and what to do when a step fails, is in [resources.md](references/resources.md) under the phase's name; the sizes and the prices in [sizing.md](references/sizing.md); the credentials and the dashboard steps in [access.md](references/access.md).
+
+### Phase 1: Access
+
+Produces the **access record**: the account id, the region, the default VPC and its subnets, the Cloudflare account and the zone of the domain (or none yet), the git host owner. Make the run's folder with its `scratch/` subfolder and `.gitignore`; install the `console` command and copy this skill's scripts into `scratch/`; import the key into the profile `console` and read the token from its file, as access.md says, and verify each with the harmless calls there; report a missing permission now, with the row to add, not at the step that fails.
+
+### Phase 2: Plan and estimate
+
+Produces the **plan**, shown at the checkpoint. From the answers: the size and what it is made of (sizing.md "The sizes"); today's prices, read as sizing.md "Reading today's prices" says, and the estimate of this size and the next one, each line saying whether it is today's price or the snapshot; the resources to create under which names; the domain's path (owned, with the registrar's steps already sent; bought at the price shown); the secrets, which are generated, which are derived, and which the person holds and will be asked for at phase 3 with the exact steps; the budget alert; the few steps only the person takes, and when. Then stop, with the estimate message of sizing.md and: "I will create <the resources>, set <n> secrets, connect <hostname> through Cloudflare, and make a repository at <owner>/<name> that deploys on every push. You do once: <the steps>. OK?"
+
+### Phase 3: Foundation
+
+Produces the **resource record**: each resource with its name and id. In this order: the zone at Cloudflare, so that nameservers propagate meanwhile; the network and its two security groups; the database, started, and waited for while the rest is made; the bucket and its keys; the image repository, the log group, the roles, the cluster; the tunnel, the hostname, always-HTTPS and the rate limiting rule; the parameters, generated and derived, from the secrets file. Then, the hostname being known, the message for each secret the person holds (access.md "The OAuth app", "The OAuth client"): "Save it in the secrets file as the line I show, or say `later` and that way of signing in stays off until it is set." A value the person pastes into the chat instead is written into the file by the agent's file tool, never repeated, and the person is told to generate a new one once the run is over, since the chat kept a copy; the new one goes in as "a secret rotated" of the record.
+
+### Phase 4: The deployment repository
+
+Produces the **repository**: `deploy/console.env`, the task definitions `deploy/migrate.task.json`, `deploy/api.task.json` and, at the large size, `deploy/worker.task.json`, the workflow `.github/workflows/deploy.yml`, `README.md` and a draft `DEPLOY.md`, as resources.md gives them, every value filled from the record; and on AWS the role the workflow assumes, trusted for this repository's `main` alone. Show the files, each with the lines that matter pointed out for a person who is not a developer; commit; create the empty private repository. Checkpoint: "Pushing starts the first build (about ten minutes), runs the migrations, and starts the console at <hostname>. OK?" On the word, push, and watch the run to its end.
+
+### Phase 5: Live
+
+Produces the **live address**. The zone is active (else the wait of "How the person is involved"); `https://<hostname>/readyz` answers `200` through Cloudflare; the page shows the sign-in buttons of the providers set (none set: the stop of "How the person is involved"); the tunnel shows a connector; the log says `api listening`; the services are stable. Create the budget alert. Report the address.
+
+### Phase 6: The first people
+
+Produces the **first administrator and the first project**. Tell the person: "Open <address> and sign in with <provider>; you are an administrator. Make the first project: Projects, New project, a key such as `general`, its name, and the skills address <address or none>. Tell me the key." Then connect this agent: `console login --url <address> --agent deploying-a-console`, which shows an address and a code; relay them, and the person approves on the console's own pages. `console use <key>` in the run's folder.
+
+### Phase 7: Proof
+
+Produces the **proof**: `console task new "Deployment check"` with a body that says what this run deployed, `console take <number>` (the number and the run's id come from the two commands' `--json` answers), `console hand-in ./deployment-check.md --label "the check"` with a small file written for it, `console run <id> --json` showing the file with its hash, the object under that hash in the bucket (`aws s3api head-object`), and `console finish --summary "<what was deployed, and what is owed>"`. The task stays on the board as the first record of the deployment.
+
+### Phase 8: Record and delivery
+
+Produces **`DEPLOY.md`** in the repository, from the template in resources.md: what exists under which names, the size and its estimate, how a deploy happens, how to add a member, update, grow, rotate a secret, pause and remove, and what is owed. Checkpoint: "Committing and pushing the record. OK?" (a change to the record alone does not redeploy). Then, on the person's word, delete the secrets file and the token file. Deliver in one message: the address, what was made in the person's words, the estimate and the alert, what the person still owes (a `later` secret, nameservers), what was verified and how, and how the console is operated from here: the record, and a push.
+
+### Running it again
+
+The same skill, from phase 2, with the plan naming only what changes: a new version (the commit in `deploy/console.env`, a push), the next size (the numbers in the task definitions and a push; the database's class with one command, as sizing.md "Growing" says), a member added or removed (`MEMBERS` and `ADMINS` in `deploy/api.task.json`, a push), a secret rotated (the parameter overwritten, the service rolled), the console paused or removed (resources.md "Removing"). Each is confirmed at the plan, and the record is updated with it.
+
+### Verdicts
+
+| Result | Verdict |
+|---|---|
+| `/readyz` answers `200` at the hostname over HTTPS; the administrator signed in; the project made; the agent connected with a code; the file handed in is in the bucket under its hash and `console run` shows it; the workflow's run is green; every parameter is present; the record is pushed | Accepted |
+| A second way of signing in is `later` (it stays off); the budget alert waits on the person confirming its email | Accepted, with the gap named in `DEPLOY.md` and the delivery |
+| The zone waits for its nameservers, or the only way of signing in is `later`: phases 5 to 7 wait with it, the record says so, and the delivery says what was verified and what waits | Paused, to resume at phase 5 |
+| A task never becomes healthy (the log says why: exit `78` names a variable, a database unreachable names the network), the tunnel shows no connector, the first sign-in is refused, the migration task exits other than `0` | Redone from the phase that failed, with resources.md "When a step fails"; the person is told what was tried |
+
+## Hard rules
+
+1. The access key, the token and every secret stay out of the repository, the logs, the chat and the agent's own words: a value is read from its file into the environment or the parameter store, never put as a literal on a command line, never echoed; a value the person pasted is written to its file with a file tool and the person is told to make a new one when the run is over; the secrets file is deleted, on the person's word, when its values are stored. A leak means a rotation, which the person is told at once.
+2. Nothing is bought or made before the price is in front of the person and they said the word: the second message carries the order of cost, the plan carries today's estimate of everything that bills; a domain is bought only after its price is shown.
+3. The first push is confirmed, and every push after it: once the repository is connected, a push is a deployment, which the person chose at the plan.
+4. The person is never asked to do what the key and the token can do; what only they can do (an OAuth app, a sign-in, approving a code, nameservers at their registrar) is given as the exact steps of the day in one message, for the registrar they named where its steps are known and in general words otherwise, so that they can do it while the run goes on.
+5. Nothing of the deployment listens on the internet: the tasks' security group has no inbound rule, the database is not publicly accessible, the bucket blocks public access, and the hostname reaches the console only through the tunnel.
+6. Names and ids go into the repository and the record; a value a secret scanner would flag never does, and `scratch/`, the key file and the token file never enter git. Every file the repository gets is shown before it is pushed.
+7. What was created is kept and recorded, never silently deleted; removing the deployment is a run of its own, asked for, and confirmed resource by resource.
+8. The console's contract holds on every rollout: `migrate` runs and exits `0` before the new `api` and `worker` start, the stop timeout stays above the shutdown grace period, and no secret is a build argument.
+
+## Terms
+
+| Term | Meaning |
+|---|---|
+| Size | `small`, `medium` or `large`: the numbers of sizing.md, chosen by how many people. |
+| The deployer | The IAM user whose key the agent acts with, as the profile `console` of the AWS CLI. |
+| The run's folder | The folder the person chose, which becomes the deployment repository; `scratch/`, the key file and the token file in it never enter git; the secrets file is beside it, in the folder above. |
+| The tunnel | The Cloudflare Tunnel whose connector runs beside the `api` container; the hostname's traffic comes in through it and nothing else does. |
+| Task, service | On ECS, a task is the containers of one role running together; a service keeps the wanted number of tasks running and rolls them to a new definition. |
+| Parameter | A value in SSM Parameter Store that a task reads as an environment variable at start. |
+| The deployment repository | The private repository of the task definitions, the workflow and the record; a push to it is a deployment. |
+| `DEPLOY.md` | The record: what exists under which names, how it is run, what is owed, what it costs. |
+| Later | A secret the person did not supply; the way of signing in it serves stays off, and the record says so. |

package/skills/deploying-a-console/assets/deployer-policy.json

@@ -0,0 +1,118 @@
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Sid": "WhoAmIAndPrices",
+      "Effect": "Allow",
+      "Action": ["sts:GetCallerIdentity", "pricing:GetProducts", "ec2:DescribeRegions"],
+      "Resource": "*"
+    },
+    {
+      "Sid": "Network",
+      "Effect": "Allow",
+      "Action": [
+        "ec2:DescribeVpcs",
+        "ec2:DescribeSubnets",
+        "ec2:DescribeSecurityGroups",
+        "ec2:DescribeAvailabilityZones",
+        "ec2:DescribeNetworkInterfaces",
+        "ec2:CreateDefaultVpc",
+        "ec2:CreateSecurityGroup",
+        "ec2:DeleteSecurityGroup",
+        "ec2:AuthorizeSecurityGroupIngress",
+        "ec2:RevokeSecurityGroupIngress",
+        "ec2:CreateTags"
+      ],
+      "Resource": "*"
+    },
+    {
+      "Sid": "Containers",
+      "Effect": "Allow",
+      "Action": ["ecs:*", "ecr:*", "logs:*"],
+      "Resource": "*"
+    },
+    {
+      "Sid": "Database",
+      "Effect": "Allow",
+      "Action": ["rds:*"],
+      "Resource": "*"
+    },
+    {
+      "Sid": "Files",
+      "Effect": "Allow",
+      "Action": ["s3:*"],
+      "Resource": ["arn:aws:s3:::console-*", "arn:aws:s3:::console-*/*"]
+    },
+    {
+      "Sid": "ListBuckets",
+      "Effect": "Allow",
+      "Action": ["s3:ListAllMyBuckets"],
+      "Resource": "*"
+    },
+    {
+      "Sid": "Parameters",
+      "Effect": "Allow",
+      "Action": [
+        "ssm:PutParameter",
+        "ssm:GetParameter",
+        "ssm:GetParameters",
+        "ssm:GetParametersByPath",
+        "ssm:DeleteParameter",
+        "ssm:AddTagsToResource"
+      ],
+      "Resource": "arn:aws:ssm:*:*:parameter/console/*"
+    },
+    {
+      "Sid": "ListParameters",
+      "Effect": "Allow",
+      "Action": ["ssm:DescribeParameters"],
+      "Resource": "*"
+    },
+    {
+      "Sid": "RolesAndUsersOfTheConsole",
+      "Effect": "Allow",
+      "Action": [
+        "iam:CreateRole",
+        "iam:DeleteRole",
+        "iam:GetRole",
+        "iam:UpdateAssumeRolePolicy",
+        "iam:AttachRolePolicy",
+        "iam:DetachRolePolicy",
+        "iam:PutRolePolicy",
+        "iam:DeleteRolePolicy",
+        "iam:ListAttachedRolePolicies",
+        "iam:ListRolePolicies",
+        "iam:PassRole",
+        "iam:TagRole",
+        "iam:CreateUser",
+        "iam:DeleteUser",
+        "iam:GetUser",
+        "iam:PutUserPolicy",
+        "iam:DeleteUserPolicy",
+        "iam:CreateAccessKey",
+        "iam:DeleteAccessKey",
+        "iam:ListAccessKeys",
+        "iam:TagUser"
+      ],
+      "Resource": ["arn:aws:iam::*:role/console-*", "arn:aws:iam::*:user/console-*"]
+    },
+    {
+      "Sid": "ServiceLinkedRolesAndTheGitHostProvider",
+      "Effect": "Allow",
+      "Action": [
+        "iam:CreateServiceLinkedRole",
+        "iam:CreateOpenIDConnectProvider",
+        "iam:GetOpenIDConnectProvider",
+        "iam:ListOpenIDConnectProviders",
+        "iam:TagOpenIDConnectProvider"
+      ],
+      "Resource": "*"
+    },
+    {
+      "Sid": "BudgetAlert",
+      "Effect": "Allow",
+      "Action": ["budgets:ViewBudget", "budgets:ModifyBudget"],
+      "Resource": "*"
+    }
+  ]
+}

package/skills/deploying-a-console/assets/secrets.example.json

@@ -0,0 +1,11 @@
+{
+  "_": "The shape of the secrets file the run keeps outside any repository and deletes, on the person's word, once every value is in the parameter store. A value is what the run generated or derived, what the person gave, or the word later; a provider the person did not choose has no line.",
+  "AUTH_SECRET": "generated: 48 random characters, never shown",
+  "DATABASE_URL": "derived: postgres://console:<generated password>@<database endpoint>:5432/console",
+  "DATABASE_CA": "derived: the regional certificate bundle of the database service, as PEM",
+  "S3_ACCESS_KEY_ID": "derived: the access key id of the files user",
+  "S3_SECRET_ACCESS_KEY": "derived: its secret",
+  "TUNNEL_TOKEN": "derived: the connector token of the tunnel",
+  "GITHUB_CLIENT_SECRET": "asked: the client secret of the OAuth app, or later",
+  "GOOGLE_CLIENT_SECRET": "asked: the client secret of the OAuth client, or later"
+}

package/skills/deploying-a-console/references/access.md

@@ -0,0 +1,78 @@
+# Access: what the person creates once, and how it reaches the agent
+
+What the agent needs to act on the organization's accounts, the exact steps of the day for the person to create each, and how each value reaches the agent without passing through the chat. Dashboards move; every path here carries the month it was checked, and the vendor's own page is the source when a label has changed.
+
+## The AWS account and the deployer
+
+**Which account.** The skill asks whether the organization has an account for this. A dedicated AWS account for the console is the simplest to run and to read the bill of: nothing else shares it, and one budget alert covers it. An account that already runs other things works with the scoped policy below. A new account (`aws.amazon.com`, Create an AWS account; a payment method is asked; checked 2026-10) is created by the person on the **paid plan**, once the order of cost is in front of them (the skill's second message): the free plan ends after six months and closes the account with its data, and a console is meant to stay. Both plans start with credits, which the paid plan spends on the first months' bills.
+
+**The deployer user and its policy.** Signed in to the account, in the IAM console (checked 2026-10):
+
+1. Users, Create user. Name `console-deployer`. Leave console access off: this user is for the agent's commands only. Next.
+2. Permissions: Attach policies directly. In a dedicated account, `AdministratorAccess`, which is the honest choice when nobody else is in the account. In a shared account, first create a policy from [deployer-policy.json](../assets/deployer-policy.json) (Policies, Create policy, JSON, paste, name it `console-deployer`), then attach that one. The scoped policy is broad where names cannot be known in advance and tight where they can (`console-` prefixed roles, users and buckets, `/console/` parameters); a step the policy does not cover fails with `AccessDenied` naming the action, and the fix is to add that action.
+3. Create user. Open it, Security credentials, Access keys, Create access key. Use case: Command Line Interface (and tick the confirmation), or Other. Next, Create access key. **Download .csv file.** The secret is shown once; the file is the one copy.
+
+**How the key reaches the agent.** Save the downloaded file as `.aws-key.csv` in the run's folder, and tell the agent. The agent reads the two values from the file with a script, writes them as the profile `console` into the AWS CLI's own credentials file (`~/.aws/credentials`, the person's file, readable by them alone where the system can say so), sets the region on the profile, and deletes `.aws-key.csv`; neither value is ever written in a command line, a message or a log. A key pasted into the chat instead is written to the profile the same way and never repeated, and the person is told to make a new key once the run is over, since the chat kept a copy.
+
+**The AWS CLI.** Version 2: `aws --version`. Without it, Windows: `winget install Amazon.AWSCLI`; macOS: `brew install awscli`, or the installer at `docs.aws.amazon.com/cli` (checked 2026-10). The agent installs it with the person's word.
+
+**Verify:**
+
+```sh
+aws sts get-caller-identity --profile console          # the account id, and the user's ARN
+aws ec2 describe-vpcs --profile console --filters Name=is-default,Values=true --query 'Vpcs[0].VpcId'
+```
+
+The first answers with the account id the plan names; the second with the default VPC, or nothing, in which case `aws ec2 create-default-vpc` makes one (the deployer's policy allows it). Every command of the run carries `--profile console` (or `AWS_PROFILE=console` in the shell) and `--region <region>`.
+
+## The Cloudflare account and the token
+
+**The domain.** The console's address is a hostname of a zone on Cloudflare: a domain the organization already has, moved to Cloudflare's nameservers (the zone is made first in the run, and the two nameservers it answers go to the person to set at their registrar), or one bought through Cloudflare's Registrar in the run with its price shown first. There is no free hostname for a tunnel; a domain is needed. The account is free (`dash.cloudflare.com/sign-up`).
+
+**The nameservers, at the registrar.** The person named the registrar with the domain; give its steps where they are known (the registrar's own help page for "nameservers" or "DNS settings", read at run time), and otherwise the general ones: sign in at the registrar, open the domain, find the nameserver (NS) setting, replace what is there with the two names Cloudflare gave, save; the change takes minutes to hours to reach the world, and the run checks the zone's status until it is `active`. Everything else of the domain's DNS (mail records, other hosts) is copied into the Cloudflare zone before the switch, from what the registrar shows, so that nothing stops working; the run asks for that list when the domain already serves something.
+
+**The token.** My Profile, API Tokens (`dash.cloudflare.com/profile/api-tokens`), Create Token, **Create Custom Token** (checked 2026-10). Name it `console deploy`. Permissions, one row each:
+
+| Scope | Permission | Level | For |
+|---|---|---|---|
+| Account | Cloudflare Tunnel | Edit | The tunnel the task connects out through, and its routing |
+| Account | Account Settings | Read | Listing accounts, the account id |
+| Zone | DNS | Edit | The console's hostname |
+| Zone | Zone | Edit | Making the zone for a domain the organization owns, finding it, its status and nameservers |
+| Zone | Zone Settings | Edit | Always use HTTPS |
+| Zone | Zone WAF | Edit | The rate limiting rule |
+| Account | Registrar | Edit | Only when a domain is to be bought in the run |
+
+Zone Resources: Include, All zones, so that a zone made in the run is covered. Account Resources: the one account. Client IP filtering: none. TTL: none, or a year. Continue to summary, Create Token, copy the secret once.
+
+**How it reaches the agent.** Save it in a file named `.cf-token` in the run's folder (a file without an extension: in Notepad, "All files" as the type, so that it is not `.cf-token.txt`), and tell the agent; the agent reads it into the environment for each call and never prints it. The file is listed in the deployment repository's `.gitignore` from the first commit, and deleted at the end of the run on the person's word. A token pasted into the chat is written into the file with the agent's file tool and never repeated, and the person is told to make a new token once the run is over, since the chat kept a copy.
+
+**Verify:**
+
+```sh
+CLOUDFLARE_API_TOKEN=$(tr -d '\r\n ' < .cf-token)
+curl -s https://api.cloudflare.com/client/v4/user/tokens/verify -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
+curl -s https://api.cloudflare.com/client/v4/zones -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
+curl -s https://api.cloudflare.com/client/v4/accounts -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
+```
+
+`"status": "active"`, the zones the token sees (the domain among them, or none yet), and the account with its id. The file carries a carriage return on Windows; the `tr` strips it.
+
+## The git host
+
+**The deployment repository.** The organization's deployment lives in a private repository on GitHub: the task definitions, the workflow that builds and deploys, the record. The agent makes it with the `gh` command signed in (`gh auth status`; `gh auth login` otherwise, which opens the browser for the person) under the owner the person names: their account, or an organization. Without `gh`, the person creates an empty private repository in the browser (New repository, private, no README) and gives its address, and the agent pushes to it.
+
+**The OAuth app, for signing in with GitHub.** Once the console's address is known, the person, signed in to GitHub (checked 2026-10): Settings (under the avatar), Developer settings, OAuth Apps, New OAuth App (Register a new application, the first time).
+
+- Application name: the board's name.
+- Homepage URL: the console's address, `https://<hostname>`.
+- Authorization callback URL: `https://<hostname>/auth/gh/callback`.
+- Register application. Copy the **Client ID** into the chat (it is not secret). Generate a new client secret, and save it to the secrets file as `GITHUB_CLIENT_SECRET` (below), as the line the agent shows. A secret pasted into the chat instead is written into the file by the agent's file tool and never repeated, and the person generates a new one once the run is over, since the chat kept a copy; the new one goes in as "a secret rotated" of the record.
+
+An organization-owned app is the same form under the organization's settings, Developer settings. No scopes are needed: the console asks only who the person is.
+
+**The OAuth client, for signing in with Google.** In the Google Cloud console, a project of the organization's, Google Auth Platform (checked 2026-10): if the project has not registered with Google Auth yet, the Overview asks for the app's name, a support address and the audience (Internal, for a Workspace organization), once. Then Clients, Create client, Application type **Web application**, name it, under Authorized redirect URIs add `https://<hostname>/auth/google/callback`, Create. Copy the **Client ID** into the chat; the client secret is shown once: save it to the secrets file as `GOOGLE_CLIENT_SECRET`, as the line the agent shows (pasted instead: written to the file by the agent, never repeated, and replaced after the run, as with GitHub's). The Workspace domain, when everyone of it is a member, is the plan's `GOOGLE_WORKSPACE_DOMAIN`. Changes take from minutes to hours to be effective at Google.
+
+## The secrets file
+
+What the person holds (a client secret) is written to a file outside any repository, in the shape of [secrets.example.json](../assets/secrets.example.json): `console-secrets.json` in the folder above the run's folder, with the generated and derived values the run adds to it. The run reads it to put each value in the parameter store, and deletes it at the end on the person's word. A value the person says `later` to leaves its provider out until it is set; the record names it. A provider the person did not choose has no line in it.