Aura Knowledge

A focused GitHub Pages knowledge garden for human-readable essays and agent-auditable research artifacts.

The site is designed around one publishing rule: every public article has a sibling agent brief, structured artifact, generated discovery feed, and graph entry.

Structure

content/articles/<year>/<slug>/
  article.md          # canonical human article source
  agent.md            # compact agent brief
  artifact.json       # claims, sources, relations, review state, hash

content/roadmap/
  *.json              # schema-validated public roadmap artifacts

public/
  agents/index.json   # generated discovery index
  agents/index.jsonl  # generated compact feed
  agents/articles/    # generated per-article packets
  agents/roadmap/     # generated roadmap packets
  graph/              # generated graph nodes/edges
  llms.txt            # generated LLM entry map

src/
  pages/              # Astro pages
  components/         # reusable UI
  styles/             # global design tokens and layouts

Commands

npm install
npm run dev
npm run generate
npm run validate
npm run build
npm run check

npm run check regenerates agent artifacts, validates source content and generated files, then builds the static site.

Publishing Workflow

Work must happen on feature branches and worktrees, not directly on main.

git worktree add ../.worktrees/aura-knowledge-<topic> -b feature/<topic> main
cd ../.worktrees/aura-knowledge-<topic>
npm install
npm run check

Before committing, install local hooks:

./scripts/install-hooks.sh

Remote main should be protected with required checks, conversation resolution, linear history, and no bypass.

GitHub Pages

The intended remote is aura-knowledge/aura-knowledge.github.io.

Once the repository exists on GitHub:

1. Push this branch.
2. Open a pull request.
3. Configure Pages source as GitHub Actions.
4. Protect main using the settings in CONTRIBUTING.md.
5. Merge through the PR after checks pass.

The site is configured for https://aura-knowledge.github.io/.

If gh is authenticated, the repo bootstrap can be automated:

./scripts/bootstrap-github.sh

The script creates aura-knowledge/aura-knowledge.github.io as a public repository if it is missing, sets origin, pushes main and feature/knowledge-garden-foundation, and opens a draft pull request.