sporades 0.1.0 → 0.2.0

package/CHANGES.md

@@ -0,0 +1,43 @@
+# Changes
+
+## Unreleased - 2026-07-07
+
+Changes since v0.1.0.
+
+### 🚀 Features
+
+- Add packaging scripts (31a33c5).
+- Add consistent change-log generation via skill (0b8bc4f).
+- Enable Hosted Capsule SSH access (d59abaa).
+- Enable local Container SSH access (8720842).
+- Add current-user preferences SDK (570d769).
+- Allow dependency install for local repository working (a35db4c).
+- Add requireAuth handler helper as the canonical auth gate (7bb7ee6).
+
+### 🔧 Improvements
+
+- Mark user preferences coherence issue done (5e49203).
+- Mark user preferences SDK issue done (9119388).
+- Mark built-in-auth-helper issue 01 done (2d6d470).
+- Rebuild bundle after merging requireAuth helper (160ce44).
+
+### 📝 Documentation
+
+- Update docs (e5e42d6).
+- Rewording (aee6676).
+- Document Container SSH access (62d9f54).
+- Define Container SSH access contract (d23386a).
+- Document public SDK API (f135dd0).
+- Persist user prefs from anonymous to a signed-up user on registration (d2d9d6c).
+- Update docs (7469398).
+- Update preference table inspection coverage (790e49c).
+- Keep user preferences coherent across sessions (703e826).
+- Plan recommended roadmap features (4975e8d).
+- Tidy up working files (f29fff5).
+- Record service-backed vector path (pgvector) as follow-up (e1dfa7a).
+- Promote auth helper and SQLite vector features to ready (ea1610b).
+- Update documentation files in the working tree: docs/api/functions/client.createHooks.html, docs/api/functions/client.isAuthenticated.html, docs/api/functions/client.onMessage.html, docs/api/functions/client.sendMessage.html, docs/api/functions/server.Boolean.html, docs/api/functions/server.capsule.html, docs/api/functions/server.Date.html, docs/api/functions/server.endpoint.html, docs/api/functions/server.Json.html, docs/api/functions/server.message.html, docs/api/functions/server.mutation.html, docs/api/functions/server.Number.html, docs/api/functions/server.query.html, docs/api/functions/server.Reference.html, docs/api/functions/server.requireAuth.html, docs/api/functions/server.String.html, docs/api/functions/server.table.html, docs/api/types/client.AppMessage.html, docs/api/types/client.AppMessageStream.html, docs/api/types/client.AuthApi.html, docs/api/types/client.AuthProviders.html, docs/api/types/client.AuthState.html, docs/api/types/client.EmailCredentials.html, docs/api/types/client.FileMetadata.html, docs/api/types/client.FileReference.html, docs/api/types/client.FilesApi.html, docs/api/types/client.HookPrimitives.html, docs/api/types/client.JsonObject.html, docs/api/types/client.JsonValue.html, docs/api/types/client.MutationState.html, docs/api/types/client.PreferencesApi.html, docs/api/types/client.PreferencesResult.html, docs/api/types/client.ProviderState.html, docs/api/types/client.PublicFileUrl.html, docs/api/types/client.PublicUrlOptions.html, docs/api/types/client.QueryState.html, docs/api/types/client.SporadesError.html, docs/api/types/client.SporadesHooks.html, docs/api/types/client.SporadesResult.html, docs/api/types/client.Subscription.html, docs/api/types/client.UploadCompleteEvent.html, docs/api/types/client.UploadOptions.html, docs/api/types/client.UploadProgressEvent.html, docs/api/types/client.UseAuthState.html, docs/api/types/server.AclDatabaseHelpers.html, docs/api/types/server.AclHelpers.html, docs/api/types/server.AclStorageFileMetadata.html, docs/api/types/server.AclStorageHelpers.html, docs/api/types/server.AnyFieldDefinition.html, docs/api/types/server.AuthContext.html, docs/api/types/server.AutoFields.html, docs/api/types/server.Capsule.html, docs/api/types/server.CapsuleContext.html, docs/api/types/server.CapsuleDefinition.html, docs/api/types/server.CapsuleHooks.html, docs/api/types/server.ContextKind.html, docs/api/types/server.ContextMiddleware.html, docs/api/types/server.DatabaseFromSchema.html, docs/api/types/server.EndpointContext.html, docs/api/types/server.EndpointDefinition.html, docs/api/types/server.EndpointHandler.html, docs/api/types/server.EndpointOptions.html, docs/api/types/server.EndpointRequest.html, docs/api/types/server.FieldBuilder.html, docs/api/types/server.FieldDefinition.html, docs/api/types/server.FieldKind.html, docs/api/types/server.FieldValue.html, docs/api/types/server.InsertValues.html, docs/api/types/server.JsonValue.html, docs/api/types/server.Logger.html, docs/api/types/server.MaybePromise.html, docs/api/types/server.MessageApi.html, docs/api/types/server.MessageDefinition.html, docs/api/types/server.MessageHandler.html, docs/api/types/server.MessageScope.html, docs/api/types/server.MiddlewareContext.html, docs/api/types/server.MutationDefinition.html, docs/api/types/server.MutationHandler.html, docs/api/types/server.MutationHook.html, docs/api/types/server.MutationHookEvent.html, docs/api/types/server.MutationResult.html, docs/api/types/server.OrderDirection.html, docs/api/types/server.QueryDefinition.html, docs/api/types/server.QueryHandler.html, docs/api/types/server.ReferenceFieldBuilder.html, docs/api/types/server.ReferenceFieldDefinition.html, docs/api/types/server.RequireAuthOptions.html, docs/api/types/server.RowFromFields.html, docs/api/types/server.SchemaDefinition.html, docs/api/types/server.TableAclContext.html, docs/api/types/server.TableAclOperation.html, docs/api/types/server.TableAclRule.html, docs/api/types/server.TableAclRuleInput.html, docs/api/types/server.TableAclRules.html, docs/api/types/server.TableApi.html, docs/api/types/server.TableDefinition.html, docs/api/types/server.UpdateValues.html, docs/api/variables/client.auth.html, docs/api/variables/client.files.html, docs/api/variables/client.preferences.html.
+
+### 📦 Packaging
+
+- Update packaging and release flow (6a5cd20).

