Contributor guide

Keeping this current

Static HTML built with Python, Jinja templates and Markdown. No app server, database, Node build chain or CMS. The visual system follows the supplied November 4 design export: Archivo / IBM Plex Mono, cool grey, square panels, teal references, red errata, and the inverted Thalamus relay.

Public site, independent repository visibility

The website and its downloadable Engram knowledge bundle are intended to be public. The CNS and organ repositories can remain private; source links may require repository access. Publishing this site does not change repository visibility or make private binaries available. Installation and release distribution remain separate concerns.

The publishing workflow builds only curated sources in this checkout, without upstream credentials or README imports. Review edits to the registry, contracts, architecture and guides as public content. The optional upstream snapshot mode below is for separately reviewed previews, not the public publishing workflow.

Everyday updates

An organ record includes its evidence basis and review date. Keep those current when changing the verification label. An upstream commit is not a verification verdict. Upstream READMEs are displayed as reference material, not used to promote status or overwrite curated summaries. A successful build is not evidence of organ health. Do not put secrets or private operational details in documentation intended for public hosting.

Use verified, early, not-yet or absent for the visual status. Add new organs with unique URL-safe id and plate values; the registry, sidebar, organ pages, channels and lifecycle lists discover them automatically. The sagittal home composition intentionally places the six named organs anatomically; placing a new faculty there requires updating site/templates/home.html.

Content ownership and promotion policy

Generated output is disposable; approved sources are not. A documentation build reads the sources below and replaces _site/. It does not rewrite its inputs. Editing generated HTML or knowledge exports is not a way to preserve a correction: change the owning source instead.

For future mixed reference/narrative pages, compose separate owned sources through templates. Do not have a model rewrite a whole page while asking it to preserve selected paragraphs. Existing editorial text embedded in templates or the builder remains curated content, not model-owned output; this policy does not require extracting it before the current site can ship.

AI supplementation is not implemented. Before adding it, enforce proposal-only changed paths in CI, require maintainer approval, and restrict generation to inputs explicitly approved for public use. A private source summary is not automatically safe to publish. Each proposal must identify its supporting source paths and revisions, distinguish implemented behavior from plans, and include executable-example results where practical. Reviewers promote accepted text into the owning source through a normal PR; rejected and unreviewed proposals never enter the website, search index or Engram export. A model cannot promote verification status or supply its own approval.

Preserving prose is not enough if its dependencies change. Reviewers should record supporting sources with accepted explanations and revisit them when those sources change. Use organ basis and reviewed fields for status provenance today; automated dependency tracking and stale-content warnings are not yet implemented. An organ-push notification or a successful rebuild does not renew a review date, validate an explanation or establish organ health. Future freshness automation should flag affected explanations for review, not rewrite them or silently recertify them.

Build and preview

From the repository root, Python 3.10+:

python3 -m venv .venv-site
.venv-site/bin/pip install -r site/requirements.txt
.venv-site/bin/python site/build.py
.venv-site/bin/python -m unittest discover -s site -p 'test_*.py'
node --test site/test-knowledge.mjs
.venv-site/bin/python -m http.server 8080 --directory _site

Build output is _site/ (ignored). Links are relative, so the same files work at a GitHub project subpath or a Cloudflare domain root. Every build checks local links, fragments and duplicate ids. Search is generated from page bodies and runs entirely in the browser; / focuses the search input. Fonts load from Google Fonts, with system fallbacks if unavailable.

For a separately reviewed upstream preview, add --refresh-upstream. Set GH_TOKEN through your environment with read-only Contents access to all six organ repositories. This includes private README contents in both the HTML and Engram export: do not publish that output without a public-content review. The builder fetches main once per organ, then reads its README at that exact commit. No organ code is checked out or executed. Any fetch failure fails the build rather than publishing an apparently fresh partial snapshot. Normal local and publishing builds use only this checkout and need no token or network for documentation sources.

GitHub Pages (recommended)

