Wiki Conventions

Wiki conventions

This page defines how NyxOS wiki articles are written. Follow it when editing an existing page or adding a new one, so the wiki reads as one document rather than a pile of notes.

See also: Contributing, Home

Article structure

Every article follows the same skeleton:

# Title

One or two sentences stating what the subsystem is and what it does.
No marketing language.

See also: [[Related]], [[Pages]]

## Overview / Concepts        (what it is)
## Reference                  (tables: constants, fields, options)
## Procedures                 (how to do things)
## Troubleshooting            (symptom → cause → fix)
## See also
## External resources         (specs, RFCs, upstream docs)

Reference pages may omit Procedures; HOWTO pages may omit Reference. Every page carries the See also line near the top and a See also section at the bottom.

Prompts

NyxOS has two shells and the host has one. Which prompt appears tells you where a command runs.

Prompt	Where
host $	Your development machine (Linux, WSL, or PowerShell)
nyx>	The NyxOS kernel shell — serial console or GUI terminal
sh$	The NyxOS userspace shell, /sh.elf

Never paste the prompt itself when copying a command.

Code blocks

Every non-trivial block gets a caption line stating what it is, in bold, immediately above it. This is the closest GitHub-flavored Markdown gets to Gentoo's CODE/FILE templates.

CODE — Building the kernel

host $ make -C kernel

FILE — kernel/Makefile (excerpt)

CFLAGS = -std=gnu99 -ffreestanding -Os -Wall -Wextra

Rules:

• Use bash for host commands, c for C, make for makefiles, asm for assembly, and no language tag for terminal output or NyxOS shell sessions.
• Show real output. If output is trimmed, say so with […].
• If a transcript came from a specific build, state which one in the caption.

Admonitions

Use GitHub alert syntax. Do not invent other kinds.

Note

Neutral information the reader may not know. Use sparingly — most facts belong in body text.

Tip

A shortcut or a better way of doing the thing just described.

Important

Something the reader must do, or the procedure will not work.

Warning

Something that can lose data, corrupt a disk image, or wedge the machine.

Caution

A security consequence.

Tables

Tables are the default form for reference material. Every constant, field, flag, option and error code belongs in a table with its value and its meaning, not in prose.

Escape a literal pipe inside a table cell as \|.

Facts and verification

• Every constant, path, syscall number and default stated in this wiki must be checkable against the source tree. Cite the file, e.g. MAX_INODES (kernel/fs/vfs.c).
• When a number changes in the source, the wiki is wrong until it is updated. AGENTS.md makes this a commit requirement — see Contributing.
• Do not document intentions. If a feature is planned but not implemented, either omit it or put it under an explicit Known limits heading.
• Prefer stating a limitation plainly over implying completeness.

Voice

• Present tense, active voice. "The scheduler picks the next task", not "the next task will be picked".
• No exclamation marks, no "simply", no "just", no "obviously".
• Bugs are worth documenting when they explain why the code looks the way it does. The wiki keeps several of these deliberately.
• British or American spelling is acceptable; be consistent within a page.

Page naming

GitHub Wiki maps a page title to a filename by replacing spaces with hyphens. [[Boot Process]] resolves to Boot-Process.md.

• Titles are sentence case: Memory management, not Memory Management, except where the existing page set already uses title case — match the neighbours.
• HOWTO pages are named HOWTO <task>, e.g. [[HOWTO Add a system call]].
• Every new page must be added to _Sidebar.md, or it will be unreachable.

Linking

