Contributing

Development setup
Work-plan with beans
Agent guidance
Documentation
Shipping a change

Development setup

git clone https://github.com/litlfred/folio-assistant.git
cd folio-assistant
bun install
bun test          # unit tests
bun run cat lint      # eslint
bun run cat test:e2e      # e2e (test:e2e)

Work-plan with `beans`

This project uses beans as the single todo/work-plan mechanism (see AGENTS.md). Do not stand up a separate todo store.

scripts/install-beans.sh
beans list
beans create "<title>"
beans <id> --status in-progress   # claim before you work

beans ≠ sidecars: never beans create bulk machine-generated queues (QA, witness, watcher) — those stay as bulk JSON.

Agent guidance

AGENTS.md is the agent-generic source of truth (read natively by Claude Code, Gemini CLI, Antigravity, Cursor, Copilot). CLAUDE.md / GEMINI.md are thin stubs that point to it. Update AGENTS.md rather than a tool-specific file when changing agent guidance.

Documentation

Prose docs live under docs/ (this Jekyll site).
Skill schema reference is generated — never hand-edit docs/reference/skills/*.md. Edit the JSON Schemas under schemas/skills/<skill>/ and regenerate:
```
bun run scripts/gen-schema-docs.ts
```
Skill instructions (docs/reference/skill-instructions/*.md) are also generated — never hand-edit them. Edit the skill bodies under skills/authoring/content-lifecycle/*.md or src/skills/*.md and regenerate:
```
bun run scripts/gen-skill-docs.ts
```
The TypeScript API reference (/api/) is generated by TypeDoc in CI.
The site is built and deployed to GitHub Pages by .github/workflows/docs-site.yml on every push to main that touches docs, schemas, or the source.

Preview locally:

cd docs
bundle install
bundle exec jekyll serve

Shipping a change

Verify → confirm mergeable → push → (only if asked) open a PR. See skills/sdlc/sdlc-core/prepare-merge.md. Keep the formalism of the framework separate from content — content belongs in its own repository, and any content in these docs is illustrative only.