Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/deploy.yml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
name: Deploy

# Build-only strict MkDocs build so a broken vendored page or nav entry
# fails CI instead of deploying. See scripts/vendor-docs.sh and rac-core's
# fails CI instead of deploying. See scripts/vendor-docs.sh and core's
# ADR-101 for the vendoring contract.

on:
Expand Down
6 changes: 3 additions & 3 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
site/

# Build-time vendored content (see rac-core's ADR-101 — never committed).
# Build-time vendored content (see core's ADR-101 — never committed).
.vendor/
docs/rac-core/*
!docs/rac-core/.gitkeep
docs/core/*
!docs/core/.gitkeep
32 changes: 16 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,28 +1,28 @@
# itsthelore.github.io
# AsDecided documentation site

The `itsthelore` org's documentation site, served at
https://itsthelore.github.io/. Built with [MkDocs](https://www.mkdocs.org)
(Material theme) — the same tool and theme `rac-core` already uses for its
own docs, so the org site and every product's docs read as one brand.
The [`asdecided`](https://github.com/asdecided) organization documentation
site, served at https://asdecided.github.io/. It uses the same MkDocs Material
foundation as the native core documentation so every product reads as one
brand.
Deployed by GitHub Actions on every push to `main`.

## How content gets here

Sections under `/rac-core/` (and future product sections) are **vendored,
Sections under `/core/` (and future product sections) are **vendored,
not authored here**: `scripts/vendor-docs.sh` sparse-checks out each source
repo's `docs/` directory into `docs/<slug>/` before `mkdocs build`. Nothing
vendored is committed — `docs/rac-core/` is gitignored. Because it lands in
vendored is committed — `docs/core/` is gitignored. Because it lands in
the same MkDocs `docs_dir` as everything else, the source repos' existing
relative links between pages (`[relationships.md](relationships.md)`, `cli.md#schema`,
etc.) resolve correctly with no rewriting.

The rationale and contract are recorded in `rac-core`'s
[ADR-101](https://github.com/itsthelore/rac-core/blob/main/rac/decisions/adr-101-org-docs-site-and-topology.md).
The rationale and contract are recorded in core's
[ADR-101](https://github.com/asdecided/core/blob/main/decisions/decisions/adr-101-org-docs-site-and-topology.md).

The site's own visual identity (light theme, Inter for prose, JetBrains
Mono for code, the lamplighter at icon size only) is recorded in `rac-core`'s
[ADR-102](https://github.com/itsthelore/rac-core/blob/main/rac/decisions/adr-102-org-site-brand-direction.md):
it deliberately *rhymes with, but does not match*, `rac-core`'s
Mono for code, the lamplighter at icon size only) is recorded in core's
[ADR-102](https://github.com/asdecided/core/blob/main/decisions/decisions/adr-102-org-site-brand-direction.md):
it deliberately *rhymes with, but does not match*, core's
`rac-localview` product-UI theme (dark, mono-everywhere) — three shared
constants (the amber accent, mono-for-code, the lamplighter), everything
else per surface. Brand assets (`docs/fonts/`,
Expand All @@ -37,13 +37,13 @@ Adding a new product section:
3. Add a card to "The ecosystem" grid in `docs/index.md`.

**The homepage hero is temporarily spec-led** (headline, CTAs, and eyebrow
all point at the rac-spec announcement essay, per an explicit "for now"
all point at the specification announcement essay, per an explicit "for now"
request) instead of the previous product pitch — see the comment at the
top of `overrides/home.html` for what to restore and why.

## Org-wide star count

The hero shows a "★ N stars across itsthelore's open-source repos" line,
The hero shows a "★ N stars across AsDecided's open-source repos" line,
sourced by `scripts/fetch-org-stats.sh` (sums `stargazers_count` across the
org's public repos via the GitHub API) and exposed to `overrides/home.html`
through `mkdocs.yml`'s `extra.total_org_stars` (an `!ENV` tag reading the
Expand All @@ -57,7 +57,7 @@ hero hides the line entirely.
`docs/essays.md` (nav label "Essays") is a **hand-curated index**, not an
auto-generated blog. An essay lives wherever it makes most sense — a spec
announcement lives inside the relevant section (e.g.
`docs/rac-spec/why-strict.md`) rather than a generic `/blog/` — and gets one
`docs/spec/why-strict.md`) rather than a generic `/blog/` — and gets one
card added to `docs/essays.md` linking to it. This is deliberate: essays
don't all belong under one directory, so there's nothing for a plugin to
auto-discover.
Expand Down Expand Up @@ -85,7 +85,7 @@ override — to add `og:*` and `twitter:*` meta tags to every page via
brand or tagline changes.
- Add a `description:` to a page's frontmatter for a tailored social
preview instead of the generic site description (see
`docs/rac-spec/why-strict.md` for an example).
`docs/spec/why-strict.md` for an example).

## Local development

Expand Down
1 change: 1 addition & 0 deletions docs/core/.gitkeep
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@

6 changes: 3 additions & 3 deletions docs/essays.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# Essays

Longer-form writing from the itsthelore team — on requirements-as-code,
Longer-form writing from the asdecided team — on requirements-as-code,
agent-grounded knowledge, and the RAC specification. An essay lives
wherever it makes most sense (a spec announcement lives with the spec's
own section; others may not), and is indexed here regardless.

<div class="lore-grid" markdown="0">
<div class="lore-card">
<p class="lore-footnote">rac-spec &middot; 2026</p>
<h3><a href="../rac-spec/why-strict/">Requirements as Code: a strict semantic layer over OKF</a></h3>
<p class="lore-footnote">AsDecided Spec &middot; 2026</p>
<h3><a href="../spec/why-strict/">Requirements as Code: a strict semantic layer over OKF</a></h3>
<p>Why RAC specifies a strict, enforced semantic layer for prescriptive
knowledge on top of OKF's deliberately permissive carrier.</p>
</div>
Expand Down
39 changes: 19 additions & 20 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,12 @@ hide:
- toc
---

RAC is the engine underneath: **Lore** keeps a team's recorded
**AsDecided** keeps a team's recorded
requirements, decisions, and designs as typed Markdown in the repo,
validates them in CI, and serves them read-only to coding agents over MCP.

```
pip install rac-core
brew install asdecided/tap/asdecided-core
```

## How it works
Expand All @@ -23,16 +23,16 @@ pip install rac-core
<p>CI rejects malformed artifacts, broken links, and references to superseded
decisions before they land.</p></div>
<div><span class="lore-step__num">03</span><h3>Serve</h3>
<p>Your agent queries Lore over MCP — four read-only tools — and cites
<p>Your agent queries AsDecided over MCP and cites
decisions by ID instead of violating them.</p></div>
</div>

> Ask your agent: *"Should I add a hard delete to the user model?"* — it calls
> Lore, finds your soft-delete decision, cites it by ID, and proposes the
> compliant change instead of reintroducing what you removed on purpose.

Serving happens over the [lore MCP server](rac-core/mcp.md); the
[`rac` CLI](rac-core/cli.md) covers validation, inspection, and ingestion.
Serving happens over the [AsDecided MCP server](core/mcp.md); the
[`decided` CLI](core/cli.md) covers validation and inspection.

## Why it's different

Expand All @@ -54,41 +54,40 @@ Serving happens over the [lore MCP server](rac-core/mcp.md); the
## The ecosystem

<div class="lore-grid" markdown="0">
<div class="lore-card"><h3>Lore (rac-core)</h3>
<p>The engine: the rac CLI, validation gates, and the read-only lore MCP
<div class="lore-card"><h3>Core</h3>
<p>The native Rust engine: the decided CLI, validation gates, and the read-only MCP
server. This is what you install.</p></div>
<div class="lore-card"><h3>Proofkeeper</h3>
<p>Turns each recorded capability into a re-runnable Playwright test,
proposed back by pull request.</p></div>
<div class="lore-card"><h3>Wayfinder</h3>
<p>Deterministic prompt-complexity routing — a hard-or-easy call on every
prompt, offline, no model call.</p></div>
<div class="lore-card"><h3>rac-sdk</h3>
<div class="lore-card"><h3>SDK</h3>
<p>Non-Python language SDKs — thin clients over the engine's stable
<code>--json</code> contracts.</p></div>
<div class="lore-card"><h3>rac-editors</h3>
<div class="lore-card"><h3>Editors</h3>
<p>IDE and editor integrations, one subdir per client.</p></div>
<div class="lore-card"><h3>rac-ci</h3>
<div class="lore-card"><h3>CI</h3>
<p>The CI delivery surface — validation and gating wrappers, GitHub
first.</p></div>
<div class="lore-card"><h3>rac-benchmarks</h3>
<div class="lore-card"><h3>Benchmarks</h3>
<p>Evaluation suites, one subdir per benchmark.</p></div>
</div>

Plus rac-connectors and everything else — see the
[full repository map](rac-core/ecosystem.md) or the
[itsthelore org on GitHub](https://github.com/itsthelore).
Plus connectors and everything else — see the
[full repository map](core/ecosystem.md) or the
[AsDecided organization on GitHub](https://github.com/asdecided).

<p class="lore-footnote">Lore is built on RAC (requirements-as-code), the
open-source engine — <code>pip install rac-core</code> installs the CLI and
the <code>lore</code> MCP server together.</p>
<p class="lore-footnote">RAC remains the stable artifact contract underneath.
<code>asdecided-core</code> installs the native CLI and MCP server together.</p>

<div class="lore-ctaband" markdown="0">
<h2>Up and running in five minutes.</h2>
<p>Install the CLI, scaffold your first artifact, connect your agent.</p>
<nav class="lore-cta">
<a class="lore-btn lore-btn--primary" href="rac-core/quickstart/">Quickstart →</a>
<a class="lore-btn" href="https://github.com/itsthelore">View on GitHub</a>
<a class="lore-btn lore-btn--primary" href="core/quickstart/">Quickstart →</a>
<a class="lore-btn" href="https://github.com/asdecided">View on GitHub</a>
</nav>
<p class="lore-footnote">Lore is open source and under active development.</p>
<p class="lore-footnote">AsDecided is open source and under active development.</p>
</div>
Empty file removed docs/rac-core/.gitkeep
Empty file.
10 changes: 5 additions & 5 deletions docs/rac-spec/why-strict.md → docs/spec/why-strict.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,12 +46,12 @@ superseded architecture decision re-introduces the exact mistake your team
already paid to rule out. The failure mode isn't degraded output; it's
confident regression, delivered with a citation.

## What rac-spec specifies
## What the AsDecided specification specifies

RAC (Requirements as Code) is the semantic layer for prescriptive
knowledge — requirements, decisions, designs — written on the same carrier
OKF standardizes. Today we're publishing rac-spec, the specification, as its
own versioned document, separate from rac-core, the reference implementation
OKF standardizes. Today we're publishing the RAC specification as its own
versioned document, separate from AsDecided Core, the reference implementation
that has been dogfooding it across 29 releases.

The spec formalizes four things the carrier layer leaves open:
Expand Down Expand Up @@ -125,7 +125,7 @@ our Python.

If you're running agents against team knowledge and you've hit the
confident-regression failure, the spec is at
[github.com/itsthelore/rac-spec](https://github.com/itsthelore/rac-spec/blob/main/SPEC.md),
the reference implementation is `pip install rac-core`, and the fastest way
[github.com/asdecided/spec](https://github.com/asdecided/spec/blob/main/SPEC.md),
the reference implementation is `brew install asdecided/tap/asdecided-core`, and the fastest way
to form an opinion is to run `rac validate` against the examples directory
and read what it rejects and why.
2 changes: 1 addition & 1 deletion docs/stylesheets/extra.css
Original file line number Diff line number Diff line change
Expand Up @@ -428,7 +428,7 @@ body,
display: none;
}

/* ---- docs polish (applies passively to vendored rac-core pages) ------- */
/* ---- docs polish (applies passively to vendored core pages) ----------- */
.md-typeset code {
background: var(--lore-bg-element);
border-radius: 4px;
Expand Down
54 changes: 27 additions & 27 deletions mkdocs.yml
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
site_name: Lore
site_name: AsDecided
site_description: >-
Requirements-as-code for AI-assisted product teams — the itsthelore
organisation's documentation site.
site_url: https://itsthelore.github.io/
repo_url: https://github.com/itsthelore
repo_name: itsthelore
Engineering decisions your agents can follow — the AsDecided documentation
site.
site_url: https://asdecided.github.io/
repo_url: https://github.com/asdecided
repo_name: asdecided

theme:
name: material
Expand All @@ -24,7 +24,7 @@ theme:
extra_css:
- stylesheets/extra.css

copyright: "© 2026 itsthelore"
copyright: "© 2026 AsDecided"

extra:
# Set by scripts/fetch-org-stats.sh via the TOTAL_ORG_STARS env var
Expand All @@ -33,15 +33,15 @@ extra:
total_org_stars: !ENV [TOTAL_ORG_STARS, 0]
social:
- icon: fontawesome/brands/github
link: https://github.com/itsthelore
link: https://github.com/asdecided

plugins:
- search

# rac-core/integration-recipes.md deliberately links to examples/ outside
# core/integration-recipes.md deliberately links to examples/ outside
# docs_dir (rendered by GitHub, not this site) — not a broken link, just one
# MkDocs can't resolve locally. Downgraded so --strict doesn't abort on
# vendored content we don't author. rac-core's own docs.yml build has the
# vendored content we don't author. Core's own docs.yml build has the
# same warning and is not currently strict-clean for it either.
validation:
links:
Expand All @@ -51,24 +51,24 @@ nav:
- Home: index.md
- Essays: essays.md
- Get started:
- Overview: rac-core/index.md
- Quickstart: rac-core/quickstart.md
- Connect your agent: rac-core/mcp.md
- Overview: core/index.md
- Quickstart: core/quickstart.md
- Connect your agent: core/mcp.md
- Guides:
- Shared Server: rac-core/shared-server.md
- Context Cost: rac-core/context-cost.md
- Watchkeeper: rac-core/watchkeeper.md
- Repository Workflow: rac-core/repo-workflow.md
- Examples: rac-core/examples.md
- Shared Server: core/shared-server.md
- Context Cost: core/context-cost.md
- Watchkeeper: core/watchkeeper.md
- Repository Workflow: core/repo-workflow.md
- Examples: core/examples.md
- Reference:
- CLI Reference: rac-core/cli.md
- Artifacts: rac-core/artifacts.md
- Relationships: rac-core/relationships.md
- Validation: rac-core/validation.md
- CLI Reference: core/cli.md
- Artifacts: core/artifacts.md
- Relationships: core/relationships.md
- Validation: core/validation.md
- Operate:
- Governance: rac-core/governance.md
- Security: rac-core/security.md
- OKF Profile: rac-core/okf-profile.md
- Governance: core/governance.md
- Security: core/security.md
- OKF Profile: core/okf-profile.md
- Project:
- Ecosystem: rac-core/ecosystem.md
- Testing & Contributing: rac-core/testing.md
- Ecosystem: core/ecosystem.md
- Testing & Contributing: core/testing.md
10 changes: 5 additions & 5 deletions overrides/home.html
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
docs/index.md and render through {{ page.content }} so they remain plain
Markdown.

TEMPORARY: hero leads with the rac-spec announcement essay rather than
TEMPORARY: hero leads with the specification announcement essay rather than
the product pitch, at the maintainer's explicit request ("for now").
The install command moved out of the hero into "How it works" in
docs/index.md; revert to the product-led hero (git history has it) once
Expand All @@ -26,14 +26,14 @@ <h1 class="lore-splash__title">A strict semantic layer over OKF.</h1>

<div class="lore-splash__actions">
<nav class="lore-cta" aria-label="Read the announcement">
<a class="lore-btn lore-btn--primary" href="{{ 'rac-spec/why-strict/' | url }}">Read the essay →</a>
<a class="lore-btn" href="https://github.com/itsthelore/rac-spec/blob/main/SPEC.md">View the spec</a>
<a class="lore-btn" href="{{ 'rac-core/quickstart/' | url }}">Get started with Lore</a>
<a class="lore-btn lore-btn--primary" href="{{ 'spec/why-strict/' | url }}">Read the essay →</a>
<a class="lore-btn" href="https://github.com/asdecided/spec/blob/main/SPEC.md">View the spec</a>
<a class="lore-btn" href="{{ 'core/quickstart/' | url }}">Get started with AsDecided</a>
</nav>

{% if config.extra.total_org_stars and config.extra.total_org_stars | int > 0 %}
<p class="lore-splash__stars">
<a href="https://github.com/itsthelore">★ {{ config.extra.total_org_stars }} stars across itsthelore's open-source repos</a>
<a href="https://github.com/asdecided">★ {{ config.extra.total_org_stars }} stars across AsDecided's open-source repos</a>
</p>
{% endif %}
</div>
Expand Down
6 changes: 3 additions & 3 deletions scripts/fetch-org-stats.sh
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
#!/usr/bin/env bash
# Sums stargazers_count across every public repo in the itsthelore org and
# Sums stargazers_count across every public repo in the AsDecided org and
# exposes it to mkdocs.yml's `extra.total_org_stars` via the TOTAL_ORG_STARS
# env var (mkdocs.yml reads it with the !ENV tag, default 0). In GitHub
# Actions, GITHUB_TOKEN gives a real count; without a token (local dev)
# this is skipped and the site falls back to hiding the stat entirely.
set -euo pipefail

ORG=itsthelore
ORG=asdecided

if [ -z "${GITHUB_TOKEN:-}" ]; then
echo "GITHUB_TOKEN not set — skipping live star fetch (site will hide the stat)." >&2
Expand All @@ -22,7 +22,7 @@ token = os.environ["GITHUB_TOKEN"]
headers = {
"Authorization": f"Bearer {token}",
"Accept": "application/vnd.github+json",
"User-Agent": "itsthelore-site-build",
"User-Agent": "asdecided-site-build",
}

total = 0
Expand Down
Loading