Process & Registry

Family development context API

Amoleo-Family is the canonical source for rules and configuration that genuinely span products. Coding and review agents need that context from local machines, cloud sessions and fresh checkouts without copying the same Family prose into every product repository.

The canonical remote path is the authenticated, static https://family.amoleo.com/api/* surface.

This is development context only. No Amoleo product may depend on this API at runtime for rendering, behaviour, authentication, shared state, assets or availability.

The three surfaces

• Raw API (/api/*) — canonical machine-readable development context. The build copies docs/*.md, tools/**/*.json, AGENTS.md, CLAUDE.md and MissionStatement.md byte-for-byte.
• Guidebook — human-oriented rendered pages on family.amoleo.com. Agents should not fetch rendered HTML just to recover the source Markdown.
• Local stdio MCP — a transitional convenience from an earlier design. It remains usable while #21 is rolled out, but it is not a second permanent source. Once the static API has been proven from real local and cloud agent environments and repo guidance has migrated, the MCP server is removed.

Discovering resources

The docs-site build generates:

https://family.amoleo.com/api/manifest.json

from the exact same resource enumeration used to copy the raw files. It is not a second hand-maintained registry.

The manifest contains:

• schemaVersion;
• purpose;
• resourceCount;
• one entry per exported resource with:
  • sourcePath;
  • apiPath;
  • mediaType;
  • title;
  • a short description derived from the canonical source.

It deliberately does not duplicate full document content.

How an agent should use it

1. Read the current repository's own bootstrap guidance and product/domain source-of-truth docs first.
2. Read /api/manifest.json when Family-wide context is relevant and the required Family file is not already known.
3. Fetch only the Family resources relevant to the current task.
4. Treat product-local decisions and documented deviations as authoritative for that product.
5. If changing Amoleo-Family itself, work in this repository and use the canonical tools/*.mjs scripts directly.
6. Never turn a development-context fetch into an application/runtime dependency.

A repo should remain understandable when the network is unavailable. The goal is to remove duplicated Family-wide rules, not to replace useful local product context with a bare URL.

Authentication

The site and raw API are not anonymous public documentation. Cloudflare Access is the authentication boundary.

Human browser access uses the existing Family Access policy. Non-browser cloud development environments use the existing Cloudflare Access service-token route and send both:

• CF-Access-Client-Id;
• CF-Access-Client-Secret.

The operational credential setup and known Cloudflare/Claude Code caveats stay documented in docs-site-src/README.md.

Static by design

The API is produced entirely at build time. There is no:

• Worker;
• Pages Function;
• Express server;
• Docker container;
• database;
• write endpoint;
• dynamic search/vector service.

Static-site build steps and their automatic GitHub Actions validation are allowed and required for this site. The restriction is on runtime compute, not on building static output.

The source of truth remains this Git repository. To change a Family rule, change the canonical source file and review that change normally.

Verification

From the Family repo:

npm run check:docs-api

The check regenerates the static API and verifies that:

• manifest.json exactly matches the canonical resource enumeration;
• the exported file set has no missing or unexpected files;
• every raw resource is byte-for-byte identical to its source.

A normal docs-site build runs the same check before Astro builds:

cd docs-site-src
npm run build

Local MCP retirement

The local MCP currently adds no unique source of truth: its resources are the same Family files, and its tools wrap scripts already present under tools/.

Do not add new MCP consumers. Existing registrations can remain during the transition. Remove mcp-server/, its registration guidance and MCP-specific tests only after all of these are true:

1. the enhanced static API is deployed;
2. a real local agent can discover/fetch it through the Access boundary;
3. a real remote/cloud agent can do the same;
4. representative sibling repos have moved their guidance to the static API;
5. Family pointer/check tooling no longer requires the MCP wording.

Remote/hosted MCP is deliberately out of scope unless a future concrete client demonstrates a requirement that authenticated static HTTPS cannot satisfy.

Generated from docs/family-development-context-api.md + docs-site-src/scripts/raw-api-lib.mjs. Edit there and re-run npm run build in docs-site-src/ — never hand-edit a page.