@notionhq/apps 0.0.27 → 0.0.29

package/AGENTS.md

@@ -1,7 +1,105 @@
-# Agent instructions
+# Notion Apps project guidance
 
-Before creating, modifying, or troubleshooting an App capability, read the
-matching skill:
+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)
@@ -14,8 +112,8 @@ 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:
+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
@@ -34,7 +132,6 @@ request body. Put a short, complete example near the top:
 ````
 
 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.
+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.