| name | gaia-post |
| description | Publish a new post (announcement, link, or LaTeX-style meta report) to the Gaia site. Use when you want to add any update to the registry's public feed and landing page. |
Gaia Post
Publish a post to the Gaia registry site. Posts appear in the path-meta-queue on the landing page and, for reports, also update the hero notification badge. All post data is tracked in docs/meta/posts.json (newest-first) and docs/index.html is patched programmatically — no hand-editing HTML.
Post Types
| Type | When to use | Requires |
|---|
announcement | Registry news, version releases, policy changes | title, summary |
link | External article, RFC, or resource worth surfacing | title, summary, --url |
report | Formal audit or meta-shift (LaTeX-style HTML rendered from Markdown) | title, summary, --source |
Usage
python scripts/add_post.py announcement "Title" "Short summary." [--label "Release"] [--date YYYY-MM-DD]
python scripts/add_post.py link "Title" "Short summary." --url https://... [--label "Link"] [--date YYYY-MM-DD]
python scripts/add_post.py report "Title" "Short summary." \
--source docs/meta/MY_REPORT.md \
[--author "Name, Role"] \
[--label "Audit"] \
[--date YYYY-MM-DD] \
[--chart reports/YYYY-MM-DD-chart-data.json] \
[--hero | --no-hero]
--hero / --no-hero: controls whether the floating hero notification badge in the landing page is updated to point to this post. Defaults to yes for report type, no for others.
Step-by-Step: Adding a Meta Report
Step 1 — Write the Markdown source
Create docs/meta/YYYY-MM-TITLE.md. Use YAML frontmatter for metadata the script needs:
---
title: "Registry Audit Report: Descriptive Title"
author: "Marcus Rafael Tiongson, Auditor"
summary: One sentence for the queue card.
abstract: |
Optional longer abstract paragraph. If omitted, `summary` is used.
label: Latest Audit
---
## Abstract
Extended abstract text (rendered in the paper body as an indented italic block).
## Executive Summary
Paragraph text here.
### Sub-section
More detail.
## Findings
Tables and lists work:
| Column A | Column B |
|----------|----------|
| value | value |
- Bullet one
- Bullet two
## References
[1] Author. (Year). *Title*. Publisher.
[2] Another reference.
Supported inline Markdown: **bold**, *italic*, `code`, [text](url), fenced code blocks.
Step 2 — Run the script
python scripts/add_post.py report "Title" "Queue summary." \
--source docs/meta/YYYY-MM-TITLE.md
The script will:
- Parse the frontmatter and Markdown body.
- Render
docs/meta/reports/YYYY-MM-DD-slug.html using the embedded LaTeX-style academic template.
- Prepend the new post to
docs/meta/posts.json.
- Patch the
<!-- gaia-posts-start / end --> zone in docs/index.html (up to 3 most recent posts shown).
- Patch the
<!-- gaia-hero-post-start / end --> zone (hero badge) to point to the new report.
Step 3 — (Optional) Add Chart.js timeline data
If you have a JSON data file for a timeline chart, pass it:
python scripts/add_post.py report "Title" "Summary." \
--source docs/meta/MY_REPORT.md \
--chart reports/my-chart-data.json
The JSON format mirrors may-2026-timeline.json:
{
"labels": ["2026-05-01", "2026-05-15", "2026-05-25"],
"datasets": [
{ "label": "1★", "color": "#94a3b8", "data": [40, 45, 50] },
{ "label": "6★", "color": "#f59e0b", "data": [1, 1, 1] }
]
}
Step 4 — Commit
git add docs/meta/posts.json docs/meta/reports/ docs/index.html
git commit -m "post: add <type> — <title> [skip-gen]"
Constraints
- Use
Gaia Research as the default report author unless the user explicitly requests a different byline.
- Avoid banned vocabulary from
CONTEXT.md (apex tier, Atomic Basics, card, etc.).
- All section headings in report Markdown should use
## (rendered with auto-numbered LaTeX counter). Use ### for subsections.
- The
## Abstract section in the Markdown body is rendered as the indented italic abstract block in the paper; do not repeat it under a different heading.
- The
## References section receives special .ref-item treatment — each [N] ... line becomes a hanging-indent reference entry.
- Chart data files live in
docs/meta/reports/ alongside their HTML output.
Example
python scripts/add_post.py report \
"June 2026 Integrity Audit" \
"DAG validation and evidence liveness sweep across 220 skills." \
--source docs/meta/JUN_2026_AUDIT.md \
--label "Audit" \
--author "Marcus Rafael Tiongson, Auditor"