hooks.md

Hook Development

When creating a new hook, always complete all of the following:

1. Implementation: Create the hook in @copilotkit/react-core. If deprecated v1 compatibility shims are needed, add them under the package's src/v1-deprecated/ boundary.
2. JSDoc: Add JSDoc on top of the hook implementation, including usage examples.
3. Tests: Write extensive tests covering behavior, edge cases, and lifecycle (mount/unmount/re-render).
4. API reference: Add a reference page at showcase/shell-docs/src/content/reference/hooks/<hookName>.mdx with title and description frontmatter. The v2 reference navigation is generated automatically by walking the reference/ tree and reading frontmatter (see showcase/shell-docs/src/lib/reference-items.ts) — there is no meta.json to edit for v2 reference; the file and its frontmatter are the metadata. (Only the legacy reference/v1/ tree uses meta.json.)
5. Conceptual docs (if needed): If the hook needs usage/how-to documentation beyond the API reference, add a guide page under showcase/shell-docs/src/content/docs/ and update that section's meta.json so it appears in navigation.

Never recreate the retired docs/content/docs/ tree. The top-level docs/ path is only a symlink to shell-docs. See Documentation.