Contributing

The foundation stays small on purpose. It owns the theme, conventions, docs, and showcase, and almost nothing else. That restraint is what makes it adoptable.

The bar for shared code

A component or utility only belongs in the foundation once the same real requirement has appeared in multiple apps. Until then it lives in the app that needs it. When something does cross that bar, it is promoted deliberately and reviewed, not added speculatively.

Explicitly out of scope: custom business components, auth/API/state abstractions, observability or feature-flag packages, routing or app-shell wrappers, a custom CLI, project generators, and a custom DI framework.

Changing the theme

Edit tokens in packages/theme/src/theme.css (the single source of truth), bump the package version, and publish. Apps pick up the change by bumping the dependency. Never fork the theme in an app.

Changing the docs

• ARCHITECTURE.md and DESIGN.md are generated by the opencode-onboard skills. Regenerate them rather than hand-editing large sections.
• STACK content lives inside ARCHITECTURE.md.
• Component pages are generated from the demos in apps/docs/components/previews/; re-run scripts/gen-component-pages.mjs after adding a demo.

Proposing a change

Open a pull request with the rationale. Keep the change small and reversible, and prefer a convention (documented) over new shared code whenever it will do the job.