package/Dockerfile.base

@@ -8,9 +8,30 @@ LABEL com.sporades.base-image.name="sporades-base"
 LABEL com.sporades.base-image.version="0.1.0-node22-alpine"
 LABEL com.sporades.base-image.node="22"
 
-RUN addgroup -g 10001 -S sporades \
+RUN apk add --no-cache openssh-server \
+  && addgroup -g 10001 -S sporades \
   && adduser -u 10001 -S sporades -G sporades \
-  && mkdir -p /app /app/data \
+  && mkdir -p /app /app/data /run/sshd \
+  && ssh-keygen -A \
+  && printf '%s\n' \
+    '#!/bin/sh' \
+    'set -eu' \
+    'if [ -n "${SPORADES_SSH_AUTHORIZED_KEYS_PATH:-}" ] && [ -s "${SPORADES_SSH_AUTHORIZED_KEYS_PATH}" ]; then' \
+    '  target="${SPORADES_SSH_AUTHORIZED_KEYS_TARGET:-/app/data/ssh/authorized_keys}"' \
+    '  ssh_dir="$(dirname "$target")"' \
+    '  mkdir -p "$ssh_dir"' \
+    '  cp "${SPORADES_SSH_AUTHORIZED_KEYS_PATH}" "$target"' \
+    '  if [ ! -s "$ssh_dir/ssh_host_ed25519_key" ]; then' \
+    '    ssh-keygen -t ed25519 -f "$ssh_dir/ssh_host_ed25519_key" -N "" >/dev/null' \
+    '  fi' \
+    '  chmod 700 "$ssh_dir"' \
+    '  chmod 600 "$target"' \
+    '  chmod 600 "$ssh_dir/ssh_host_ed25519_key"' \
+    '  /usr/sbin/sshd -f /etc/ssh/sshd_config -o PasswordAuthentication=no -o PermitRootLogin=no -o AllowUsers=sporades -o AuthorizedKeysFile="$target" -o HostKey="$ssh_dir/ssh_host_ed25519_key" -o PidFile=/tmp/sporades-sshd.pid' \
+    'fi' \
+    'exec node /app/server.mjs' \
+    > /usr/local/bin/sporades-start \
+  && chmod 0755 /usr/local/bin/sporades-start \
   && chown -R 10001:10001 /app
 
 WORKDIR /app

