Microproduct lab (Build Trilemma)

This repository is the Build Trilemma site—patterns, templates, standards, registry, and playbooks for humans and AI agents—served from https://build.trilemma.foundation. Microproducts remain focused apps that turn data into usable tools and real utility.

This repository is an open knowledge hub to help builders learn, contribute, and ship microproducts through community-reviewed playbooks, resources, and examples.

Start Here

• Site routing: On the deployed site, / is an audience chooser. Use /docs/human-overview as the human entry point and /agents as the agent web hub (paths match this repo’s Docusaurus routes). Stable machine-readable URLs such as /registry.json and /schemas/product.schema.json are summarized on the agents hub.
• Read: What is a Microproduct?
• Learn the process: Playbook
• Explore examples: Showcase
• Contribute: How to contribute
• Agent-facing files in the static site root: static/AGENTS.md, static/llms.txt, and generated static/llms-full.txt (created on npm run build)

Local Development

Requires Node.js 22. With nvm, run nvm use to select the repository's reproducible development and CI version, Node.js 22.18.0, from .nvmrc.

npm install
npm run dev

npm run dev runs a short pre-step that removes .docusaurus and node_modules/.cache, then regenerates the agent mirror under docs/agents/human/ from docs/human/. Do not edit generated mirror files directly. Use npm run clear for a full Docusaurus clean (including build/).

Validation

npm run check

This runs:

• TypeScript checking (tsc --noEmit)
• spelling check (cspell on docs/, product-templates/, templates/)
• full YAML frontmatter validation, including real YYYY-MM-DD review dates and mirror-specific rules for generated agent docs when present
• registry JSON and starter product.yaml validation against static/schemas/product.schema.json; product and starter archetypes must match the catalog
• playbook tree sync check (humanPlaybook.data.json must match every file under docs/human/)
• markdown lint for docs/**/*.md and docs/**/*.mdx, plus README.md, CONTRIBUTING.md, templates/**/*.md, product-templates/**/*.md, and products/**/*.md (generated docs/agents/human/** is excluded)
• generate-agent-docs, generate-llms-full, production Docusaurus build, and build-artifact validation (static output + link checks)

Tests

CI runs npm run check then npm run test:coverage. Locally:

npm run test:coverage

npm test and npm run test:coverage run Jest for React code and Node's built-in test runner for scripts. Coverage enforces 100% line, branch, and function coverage for the critical validation utilities while excluding thin CLI wrappers.

Spelling Check

We use cspell to automatically check for spelling mistakes in the docs, which helps prevent noisy review comments. This tool is integrated into IDEs, which highlight spelling errors similarly to other linting or quality issues. If you find that a word is not recognized, you have the option to add it to our dictionary which is included in version control. Examples of domain-specific but legitimate words that might be added include the term "Microproduct" itself.

Example: echo "microproduct" >> project-words.txt

Many IDEs support auto-fixing the issue. Here's what it looks like in VSCode:

Make sure to add to dictionary file and not just editor settings so that the change is picked up in the checker script and can be used by others.