Skip to content

docs: clarify authoring documentation boundary #129

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
robinvrd merged 1 commit into from
Oct 30, 2026
Merged

docs: clarify authoring documentation boundary #129

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,4 +4,10 @@ Follow [app authoring](docs/app-authoring.md) with the selected starter for a ne
app or the current source for an existing app. Open another guide only when the
task needs a pattern that source does not cover. Search [REFERENCE.md](REFERENCE.md) for the exact export or prop.

Package contributors follow [Contributing](CONTRIBUTING.md).
## Contribute to this repository

Read [Contributing](CONTRIBUTING.md) before changing packages or contributor
tooling. App authoring guides teach agents how to build apps with the SDK.
Keep reusable behavior in components, defaults, types, and tests. Add authoring
documentation only when an app author must make a decision or take an action;
do not restate patterns already handled by the SDK.
15 changes: 12 additions & 3 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,8 @@ bash scripts/install-test-browser.sh
for the kind of change being made.
2. **Change source and consumers.** Keep the public API focused on concrete app
needs. Preserve package boundaries and explicit exports. Update affected
callers, starters, and guides with public behavior changes.
callers when public behavior changes. Update starters and guides only when
app authoring must change; apply the documentation boundary below.
3. **Run focused checks.** Build with `bun run build` before consumer tests.
Select the test file or `-t "workflow name"` matching the change. For example,
CSV export changes use `bun run test tests/public-api/apps-export.test.ts`.
Expand Down Expand Up @@ -58,14 +59,22 @@ imports, fabricated internal state, and implementation assertions. Prefer
accessible role/name or label queries scoped to the relevant region. Keep browser
workflows self-contained in `apps-*.test.ts`.

Update the relevant guide and starter. Keep app authoring in `docs/`; document
current usage with one focused example, `<Component>` and `functionName()` notation.
When a change requires new app code or an authoring decision, update the relevant
guide and starter. Keep app authoring in `docs/`; document current usage with one
focused example, `<Component>` and `functionName()` notation.
Show complete enclosing calls and components; use `// ...` for unrelated setup.
Name the app declaration `dataApp`; keep the API's `app` prop name.
Leave prop inventories to TypeScript and JSDoc. Generate `REFERENCE.md` with
`bun run build` and stage it before `bun run check:reference`; improve entries
through types and JSDoc, never generated output.

## Documentation boundary

App authoring guides teach agents what to decide, supply, or change in app code.
Keep automatic behavior and reusable patterns in components, defaults, types,
and regression tests. Do not document them as authoring steps or end-user
instructions.

## UI platform principles

- Express intent through small typed props and simple data structures.
Expand Down