Skip to content

Pillar-first content structure and document intake - #5

Merged
WDrijver merged 2 commits into
mainfrom
content-structure
Nov 2, 2026
Merged

WDrijver merged 2 commits into
mainfrom
content-structure

Conversation

@WDrijver

@WDrijver WDrijver commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Creates the content folder structure (Git doesn't track empty folders) and reorganizes it around the three pillars.

Pillar-first layout

  • core/, os/ and toolchain/ each have reference files plus their own best-practices/ and pitfalls/. guides/, examples/, conventions/ and lessons/ stay top-level, because their content cuts across the pillars.
  • core/ gets an index.md per CPU/chip folder (cpu-68080, saga-video-isabelle, saga-audio-arne, saga-dma-anni, saga-3d-maggie) with:
    • the folder's scope;
    • suggested files;
    • an explicit "no content yet" note, so agents report gaps instead of guessing.
  • CI (kblib.expected_type) derives the expected type from the path: <pillar>/best-practices/ → best-practice, <pillar>/pitfalls/ → pitfall, other pillar files → reference.

OS best practices and pitfalls

os/best-practices/ and os/pitfalls/ are allowed. Excluded: anything that works on AmigaOS but fails on ApolloOS. That's an ApolloOS bug and goes to an issue in ApolloOS.R10. Takeover entry/exit knowledge goes in os/, and hardware programming during a takeover goes in core/.

Document intake (maintainers only)

CONTRIBUTING.md section 11 describes how official Apollo documents enter the knowledge base:

  • The original goes in sources/official/ (ODT preferred) and is leading: updates go through intake again, and generated files are never edited by hand.
  • Each generated file gets origin: official (new value), a maintainer as owner, and generated_from: sources/official/<file>.
  • CI checks:
    • an official file's owner is a maintainer (read from the * line in CODEOWNERS.base);
    • generated_from requires origin: official, points into sources/official/, and the file exists.
  • AGENTS.md tells agents to treat official files as authoritative and never to edit generated files.
  • The section lists the "optimized for AI" format rules.

sources/ is excluded from content checks and owned by the maintainers.

🤖 Generated with Claude Code

Add an index.md to each core/ folder (CPU and the four SAGA chips) stating
its scope, planned files and that it has no content yet, and .gitkeep
files for the other planned folders so they exist in Git.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@WDrijver
WDrijver requested a review from TuKo1982 as a code owner November 2, 2026 12:40
- best-practices/ and pitfalls/ move under each pillar: core/, os/,
  toolchain/. CI derives the expected type from the path.
- os/best-practices/ and os/pitfalls/ are allowed. Only 'works on AmigaOS,
  fails on ApolloOS' is excluded: that is an ApolloOS.R10 issue.
- Document intake for official Apollo documents (maintainers only): the
  original in sources/official/ is leading, generated files carry
  origin: official and generated_from, CI checks maintainer ownership.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@WDrijver WDrijver changed the title Create the planned content folder structure Pillar-first content structure and document intake Nov 2, 2026
@WDrijver
WDrijver merged commit 833e0d7 into main Nov 2, 2026
2 checks passed
@WDrijver
WDrijver deleted the content-structure branch November 2, 2026 13:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant