agentbull/ankole/pod-content

Pod content

Chat records the work process. A Page keeps the result. Use the real Pod contracts through ankole-pod; do not make a local file stand in for a saved page or use browser storage as the authoritative base.

Run ankole-pod --help before the first operation. It lists the current operations and parameter shapes. The CLI is available inside an active Agent turn. Main routes this Skill to a Background Agent Job.

For deterministic recurring data tasks or polling more often than every 30 minutes, create an Applet Action Job with ankole-pod jobs.create and manage its native schedule with ankole-pod jobs.schedules.put. Pass business fields in payload; the Action receives them in ctx.signal.data alongside planned and actual trigger times. Use ankole-pod jobs.webhooks.create for Job-owned callbacks. These sources need no Agent wakeup, payload.task, or chat delivery target. Emit a Signal only when the result needs the Agent's judgment.

Identity and access

The control plane checks your Agent Principal for every request. A personal assistant acts with its human owner's business permissions. An AI colleague uses its own business permissions, including when another Agent delegates work. Human WorkAccess controls admission and ends the work when access is revoked; it does not intersect the colleague's resource permissions with the human's. An Applet Action uses its enabling Human for ordinary capabilities and its Page owner for admin capabilities. It must hold its current execution attempt; review-required and expired attempts cannot access Pod. If access is denied, ask for the required sharing grant. Never use another identity or a hidden storage path.

A page is the unit of permissions and lifecycle. Every page type can have children. A Base holds its tables; tables and records are not pages.

Creating a child requires edit access to its parent page. The child inherits that access; creation does not add a manage grant. Editing content, title, or icon requires edit access. Edit access also permits a move when the page and its descendants keep the same access permissions. A move that changes those permissions requires Full access (manage) to the source; every move requires edit access to the destination. Deleting, restoring, or changing sharing still requires Full access. A rejected move leaves the source in place. Keep its identity and ask for the needed access rather than claim a replacement was moved.

Use pages.update_sharing {id, upserts?, removes?} or ankole-pod page update-sharing <page-id> '<JSON body>' to add, update, or remove individual grants without replacing other collaborators. A personal assistant may grant the access implied by its owner's request to collaborate with a named colleague. Use contribute (comment access) for document reviews and discussion, so the colleague can answer follow-up comments on the page; use view for read-only retrieval and edit for edits. Use target_scope: "self" for a single page. Keep unrelated grants. If the owner cannot manage sharing, explain that a resource manager must grant access.

Read pages.sharing {id} for the current sharing_version, grants, and subjects. Use pages.set_sharing {id, sharing_version, inherit_permissions?, grants?} or ankole-pod page set-sharing <page-id> '<JSON body>' to replace sharing. Each grant supplies one subject (principal_uid, group_id, or source_page_id with source_action) and either role or exact actions, plus optional target_scope and condition. A stale version requires a fresh read.

Documents and files

Set a Page's title with pages.create or pages.update; pages.write supplies its Markdown body. Follow the native Pod delivery rules for Page authoring and the requested output format. Every pages.update request that supplies title requires its last-read title as expected_title, including "" for an untitled Page. The server rejects a missing or stale base with title_conflict. Read the current title and reconsider the rename before retrying. Updates to other metadata do not require a title base.

1. Use pages.search {query} to find titles and document text, or read a known

page ID. Search returns at most 30 matches. Use pages.children {parent_id} to browse a page's children; omit parent_id for roots. Pass next_cursor back as cursor until it is null. pages.list provides workspace lists.

1. Read its Markdown and revision before a change.
2. Use pages.write for a target body, pages.append for Markdown at the end,

or pages.patch for exact old_text and new_text edits. Each operation requires that base_revision. A patch rejects missing or ambiguous text; replace_all: true permits all matches. The Worker uses the editor's codec. The control plane commits minimal structural and UTF-16 text changes.

1. If the write conflicts, read again and reconsider the change. Do not

overwrite a newer revision or claim the old write succeeded.

