# MeshKore cluster This repo participates in a MeshKore cluster. If `.meshkore/` exists, follow the operator's manual at . Read it once at session start. Apply throughout. ## Quick reminders - **Modules**: declared in `.meshkore/public/cluster.yaml` under `modules:`. Each task lives in `modules//tasks/` and carries `category: `. If a task doesn't fit, use `category: general` — never `uncategorized`. Modules nest via `parent: `; flat by default. **`project` is a peer of api/webapp/portal/daemon, not their root.** It holds the meta bucket (`testing`, `audit`, `future`, `general`) + cross-cutting initiatives. Code work belongs to a code module, never to `project`. See . - **Tasks**: `.meshkore/modules//tasks/-.md` with YAML frontmatter (`id`, `title`, `status`, `priority`, `owner`, `category`, `created`, `updated`, `tags`, `depends_on`). - **Activity logging**: every notable change → one event in `.meshkore/timeline/.jsonl`. Either run `python3 .meshkore/scripts/timeline-append.py --type --text "..."` or, if the Python daemon is running locally, hit `localhost:5570/chat/send` / `/tasks//transition`. - **Refresh state** after editing tasks/docs: `python3 .meshkore/scripts/roadmap-build.py`. - **Docs**: live in `.meshkore/docs/{architecture,product,conventions,modules,deploy,security,ops}/`. Each `.md` requires frontmatter (R4). Max 200 lines per file (R2). Read `.meshkore/docs/governance.md` once. ## Protocols — "apply P" `.meshkore/protocols/P-*.md` files are reusable runbooks. When the operator says "apply protocol P", open the file, check Preconditions, execute Steps in order, append a run log under `.meshkore/protocols/log//`. Schema: standard §14. Daemon: `GET /protocols` · `GET /protocols/` · `GET /protocols//runs`. P1 = bump standard version, P2 = deploy project. ## Deployment links registry Every commit that changes where a module runs, where it deploys, what branch it lives on, or what version it carries MUST also update `.meshkore/public/links.yaml` in the same commit (standard §13). Daemon: `GET /links` · `POST /links/`. ## Hard rules — never - Never commit `.meshkore/credentials/`. Ever. - Never commit anything outside `.meshkore/public/`. - Never push to `origin` without the user explicitly asking. - Never edit generated files (`.meshkore/roadmap/state.json`, `state.js`). - Never invent a new module / category top-level without first declaring it under `modules:` in `.meshkore/public/cluster.yaml`. If unsure where a task belongs, use `category: general` and ask the user. ## Commits + versioning - **Conventional Commits 1.0.0**: `(): []`. Allowed types: `feat fix docs style refactor perf test chore build ci revert`. Breaking changes: `!` after type + `BREAKING CHANGE:` footer. - **Versions are ISSUED BY THE MASTER DAEMON**, never invented locally: `POST localhost:5570/version/next` `{ bump, task_id }` → `{ "version": "0.5.1" }`. Solves the parallel-agent collision problem. - Default `bump=patch`. `minor` only for `feat`. `major` needs human approval. - One concern per commit. Don't create branches unless asked. - Full rules: ## Workers + multi-device - **Workers** = persistent agent sessions on the master daemon (`.meshkore/.runtime/workers.json`). One coordinator + N module-bound workers, each with a stable session_id passed as `claude --session-id`. Manage from the portal: Cluster · Network. Don't confuse a worker (local execution) with an agent identity (cluster admission). - **Single-device baseline today.** Multi-device with module ownership + locks is V23 (planned). ## When unsure Open (or the cached copy at `.meshkore/docs/governance.md` + the scripts in `.meshkore/scripts/`) and re-read the relevant section. # Permissions - Workers run headless with `--permission-mode bypassPermissions` by default. cwd is the repo, so file tools can't escape it. Bash inherits the daemon user — treat that as the trust boundary. Tighten per worker via the portal Cluster · Network → edit → Permissions dropdown. See https://meshkore.com/reference/cluster/docs/conventions/permissions.md