# Contributing to the 1Hive website

Help make 1Hive easier to understand and participate in. Small, accurate improvements are welcome, whether made directly or with a personal agent. Follow the [Code of Conduct](CODE_OF_CONDUCT.md).

## Choose a useful change

Read the [mission and values](https://1hive.org/Our-mission-and-values) and check [existing issues](https://github.com/1Hive/1hive.org/issues) and [pull requests](https://github.com/1Hive/1hive.org/pulls). Small, reversible site and documentation improvements can go straight to a focused pull request. For a substantial architecture change, coordinate with the maintainers responsible for it. A documentation change does not itself establish community policy or authorize funding.

For self-directed work, start with the [contribution launchpad](https://1hive.org/First-contribution-launchpad) and [concept template](contributions/CONCEPT.md). Explain who benefits, how the work advances Honey, contributor capacity, or the commons, and the smallest useful experiment. A source-backed correction or small skill can be valuable when it serves that purpose. Prefer a complete, reusable result over a collection of speculative pages.

## When a proposal helps

Use the [improvement-proposal template](proposals/TEMPLATE.md) when a change spans several contributions, introduces a new process, or needs a durable record of the choices and decision. The [proposal index and workflow](proposals/README.md) are a working draft for this repository, not an adopted DAO-wide policy. A separate proposal is optional for routine maintenance; useful work can progress through the normal review path.

Keep the scope of any decision explicit. Repository maintainers can authorize changes within their remit, but a repository proposal or merge cannot approve spending, change a covenant, or authorize an on-chain action. Those changes require the relevant existing governance process.

## Local development

1. Fork the repository and create a branch from `v4`.
2. Use Node.js 22 or later and npm 10.9.2 or later. `.node-version` records the project's Node.js 22 version.
3. Install dependencies with `npm ci`.
4. Preview with `npm run serve` and open the local URL printed by Quartz.
5. Make the change and run all checks below before requesting review.

```sh
npm run check
npm test
npm run build
npm run check:site
```

`check` runs TypeScript and Prettier. `test` runs the test suite. `build` generates the site in `public/`. `check:site` checks local links in that generated site and verifies the raw agent documents match their source files. It does not verify external websites or replace visual review.

The homepage is generated by `quartz/plugins/emitters/landingPage.ts`; the wiki lives in `content/`. A new page should be linked from an appropriate existing page. Use file names, rather than display titles, in wiki links: for example, `[[wiki|1Hive Wiki]]`.

Agent and proposal documents are maintained once in the repository and published as raw Markdown by `quartz/plugins/emitters/agentResources.ts`. The allowlist keeps private or unrelated files out of the output. When adding a skill, update the allowlist and [skills index](skills/README.md). When adding a proposal, follow the [metadata guide](proposals/README.md#metadata-and-validation) and add it to the allowlist. The build validates the metadata and generates normal wiki pages and a stage index from those sources. Do not edit the generated `content/proposals/` directory. Restart the preview after changing these files, since they are outside Quartz's watched content directory.

## Content and review standards

- Explain who a change helps and why it is useful.
- Link to original sources for factual claims. Date observations about active work, governance, deployments, and funding. Distinguish a proposal or aspiration from a deployed capability or community decision.
- Keep prose clear and specific. Use the existing wiki structure rather than creating duplicate explanations.
- Do not publish secrets, private conversations, or personal data without the appropriate permission.
- For agent-assisted work, describe the agent's role and the checks performed. The submitting contributor remains responsible for accuracy, permissions, and responding to review. No model credentials or private prompts are needed.
- Review agent instructions and skills as carefully as code. They must not grant themselves permissions, silently expand access, or encourage spam or unsafe actions.
- Explain which checks passed, failed, or were not run. For visible changes, inspect desktop and mobile layouts and include screenshots when useful.

## Submit for review

Use the pull-request template. Keep the diff small enough to review, include source links and a test summary, and open a draft if work or review is still pending. An agent should publish a branch, issue, or pull request only when its human has authorized that action.

Maintainers review and merge contributions. Pushes to `v4` trigger the existing GitHub Pages deployment, so approval to prepare a change is not approval to merge or publish it. The pull-request validation workflow builds and tests without deploying.

Funding and recognition follow the relevant community process described in [Curating community contributions](https://1hive.org/Curating-community-contributions). Submitting or merging a change does not automatically create a claim to Honey.