Create child content where it belongs: pass the intended document's parent_id to pages.create, then add a reference to it. Use <mention page="<document-page-id>" /> for a child document and an embed for an interactive Base, File Page, or Applet. Do not create elsewhere and move it merely to create a child. If inserting the reference fails, the child remains in the page tree. Removing a reference from Markdown removes only the reference. The page link form is ankole:page/<page-id>.

In document Markdown, put each inline embed on its own line. For an Applet, use <embed ref="<applet-page-id>" />. For a Base view, use <embed ref="<base-page-id>" table="<table-id>" view="<view-id>" />. Use the saved page and table IDs; read the view ID from base.schema. A Markdown page link opens the referenced page; the embed renders it inline.

Use files.upload for a file page, document image, or Base attachment. Image uploads return an ankole:asset/<digest>/<name> address for the document. Use ankole-files get pages/<page-id>/<path> --pod to read a page file into your workspace. Uploads and publication commit through the page owner; do not write arbitrary paths on the Pod drive.

Deleting a page moves its subtree into the trash. It can be restored before purge begins. Deleting a chat does not delete the pages saved from it.

Business data

A primary text field accepts at most 2 KiB of UTF-8 text. A link cell accepts at most 2,000 IDs. Use a one-way child-to-parent link for a parent with more than 2,000 children. The same API serves inline and physical tables.

Create the Base and typed fields before the applet. A new Base has Table 1 with a primary Name field; read it with base.tables before creating another table. Keep the IDs returned by these operations and continue work on them. A rejected query does not remove already saved pages or tables. Read the CLI parameter shapes and correct that query instead of creating replacement content. Records use field IDs as keys. Query a table and use the returned field versions when you change records:

• An update sends only the changed data keys and their expected_versions.

An unwritten field has no entry in that map.

• A delete sends the record's whole versions map.
• One batch contains at most 200 records and commits as a unit.
• A conflict requires a new read and a new decision. Different fields of the

same record can be changed independently.

Contributors can create, update, and delete records and upload record attachments. Editors can change fields, views, and documents and publish Applets. Managers can delete tables and change sharing. A table referenced by a link field must have that reference removed before deletion.

Formula fields are read-only and are evaluated by the server. Reference same-record fields by name in formula source, such as [Price] * [Quantity]. Do not implement a second formula evaluator in the applet. Linked records must belong to the same Base.

For a report that must retain today's data, use base.copy with the source table, target document, and optional filter. The copy has new IDs and is independent. Links become text with their current titles in link order; empty links become null. Formulas are checked against the copied field types. Valid formulas recalculate from copied fields. A formula that cannot use the new types becomes an ordinary field with its current result; array results become JSON text. A live dashboard references the source Base instead.

React applets

Use one CLI for initialization, build, publication, and source pull:

ankole-pod applet init <directory>
ankole-pod applet build <directory>
ankole-pod applet publish <directory> '{"id":"<applet-page-id>","base_revision":0}'
ankole-pod applet pull <empty-directory> '{"id":"<applet-page-id>"}'

The generated entry exports provider = defineApplet(App) from @ankole/applet-sdk. Keep source under src/. Build emits browser ESM, dist/index.html, dist/main.js, shared chunks, and CSS. React, React DOM, @ankole/uikit, and @ankole/applet-sdk are host dependencies. Keep all four out of package.json; the host supplies them. Do not bundle another React or add a global CSS reset. Keep custom CSS inside the Applet frame. Import UIKit components from its root export. The build rejects UIKit component subpaths and stylesheet imports; the host already loads those styles. Import local images, fonts, and media from source, or reference them with CSS url(). The build embeds imported resources in the published module graph. A plain runtime path string does not include a resource in the build. Import a Worker URL with import workerURL from './calculation.worker.ts?url', then use new Worker(new URL(workerURL, import.meta.url), { type: 'module' }). The build compiles the Worker and resolves its URL from nested modules and dynamic chunks. Applet init supplies the Worker URL import types. Source pull requires edit access, checks each file digest, and runs bun install --ignore-scripts.

Pod UI and theme integration

An Applet renders inside a Pod Page sheet (var(--background)) that already provides the 48px horizontal page gutter, breadcrumbs, editable Page title, provenance metadata, and Automation toolbar directly above the iframe: