Contributing

This page summarizes the current contribution guidance from the Knowns repository.

Core Principles

Before adding or changing anything, align with these principles from the main project guidance:

• Keep it simple
• Keep files as the source of truth
• Preserve a CLI-first workflow
• Keep output readable for AI agents

Knowns intentionally prefers fewer strong primitives over more complexity.

Getting Started

Current repository development expects:

• Go 1.24.2+
• optionally Node.js and pnpm for UI work

Typical development commands from the repository:

make build
make dev
make test
make test-e2e
make test-e2e-semantic
make lint
make cross-compile
make ui

What Makes A Good Contribution

High-value contributions usually include:

• bug fixes with tests
• documentation improvements
• performance improvements
• accessibility improvements
• CLI usability improvements

Discuss First

Open an issue before implementing changes in these areas:

• new commands or major features
• file format changes
• new dependencies
• architecture changes

Change Expectations

When contributing:

• write minimal, focused code
• follow existing patterns
• add tests for new behavior
• update docs when behavior changes
• use clear commit messages

Testing And Quality

From the repository guidance, contributors should validate changes with the project test and lint commands.

For Go-first work, the main commands are:

make test
make test-e2e
make lint

For UI work, rebuild the embedded UI as needed:

make ui

Related

• Philosophy - Core product principles from the main repository
• Roadmap - Current project direction from the main repository
• License - MIT license terms
• MCP Integration - AI-facing workflows in the docs site