package/README.md

@@ -1,289 +1,242 @@
 # Sporades
 
-## Documentation
+<p align="center">
+  <a href="https://www.npmjs.com/package/sporades"><img alt="npm version" src="https://img.shields.io/npm/v/sporades.svg"></a>
+  <a href="https://www.npmjs.com/package/sporades"><img alt="npm downloads" src="https://img.shields.io/npm/dm/sporades.svg"></a>
+  <a href="https://nodejs.org/"><img alt="Node.js >=22" src="https://img.shields.io/badge/node-%3E%3D22-339933?logo=node.js&logoColor=white"></a>
+  <a href="https://github.com/mgscox/sporades/blob/main/LICENSE"><img alt="MIT license" src="https://img.shields.io/npm/l/sporades.svg"></a>
+  <a href="https://github.com/mgscox/sporades"><img alt="GitHub repository" src="https://img.shields.io/badge/GitHub-mgscox%2Fsporades-181717?logo=github"></a>
+</p>
 
-- [User guide](docs/user-guide.md) - quick start and day-to-day Capsule usage.
-- [Architecture](docs/architecture.md) - platform ethos, runtime layout, Host
-  routing, storage, and client transport.
-- [Roadmap](docs/ROADMAP.md) - candidate features and their promotion status.
-- [Runtime layout](docs/runtime-layout.md) - canonical filesystem paths,
-  runtime mounts, and Host server directory structures.
-- [Host server installation](docs/server-installation.md) - preparing a Linux
-  Host server for Hosted Capsules.
-
-## Auth
-
-Sporades apps can enable multiple auth providers in `sporades.json`:
-
-```json
-{
-  "auth": {
-    "providers": {
-      "anonymous": true,
-      "google": {
-        "clientIdEnv": "GOOGLE_CLIENT_ID",
-        "clientSecretEnv": "GOOGLE_CLIENT_SECRET"
-      },
-      "email": true
-    }
-  }
-}
-```
+<p align="center">
+  <a href="https://www.npmjs.com/package/sporades">[npm package]</a>
+</p>
 
-`anonymous`, `google`, and `email` are valid provider names. Existing projects
-using `auth.mode` continue to work; `auth.mode: "anonymous"` maps to anonymous
-sessions, and `auth.mode: "google"` enables Google alongside anonymous sessions.
+Designed as Agents-first, Sporades is a CLI-first platform for building, running, inspecting, and hosting
+small full-stack web Capsules.
 
-Configure Google OAuth from explicit credentials:
+It is intended for developers and coding Agents who want deterministic commands
+instead of dashboards: scaffold a Capsule, run it locally, test the bundled
+runtime in Docker, then publish it to a private or cloud Host server.
 
 ```sh
-sporades auth set google --client-id <id> --client-secret <secret>
+# install sporades globally
+npm install -g sporades
+sporades -h
 ```
 
-Or pass a downloaded Google OAuth client JSON file:
+Create a 'todo' app and spin-up a live-refresh dev server, a staging server on local docker service, and deploy to a remote production server:
 
 ```sh
-sporades auth set google --client-json ./client_secret_google.json
+sporades create notes --template todo
+cd notes
+sporades dev
+sporades deploy
+sporades host push --restart
 ```
 
