diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..20b3ee9
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+ - name: Read the spec first
+ url: https://github.com/frankxai/bless/blob/main/SPEC.md
+ about: The Blessing Protocol — the file contract, ritual, schemas, voice.
+ - name: SIP substrate
+ url: https://github.com/frankxai/Starlight-Intelligence-System
+ about: The substrate the lowercase file-contract reconciles with.
+ - name: frankx.ai
+ url: https://frankx.ai
+ about: Frank's hub.
diff --git a/.github/ISSUE_TEMPLATE/proposal.yml b/.github/ISSUE_TEMPLATE/proposal.yml
new file mode 100644
index 0000000..31a44ae
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/proposal.yml
@@ -0,0 +1,35 @@
+name: Protocol proposal
+description: Propose a change or addition to the Blessing Protocol.
+title: "proposal: "
+labels: ["proposal"]
+body:
+ - type: textarea
+ id: problem
+ attributes:
+ label: The problem
+ description: What is missing or wrong today? Who experiences it?
+ validations:
+ required: true
+ - type: textarea
+ id: proposal
+ attributes:
+ label: The proposal
+ description: What you propose, concretely. Which file/schema/section it touches.
+ validations:
+ required: true
+ - type: dropdown
+ id: scope
+ attributes:
+ label: Scope
+ options:
+ - Additive (templates, docs, examples)
+ - File contract (the five files)
+ - Record or room schema
+ - Voice register
+ - Breaking change
+ validations:
+ required: true
+ - type: textarea
+ id: alternatives
+ attributes:
+ label: Alternatives considered
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..6a9b883
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,19 @@
+## What
+
+
+
+## Why
+
+
+
+## Spec impact
+
+- [ ] No change to the file contract / record schema / room schema
+- [ ] Additive change (templates, docs, examples)
+- [ ] Breaking change (bumps the protocol minor version + CHANGELOG)
+
+## Checklist
+
+- [ ] `node scripts/validate-protocol.mjs` passes
+- [ ] Voice stays in the grounded witness register (no spiritual-bypass vocabulary, SPEC §7)
+- [ ] CHANGELOG.md updated if the spec changed
diff --git a/.github/hero.svg b/.github/hero.svg
new file mode 100644
index 0000000..52b57bd
--- /dev/null
+++ b/.github/hero.svg
@@ -0,0 +1,59 @@
+
diff --git a/.github/og.svg b/.github/og.svg
new file mode 100644
index 0000000..b578a3c
--- /dev/null
+++ b/.github/og.svg
@@ -0,0 +1,31 @@
+
diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
new file mode 100644
index 0000000..43be8c5
--- /dev/null
+++ b/.github/workflows/validate.yml
@@ -0,0 +1,18 @@
+name: Validate
+
+on:
+ push:
+ branches: [main]
+ pull_request:
+ branches: [main]
+
+jobs:
+ validate:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-node@v4
+ with:
+ node-version: "20"
+ - name: Validate the Blessing Protocol
+ run: node scripts/validate-protocol.mjs
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000..c39dc61
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,17 @@
+# Code of Conduct
+
+This project follows the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/),
+version 2.1.
+
+We pledge to make participation a harassment-free experience for everyone. We act with respect, accept
+constructive feedback, and prioritize what is best for the community.
+
+Examples of unacceptable behavior: harassment, insulting or derogatory comments, publishing others'
+private information, and other conduct that would reasonably be considered inappropriate.
+
+Maintainers are responsible for clarifying standards and may remove contributions or contributors that
+violate this code.
+
+**Reporting:** contact **friemerx@gmail.com**. All reports are reviewed and handled confidentially.
+
+This Code of Conduct is adapted from the Contributor Covenant v2.1.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..6c786bf
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,77 @@
+# Contributing to bless
+
+`bless` is the open standard for the Blessing Protocol. It is small on purpose. Contributions
+are welcome — and the bar is restraint: the protocol earns its keep by staying legible, not by
+growing features.
+
+By participating you agree to the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+---
+
+## Ways to contribute
+
+- **Adopt it.** Drop the [five files](README.md#the-five-files) into a repo and run a Sunday
+ ritual. Lived adoption is the most useful feedback the protocol can get.
+- **Extend a template.** Improve a starting template in [`templates/`](templates/) without
+ breaking the file contract in [`SPEC.md` §2](SPEC.md).
+- **Build a renderer.** A palace can render as HTML, React, Three.js, or print. The spec defines
+ the room schema ([`SPEC.md` §5](SPEC.md)); the renderer is yours.
+- **Propose a spec change.** Open a [proposal](https://github.com/frankxai/bless/issues/new/choose)
+ before sending a PR that touches `SPEC.md`, the file contract, or either schema.
+- **Fix the small things.** Typos, broken links, clarity. These are always welcome.
+
+---
+
+## Proposing a change to the spec
+
+The normative surface — the five-file contract, the `blessings.jsonl` record, the `rooms.json`
+room schema, the voice register — changes deliberately, never casually. Before opening a PR that
+touches any of it:
+
+1. **Open a proposal first.** Use the proposal form. State the problem, the smallest change that
+ solves it, and what it would break. A spec change with no stated problem will be closed.
+2. **Default to additive.** Additive changes (new optional fields, new enum values) are easy.
+ Breaking changes to the contract or a schema bump the minor version until v1.0 — they need a
+ clear reason and a migration note.
+3. **Respect the voice register.** Copy in this repo obeys [`SPEC.md` §7](SPEC.md): the allowed
+ vocabulary and the refused vocabulary are load-bearing, not stylistic. No spiritual-bypass
+ language, no AI-slop, no canon leak from any single brand's mythology into the protocol.
+4. **Keep the witness honest.** Nothing in a proposal may turn `bless` into a streak mechanic, a
+ guilt loop, or a metaphysical claim. Blessing means whole-at-this-moment closure — and only
+ that.
+
+---
+
+## Branch naming
+
+Branch off `main` with a typed prefix:
+
+| Prefix | For |
+|---|---|
+| `feat/` | A new template, renderer reference, or additive spec change |
+| `fix/` | A correction — broken link, typo, schema mismatch |
+| `docs/` | README, CONTRIBUTING, or other prose without behaviour change |
+
+Examples: `feat/rooms-schema-aurora-surface` · `fix/spec-section-anchor` · `docs/quick-start-clarity`.
+
+---
+
+## Before you open a PR
+
+- Run the validator locally: `node scripts/validate-protocol.mjs`. It must exit `0`.
+- Keep the change surgical. Touch only what the proposal named.
+- If you added or renamed a template, make sure `SPEC.md` still references all five files plus
+ `weekly.md`, and that the validator still passes.
+- Fill out the PR template: What / Why / Spec impact / Checklist.
+
+CI runs the same validator on every push and pull request to `main`. A green check is the gate.
+
+---
+
+## Reviews
+
+PRs are reviewed for: correctness against the spec, restraint (does this need to exist?), and
+voice. A change that passes the validator but fails restraint will be sent back. The answer is
+usually less.
+
+Built on SIP · The Blessing Protocol v0.1 · MIT
diff --git a/README.md b/README.md
index dda2057..363a05c 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,22 @@
+
+
+
+
# bless
-**The Blessing Protocol** — a weekly, agentic practice for *witnessing* the work you ship and *growing a palace* from it.
+*The Blessing Protocol — a weekly, agentic practice for witnessing the work you ship and growing a palace from it.*
+
+[](LICENSE)
+[](https://github.com/frankxai/Starlight-Intelligence-System)
+[](SPEC.md)
+[](https://github.com/frankxai/bless/actions/workflows/validate.yml)
+[](CONTRIBUTING.md)
+
+[**Why**](#why-this-exists) · [**The five files**](#the-five-files) · [**The weekly loop**](#the-weekly-loop) · [**Quick start**](#quick-start) · [**What blessing means**](#what-blessing-means-precise) · [**Spec**](SPEC.md) · [**Contribute**](CONTRIBUTING.md)
+
+
+
+---
> Work for six days. On the seventh, bless the work.
@@ -38,17 +54,14 @@ Lowercase by intent: these are the **public builder tier**. They reconcile with
## The weekly loop
-```
- your GitHub + connectors
- │ ingest (agent reads the week)
- ▼
- bless.md ──── witness the week, ratify what is whole
- │ append
- ▼
- palace.md ──── each blessed thing becomes a room
- │ build
- ▼
- a palace ──── HTML / React / Three.js — grows each Sunday
+Each Sunday, an agent reads the week, the ritual ratifies what is whole, and the palace accrues one ring of rooms.
+
+```mermaid
+graph TD
+ A["your GitHub + connectors"] -->|ingest · agent reads the week| B["bless.md witness the week, ratify what is whole"]
+ B -->|append| C["palace.md each blessed thing becomes a room"]
+ C -->|build| D["a palace HTML · React · Three.js — grows each Sunday"]
+ D -.->|next Sunday| A
```
1. **Ingest.** An agent rolls your week's commits across repos and surfaces what changed.
@@ -81,10 +94,23 @@ You do not need the full toolchain to start. The minimum viable practice is `ble
Blessing is not permanent and not a promotion. New facts can break wholeness; new ambition can compose new rooms. When that happens, the next week's witness records it. Until then, the blessing stands.
+The normative definition, the refusals the ritual must honor, the ledger and room schemas, and the SIP reconciliation all live in [`SPEC.md`](SPEC.md). The honest claim a practitioner may carry lives in [`ATTESTATION.md`](ATTESTATION.md).
+
---
## License
MIT. The spec, the templates, the file contract — open forever. See [`LICENSE`](LICENSE).
-Built on SIP · The Blessing Protocol v0.1
+---
+
+## The Blessing family
+
+| Repo | Role |
+|---|---|
+| [**bless**](https://github.com/frankxai/bless) | The open standard — the Blessing Protocol |
+| [**mind-palace-agent-skills**](https://github.com/frankxai/mind-palace-agent-skills) | Portable agent skills — ingest · witness · grow |
+| [**frankx-mind-palace**](https://github.com/frankxai/frankx-mind-palace) | The mind — Frank's blessed work as data |
+| [**frankx-palace**](https://github.com/frankxai/frankx-palace) | The palace — the 3D memory palace that grows each Sunday |
+
+Built on SIP · The Blessing Protocol v0.1 · MIT
diff --git a/docs/.nojekyll b/docs/.nojekyll
new file mode 100644
index 0000000..e69de29
diff --git a/docs/index.html b/docs/index.html
new file mode 100644
index 0000000..6c34775
--- /dev/null
+++ b/docs/index.html
@@ -0,0 +1,113 @@
+
+
+
+
+
+bless — The Blessing Protocol
+
+
+
+
+
+
+
+
+
+
The Blessing Protocol · v0.1
+
bless
+
Work for six days. On the seventh, bless the work.
+
An open standard: five small files, one weekly ritual, one honest attestation — so an
+ agent can read your GitHub, witness what became whole this week, and render it as a palace that
+ grows more beautiful over time.
The bottleneck at high velocity is not production — it is the witness.
+
Builders ship faster than they witness. Work piles
+ up uncategorised; the memory of what was made goes stale; the next ambition is seeded by
+ restlessness instead of orientation. The practice is old — the Stoics' evening review, the
+ monastic Examen, Sabbath, the engineering postmortem, sangha ratification. They encode one
+ insight: the work of witnessing is its own work, and complex systems become legible only at the
+ right cadence. bless ports that
+ into the agentic era.
+
+
+
+
The five files
+
Drop them into any repo to make it blessable.
+
+
soul.md
Essence — what must not drift.
+
agent.md
How agents behave here.
+
skills.md
What agents can do, and when.
+
palace.md
How work becomes rooms.
+
bless.md
The cadence + the ledger.
+
+
+
+
+
The weekly loop
+
Invoked, never auto-fired. A skipped week is silent.
+
+ your GitHub→ingest→
+ witness→bless what is whole→
+ grow the palace
+
+
+
+
+
What blessing means
+
Closure semantics, not metaphysics.
+
Blessed = whole at this moment. Further iteration is creator-restlessness,
+ not improvement. Future-you may extend it from a new vantage; present-you does not.
+
+
+
+
+
+
diff --git a/scripts/validate-protocol.mjs b/scripts/validate-protocol.mjs
new file mode 100644
index 0000000..39071a1
--- /dev/null
+++ b/scripts/validate-protocol.mjs
@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * validate-protocol.mjs — CI guard for the Blessing Protocol repo.
+ *
+ * Asserts:
+ * 1. the five standard templates + weekly.md exist under templates/
+ * 2. SPEC.md references each of the five files + weekly.md
+ * 3. ATTESTATION.md exists
+ * 4. every local markdown link in README.md + SPEC.md resolves on disk
+ *
+ * Zero-dependency. Exit 0 on success, 1 with specific errors.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const errors = [];
+const p = (rel) => resolve(ROOT, rel);
+
+// 1. templates exist
+const TEMPLATES = ["soul", "agent", "skills", "palace", "bless", "weekly"];
+for (const t of TEMPLATES) {
+ if (!existsSync(p(`templates/${t}.md`))) errors.push(`missing template: templates/${t}.md`);
+}
+
+// 2. SPEC.md references each file
+if (!existsSync(p("SPEC.md"))) {
+ errors.push("missing SPEC.md");
+} else {
+ const spec = readFileSync(p("SPEC.md"), "utf8");
+ for (const t of TEMPLATES) {
+ if (!spec.includes(`${t}.md`)) errors.push(`SPEC.md does not reference ${t}.md`);
+ }
+}
+
+// 3. attestation exists
+if (!existsSync(p("ATTESTATION.md"))) errors.push("missing ATTESTATION.md");
+
+// 4. local markdown links resolve
+const LINK_RE = /\[[^\]]*\]\(([^)]+)\)/g;
+for (const file of ["README.md", "SPEC.md", "CONTRIBUTING.md"]) {
+ if (!existsSync(p(file))) continue;
+ const text = readFileSync(p(file), "utf8");
+ let m;
+ while ((m = LINK_RE.exec(text)) !== null) {
+ let target = m[1].trim();
+ if (/^(https?:|mailto:|#)/.test(target)) continue; // external or anchor
+ target = target.split("#")[0].split("?")[0];
+ if (!target) continue;
+ if (!existsSync(resolve(ROOT, target))) {
+ errors.push(`${file}: broken local link → ${target}`);
+ }
+ }
+}
+
+if (errors.length) {
+ console.error("FAIL — Blessing Protocol validation");
+ for (const e of errors) console.error(` - ${e}`);
+ process.exit(1);
+}
+console.log("OK — five files + weekly template present, SPEC references intact, local links resolve.");
+
# bless
-**The Blessing Protocol** — a weekly, agentic practice for *witnessing* the work you ship and *growing a palace* from it.
+*The Blessing Protocol — a weekly, agentic practice for witnessing the work you ship and growing a palace from it.*
+
+[](LICENSE)
+[](https://github.com/frankxai/Starlight-Intelligence-System)
+[](SPEC.md)
+[](https://github.com/frankxai/bless/actions/workflows/validate.yml)
+[](CONTRIBUTING.md)
+
+[**Why**](#why-this-exists) · [**The five files**](#the-five-files) · [**The weekly loop**](#the-weekly-loop) · [**Quick start**](#quick-start) · [**What blessing means**](#what-blessing-means-precise) · [**Spec**](SPEC.md) · [**Contribute**](CONTRIBUTING.md)
+
+