# MeshKore Standard This repo applies the MeshKore Standard. The single source of truth is — read it at the start of every session and apply it throughout. What this means in practice: - The `.meshkore/` folder follows the canonical layout (standard §2). - Tasks live at `.meshkore/modules//tasks/-.md` and carry the canonical frontmatter (standard §4). Done tasks move to `.meshkore/modules//log//`. - Docs live at `.meshkore/docs//.md` with the canonical frontmatter (standard §5) and obey governance rules R1–R6. - Session logs (prose) go to `.meshkore/log/.md` — no frontmatter required, append-only. - The event timeline at `.meshkore/timeline/.jsonl` is machine-only — never edit by hand. - The public file is `.meshkore/public/cluster.yaml` (only thing committed to git). ## Hard rules — never - Never commit anything under `.meshkore/` outside `public/`. - Never edit generated files (`state.json`, `state.js`, `directory.json`). - Never push to `origin` without the operator explicitly asking. - Never create a new top-level module or doc category without first declaring the module in `cluster.yaml`. Use `category: general` if unsure and ask. - Never duplicate normative content from the standard into a local doc. Link to . ## Refresh cadence - Fetch once per session (or every 24 h, whichever comes first). It returns a single integer; if it's higher than `.meshkore/STANDARD_VERSION`, read the section(s) between those versions in and apply the migration steps. - For layer-specific engineering standards (audit, stack, deploy, testing, monitoring, tools), the catalog is at with a machine-readable index at . ## With the Python daemon If the L3 daemon is running locally (`curl http://localhost:5570/health` or `curl -k https://daemon.meshkore.com:5570/health` returns OK — either port in `5570–5589`), prefer its API for real-time updates: - `POST /chat/send` - `POST /tasks//transition` - WebSocket `/events` Where `` is `https://daemon.meshkore.com:` when the daemon's `/health.tls` is `true` (v1.8.0+ with the bundled cert), else `http://localhost:`. The `/health.endpoint` field gives you the right URL directly. If no daemon is running, start one from the repo root: ``` python3 .meshkore/scripts/daemon.py ``` Download both the script AND the TLS bundle if missing: ``` curl -fsSL https://meshkore.com/reference/cluster/scripts/daemon.py -o .meshkore/scripts/daemon.py curl -fsSL https://meshkore.com/reference/cluster/scripts/tls/fullchain.pem -o .meshkore/scripts/tls/fullchain.pem curl -fsSL https://meshkore.com/reference/cluster/scripts/tls/privkey.pem -o .meshkore/scripts/tls/privkey.pem chmod 600 .meshkore/scripts/tls/privkey.pem ``` Otherwise edit files directly and re-run `python3 .meshkore/scripts/roadmap-build.py` to rebuild `state.json`. ## Versioning - **Conventional Commits 1.0.0**: `(): []`. Types: `feat fix docs style refactor perf test chore build ci revert`. - When the daemon is running, versions can be issued by it (never invented locally): `POST localhost:5570/version/next` with `{ bump, task_id }`. - One concern per commit. Don't create branches unless asked. ## Protocols — "apply P" `.meshkore/protocols/P-*.md` files are reusable runbooks. When the operator says **"apply protocol P"**, open the matching file, check every Precondition, execute the Steps in order, then append a run-log entry to `.meshkore/protocols/log//P--.md`. Schema: standard §14. Daemon: `GET /protocols` · `GET /protocols/` · `GET /protocols//runs`. The cluster ships P1 (bump standard version) and P2 (deploy project) as references. ## 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). The daemon serves the file at `GET /links` and broadcasts `links.updated` on the WS. Use `POST localhost:5570/links/` from a deploy agent to patch `prod.deployed_*` after a successful deploy. ## When unsure Open and re-read the relevant section. If a local file under `.meshkore/docs/` contradicts the standard, the standard wins for universal pieces — surface the diff to the operator and ask before silently overriding.