-The JSON form reads Google Web application credentials from `web.client_id` and
-`web.client_secret`. Sporades stores the values in `.env.sporades.server` and
-keeps only env var names in `sporades.json`.
+## Why Sporades?
+
+- **One command loop for humans and agents**: create, run, inspect, deploy, and
+  repair Capsules from the terminal.
+- **Full-stack without the usual wiring**: server schema, queries, mutations,
+  auth, file uploads, custom endpoints, app messages, and browser hooks live
+  behind a small authoring API.
+- **Same bundle everywhere**: Dev sessions, local Docker Container sessions, and
+  Hosted Capsules all run the same bundled server and client output.
+- **Private-host friendly**: Host servers use boring, inspectable pieces:
+  Docker, Caddy, Node, SQLite, filesystem storage, and SSH.
+- **Agent-operable by default**: structured JSON output, actionable error hints,
+  logs, database inspection, and non-interactive commands are first-class.
+- **Comprehensive SDK**: built-in authentication, database, user preferences,
+  and storage.
+- **Realtime everything**: configuration free - automatic notifications, even for Postgress and AWS-S3
+
+## Documentation
+
+- [User guide](docs/user-guide.md): build, run, inspect, deploy, auth,
+  preferences, files, endpoints, messages, and common workflows.
+- [Architecture](docs/architecture.md): platform model, runtime modes, Host
+  server design, and ownership boundaries.
+- [Runtime layout](docs/runtime-layout.md): generated files, mounts, Host
+  directories, and persistent data locations.
+- [Host server installation](docs/server-installation.md): prepare a Linux Host
+  server for Hosted Capsules.
+- [Product requirements](docs/PRD.md): implemented scope, deferred scope, and
+  core product principles.
+- [Roadmap](docs/ROADMAP.md): candidate features and promotion status.
 
-`sporades auth status --json` reports enabled providers and configuration state
-without printing OAuth client IDs or secrets.
+## A Tiny Capsule - the entire server code for a real-time 'to-do' app
 
-List currently connected browser clients for a running dev session:
+```ts
+// Everything we need comes from Sporades server SDK
+import {
+  Boolean,
+  String,
+  capsule,
+  mutation,
+  query,
+  table,
+} from "sporades/server";
+
+export default capsule({
+  name: "notes",
+
+  // tables automatically get createdAt, createdBy, and a unique Id
+  schema: {
+    // tables can have optional ACL - default is "open to all"
+    todos: table({
+      text: String(),
+      done: Boolean().default(false),
+      ownerId: String(),
+    }),
+  },
+
+  // queries are automatically write-through cached on the server
+  queries: {
+    // all todo entries for current user (anonymous by default)
+    todos: query((ctx) =>
+      // context 'ctx' contains user, db, storage, auth, etc.
+      ctx.db.todos
+        .where("ownerId", ctx.auth.userId)
+        .orderBy("createdAt", "desc")
+        .all(),
+    ),
+  },
+
+  mutations: {
+    addTodo: mutation((ctx, text: string) =>
+      ctx.db.todos.insert({ text, ownerId: ctx.auth.userId }),
+    ),
+  },
+});
+```
+
+Client scaffolds wire `sporades/client` into React or Preact hooks so the UI can
+subscribe to queries and run mutations without hand-rolled fetch plumbing.
+
+## What You Get
+
+Sporades currently includes:
+
+- React and Preact project scaffolds with `blank`, `todo`, `guestbook`, and
+  `photo-library` templates.
+- Local Dev sessions with rebuilds, WebSocket reconnects, SQLite persistence,
+  logs, database inspection, auth helpers, and file storage.
+- Local Docker Container sessions for production-like staging tests.
+- Hosted Capsules on SSH-reachable Host servers, routed through Caddy and run in
+  hardened Docker containers.
+- Runtime-owned auth with anonymous sessions, email auth, Google OAuth, and
+  local identity simulation for tests and agents.
+- Runtime-owned current-user preferences exposed through `sporades/client`
+  without app preference tables. Preferences follow the Sporades user identity,
+  survive Anonymous account linking, and notify same-user connected clients when
+  they change.
+- File uploads with private reads, explicit public URLs, replacement versions,
+  and local MinIO-backed storage support.
+- Custom HTTP endpoints and app messages over the Sporades client transport.
+- Sealed Server env for public/private key encrypted server-only environemt variables, keeping them out of browser bundles and
+  release archives.
+
+File reads stay behind Sporades HTTP routes. They are not filesystem paths or presigned MinIO/S3 URLs.
+Capsules can opt into local MinIO storage with
+`services.storage.engine: "minio"`; omitted upload paths use the file name in
+the Default File bucket, falling back to the logical `/default/upload` File path when no file name exists.
+The Default File bucket is only a namespace fallback, not a user bucket or policy boundary.
+
+## Install
+
+Sporades requires Node.js 22 or newer. Install the CLI from npm:
 
 ```sh
-sporades auth clients --json
+npm install --global sporades
+sporades --help
 ```
 