• Link the first mention of another subsystem in a section, not every mention.
• The link target must be the literal filename (hyphenated), not the spaced title. Write [[Boot-Process|Boot Process]], never [[Boot Process]]. GitHub Wiki resolves both forms identically (it replaces spaces with hyphens itself), but this wiki also doubles as an Obsidian vault (see Obsidian vault below), and Obsidian resolves [[...]] by exact filename — it does not do the space-to-hyphen substitution GitHub does. A link typed as [[Boot Process]] renders fine on GitHub but shows as an unresolved, unlinked node in Obsidian, breaking the graph and backlinks.
• Single-word titles need no pipe — [[Home]], [[FAQ]], [[SMP]] already match their filename exactly.
• Use the pipe purely to keep the display text human-readable; never to change what the link points to.
• External links go in the External resources section as a list, with the publisher named.

Obsidian vault

This wiki's root is an Obsidian vault — .obsidian/ lives at the top level, not in a subfolder. Anyone maintaining the wiki can open this folder directly in Obsidian and get a working graph view, backlinks, and outgoing-links panel over the exact same 40-odd files that render as the public GitHub wiki. No converted copy, no separate "brain" folder — one set of files, two renderers.

Tracked (versioned)	Untracked (local, in .gitignore)
.obsidian/app.json, appearance.json, core-plugins.json, graph.json	.obsidian/workspace.json, workspace-mobile.json, cache

The tracked files are the reproducible "IDE setup" — which core plugins are on, and the graph's colour groups (see below). The untracked files are pure session state (open tabs, pane widths) that would otherwise generate merge noise with no informational value.

Graph colour groups

graph.json groups nodes by filename pattern, matching the categories in Index: Kernel core, Storage and network, Graphics and apps, Userspace, HOWTO, Reference, Project/meta. A page added to a new category should get a matching path:"…" clause added to the relevant colorGroups entry — this is a config change, not a content change, so it never touches the rendered wiki.

Why this works without touching page content

The obvious alternative — YAML frontmatter with aliases: on every page, which is Obsidian's native mechanism for this — was deliberately rejected: GitHub does not special-case frontmatter on wiki pages the way Jekyll does on GitHub Pages, so a ---\naliases: [...]\n--- block would render as a literal, visible block at the top of every page on the actual published wiki. Rewriting link targets to the real filename achieves the same resolution with zero visual cost on GitHub.

The three layers

This wiki is maintained as an LLM wiki, not a one-shot dump: sources are read once, integrated, and the wiki compounds — it is not re-derived from scratch on every question. Three layers:

Layer	What	Owner
Raw sources	The nyx-os git repository — kernel/, user/, AGENTS.md (the authoritative release table), commit history, README.md, SECURITY.md	Immutable. The wiki reads from it, never edits it
The wiki	This repository — every .md file	Owned entirely by whoever (human or LLM) is maintaining it. Written to be read, not written by the reader
The schema	This page	Co-evolves with the wiki; update it when a convention proves wrong

AGENTS.md is the fixed point: its release table is more current and more authoritative than any wiki page, by construction — the wiki is a reader-facing summary of it (see Version-History), never the other way round.

Operations

Ingest

Triggered by a new release landing in AGENTS.md, a batch of commits, or a direct read of source you haven't covered yet.

1. Read the new material — the AGENTS.md row(s), the diff, or the file directly.
2. Identify every wiki page the change touches. A single release commonly touches 3–10 pages: the subsystem page, Version-History, Command-Reference or Syscall-Reference if the surface changed, and any page that states a now-stale count (syscall total, page count, capacity limit).
3. Update each page. Prefer extracting facts programmatically (grep/regex over the source, ELF/header parsing) over hand-transcribing — every reference page in this wiki was built that way, and it is what keeps a 1000-line table like Syscall-Reference actually correct.
4. Update Index if a page was added, removed, or its one-line summary changed.
5. Append an entry to Log.

Tip

When a fast-moving source outpaces you mid-ingest — this happened once already, v5.9.86 → v5.9.91 mid-pass — finish the current page, then sweep every page for the old version string before logging. Don't silently ingest half a release.

Query

You ask a question; the wiki gets searched (start from Index), relevant pages get read, and an answer gets synthesized with the underlying facts re-derived from source where the wiki doesn't already state them (parsing an ELF header, reading a struct definition, checking a Makefile rule).

