AGENTS.md

1# Agent Guide
2 
3Guidance for agents (and humans) working on this repository.
4 
5## App authoring default
6 
7Native SDK itself is implemented in Zig, but Native SDK **apps are authored in TypeScript + Native markup by default**. Do not infer the app-authoring language from this repository's implementation language or from older Zig-core examples.
8 
9- For a new app, use `native init <path>` and expect `src/core.ts`, `src/app.native`, and `app.zon`. Ordinary compiled TypeScript work that needs filesystem, process, JSON, regex, classes, or other static-tier APIs belongs under optional `src/services/`, reached from the core with `Cmd.request`; do not import a service from the core. Do not add Zig app code unless the user explicitly chooses `--template zig-core` or the feature requires a toolkit extension.
10- Before changing an existing app, inspect its tree. A `src/core.ts` app stays TypeScript; a `src/main.zig` app stays Zig unless the task is specifically a migration.
11- For default app work, read `skill-data/native-ui/SKILL.md` and `skill-data/ts-core/SKILL.md`; also read `skill-data/ts-services/SKILL.md` when the tree has `src/services/` or the task needs ordinary TypeScript beyond the core subset. `skill-data/core/SKILL.md` covers shared/runtime concerns; `skill-data/zig/SKILL.md` is for Zig-core apps and SDK implementation work.
12- The `-ts` suffix on a few examples only distinguishes ports from older Zig originals. New TypeScript apps need no suffix because TypeScript is the default.
13 
14## Build, test, and gate
15 
16```bash
17zig build test                # root engine + runtime suites
18zig build validate            # sample app.zon manifest check
19zig build test-example-&lt;name&gt; # one example's suite (e.g. test-example-notes)
20scripts/gate.sh fast [ref]    # affected-only local gate for your diff (default base: main)
21scripts/gate.sh full          # everything CI-shaped that runs locally
22```
23 
24Run `scripts/gate.sh fast` before finishing any change; it maps your diff to the suites that cover it. The docs site checks with `pnpm --dir docs check` (the gate runs it only when `docs/` changed).
25 
26This repository builds with Zig 0.16.0. If a build fails with "no member named" errors on std APIs (`std.fs.cwd`, `ArrayList.init`, `std.io`), you are writing pre-0.16 idioms — `skill-data/zig/SKILL.md` maps each such compile error to the current idiom as this codebase writes it.
27 
28Pinned goldens (pixel signatures, schema fingerprints, command counts) are updated deliberately: review the rendered output or the counted commands first, and keep the pin's comment a self-contained description of what the value represents.
29 
30## Changelog
31 
32Do not edit `CHANGELOG.md` as part of regular feature or fix work. The release agent reviews the git history since the previous release and writes the complete changelog entry during release preparation; see [RELEASING.md](./RELEASING.md).
33 
34## Where things live
35 
36- `src/` — the engine and runtime; `src/primitives/canvas/` holds the widget, markup, and vector core.
37- `examples/` — the showcase apps, most zero-config (`app.zon` + `src/`).
38- `docs/` — the documentation site; `docs/AGENTS.md` has its MDX conventions.
39- `skills/` and `skill-data/` — the agent skills the CLI ships (`native skills list`).
40- `tools/` and `scripts/` — dev tooling and the local gate.
41 
42Releases are maintainer-run; see [RELEASING.md](./RELEASING.md).
43