gaia-post

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

# Announcement
python scripts/add_post.py announcement "Title" "Short summary." [--label "Release"] [--date YYYY-MM-DD]

# External link
python scripts/add_post.py link "Title" "Short summary." --url https://... [--label "Link"] [--date YYYY-MM-DD]

# Meta report (renders HTML from a Markdown source file)
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:

1. Parse the frontmatter and Markdown body.
2. Render docs/meta/reports/YYYY-MM-DD-slug.html using the embedded LaTeX-style academic template.
3. Prepend the new post to docs/meta/posts.json.
4. Patch the <!-- gaia-posts-start / end --> zone in docs/index.html (up to 3 most recent posts shown).
5. 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"