Document app knowledge bundles and SQL migrations

concepts/app-manifests.mdx

@@ -30,6 +30,7 @@ manifest as version 1.
   "app_id": "com.tinycloud.conversation-sync",
   "name": "Conversation Sync",
   "description": "Sync meeting transcripts into TinyCloud.",
+  "knowledge": true,
   "defaults": true,
   "permissions": [
     {
@@ -58,6 +59,7 @@ compose those manifests before sign-in.
 | `did` | No | Delegate DID for this manifest. If absent, permissions can still be requested, but no delegation target is created automatically. |
 | `space` | No | Default TinyCloud space for this manifest. Missing means `applications`. |
 | `prefix` | No | Path prefix override. Missing means `app_id`; `""` disables prefixing. |
+| `knowledge` | No | `true` for `knowledge/index.md`, or a `knowledge/*.md` root path. |
 | `defaults` | No | Default TinyCloud permission tier. Missing means `true`. |
 | `expiry` | No | Default permission expiry, using `ms` format such as `30d` or `2h`. |
 | `permissions` | No | Explicit permissions beyond defaults. |
@@ -122,6 +124,47 @@ The SDK does not create encryption networks owned by another DID. A decrypt
 grant for another owner's network authorizes decrypt requests only after that
 owner has created and hosted the network.
 
+## Agent-readable knowledge
+
+Manifests are intentionally concise. They declare app identity, resource
+permissions, and delegation targets. Apps that need richer operational context
+can ship a `knowledge/` bundle next to `manifest.json` and point to it with the
+`knowledge` field.
+
+```json
+{
+  "knowledge": true
+}
+```
+
+Use a string when the root is not the default:
+
+```json
+{
+  "knowledge": "knowledge/index.md"
+}
+```
+
+The bundle should explain what the app does, what its TinyCloud resources mean,
+how SQL/KV/secrets are used, and what agents should preserve when operating on
+the data. Keep small apps flat:
+
+```text
+knowledge/
+  index.md
+  resources.md
+  sql.md
+  kv.md
+  secrets.md
+  operations.md
+```
+
+Only add nested directories when a category has enough independent material to
+justify the extra traversal. See [Agent-readable Apps](/guides/agent-readable-apps)
+for the package shape and
+[TinyCloudLabs/tinycloud-app-kit](https://github.com/TinyCloudLabs/tinycloud-app-kit)
+for schemas and examples.
+
 ## Defaults
 
 `defaults` defaults to `true`. The standard default tier includes app-scoped:
@@ -130,6 +173,11 @@ owner has created and hosted the network.
 - `tinycloud.sql` with `read` and `write`
 - `tinycloud.capabilities` with `read`
 
+These are implicit default resources under the manifest `app_id` prefix. Do not
+request them again unless the app needs a different space, a path outside the
+app prefix, non-default actions such as `tinycloud.sql/ddl`, or explicit
+resource documentation for humans and agents.
+
 The SDK also supports higher tiers such as `admin` and `all`. Use
 `defaults: false` when an app wants every requested permission to be explicit.
 

docs.json

@@ -54,8 +54,10 @@
               "guides/authentication",
               "guides/spaces",
               "guides/kv-storage",
+              "guides/sql-schema-and-migrations",
               "guides/tinycloud-vfs",
               "guides/write-hooks",
+              "guides/agent-readable-apps",
               "guides/data-vault",
               "guides/delegations",
               "guides/sharing"

guides/agent-readable-apps.mdx

@@ -0,0 +1,154 @@
+---
+title: "Agent-readable Apps"
+description: "Ship concise app knowledge alongside TinyCloud app manifests"
+icon: "bot"
+sidebarTitle: "Agent-readable Apps"
+---
+
+TinyCloud app manifests declare what an app needs at install and sign-in time.
+Agent-readable app knowledge explains what those resources mean after the app is
+installed.
+
+Ship the two together:
+
+```text
+my-app/
+  manifest.json
+  knowledge/
+    index.md
+    resources.md
+    sql.md
+    kv.md
+    secrets.md
+    operations.md
+```
+
+Small apps should keep this flat. Add nested directories only when a category is
+large enough that a single file becomes hard to scan.
+
+## Manifest Link
+
+Use the manifest to point to the knowledge bundle:
+
+```json
+{
+  "manifest_version": 1,
+  "app_id": "com.example.notes",
+  "name": "Notes",
+  "knowledge": true
+}
+```
+
+`knowledge: true` means the default root is `knowledge/index.md`. Use a string
+when the root differs:
+
+```json
+{
+  "knowledge": "knowledge/index.md"
+}
+```
+
+The manifest remains the runtime declaration. The knowledge bundle is the
+operational map for humans and agents.
+
+## Required File
+
+Every bundle starts with `knowledge/index.md`:
+
+```md
+---
+type: TinyCloud App
+title: Notes
+description: Personal notes with optional AI summaries.
+---
+
+# Notes
+
+Notes stores user-authored documents in KV and search metadata in SQLite.
+
+## Resources
+
+- [KV](kv.md) - Note documents under `documents/*`.
+- [SQL](sql.md) - Search metadata in the `main` SQLite database.
+- [Secrets](secrets.md) - Optional model provider key for summaries.
+- [Operations](operations.md) - Install, migration, and recovery notes.
+```
+
+The index should be useful by itself. Do not make it a table of contents that
+forces agents to open several files before understanding the app.
+
+## Category Files
+
+Use category files only when the app uses that category.
+
+| File | Purpose |
+| --- | --- |
+| `resources.md` | One-page summary of all TinyCloud data surfaces. |
+| `sql.md` | SQLite databases, tables, schema notes, and mutation rules. |
+| `kv.md` | KV prefixes, value shapes, and lifecycle rules. |
+| `secrets.md` | Secret references, consumers, rotation, and failure behavior. |
+| `operations.md` | Install, migration, repair, and agent operating notes. |
+
+For a single SQLite database, prefer `sql.md`. Use `sql/index.md` only when the
+app has multiple independent databases or a large schema.
+
+For schema setup, document the migration path and required `ddl` capability. See
+[SQL Schema and Migrations](/guides/sql-schema-and-migrations).
+
+## Resource Sections
+
+Each resource section should stay concise:
+
+```md
+## Documents
+
+Prefix: `documents/*`
+
+Purpose: User-authored notes stored as JSON documents.
+
+Access:
+
+| Capability | Why |
+| --- | --- |
+| `tinycloud.kv/get` | Read notes. |
+| `tinycloud.kv/put` | Save edits. |
+| `tinycloud.kv/list` | List note ids. |
+
+Agent notes:
+
+- Do not delete documents unless the user explicitly asks.
+- Preserve unknown JSON fields.
+```
+
+SQL files should also say whether tables are canonical data or rebuildable
+indexes. Rebuildable tables should name the source of truth.
+
+## Secrets
+
+Document secret references, never secret values:
+
+```md
+## Model API Key
+
+Name: `model-api-key`
+
+Purpose: Optional provider key used by the summary worker.
+
+Consumers:
+
+- `agent.summarizer`
+
+Rotation: User-managed.
+
+Agent notes:
+
+- Never write the plaintext value into the knowledge bundle.
+- If missing, disable summaries instead of blocking note editing.
+```
+
+## Tooling
+
+TinyCloud app-kit owns schemas, examples, guides, and app-authoring skills:
+[TinyCloudLabs/tinycloud-app-kit](https://github.com/TinyCloudLabs/tinycloud-app-kit).
+
+The docs explain the contract; app-kit artifacts make it executable.

guides/sql-schema-and-migrations.mdx

@@ -0,0 +1,88 @@
+---
+title: "SQL Schema and Migrations"
+description: "Set up SQLite schema safely in TinyCloud apps"
+icon: "database-zap"
+sidebarTitle: "SQL Schema and Migrations"
+---
+
+TinyCloud SQL uses SQLite. Apps own their schemas, but schema setup should use
+TinyCloud's migration primitive instead of ad hoc `CREATE TABLE` calls in hot
+paths.
+
+## Schema, Migration, Apply
+
+Schema is the desired database shape: tables, columns, indexes, constraints,
+and views.
+
+Migration is a versioned change from one schema state to another.
+
+The apply API makes the database ready at runtime:
+
+```ts
+await tc.sql.db("main").migrations.apply({
+  namespace: "com.example.notes",
+  migrations: [
+    {
+      id: "001_initial_note_index",
+      sql: [
+        "CREATE TABLE IF NOT EXISTS note_index (id TEXT PRIMARY KEY, title TEXT NOT NULL, updated_at TEXT NOT NULL)",
+        "CREATE INDEX IF NOT EXISTS idx_note_index_updated_at ON note_index(updated_at)"
+      ],
+    },
+  ],
+});
+```
+
+Use stable migration ids. Keep migrations ordered. Run migrations during
+install, startup, app registration, or another setup phase before serving user
+traffic.
+
+## Manifest Permissions
+
+Apps that create or alter schema need `ddl` permission for the same database
+path they use at runtime.
+
+```json
+{
+  "service": "tinycloud.sql",
+  "space": "applications",
+  "path": "com.example.notes/main",
+  "actions": ["read", "write", "ddl"],
+  "description": "Read, update, and migrate the notes SQLite database."
+}
+```
+
+If you use the `tc.sql` shortcut, the database name is `default`.
+
+```ts
+tc.sql.execute(sql)
+tc.sql.db("default").execute(sql)
+```
+
+These target the same SQLite database. The manifest permission should name
+`default` when the app uses that shortcut.
+
+## What To Avoid
+
+Do not run cold DDL in hot user paths. Runtime `CREATE TABLE` or `ALTER TABLE`
+can fail behind proxies, race under concurrent requests, or produce confusing
+authorization errors if the manifest does not include `ddl`.
+
+Do not copy app-specific `ensureSchema` helpers between apps. Use migrations so
+locking, idempotency, action signing, and error shape are handled consistently.
+
+Do not treat materialized indexes as canonical data. If a table mirrors KV,
+capabilities, or another source of truth, document it as rebuildable.
+
+## Agent Notes
+
+When reviewing a TinyCloud app:
+
+- Check that schema-changing SQL has `ddl` in the manifest.
+- Check that the manifest database path matches the SDK database name.
+- Prefer `migrations.apply(...)` over custom `ensureSchema` code.
+- Treat missing cache tables as setup drift or cache misses, not data loss.
+- Surface migration errors visibly instead of turning them into empty states.
+
+For manifest schema examples and app-review skills, see
+[TinyCloudLabs/tinycloud-app-kit](https://github.com/TinyCloudLabs/tinycloud-app-kit).