From a086891bdd6f0d5917dbd4eb32e9ac5c2def7946 Mon Sep 17 00:00:00 2001 From: Samuel Gbafa Date: Tue, 23 Jun 2026 10:31:41 -0400 Subject: [PATCH 1/2] Document app knowledge bundles and SQL migrations --- concepts/app-manifests.mdx | 43 ++++++++ docs.json | 2 + guides/agent-readable-apps.mdx | 149 +++++++++++++++++++++++++++ guides/sql-schema-and-migrations.mdx | 88 ++++++++++++++++ 4 files changed, 282 insertions(+) create mode 100644 guides/agent-readable-apps.mdx create mode 100644 guides/sql-schema-and-migrations.mdx diff --git a/concepts/app-manifests.mdx b/concepts/app-manifests.mdx index 939b143..f15d908 100644 --- a/concepts/app-manifests.mdx +++ b/concepts/app-manifests.mdx @@ -30,6 +30,11 @@ manifest as version 1. "app_id": "com.tinycloud.conversation-sync", "name": "Conversation Sync", "description": "Sync meeting transcripts into TinyCloud.", + "knowledge": { + "format": "okf", + "profile": "tinycloud.app.v1", + "root": "knowledge/index.md" + }, "defaults": true, "permissions": [ { @@ -58,6 +63,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 | Pointer to an agent-readable knowledge bundle shipped with the app. | | `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 +128,43 @@ 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": { + "format": "okf", + "profile": "tinycloud.app.v1", + "root": "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: diff --git a/docs.json b/docs.json index f663f01..0ccd845 100644 --- a/docs.json +++ b/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" diff --git a/guides/agent-readable-apps.mdx b/guides/agent-readable-apps.mdx new file mode 100644 index 0000000..5051c24 --- /dev/null +++ b/guides/agent-readable-apps.mdx @@ -0,0 +1,149 @@ +--- +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": { + "format": "okf", + "profile": "tinycloud.app.v1", + "root": "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. diff --git a/guides/sql-schema-and-migrations.mdx b/guides/sql-schema-and-migrations.mdx new file mode 100644 index 0000000..94dc313 --- /dev/null +++ b/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). From 36a80a3e977816d7da640b816727fe31ff62546e Mon Sep 17 00:00:00 2001 From: Samuel Gbafa Date: Tue, 23 Jun 2026 11:31:06 -0400 Subject: [PATCH 2/2] Use concise app knowledge manifest field --- concepts/app-manifests.mdx | 27 ++++++++++++++++----------- guides/agent-readable-apps.mdx | 15 ++++++++++----- 2 files changed, 26 insertions(+), 16 deletions(-) diff --git a/concepts/app-manifests.mdx b/concepts/app-manifests.mdx index f15d908..a5be3c8 100644 --- a/concepts/app-manifests.mdx +++ b/concepts/app-manifests.mdx @@ -30,11 +30,7 @@ manifest as version 1. "app_id": "com.tinycloud.conversation-sync", "name": "Conversation Sync", "description": "Sync meeting transcripts into TinyCloud.", - "knowledge": { - "format": "okf", - "profile": "tinycloud.app.v1", - "root": "knowledge/index.md" - }, + "knowledge": true, "defaults": true, "permissions": [ { @@ -63,7 +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 | Pointer to an agent-readable knowledge bundle shipped with the app. | +| `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. | @@ -137,11 +133,15 @@ can ship a `knowledge/` bundle next to `manifest.json` and point to it with the ```json { - "knowledge": { - "format": "okf", - "profile": "tinycloud.app.v1", - "root": "knowledge/index.md" - } + "knowledge": true +} +``` + +Use a string when the root is not the default: + +```json +{ + "knowledge": "knowledge/index.md" } ``` @@ -173,6 +173,11 @@ for schemas and examples. - `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. diff --git a/guides/agent-readable-apps.mdx b/guides/agent-readable-apps.mdx index 5051c24..28b89f4 100644 --- a/guides/agent-readable-apps.mdx +++ b/guides/agent-readable-apps.mdx @@ -35,11 +35,16 @@ Use the manifest to point to the knowledge bundle: "manifest_version": 1, "app_id": "com.example.notes", "name": "Notes", - "knowledge": { - "format": "okf", - "profile": "tinycloud.app.v1", - "root": "knowledge/index.md" - } + "knowledge": true +} +``` + +`knowledge: true` means the default root is `knowledge/index.md`. Use a string +when the root differs: + +```json +{ + "knowledge": "knowledge/index.md" } ```