@notionhq/apps 0.0.29 → 0.0.31

package/src/notion-as-code/intents.ts

@@ -1,3 +1,4 @@
+import type { ResourceAccessLevel } from "../workflow-access.js";
 import type { CustomAgentArgs } from "./custom-agent.js";
 import type { PageArgs } from "./page.js";
 import type { TeamspaceArgs } from "./teamspace.js";
@@ -346,7 +347,9 @@ export type DatabaseIntent = {
 };
 
 export type PageIntent = PageArgs & { parent: Parent };
-export type CustomAgentIntent = CustomAgentArgs;
+export type CustomAgentIntent = Omit<CustomAgentArgs, "access"> & {
+	access?: readonly { resourceId: ResourceId; level: ResourceAccessLevel }[];
+};
 
 export type ViewIntent = {
 	databaseResourceId: ResourceId;

package/src/notion-as-code/notion-as-code-types.test.ts

@@ -1,8 +1,9 @@
 import { expectTypeOf, it } from "vitest";
+import { access } from "../workflow-access.js";
+import { page, database, customAgent } from "../index.js";
 
 import type {
 	CustomAgentAccess,
-	CustomAgentAccessRole,
 	CustomAgentArgs,
 	CustomAgentPropertyUpdatedTrigger,
 	CustomAgentTrustedUrls,
@@ -16,17 +17,26 @@ import type {
 } from "./index.js";
 
 it("types custom agent resource access and URL trust", () => {
-	expectTypeOf<
-		"full_access" | "can_edit_content" | "can_comment" | "can_view"
-	>().toEqualTypeOf<CustomAgentAccessRole>();
-	expectTypeOf<{
-		resourceId: "tasks";
-		role: "can_view";
-	}>().toExtend<CustomAgentAccess>();
-	expectTypeOf<{
-		resourceId: "tasks";
-		role: "read_and_write";
+	const home = page({ resourceId: "home" });
+	const tasks = database("tasks", {
+		dataSourceResourceId: "source",
+		name: "Tasks",
+		schema: { Title: { resourceId: "title", type: "title" } },
+	});
+	expectTypeOf(access.view(home)).toExtend<CustomAgentAccess>();
+	expectTypeOf(access.edit(tasks)).toExtend<CustomAgentAccess>();
+	expectTypeOf(access.view(tasks.dataSource)).not.toExtend<CustomAgentAccess>();
+	expectTypeOf(access.comment(tasks.dataSource)).not.toExtend<CustomAgentAccess>();
+	expectTypeOf(access.edit(tasks.dataSource)).not.toExtend<CustomAgentAccess>();
+	expectTypeOf(access.fullAccess(tasks.dataSource)).not.toExtend<CustomAgentAccess>();
+	expectTypeOf<{
+		resource: typeof tasks.dataSource;
+		level: "view";
 	}>().not.toExtend<CustomAgentAccess>();
+	expectTypeOf<{ resourceId: "tasks"; role: "can_view" }>().not.toExtend<CustomAgentAccess>();
+	expectTypeOf(
+		access.call(customAgent({ resourceId: "agent", name: "Agent" })),
+	).not.toExtend<CustomAgentAccess>();
 	expectTypeOf<{ type: "all" }>().toEqualTypeOf<CustomAgentTrustedUrls>();
 	expectTypeOf<CustomAgentArgs["webAccess"]>().toEqualTypeOf<boolean | undefined>();
 	expectTypeOf<CustomAgentArgs["trustedUrls"]>().toEqualTypeOf<

package/src/workflow-access.ts

@@ -20,17 +20,17 @@ type WorkflowAccessContentResource = Exclude<WorkflowAccessResource, CustomAgent
 export type WorkflowAccessResourceType = WorkflowAccessResource["resourceType"];
 
 /** Levels accepted by pages, databases, and data sources. */
-export type WorkflowAccessResourceLevel = "view" | "comment" | "edit" | "fullAccess";
+export type ResourceAccessLevel = "view" | "comment" | "edit" | "fullAccess";
 
 /** The only level accepted by a custom agent. */
 export type WorkflowAccessAgentLevel = "call";
 
 /** Every level accepted by at least one workflow access resource. */
-export type WorkflowAccessLevel = WorkflowAccessResourceLevel | WorkflowAccessAgentLevel;
+export type WorkflowAccessLevel = ResourceAccessLevel | WorkflowAccessAgentLevel;
 
 /** The level set accepted by a particular resource kind. */
 export type WorkflowAccessLevelFor<TType extends WorkflowAccessResourceType> =
-	TType extends "customAgent" ? WorkflowAccessAgentLevel : WorkflowAccessResourceLevel;
+	TType extends "customAgent" ? WorkflowAccessAgentLevel : ResourceAccessLevel;
 
 type AccessResourceFor<TType extends WorkflowAccessResourceType> = Extract<
 	WorkflowAccessResource,
@@ -159,57 +159,62 @@ export function normalizeWorkflowAccess(
 		if (!ACCESS_ALIAS_PATTERN.test(alias) || RESERVED_ACCESS_ALIASES.has(alias)) {
 			throw new Error(`Invalid workflow access alias: ${alias}`);
 		}
+		normalized[alias] = normalizeAccessDeclaration(source[alias], `Workflow access "${alias}"`);
+	}
 
-		const declaration: unknown = source[alias];
-		if (
-			!isRecord(declaration) ||
-			!Object.hasOwn(declaration, "resource") ||
-			!Object.hasOwn(declaration, "level")
-		) {
-			throw new Error(`Workflow access "${alias}" must declare a resource and level.`);
+	return Object.freeze(normalized);
+}
+
+/**
+ * Check one access entry and return its resource type, ID, and level.
+ * Workflows check the entry's alias separately; custom-agent grants have no alias.
+ */
+export function normalizeAccessDeclaration(
+	declaration: unknown,
+	label: string,
+): WorkflowAccessRequirement {
+	if (
+		!isRecord(declaration) ||
+		!Object.hasOwn(declaration, "resource") ||
+		!Object.hasOwn(declaration, "level")
+	) {
+		throw new Error(`${label} must declare a resource and level.`);
+	}
+	const resource: unknown = declaration.resource;
+	if (
+		!isRecord(resource) ||
+		!Object.hasOwn(resource, "resourceType") ||
+		!Object.hasOwn(resource, "resourceId") ||
+		typeof resource.resourceId !== "string" ||
+		resource.resourceId.length === 0 ||
+		!isWorkflowAccessResourceType(resource.resourceType)
+	) {
+		throw new Error(`${label} must reference a supported NaC resource handle.`);
+	}
+
+	let requirement: WorkflowAccessRequirement;
+	if (resource.resourceType === "customAgent") {
+		if (declaration.level !== "call") {
+			throw new Error(`${label} custom agents only support level "call".`);
 		}
-		const resource: unknown = declaration.resource;
-		if (
-			!isRecord(resource) ||
-			!Object.hasOwn(resource, "resourceType") ||
-			!Object.hasOwn(resource, "resourceId") ||
-			typeof resource.resourceId !== "string" ||
-			resource.resourceId.length === 0 ||
-			!isWorkflowAccessResourceType(resource.resourceType)
-		) {
+		requirement = {
+			type: resource.resourceType,
+			resourceId: resource.resourceId,
+			level: declaration.level,
+		};
+	} else {
+		if (!isResourceAccessLevel(declaration.level)) {
 			throw new Error(
-				`Workflow access "${alias}" must reference a supported NaC resource handle.`,
+				`${label} ${resource.resourceType} level must be view, comment, edit, or fullAccess.`,
 			);
 		}
-
-		let requirement: WorkflowAccessRequirement;
-		if (resource.resourceType === "customAgent") {
-			if (declaration.level !== "call") {
-				throw new Error(
-					`Workflow access "${alias}" custom agents only support level "call".`,
-				);
-			}
-			requirement = {
-				type: resource.resourceType,
-				resourceId: resource.resourceId,
-				level: declaration.level,
-			};
-		} else {
-			if (!isWorkflowAccessResourceLevel(declaration.level)) {
-				throw new Error(
-					`Workflow access "${alias}" ${resource.resourceType} level must be view, comment, edit, or fullAccess.`,
-				);
-			}
-			requirement = {
-				type: resource.resourceType,
-				resourceId: resource.resourceId,
-				level: declaration.level,
-			};
-		}
-		normalized[alias] = Object.freeze(requirement);
+		requirement = {
+			type: resource.resourceType,
+			resourceId: resource.resourceId,
+			level: declaration.level,
+		};
 	}
-
-	return Object.freeze(normalized);
+	return Object.freeze(requirement);
 }
 
 /**
@@ -294,14 +299,14 @@ function isWorkflowAccessResourceType(value: unknown): value is WorkflowAccessRe
 	return typeof value === "string" && Object.hasOwn(RESOURCE_TYPES, value);
 }
 
-function isWorkflowAccessResourceLevel(value: unknown): value is WorkflowAccessResourceLevel {
+function isResourceAccessLevel(value: unknown): value is ResourceAccessLevel {
 	return value === "view" || value === "comment" || value === "edit" || value === "fullAccess";
 }
 
 function isBinding(value: unknown): value is {
 	type: WorkflowAccessResourceType;
 	resourceId: string;
-	level: WorkflowAccessResourceLevel | WorkflowAccessAgentLevel;
+	level: ResourceAccessLevel | WorkflowAccessAgentLevel;
 	id: string;
 } {
 	if (!isRecord(value) || Reflect.ownKeys(value).length !== 4) return false;
@@ -320,7 +325,7 @@ function isBinding(value: unknown): value is {
 		typeof value.resourceId === "string" &&
 		value.resourceId.length > 0 &&
 		typeof value.level === "string" &&
-		(isWorkflowAccessResourceLevel(value.level) || value.level === "call") &&
+		(isResourceAccessLevel(value.level) || value.level === "call") &&
 		typeof value.id === "string" &&
 		value.id.length > 0
 	);

package/src/workflow.ts

@@ -191,7 +191,7 @@ export type {
 	WorkflowAccessLevel,
 	WorkflowAccessLevelFor,
 	WorkflowAccessResource,
-	WorkflowAccessResourceLevel,
+	ResourceAccessLevel,
 	WorkflowAccessResourceType,
 	WorkflowAccessRequirement,
 	WorkflowAccessRequirements,

package/AGENTS.md

@@ -1,137 +0,0 @@
-# Notion Apps project guidance
-
-This file is included in projects scaffolded from this template. Read it completely
-before designing, implementing, or troubleshooting an App.
-
-## Design the App before implementation
-
-After the project has been scaffolded, establish what the complete App should
-do. Clarify the desired outcome, source data, triggers, external services, and
-every Notion resource the App needs. Recommend a workflow for most automations;
-use a sync when the goal is to mirror an external collection into a Notion
-database. An App may contain both.
-
-Before proposing the design, read only enough to describe each open decision as a
-concrete option: this file and the top-level description of each relevant capability
-(workflow, sync, connections, and Notion as Code). Do not read generated type
-declarations (`*.generated.d.ts`), full provider API surfaces, or other
-implementation-level detail before the user agrees on a direction. Save that
-verification for the selected option during implementation.
-
-Present the proposed design concisely and get the user's agreement before
-implementing. Include:
-
-- Always include an App home page that explains what the App does and links to
-  all of its Notion resources.
-- Every Notion resource the App will create, such as databases, pages, and custom
-  agents, with its purpose and the capabilities that depend on it.
-- Every sync, including its third-party source, destination database, and
-  synchronization behavior.
-- Every workflow, including its trigger, major actions, resources it reads or changes,
-  and external connections.
-- Unresolved decisions and required access.
-
-Adapt the format to the App rather than copying this example mechanically:
-
-### Example App design
-
-**Outcome:** Bring support tickets into Notion and escalate urgent tickets to the
-support team.
-
-**Notion resources**
-
-| Kind         | Name              | Purpose                                             | Used by                          |
-| ------------ | ----------------- | --------------------------------------------------- | -------------------------------- |
-| Database     | Support tickets   | Store synchronized tickets and triage status        | Ticket sync, escalation workflow |
-| Page         | Support dashboard | Give the team an operational home and database view | Team members                     |
-| Custom agent | Ticket triage     | Classify urgency and summarize a ticket             | Escalation workflow              |
-
-**Syncs and workflows**
-
-| Kind     | Name                   | Source or trigger                       | Behavior                                              | Dependencies                                                        |
-| -------- | ---------------------- | --------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------- |
-| Sync     | Ticket sync            | Support-system tickets                  | Upsert by stable external ID                          | Support-system connection, Support tickets database                 |
-| Workflow | Escalate urgent ticket | Support tickets page created or updated | Run triage, update status, and notify support channel | Ticket triage agent, Support tickets database, messaging connection |
-
-**Open questions:** Which support system and messaging channel should the App use?
-
-Ask the user to confirm or revise the design. Do not begin implementation until they
-agree. If implementation reveals a material resource or capability not covered by the
-agreed design, update the proposal and confirm the change before adding it.
-
-## Implement against the generated project
-
-Before implementing the agreed design, compare it with everything included by the
-scaffold. Remove template workflows, syncs, custom blocks, Notion resource declarations,
-sample assets, and supporting code that the App does not need. Do not leave example or
-placeholder capabilities in discovered capability directories: if they remain there,
-the build can include and deploy them. Preserve shared configuration and infrastructure
-that the selected capabilities still require.
-
-Feature-specific skills are installed at
-`./node_modules/@notionhq/apps/skills`. Inspect that directory and read every relevant
-`SKILL.md` completely before implementing a feature. At minimum, use the `workflow`
-skill for workflows or the `sync` skill for syncs, plus any additional skills they
-route to, such as connections or Notion as Code. Do not rely on remembered SDK APIs
-when the installed declarations or skills can answer the question.
-
-Preserve the template's structure and examples unless the user's App requires a
-change. Use the project's documented check and build commands after edits. Deploy
-with `ntn apps deploy` only when deployment is part of the user's request, and report
-local build success separately from deployment success.
-
-## Deploy and hand off
-
-When deploying, use `ntn apps deploy --json` (plus any other required arguments) so
-the final deployment result includes `worker_url`, `setup_url`, and `is_update`. These
-are JSON-only field names. Human output shows the worker page URL without a
-`worker_url` label, and non-interactive plain output may show only the worker ID
-followed by a `Finish setup:` line. That line is the setup URL, not the worker URL.
-
-For a first deployment (`is_update` is false), show only the onboarding/setup URL from
-`setup_url` and tell the user to open it to finish setting up the App.
-
-For a redeployment (`is_update` is true), show both `worker_url` and `setup_url`,
-clearly labeled and clickable. Explain that the worker URL opens the deployed App and
-the setup URL lets them revisit onboarding. Use the URLs returned by the CLI rather
-than constructing or guessing them.
-
-## Capability-specific guidance
-
-Before creating, modifying, or troubleshooting an App capability, read the matching
-skill:
-
-- [Workflows](./skills/workflow/SKILL.md)
-- [Connections](./skills/connections/SKILL.md)
-- [Database syncs](./skills/sync/SKILL.md)
-- [Custom blocks](./skills/custom-blocks/SKILL.md)
-- [Notion as Code](./skills/notion-as-code/SKILL.md)
-
-Resolve these links relative to this package directory. Check the installed SDK
-declarations for current API details.
-
-## Pull requests for SDK changes
-
-For a change to the public SDK, show the user-facing code change in the pull request
-body. Put a short, complete example near the top:
-
-````md
-## User code
-
-### Before
-
-```ts
-// Existing app code
-```
-
-### After
-
-```ts
-// Updated app code
-```
-````
-
-Use the same small example in both sections so reviewers can compare them
-quickly. Include imports and the call that changed when they matter. Show normal
-app code, not internal types, tests, generated files, or provisioning output. Explain
-any required migration steps in plain language below the example.

package/docs/BUILD.md

@@ -1,268 +0,0 @@
-# App build process
-
-`notion-apps build` discovers capability modules and produces:
-
-- `dist/worker.js`, an ESM bundle containing the app's workflows and syncs.
-- `dist/manifest.json`, the static capability and resource manifest.
-- `dist/provisioning.json`, only when the app declares Notion-as-Code resources.
-
-## Project convention
-
-Each top-level TypeScript file under a capability directory must default-export the
-corresponding capability. The filename becomes its key:
-
-| Directory           | Default export     |
-| ------------------- | ------------------ |
-| `src/workflows/`    | `workflow(...)`    |
-| `src/syncs/`        | `sync(...)`        |
-| `src/customBlocks/` | `customBlock(...)` |
-
-```text
-my-app/
-├── src/
-│   ├── notion.ts
-│   ├── workflows/
-│   │   └── onPageCreated.ts
-│   └── lib/
-│       └── processPage.ts
-├── .notion/
-└── dist/
-    ├── worker.js
-    └── manifest.json
-```
-
-Files elsewhere under `src/` are ordinary modules and enter the build only when imported
-by a capability. Capability discovery does not recurse into subdirectories.
-Notion-as-Code declarations may be inline or in an imported helper. Use a local
-module such as `src/workflows/myWorkflow/lib/notion.ts` for resources owned by one
-capability, and `src/notion.ts` for app-wide declarations or resources without a
-natural capability owner.
-
-## Pipeline
-
-1. Discover top-level files in the capability directories.
-2. Generate `.notion/entry.ts` with workflow and sync imports and a dispatcher.
-3. Bundle the app's code into `dist/worker.js`, leaving npm packages external.
-4. Evaluate custom-block declarations separately. Blocks do not enter `worker.js`.
-5. Evaluate worker and custom-block capabilities in a separate build-only metadata bundle to record
-   Notion-as-Code declarations. Validate workflow access references against those
-   declarations before writing the manifest and optional provisioning artifact.
-6. Emit `dist/manifest.json` and, when declarations exist, `dist/provisioning.json`.
-
-Capability modules must therefore be importable without secrets or network access.
-Read required environment variables and make requests inside handlers or workflow
-steps, not at module scope.
-
-## Declaring Notion-as-Code databases
-
-Database declarations use explicit resource IDs and keyed schemas. For a single
-data source, supply the database ID as the first argument and the distinct data
-source ID in `dataSourceResourceId`:
-
-```ts
-import { notion } from "@notionhq/apps/notion-as-code";
-
-const tasks = notion.database("tasks-db", {
-	dataSourceResourceId: "tasks-source",
-	name: "Tasks",
-	schema: {
-		Name: { type: "title", resourceId: "tasks-name" },
-		Effort: { type: "text", resourceId: "tasks-effort" },
-	},
-});
-```
-
-Here `name` is the single-source shorthand: it supplies both the database and
-data-source display names. The source handle is `tasks.dataSource`; pass it to
-`sync({ dataSource, ... })` from `@notionhq/apps`.
-
-For multiple sources, use `datasources` instead of the top-level `schema`:
-
-````ts
-const work = notion.database("work-db", {
-	name: "Work",
-	datasources: {
-		Tasks: {
-			resourceId: "work-tasks-source",
-			schema: {
-				Name: { type: "title", resourceId: "work-tasks-name" },
-				Effort: { type: "text", resourceId: "work-tasks-effort" },
-			},
-		},
-		Projects: {
-			resourceId: "work-projects-source",
-			schema: {
-				Name: { type: "title", resourceId: "work-projects-name" },
-			},
-		},
-	},
-});
-
-The keys in `datasources` are the source names, so the handles are indexed by
-those names: `work.datasources.Tasks` and `work.datasources.Projects`. Nested
-data-source configs do not accept `name`. The top-level database `name` remains
-supported and names the database; in a single-source declaration it also
-supplies the source display name. Property configs do not accept `name`; each
-schema key is always the property's name. Typed property access uses
-`work.datasources.Tasks.schema.Effort`; sync primary keys and row properties use
-the string/object key `"Effort"`.
-
-Every database, source, and property ID remains explicit and must be unique
-across the provisioning declarations. No IDs are generated from keys or names.
-Preserve explicit IDs when changing authoring keys or display names.
-
-Page and teamspace handles accept the same forms through
-`page.addDatabase("database-id", args)` and `teamspace.addDatabase("database-id", args)`.
-Top-level declarations also accept
-`parent: { type: "resourceId", resourceId: "parent-id" }`; omitting it retains the
-private Apps workspace parent. A database must declare at least one data source
-or at least one view. A linked-only declaration may omit `datasources`, or use
-`datasources: {}`, only with a nonempty `views` list. The empty forms `{}`,
-`{ datasources: {} }`, and `{ datasources: {}, views: [] }` are rejected; widened
-or dynamic maps and arrays are checked at runtime. The single-source `schema` and
-multi-source `datasources` forms cannot be combined.
-
-Here is a linked-only database whose typed table view references an explicit
-data source resource ID:
-
-```ts
-const linked = notion.database("work-linked-db", {
-	views: [
-		{
-			resourceId: "work-issues-table",
-			type: "table",
-			dataSourceResourceId: "issues-source",
-			properties: [{ property: "issue-title", visible: true }],
-		},
-	],
-});
-````
-
-The build converts these declarations to the existing serialized database
-intents: `dataSources` and `properties` remain arrays with exact resource IDs
-and names from the authoring keys. Authoring-only `schema`, `datasources`, and
-database-level `dataSourceResourceId` fields do not leak into the serialized
-database intent. The provisioning JSON envelope and server API are unchanged.
-
-## Provisioning artifact and deployment
-
-The optional provisioning artifact uses `$schema: "notion:apps-provisioning:v1"`,
-`version: 1`, and an `intents` array. These declarations are build metadata, not
-provisioning operations executed by the deployed Worker.
-
-After a successful build, the artifact reflects the current declarations. If no
-declarations remain, the build removes any previous `dist/provisioning.json`
-rather than uploading stale intents or emitting an empty artifact. This also
-works when rebuilding into a reused `dist/` directory. Removing the artifact does
-not delete previously provisioned Notion resources or reset their cloud state.
-Do not deploy the output of a failed build.
-
-Build and coordination modes use the existing CLI arguments:
-
-| Command                               | Build location                                   | Deployment coordination       |
-| ------------------------------------- | ------------------------------------------------ | ----------------------------- |
-| `ntn apps deploy`                     | Cloud sandbox, using the project's installed SDK | Server (`workersBuildWorker`) |
-| `ntn apps deploy --local-build --yes` | Local `notion-apps build`                        | CLI, as on `main`             |
-
-Cloud builds do not require the SDK or Node.js on the invoking machine. The
-uploaded project must declare its SDK dependency and a `build` script that invokes
-`notion-apps build`; the cloud runner uses the existing `npm run build` or
-`pnpm run build` command, not a separate SDK command. The CLI creates an App-linked
-Worker using `workersCreateWorker` with `createApp: true`, or updates the existing
-Worker, then uploads source and calls `workersBuildWorker` with the Worker ID.
-For App-linked Workers, the build endpoint coordinates capability registration,
-Notion-as-Code provisioning, database attachment, workflow binding resolution,
-and workflow permission reconciliation before reporting build success.
-It returns the normal build result and run ID, not provisioning state. No separate
-Apps deployment endpoint is required.
-
-For App-linked Workers, the Notion-as-Code build phase prepares a separate
-upload target, like the manifest target, for optional `dist/provisioning.json`.
-The cloud runner uploads the file only if the build emits it; an upload failure
-fails the build. The provisioning hooks read the JSON directly, not from the Worker
-bundle. Provisioning JSON is limited to 5 MiB; a missing object means there are no
-provisioning declarations, while other read errors or invalid JSON fail deployment.
-
-This upload is a retained, deployment-scoped object in the existing Workers S3
-bucket. The coordinator leaves it in storage after successful or failed deployment
-attempts. It records build declarations, not the durable installation-owned
-Notion-as-Code resource mappings and state.
-Ordinary Worker deployment APIs, responses, and storage lifecycle are unchanged.
-
-`--local-build` preserves the current CLI-coordinated setup. The CLI builds and
-uploads the Worker bundle and manifest, uses the existing Notion-as-Code apply
-flow and local state, and reconciles attachments. It reads the optional
-`dist/provisioning.json` locally and does not upload it separately or invoke
-the cloud build endpoint.
-
-Workflows with nonempty `access` require cloud deployment. The local-build path
-rejects them after the SDK build and before uploading or deploying the bundle.
-
-Custom-block default bindings are stored in `manifest.json` as resource IDs and
-resolved to live data source and property IDs during deployment. Live resource
-bindings are not stored in SDK build output. Local deployments retain a
-local state file and report `state_file`; cloud deployments keep installation-owned
-resource mappings and state on the server. Cloud builds do not import local state
-or return provisioning state to the CLI. Local and cloud state are independent:
-switching between modes may recreate resources rather than reuse existing bindings.
-
-Cloud failures never automatically retry locally. There is no rollback: code or
-resources may already have changed when a deployment fails.
-
-## Workflow access
-
-`workflow({ access: { handbook: access.view(handbook) }, ... })`
-declares access to a NaC resource and a named runtime binding. The manifest
-contains only the alias and its symbolic `{ type, resourceId, level }`
-requirement; live IDs are not build output.
-Build validation rejects references missing from the current provisioning
-declarations or having the wrong resource kind. `resourceId` is required because
-it identifies the declaration used for this validation and binding.
-
-After provisioning, cloud deployment resolves requirements against the successful
-NaC apply result. It reconciles code-managed grants through the existing
-Notion-module permissions and saves those permissions together with resolved
-bindings on the workflow's worker module, keyed by capability and alias, in one
-workflow transaction. Bindings are not authorization: the existing permissions
-authorize `context.notion` calls. Redeployment updates or removes code-managed
-grants as declarations change while preserving manually configured UI grants.
-
-Execution reads the selected workflow configuration, not the latest NaC state,
-validates the bindings against the capability requirements, and injects only that
-capability's declared bindings. The SDK exposes typed, readonly `{ type, id }`
-entries in `context.access`; UI-granted resources do not appear there. Use live
-record IDs directly in `context.notion` calls for UI-granted resources; those
-calls remain subject to the existing permissions. Missing or mismatched bindings
-fail before the handler executes.
-
-See the [workflow skill](../skills/workflow/SKILL.md#resources-created-with-the-app)
-for supported resource types, access levels, and an authoring example.
-
-## Manifest
-
-The workflow-only manifest retains the platform's existing resource fields as empty arrays:
-
-```json
-{
-	"$schema": "notion:apps-manifest:v1",
-	"sdkVersion": "0.0.1",
-	"databases": [],
-	"xldbs": [],
-	"pacers": [],
-	"capabilities": [
-		{
-			"type": "workflow",
-			"key": "onPageCreated",
-			"config": {
-				"name": "Log New Pages",
-				"description": "Logs every page created in the workspace",
-				"triggers": [{ "type": "notion.page.created" }]
-			}
-		}
-	]
-}
-```
-
-The platform invokes a workflow through the generated bundle's `run("workflow", key, event)`
-dispatcher. Workflow results continue using the existing Notion output envelope, and runtime
-metadata continues using the existing `NOTION_*` environment variables and `workerId` field.