Testing and documentation >> Wild HQ handbook

Verification answers “what evidence says the requested behaviour works?” A long command list without the changed behaviour is not an answer, and a passing build is not proof that an interface is usable.

Match checks to risk

Use the smallest fast check while iterating, then cover the full affected boundary before hand-off.

Change	Minimum useful evidence
Pure function or parser	Focused unit test including failure and edge cases.
Packbase server route	Handler or route test, route compilation, types, and server tests.
Public API shape	Response-schema test, SDK compatibility, and affected client test.
React component	Unit test for logic plus representative Storybook states.
Interaction or accessibility	Keyboard and focus behaviour, Storybook interaction/a11y check, narrow and zoomed layout.
Localised copy	Lingui extraction diff, placeholder review, and affected locale rendering where available.
Database change	Generated diff review, disposable-database exercise, affected query tests, and recovery plan.
Background job	Success, retry, duplicate, partial failure, status visibility, and shutdown behaviour.
Deployment or configuration	Exact revision and environment, preflight, post-deploy behaviour, logs, and rollback or fix-forward condition.
Handbook or site content	Astro check, production build, internal-link/search/sitemap checks, and diff whitespace check.

Repository commands

Wild HQ site

pnpm check
pnpm build
git diff --check

Packbase web

bun run lint
bun run typecheck
bun run format:check
bun run test
bun run build
bun run build-storybook

bun run check runs that release-readiness sequence. The test project includes headless Chromium Storybook checks. If the browser dependency cannot run, report the narrower checks that did run and leave the Storybook/browser suite explicitly unverified.

Packbase server

pnpm --dir apps/server routes:check
pnpm --dir apps/server check-types
pnpm --dir apps/server test
git diff --check

Add routes:list while investigating route ownership. Use routes:snapshot only for an intentional public path-set change. Format commands write files; format-check commands do not.

Report evidence, not vibes

Use a verification note like:

Automated
- <command>: passed / failed / not run

Manual
- <behaviour and environment checked>

Not verified
- <missing environment, permission, tool, or scenario>

Known baseline
- <pre-existing failure reproduced before the change>

Never convert “not run” into “should pass.” Separate a targeted pass from an unrelated full-suite failure and include the first useful failing command rather than only the wrapper’s exit code.

Keep instructions current

Update documentation in the same change when you alter a command, route, environment name, public behaviour, reusable interface rule, operational step, or product promise.

Repository-specific setup and commands belong in the repository README or contribution guide.
Public volunteer practice and cross-repository procedure belong in this handbook.
Product-specific user behaviour belongs in product documentation.
A task or pull request records a particular decision; do not turn one incident into a timeless policy without review.

For a handbook page, add or edit src/content/handbook/pages/<path>/index.mdx, use only registered tags, set a truthful reviewed date, and add descriptive root-relative links. The build derives navigation, search, topic pages, and sitemap entries from the collection.

If documentation and code disagree, do not silently pick the friendlier answer. Establish current behaviour, correct the authoritative source, and preserve historical context where it still explains old URLs or data.