#@teakit/napi

Preserve the public identity boundaries: the product and repository are @teakit/napi, Zig users import napi, and command-line users install or run napikit.

#Workflow

1. Read AGENTS.md, skills/llms.md, and the relevant accepted spec.
2. Identify the affected surface: runtime, build integration, CLI, docs, or release tooling.
3. Load only the matching reference pages below. Start with a maintainer reference for repository work, then open detailed guides only when needed.
4. Add or update tests before changing behavior.
5. Keep public docs, scripts, and CI aligned with the implementation.
6. Run the narrowest checks while iterating, then the canonical checks before handoff.

#Reference routing

Treat every references/*.md label below as a local path relative to this file. Its link points to the corresponding stable public documentation route.

#Maintainer references

• Read references/runtime.md for Zig exports, conversions, callbacks, async work, classes, and namespaces.
• Read references/build-and-packaging.md for build.zig, native targets, declarations, generated npm packages, and publishing boundaries.
• Read references/cli-and-docs.md for CLI commands, Bun scripts, Rspress routing, and repository tooling.

#Getting started

• Use references/quick-start.md for the scaffolded addon path.
• Use references/manual-setup.md for hand-written project setup.
• Use references/project-layout.md for the consumer repository and generated package tree.

#Authoring addons

• Use references/functions.md for exported functions and registration.
• Use references/namespaces.md and references/classes.md for nested exports and stateful instances.
• Use references/type-conversion.md and references/memory.md for Zig/JavaScript values, allocation, and lifetimes.
• Use references/errors.md and references/callbacks.md for failures and JavaScript callbacks.

#Async work

• Use references/workers.md for one-result background work.
• Use references/threadsafe.md for cross-thread, multi-call callbacks.
• Use references/promises.md for manually settled promises.

#Build and release

• Use references/typescript.md for declaration generation.
• Use references/cross-compiling.md for release targets and partial builds.
• Use references/publishing.md for npm package layout, trusted publishing, and release CI.

#API reference

• Use references/cli.md for napikit commands and references/build.md for the consumer build.zig API.
• Use references/env.md, references/val.md, and references/error.md for the core runtime environment, JavaScript values, and N-API errors.
• Use references/callback.md, references/threadsafe-fn.md, references/ref.md, and references/deferred.md for callback and lifetime primitives.
• Use references/call-info.md and references/class.md for low-level calls and class definitions.
• Use references/dts.md for declaration generator APIs.

#Guardrails

• Use @teakit/napi for product and repository branding; reserve napikit for the CLI package, executable, and commands.
• Do not rename the Zig package from napi or the npm CLI from napikit.
• Do not change public Zig APIs, CLI commands, generated package layouts, supported targets, registry, or access level without explicit approval.
• Keep bunup and public npmjs publishing unless a proposal explicitly replaces them.
• Keep public Rspress entry files at skills/ and detailed package guidance in skills/teakit-napi/references/; internal documents under docs/ are not site pages.
• Keep the public documentation origin https://napi.teakit.org synchronized across Rspress, README, skills/llms.md, and npm package metadata.
• Keep the canonical source repository https://github.com/teakit/napi synchronized across Rspress, README, skills/llms.md, CLI scaffolding, and npm package metadata.
• Preserve the public documentation routes declared in rspress.config.ts when reorganizing reference files.
• Use Biome for supported files and zig fmt for Zig. Do not introduce another formatter, linter, package manager, or test runner.

#Verification

bun run check
bun run typecheck
bun run test
bun run build
bun run docs:build