Conventions

中文 | English

Link Rules

• Prefer relative links for in-repo navigation.
• If a local target contains spaces, wrap it in angle brackets:

[Raw file](<../../raw/File Name With Spaces.md>)

This avoids broken clicks in Obsidian and other markdown renderers.

Git Rules

This knowledge base root is itself a git repository.

Rules:

• If the vault is not initialized as git, bootstrap should run git init
• Any material ingest / query write-back / lint change should be committed
• Commits should explain why the knowledge base changed, not just which files changed

Remote Strategy

This repo uses two remotes:

• origin GitHub, the source of truth
• gitlab Internal mirror

Required flow:

1. Before starting material work, check whether origin has newer commits.
2. If origin/master is ahead, sync local master from origin/master.
3. After any local commit, push to both origin and gitlab.

If the remotes diverge, prefer origin unless explicitly told otherwise.

Current ignore rules:

• .obsidian/
• .omx/
• __pycache__/

Raw Media Layout

Recommended conventions as the corpus grows:

• keep standalone screenshot sources under raw/screenshots/
• keep attachment-style image assets referenced from markdown sources under raw/assets/
• prefer ingesting screenshot meaning into wiki/sources/ instead of duplicating interpretation in filenames
• use .codex/skills/llm-wiki/scripts/extract_visual_sources.py before integrating screenshot-heavy sources

Raw Markdown Hygiene

When a raw markdown file causes bad rendering or fails the local VitePress build, fix the markdown syntax without changing the source substance.

Typical allowed repairs:

• convert accidental escaped-backtick prose such as \foo`` into real inline code when the intent is clearly a code span
• escape literal angle-bracket placeholders such as <name here> or keep them inside inline code so Vue-style renderers do not parse them as HTML
• replace transient browser-only embeds such as blob: media URLs with stable screenshots or ordinary links
• remove or repair malformed inline links, unmatched HTML tags, and other renderer-breaking markdown damage

Prefer the smallest edit that restores renderability while preserving the original claim or example.

Taxonomy Refactors

As the wiki and raw corpus grow, directory structure is allowed to evolve.

Rules:

• split oversized folders when they stop being navigable
• for wiki/, move pages instead of copying them
• for raw/, preserve source substance and limit edits to path-dependent links or metadata
• repair all affected links in the same pass
• update index.md, index.zh.md, and any overview/navigation pages that expose the moved pages

Use:

python3 .codex/skills/llm-wiki/scripts/move_markdown_pages.py --repo . --move wiki/topics/foo.md:wiki/topics/sub/foo.md

For raw refactors use:

python3 .codex/skills/llm-wiki/scripts/move_raw_sources.py --repo . --move raw/foo.md:raw/articles/foo.md

Log Rules

log.md is an operational record, not a repository changelog.

It currently has four strict rules:

1. Minute precision

## [YYYY-MM-DD HH:MM] ingest | Source Title

2. Reverse chronological order

• newest entries first
• not append-only at the bottom

3. Operation-only headings

• use only ingest, query, or lint
• do not use feat, fix, refactor, bootstrap, or release-note style headings

4. Material vault changes only

• write a log entry only when the durable vault state changed
• scheduled patrols that do no work should not touch log.md
• code-only or config-only changes belong in git history, not in log.md

Older historical entries should not be backfilled with invented minute values.

Where Design Philosophy Lives

This is no longer duplicated in README. It lives in the canonical wiki pages:

• LLM Wiki
• Knowledge Operations
• Vault Architecture