A good answer gets filed back. A comparison, a derived fact, a contract spelled out for an external reader (see the "Boot protocol contract" section of Boot-Process, or the "Supported hardware" note in Networking-Stack) — these are exactly as valuable as ingested source material and should not disappear into chat history. File them as a new section on the most relevant existing page, or a new page if nothing fits, then log the query in Log.

Not every query needs filing — a one-off clarification that repeats what's already on a page doesn't need a new section. File it when the answer required real synthesis (reading multiple files, deriving a value not already in the wiki) or when the question is one a future reader will plausibly ask again.

Lint

Periodically, health-check the wiki:

Check	How
Broken [[links]]	A page reference with no matching filename (see the validator pattern below)
Orphan pages	A page nothing links to — check against Index and _Sidebar.md
Stale version references	grep -rn "v5\.9\.[0-9]*" across the wiki, compare to KERNEL_VERSION in kernel/core/kernel.h
Contradictions	Two pages stating different values for the same constant
Missing cross-references	A concept explained on one page, mentioned but not linked on another
Structural gaps	A page missing See also / External resources (every page must carry both — see Article structure above)

CODE — Link and structure validator (run from the wiki root; strips code blocks so example [[links]] in HOWTO pages don't false-positive)

host $ python3 -c "
import re, os, glob
pages = {os.path.splitext(os.path.basename(f))[0] for f in glob.glob('*.md')}
def strip(t):
    t = re.sub(r'\`\`\`.*?\`\`\`', '', t, flags=re.S)
    return re.sub(r'\`[^\`]*\`', '', t)
bad, targets = [], set()
for f in sorted(glob.glob('*.md')):
    for m in re.finditer(r'\[\[([^\]]+)\]\]', strip(open(f, encoding='utf-8').read())):
        # target is before any '|' alias and any '#' anchor; must be the exact
        # filename (no space-to-hyphen normalisation) so this also validates
        # Obsidian's resolution rule, not just GitHub's — see Linking, above.
        fn = m.group(1).split('|')[0].split('#')[0]; targets.add(fn)
        if fn not in pages: bad.append((f, m.group(1)))
print('PAGES:', len(pages), ' BROKEN:', len(bad),
      ' ORPHANS:', sorted(pages - targets - {'_Sidebar', '_Footer', 'Home'}))
"

Log a lint pass in Log even when it finds nothing — an absence of findings on a given date is itself useful information later.

Index.md and Log.md

Two files exist purely to help navigation at scale; neither is a subsystem page and neither should describe NyxOS itself.

File	Purpose	Ordering	Updated
Index	Content catalog — every page, one line, grouped by category	By category, not time	Every ingest that adds/removes/retitles a page
Log	Chronological record of what happened to the wiki	Append-only, oldest first	Every ingest, query-filed-back, and lint pass

Log.md entries start with a fixed, grep-friendly prefix: ## [YYYY-MM-DD] type | subject, where type is ingest, query, or lint. This is what makes grep "^## \[" Log.md | tail -5 work. Never edit a past entry except to correct a factual error in it — it is a history, not a draft.

Checklist before committing

• Every stated fact checked against the source tree
• Page added to _Sidebar.md if new
• Page added to Index if new, or its summary updated if its scope changed
• Entry appended to Log — ingest, query, or lint
• All [[links]] target the exact hyphenated filename (Obsidian-resolvable, not just GitHub-resolvable)
• Code blocks have captions and language tags
• See also present at top and bottom
• README, docs/ and AGENTS.md updated if the change affects them

See also

• Index — the content catalog this schema keeps current
• Log — the maintenance history this schema requires
• Contributing — development workflow and the commit rule
• Home — wiki landing page

External resources

• GitHub Flavored Markdown spec — GitHub
• Alerts syntax — GitHub Docs