Thanks for your interest in improving knowledge-base.
npm install # Node >= 24
npm run build:headless # hermetic build from the vendored fixture (tests/fixtures/)
npm test # embedded web-fragment E2E (Playwright)The build and tests are fully hermetic — they use the committed
tests/fixtures/docs-example.dist.tar.gz fixture (registered via apps.json),
so no GITHUB_TOKEN, network, or sibling repository is required.
If your ~/.npmrc points at a corporate registry, install with
--registry=https://registry.npmjs.org/ before committing a lockfile change:
both lockfiles must keep resolving to the public registry (see AGENTS.md).
See CLAUDE.md for an architecture overview and the full command
list, and README.md for usage.
AGENTS.md is the mechanical checklist for what CI enforces on a
pull request — branch name, title format, description, size — plus the
repository conventions a change is expected to respect. Worth a read before
opening your first PR, and required reading for automated contributors.
| Command | What it runs |
|---|---|
npm test |
Embedded web-fragment harness (playwright.config.js) — host gateway proxies/embeds the fragment on :4201. |
npx playwright test --config=playwright.config.ci.js |
Standalone fragment-server layer (:3000) — headers, headless contract, asset routing, #297. |
npm run test:container |
Integration tests against the real nginx image. Needs Docker, so it is not part of npm test. Run it when changing nginx.conf, nginx.headers.conf or the Dockerfile. |
Both run in CI (.github/workflows/ci.yml). Please make sure both pass before
opening a PR.
- Branch off
master. - Keep changes focused; update docs/tests alongside code.
- Ensure
npm run build:headless,npm test, and the standalone suite pass. - CI (type-check, build, E2E, audit) must be green.
Please follow SECURITY.md — do not file public issues for
vulnerabilities.
By contributing, you agree that your contributions are licensed under the Apache License 2.0.