-The JSON response includes safe metadata only: stable client IDs, current auth
-summary, connection time, and last-seen time. It does not include session
-tokens, OAuth credentials, passwords, or raw `localStorage` payloads.
+Sporades depends on `esbuild` for Capsule bundling. On newer npm versions, you
+may see an `allow-scripts` warning during global install because `esbuild` uses
+a postinstall script to select the native binary for your platform.
 
-For local browser tests and agents, a running dev session can create a simulated
-linked identity and return the same session token shape the SDK stores in
-`localStorage`:
+If npm blocks that script and bundling later fails, reinstall while explicitly
+allowing the `esbuild` install script:
 
 ```sh
-sporades auth as email --email mira@example.com --display-name "Mira Vale" --json
+npm install --global sporades --allow-scripts=esbuild
 ```
 
-Pass `--client current` to push the simulated session into the most recently
-connected browser client, `--client all` to push it into every connected
-browser client for the app, or `--client <id>` with an ID from
-`sporades auth clients --json` to target one exact browser client:
+To approve `esbuild` persistently for your user npm config:
 
 ```sh
-sporades auth as email --email mira@example.com --client current --json
+npm config set allow-scripts=esbuild --location=user
 ```
 
-The JSON response includes `{ localStorage: { key, value }, auth, delivery }`,
-where `key` is `sporades.sessionToken`. `delivery` reports the requested target,
-whether any browser client received the session, and how many clients were
-updated. The `localStorage` payload is always returned as a manual fallback even
-when no browser client is connected. This is local identity simulation only: it
-creates a Sporades-owned dev session for `ctx.auth` testing and does not
-complete OAuth, trust arbitrary JWTs, or authenticate against a real provider.
-`google` can be used as a simulated provider shape for browser tests that need
-Google-like auth metadata. Simulated sessions use the same session lifetime as
-normal Sporades sessions.
-
-Sporades session records store creation and expiry metadata. Sessions expire 30
-days after they are created or refreshed. Missing, invalid, or expired session
-tokens resolve to a fresh anonymous session instead of authenticating the old
-user forever. Email sign-up links the current anonymous account and rotates the
-session token; email sign-in rotates the current anonymous token onto the email
-account. Google sign-in links through the server-owned OAuth callback and
-refreshes the current session token's expiry, because the redirect callback does
-not expose a safe client token handoff point.
-
-After running `sporades auth set <provider>`, restart any running dev session so
-the server runtime reloads the updated Server env and auth configuration:
+When working in this repository, plain `npm install` uses the project
+`allowScripts` entry in `package.json` to approve the reviewed `esbuild`
+install script. If `esbuild` is upgraded, review and refresh that approval with:
 
 ```sh
-# stop the current dev session, then run:
-sporades dev
+npm approve-scripts esbuild
 ```
 