1. In this repository's Settings → Pages → Build and deployment, choose GitHub Actions. No gh-pages branch is needed.
2. Merge the site and workflow into main. The docs-site workflow checks pull requests, and builds on main pushes, manual dispatches, organ notifications and a daily fallback (09:23 UTC; 03:23 CST / 04:23 CDT). Merging, notifications and scheduled builds do not publish.
3. No organ-read token is needed or consumed by this workflow. Both PR and production builds exclude upstream README imports, including if a CNS_ORGANS_TOKEN secret already exists.
4. Keep the site public and repository visibility unchanged. Confirm the GitHub plan supports Pages from this private source repository; otherwise use Cloudflare Pages with the same curated build command.
5. After public-content approval and Pages setup, explicitly run docs-site from Actions → Run workflow on main with publish enabled. The input defaults to false; only this manual main-branch run can deploy. Automatic deployment after organ notifications is deliberately gated pending separate publishing approval; those events currently produce build artifacts only.

The workflow does not run live inference, mutate repositories, or automatically mark anything verified. GitHub may delay scheduled workflows; push notifications provide the prompt path. Configure Pages and secrets once; subsequent updates need only normal source commits.

Rebuild on any organ's main push

The CNS workflow receives the organ-main repository-dispatch event. Install the ready-to-copy workflow in site/organ-notify.yml as .github/workflows/cns-docs.yml in each organ repository. It runs on main pushes only, and sends a notification, not source code or arbitrary build parameters.

Provide each sender with CNS_DOCS_DISPATCH_TOKEN: a fine-grained token scoped only to ivannovak/cns, with Contents: write (GitHub requires this permission for repository dispatch). An ordinary organ GITHUB_TOKEN cannot dispatch into another repository. A GitHub App installation token with the equivalent permission is preferable if one is already available. The receiver ignores event payloads and always builds the curated CNS default-branch sources, without importing private READMEs. Concurrent notifications coalesce into one fresh build. A notification rebuilds the site but does not infer public progress from a private commit: update the public registry summary and review date when an organ reaches a publishable milestone. Publication remains a separate manual action as described above.

The sender files, token setup and Pages settings must be installed separately; adding them to this checkout does not activate them in other repositories. The daily build catches missed notifications. It is a GitHub Actions schedule, not a schedule tied to an Amp thread.

Cloudflare Pages alternative

Use the same checkout with build command pip install -r site/requirements.txt && python site/build.py, output directory _site, production branch main, and a Python 3.10+ build environment. Keep GH_TOKEN and --refresh-upstream out of this public build as well.

For cross-repo refresh on Cloudflare, use a Pages deploy hook in place of the GitHub repository-dispatch sender, and a scheduled trigger for fallback. Keep the hook URL secret. The supplied automation targets GitHub Pages; do not enable both deployment paths accidentally.

Engram Knowledge Layer

Every build also emits _site/knowledge/compartments.json, 23 tagged Markdown plates in four M2 compartments, a current key inventory, and _site/knowledge.zip. Navigation-only pages are excluded. The same source edits drive the human site and this Tier 1 export. See the site's knowledge.html page for hydration and retirement semantics.

Knowledge links to bundled plates target .md files at page level, with HTML-only anchors removed. Non-bundled references are labeled website-only rather than emitted as broken offline links. Links to source repositories are labeled as potentially access-restricted in both HTML and Markdown; private source access is not a prerequisite for reading the exported contract or guide itself.

To run conformance and hydration against a real Engram executable, set ENGRAM_BIN to its absolute path when running the Python tests. This also checks that unchanged hydration creates no duplicate memories and a single edited plate supersedes only its previous memory. Without that variable, the real-Engram test is explicitly skipped.

Cloudflare Pages additionally deploys functions/knowledge.js at POST /knowledge, implementing only the read-only pull tools list_knowledge_compartments and read_knowledge_page. It is not a CRDT fact-sync hub. GitHub Pages serves the static bundle only. KNOWLEDGE_TOKEN can require a bearer token on the RPC endpoint; it does not protect static pages or bundles. Set access control for the entire site before publishing private content.

Engram transport versions: Engram 1.6.2 adds certificate-validated HTTPS hub transport for hydration and conformance (release (repository access may be required)). Earlier clients need the static bundle or a separately operated trusted local HTTP-to-HTTPS proxy. Do not send bearer tokens over public plain HTTP or disable certificate validation. GitHub Pages still has no RPC endpoint; this transport change does not create one, and this repository does not establish that a Cloudflare endpoint is deployed.