new

AGENTS.md

@@ -40,3 +40,9 @@ If `dist/markdown/` is not available locally, the specification
 - Do NOT modify the RST source under `src/`.
 - Changes to this specification MUST be made upstream in the vendor
   repository.
+
+## Maintaining This Repository
+
+If you are explicitly invoked to maintain this specification repository
+(building, publishing, or managing URLs), see `CONTRIBUTING.md` for
+instructions.

CONTRIBUTING.md

@@ -0,0 +1,100 @@
+# Contributing to the MIME TODO Specification
+
+This document covers how to maintain the MIME TODO specification repository:
+building, deploying, and managing URLs.
+
+---
+
+## Prerequisites
+
+All build and publish commands run inside a pipenv environment. Install
+dependencies first:
+
+```sh
+pipenv install
+```
+
+---
+
+## Building
+
+### HTML
+
+```sh
+pipenv run make build/html
+```
+
+Output: `build/html/`
+
+### Markdown (agent-consumable)
+
+```sh
+pipenv run make dist/markdown
+```
+
+Output: `dist/markdown/`
+
+### Both + publish
+
+```sh
+pipenv run make all
+```
+
+---
+
+## Publishing
+
+The specification is served from `specs.code.tiararodney.com`. The `publish`
+Makefile recipe deploys both `build/html` and `dist/markdown` via rsync:
+
+```sh
+pipenv run make publish
+```
+
+This uploads to:
+
+```
+root@tiararodney.com:/root/webserver/srv/http/spec.tiararodney.com/mime-todo
+```
+
+The resulting web structure is:
+
+```
+https://specs.code.tiararodney.com/mime-todo/
+├── html/          ← HTML output
+└── markdown/      ← Markdown output (agent-consumable)
+    ├── README.md  ← The specification
+    └── AGENTS.md  ← Agent consumption instructions
+```
+
+---
+
+## URL Management
+
+The following files contain URLs pointing to the web server. If the server
+address, path structure, or spec name changes, update these:
+
+- `AGENTS.md` — the "Consuming the Specification" section lists direct URLs
+
+If this spec is bundled inside another spec (e.g., tiara-gitflow-spec), that
+parent spec's `AGENTS.md` and `CONTRIBUTING.md` will also reference these
+URLs and must be updated accordingly.
+
+---
+
+## Release Process
+
+1. Make changes to `src/README.rst`
+2. Build: `pipenv run make build/html dist/markdown`
+3. Review the output
+4. Commit the source changes and the built `dist/markdown/` output
+5. Publish: `pipenv run make publish`
+
+---
+
+## Rules
+
+- Do NOT modify this spec inside a consuming repository. Changes MUST be
+  made upstream in this repository.
+- The `dist/markdown/` directory is committed so that consuming repositories
+  have access to the agent-consumable output without needing to build.

Makefile

@@ -13,4 +13,4 @@ publish:
 
 
 clean:
-	rm -rv build
+	rm -rv build dist

dist/markdown/AGENTS.md

@@ -16,8 +16,11 @@ access. Do NOT parse the RST source under `src/` directly.
 
 If `dist/markdown/` is not available locally, the specification
 (including this `AGENTS.md`) can be retrieved from
-`specs.code.tiararodney.com`, which provides HTML indexes that can be
-traversed to locate the applicable markdown files.
+`specs.code.tiararodney.com`:
+
+- Specification: `https://specs.code.tiararodney.com/mime-todo/markdown/README.md`
+- Agent instructions: `https://specs.code.tiararodney.com/mime-todo/markdown/AGENTS.md`
+- Index: `https://specs.code.tiararodney.com/mime-todo/markdown/`
 
 ## What This Spec Defines
 
@@ -37,3 +40,9 @@ traversed to locate the applicable markdown files.
 - Do NOT modify the RST source under `src/`.
 - Changes to this specification MUST be made upstream in the vendor
   repository.
+
+## Maintaining This Repository
+
+If you are explicitly invoked to maintain this specification repository
+(building, publishing, or managing URLs), see `CONTRIBUTING.md` for
+instructions.