[mmcky]

Builds the three pieces planned to land together: a web page for each model description (#12), a version for each description that solutions cite (#13), and the AI-disclosure and human-verification record on descriptions and solutions (#14). It also reorganises submitted solutions by model, so that individuals as well as toolkit projects can submit, and one project can submit several.

Closes #12. Closes #13.

What this adds

Piece	Where
Web page per model description	tools/build_pages.py renders each models/<model>/model-description.md into docs/models/<model>/index.html, with the PDF beside it, in the site's header, footer and styles. MathJax 3.2.2 renders the equations, the same renderer GitHub uses. The publishing workflow builds the pages, so they are not committed.
Version box	The PDF (top right of page 1) and the web page show the version, status, date, AI level and verification. The title now starts below the box, so a long title cannot run into it.
Versioning	MAJOR.MINOR in the front matter's options, models/buffer-stock/CHANGELOG.md, and the rules and release steps in a new CONTRIBUTING.md.
AI disclosure and verification	Four categories, recorded as ai_level 0 to 3 and shown by name: No AI, AI-edited, AI-assisted (AI drafted some or most of it; people edited it throughout) and AI-generated. CONTRIBUTING.md defines them, with the rules, the used_for list and what "human verified" means. Slots show the word in a neutral chip; the version box adds a marker on a line from Human to AI and a one-line summary. Verification is a solid blue label once the current version is verified and a dashed grey one until then.
Solutions layout	Solutions live in solutions/<model>/<NNN>-<toolkit>-<method>/. The number is the next free one among the model's solutions and makes every name unique; the rest is a label for browsing, and metadata.yml is the record. The HARK solution moves from projects/HARK/buffer-stock/ to solutions/buffer-stock/001-hark-egm/, at the same depth, so its relative links still work.
Required metadata.yml	schemas/solution-metadata.schema.json defines the required fields: toolkit, method, authors, maintainers (the GitHub users who approve changes), model_description_version, ai_level, and ai_used_for when the level is above 0. project is added for a solution submitted on behalf of a toolkit's project, and the verification fields once someone verifies.
Checks	tools/check_metadata.py runs in the publishing workflow. It validates every metadata.yml, enforces the directory names and unique numbers, checks each description's version against its changelog and status, and checks that the library table has a slot for each solution, labelled and showing what its metadata records. The link and anchor checks now cover pages in subdirectories.
Library table	Each model's name now carries a blue "Model description · v0.1 draft" button to its page, with "Download PDF" beside it, or "Model description planned"; the right-hand description column goes. The HARK slot reads "HARK · EGM · Econ-ARK · v0.1" (toolkit, method, submitter, version) with the level's segments. Slots run down a column at the right, filled first and open below, and the column moves under the model's name when the table is narrow. Slots show the AI category's word in a neutral chip, and a verified solution's slot, or a verified description's button, carries a "✓ Verified" badge.
Authorship wording	The README, the site and CONTRIBUTING.md now say that each solution is authored and maintained by its submitters, whether a toolkit's project or individual contributors, and that changes to it need its maintainers' approval.
HARK notebook	It refreshes only the run's software and numerical settings in metadata.yml, keeps what people record there, and saves nothing when run from another directory. Its long description of the method is now method_details, so method holds the short name.

Departures from the issues

• Flat field names. Disclose AI assistance and record human verification #14 named the fields ai.level, verified.by and so on. MyST passes the description's values to the PDF template only as flat options (string, number, choice), so the fields are ai_level, ai_used_for, verified_by, verified_date and verified_version. Solutions use the same names, so the two still match.
• Verification is three fields, added together. Instead of a required verified field, a solution leaves the three verified_ fields out until someone verifies it, and the checker requires all three together. The page, the box and the slot then say "not yet verified".
• No CODEOWNERS file. GitHub ignores a CODEOWNERS entry for anyone without write access to the repository. @akshayshanker has read access, and most individual submitters will have none, so a generated CODEOWNERS would request no reviews. maintainers records who approves changes; enforcing that approval is left for a later check or a decision about access.
• Disclose AI assistance and record human verification #14 stays open for its later step, the "Submit an implementation" issue form.

Checks

• The workflow's steps, run locally, all pass: build the pages, check versions and disclosure, check local references, check anchors, check the contents rail.
• tools/check_metadata.py fails on each of 20 deliberate breakages. These include a category out of range, a slot showing the wrong category, a missing method or maintainers, an invalid GitHub username, an unnumbered directory, a reused number, a second solution without a slot, a slot whose label, level or verification disagrees with metadata.yml, a new version without a changelog entry, and a 0.x version marked released.
• All 81 equations typeset without errors in MathJax 3.2.2 and in headless Chrome. The page and the library table fit at 390px width.
• The PDF rebuilds at 4 pages.
• The HARK notebook re-runs from a fresh kernel (Python 3.12.7, HARK 0.17.1) with its outputs and results unchanged, and run from another directory it saves nothing. The 16 tests pass from the solution's directory and from the repository root.

Before merge

• Confirm the AI categories. The buffer-stock description and the HARK solution both propose AI-assisted (ai_level: 2): the description lists drafting and editing, HARK adds code. These are self-reports for their authors, @akshayshanker and @mmcky, to confirm or correct.
• Confirm the HARK solution's project and maintainers. It proposes project: Econ-ARK, which labels its slot, and maintainers: [akshayshanker].
• Verification. Neither is verified yet. Once someone has read either end to end, add the three verified_ fields and update the slot's data-verified; the check enforces both.

After merge

• Tag the merge commit buffer-stock/v0.1 and publish a GitHub release with model-description.pdf attached. HARK's model_description link points at that tag.

🤖 Generated with Claude Code

[Copilot]

🔵 Needs a closer look

It spans CI, a new build/validation pipeline, LaTeX templating and a schema whose end-to-end rendering (MyST/LaTeX/MathJax) can't be fully verified here, and the PR itself states AI-level and verification values must be confirmed by humans before merge.

No open issues 🎉

What changed in this PR

This PR lands three planned features together (#12 web page per model description, #13 versioning, #14 AI disclosure/verification). It adds a lightweight Python build step (tools/build_pages.py) that renders each models/<model>/model-description.md into docs/models/<model>/index.html with MathJax, a metadata validator (tools/check_metadata.py) wired into the publish workflow, a JSON Schema for a now-required per-implementation metadata.yml, a PDF/web "version box" showing version, status, AI level and verification, and a root CONTRIBUTING.md documenting the rules.

Changes:

• New site tooling: build_pages.py, check_metadata.py, model-page.html, requirements.txt; publish workflow builds pages and runs checks, extended to subdirectory link/anchor validation.
• Versioning + AI disclosure surfaced in the PDF template, the generated web page, and the library table; flat option field names (ai_level, ai_used_for, verified_*).
• Docs, HARK notebook/metadata, README and model README updated so each implementation carries a validated metadata.yml.

File	Description
tools/​build_pages.py	Renders model-description Markdown to HTML with the version box.
tools/​check_metadata.py	Validates descriptions, metadata.yml and the library table.
tools/​model-page.html	Page template; placeholders all mapped by build_pages.
tools/​requirements.txt	Pins build/check dependencies.
templates/​plain_latex_wide/​template.tex,.yml	Adds PDF version box options/rendering.
schemas/​implementation-metadata.schema.json	Defines required metadata fields and conditional rules.
.github/​workflows/​publish.yml	Adds build + metadata-check steps; extends ref/anchor checks to subdirs.
docs/​site.css, docs/​index.html	Styles/markup for AI-level and verification indicators and doc pages.
CONTRIBUTING.md, README.md, models/​buffer-stock/​* , projects/​HARK/​buffer-stock/​*	Documents the scheme; HARK metadata/notebook updated; new CHANGELOG.
.gitignore	Ignores generated docs/models/.

I did not find concrete defects to flag: placeholder/variable/package dependencies resolve, the checker regex matches the changelog, the HTML table parser balances correctly for the current slots, and the extended CI reference/anchor checks resolve the generated pages.

_{Review effort: Balanced}

[akshayshanker]

This is awesome. I am going to merge this in .

[mmcky]

@akshayshanker you have write access now. I'll merge but if you verify the AI level settings are inline with what you did that would be great.