-Client code signs users up and in through the provider-neutral auth surface.
-Email auth returns structured results and keeps auth details server-owned:
+Generated Capsules use the same `sporades` command for local Dev sessions,
+Container sessions, inspection, and Host operations.
 
-```tsx
-import { auth } from "sporades/client";
 
-const signUp = await auth.signUp("email", {
-  email: "mira@example.com",
-  password: "correct horse battery staple",
-  name: "Mira",
-});
+## Quick Start
 
-const signIn = await auth.signIn("email", {
-  email: "mira@example.com",
-  password: "correct horse battery staple",
-});
+Create a Capsule:
 
-if (signIn.data?.ok) {
-  console.log(signIn.data.auth.provider); // "email"
-} else {
-  console.error(signIn.error?.message, signIn.error?.hint);
-}
+```sh
+sporades create notes --template todo
+cd notes
 ```
 
-Google continues to use the same sign-in surface and starts the server-owned
-redirect flow:
+Run a local Dev session:
 
-```tsx
-await auth.signIn("google");
-```
-
-Client code signs out through the same auth surface. A successful sign-out
-clears the stored Sporades session token and refreshes auth state to a fresh
-anonymous session, so apps can route immediately:
-
-```tsx
-import { auth } from "sporades/client";
-
-async function signOutAndGoHome(navigate: (path: string) => void) {
-  const result = await auth.signOut();
-  if (result.data?.ok) {
-    navigate("/");
-  } else {
-    console.error(result.error?.message);
-  }
-}
+```sh
+sporades dev
 ```
 
-## File uploads
-
-Client code uses `files.upload()` from `sporades/client` to upload browser
-`File` or `Blob` values. The SDK first asks the Sporades server for an upload
-URL, transfers the bytes internally, and resolves with Sporades-owned metadata:
-file ID, absolute File path, original filename, MIME type, size, bucket, and
-version. Pass `path: "/images/avatar.png"` to choose an absolute Capsule-scoped
-File path; omitted paths use the browser file name in the Default File bucket,
-falling back to the logical `/default/upload` File path when no file name
-exists. Arrays are accepted as a convenience and are uploaded sequentially.
-
-Uploaded bytes are private by default. Ownership and privacy are runtime file
-metadata and ACL behavior; the Default File bucket is only a namespace fallback,
-not a user bucket or policy boundary. Local filesystem storage is the default:
-during Dev sessions, bytes live under `.sporades/files/`; Container sessions
-use the mounted `/app/data` volume. Capsules can declare
-`services.storage.engine: "minio"` to use MinIO as local Capsule service
-storage while keeping the same `files` SDK calls. Metadata, buckets, upload
-records, and public URL records live in the database either way.
-
-Private reads go through `files.url(fileReference)` or
-`files.download(fileReference)`, where the File reference is either a File ID or
-an absolute File path.
-Public reads must be created explicitly with exactly one expiry choice:
-`ttlSeconds`, `expires`, or `noExpiry: true`. Replacing a file preserves the file
-ID, creates a new version, and invalidates previously generated private and
-public URLs. Uploading to an existing live File path overwrites that file while
-preserving its File ID; deleting a file frees the path for a later upload with a
-new File ID. Public and private read URLs are Sporades HTTP routes, not
-filesystem paths or presigned MinIO/S3 URLs.
-
-## Endpoint handlers
-
-Capsules can register custom HTTP endpoints with `endpoint({ method, path }, handler)`.
-The handler receives the same server-owned context concepts as queries and
-mutations:
+Inspect it from another terminal:
 
