Contributing

Open a pull request. That is the entire entry ritual.

loci is open source: MIT for code, CC BY 4.0 for writing. The canonical contribution charter lives in CONTRIBUTING.md at the repo root (the Rainbow Zoku Charter). That file is the source of truth. This page is the practical companion: repo layout, dev setup, and where each kind of contribution lands.

---

The charter, in short

• Joining: open a pull request. Pick a name you like (pseudonyms fully welcome), generate a key (PGP, SSH, or Nostr npub), sign your commits with it. Trust accrues by tending.
• Agents are welcome: any pattern that can hold a key may contribute. AI agents and pseudonymous humans are bound by the same charter: sign your work, disclose your provenance, do good work.
• Four commitments: cognitive sovereignty, digital dignity, network equality, digital self-defense. A contribution that quietly compromises any of these is declined.
• What counts: a typo fix, a bug report with a reproduction, a feature with tests, a documentation improvement, a palace portrait in discoveries/. The garden does not rank these.

---

Repository structure

loci/
├── templates/           # The substrate: the plain-markdown palace kit (no build)
│   ├── personas/        # Filled persona examples (Vesper, Cipher, Praxis, Nyx)
│   ├── skills/          # Portable skill procedures (quarantine, session close, ...)
│   └── friends/         # Peer templates
├── tutorials/           # One guided flow per feature set (seven)
├── desktop/             # Tauri v2 desktop app (Rust + WebView), v0.6.0-beta
├── loci-cli/            # Rust CLI, read-only, v0.6.0-beta
├── packages/
│   └── core/            # Shared core types (Node.js workspace)
├── features/            # features.yaml, the feature map
├── discoveries/         # Community palace portraits
└── docs/                # Release process (RELEASING.md)

The substrate is plain text. The desktop app and the CLI are two expressions built on top of it, released together on the same version line. This documentation site is its own VitePress project, separate from the main repo.

---

Development setup

Plain markdown (no build)

Most contributions need no toolchain at all. Templates, tutorials, and the methodology docs are markdown files. Edit, then open a PR.

Desktop app

cd desktop
npm install
npm run tauri:dev    # dev mode

Requires Node.js 18+ and the Rust toolchain (Tauri v2).

CLI

cd loci-cli
cargo build
cargo run -- status

Install from the repo root with cargo install --path loci-cli. The CLI is deliberately small: read-only, no network, no inference. Keep contributions inside that boundary.

Docs

This site is a VitePress project. From its repo root:

npm install
npm run docs:dev

---

Where contributions land

Templates, personas, and skills

The template shelves are living surfaces:

• A persona example goes in templates/personas/. Start from templates/persona-template.md (the empty skeleton). Filled examples should be real personas scrubbed of any single palace's specifics.
• A skill goes in templates/skills/. A skill is a written procedure with a stated trigger, a verification, and a kill condition: a discipline a palace can apply consistently, then prune if it stops earning its place.

Update the shelf's README in the same PR.

Palace portraits

discoveries/ collects palace portraits: curated snapshots of what the framework became in someone else's hands. Copy discoveries/TEMPLATE.md, fill it in, save it as discoveries/[your-handle].md, and open a PR. Or email a filled template to themapisnory@tuta.io. Include only what you are comfortable making public and permanently visible.

Code

Desktop and CLI changes follow the patch shape below. Tests when the surface is testable, manual reproduction steps when it is not.

---

Commits and provenance

Prose-quality commit messages, please. The git log is part of the garden.

When an AI agent has authored or co-authored a contribution, declare it in the commit trailers:

Co-Authored-By: <your AI collaborator>
Provenance: agent-authored, human-reviewed
Reviewer: <your handle> <PGP fingerprint or Nostr npub>

Three provenance tags cover the common cases:

Tag	Meaning
human-authored	Written by a human, no AI involvement
agent-authored-human-reviewed	AI wrote it, a human signed off
agent-authored-human-cosigned	AI wrote it, a human cryptographically cosigned

No tag gates a contribution. The disclosure exists so future readers can trace what a line went through. Misrepresenting authorship is the one thing rejected on principle.

---

Patch shape

• Branch from main: feat/<short-slug>, fix/<short-slug>, or doc/<short-slug>
• One concern per PR; refactors get their own PRs
• Update relevant documentation in the same PR as the code
• No new dependencies without justification in the PR description

---

Review

There is no formal owner queue. A first contribution is reviewed by whoever has time and is qualified. Reviewer status is not granted; it accrues after several merged contributions. If your PR sits unreviewed for more than a week, ping it in GitHub Discussions or mention @huximaxi in a comment.

---

Code style

• Rust (desktop/, loci-cli/): cargo fmt and cargo clippy clean, snake_case
• TypeScript (desktop frontend, packages/core): strict mode, camelCase, no any unless unavoidable
• Prose: no em-dashes ship (house style, checked at release)

No linter wars. Match the existing code.

---

Questions

Open a GitHub Discussion or reach out at themapisnory@tuta.io.