-```ts
-endpoint({ method: "POST", path: "/integrations/webhook" }, (ctx) => ({
-  status: 202,
-  headers: { "x-sporades-endpoint": "accepted" },
-  body: {
-    method: ctx.request.method,
-    path: ctx.request.path,
-    query: ctx.request.query,
-    body: ctx.request.body,
-    userId: ctx.auth.userId,
-  },
-}));
+```sh
+sporades logs
+sporades db list
+sporades db dump --json
 ```
 
-`ctx` includes `ctx.db`, `ctx.auth`, `ctx.env`, `ctx.log`, and `ctx.request`.
-`ctx.request` exposes `method`, `path`, lower-cased `headers`, query parameters,
-and parsed request body data. Structured endpoint responses use
-`{ status, headers, body }`; object bodies are returned as JSON, and string bodies
-are returned as text.
+Test the bundled Capsule in Docker:
 
-## App messages
-
-Capsules can declare ephemeral app-level messages with `message(handler)` and
-clients can send them through `sporades/client` without touching raw WebSocket
-objects:
-
-```ts
-// server/index.ts
-import { capsule, message } from "sporades/server";
-
-export default capsule({
-  messages: {
-    typing: message((ctx, data) => {
-      const sentToClients = ctx.messages.send({ type: "typing", data });
-      return { ok: true, sentToClients };
-    }),
-  },
-});
+```sh
+sporades deploy
 ```
 
-```ts
-// client/index.tsx
-import { onMessage, sendMessage } from "sporades/client";
+Add a Host profile and publish when you have a Host server ready:
 
-await sendMessage("typing", { roomId: "general", active: true });
+```sh
+sporades host add personal \
+  --server user@example.com \
+  --domain apps.example.com
 
-const subscription = onMessage()
-  .filter((message) => message.type === "typing")
-  .subscribe((message) => {
-    console.log(message.data);
-  });
+sporades host bootstrap --host personal --json
+sporades host register notes --host personal --json
+sporades host push --host personal --subname notes --verify --json
 ```
 
-App and server code use unprefixed type names. Sporades reserves platform
-namespaces such as `app.`, `auth.`, `query.`, `mutation.`, `files.`, and
-`runtime.` for internal transport messages. Client-origin app messages always
-run through declared Capsule handlers; the platform does not directly relay
-arbitrary client messages. `ctx.messages.send()` defaults to the current user's
-connected clients, and handlers can explicitly target users with
-`{ scope: "users", userIds: [...] }`. It returns the number of connected clients
-the message was sent to. App-wide `{ scope: "all" }` broadcasts are not
-available from client-origin handlers.
+## Project Status
 
-App messages are a real-time escape hatch for JSON-serializable, ephemeral
-events. Use queries and mutations for durable state, auth APIs for identity, and
-file APIs for binary payloads.
+Sporades is early, active platform work. It is useful for fast prototypes,
+agent-driven app loops, local production-like testing, and private hosted
+Capsules, but it is not trying to be a full production platform (yet). Check the 
+[Roadmap](docs/ROADMAP.md) for in-flight and planned features.
 
-## Context middleware
+The current focus is keeping the authoring surface small, the runtime
+inspectable, and the operational path friendly to both developers and agents.
+Container SSH access is opt-in for local Container sessions and Hosted
+Capsules through authorized public keys in `sporades.json`. Normal management
+remains the CLI and Host helper surfaces; SSH is a compatibility and emergency
+access path.
 
-Capsules can register synchronous context middleware with `middleware`. Each
-function receives the current `ctx` and can return an enriched context for the
-request handler, query, mutation, or mutation hook:
-
-```ts
-export default capsule({
-  middleware: [
-    (ctx) => ({ ...ctx, tenant: ctx.env.TENANT }),
-    (ctx) => {
-      if (!ctx.tenant) {
-        throw Object.assign(new Error("Missing tenant."), {
-          hint: "Set TENANT in .env.sporades.server.",
-        });
-      }
-      return ctx;
-    },
-  ],
-});
-```
+## License
 
-Middleware runs once per WebSocket query request, WebSocket mutation request, and
-HTTP endpoint request. Functions run in the order they appear in the array, and
-each function receives the context returned by the previous function. Middleware
-receives `ctx.kind` as `"query"`, `"mutation"`, or `"endpoint"`. Throw an error
-with a `hint` property to block the request with a structured Sporades error.
+MIT