docs: add reference documentation, and actually publish the site

[refeed]

Adds the reference material the site never had, and fixes the reason none of it would have been visible.

The docs explained how to write a policy but never said what you could put in one: no list of providers, no list of operation types and their arguments, no list of condition types, no CLI or exit-code reference. This adds 14 pages, and publishes the site.

Publishing was broken

deploy_docs.yml built the site and then published ./build. Docusaurus builds to ./documentation/build. So every push to main published an empty directory — which is why gh-pages contains nothing but .nojekyll and https://stackguardian.github.io/tirith/ has always returned 404.

• publish_dir → ./documentation/build
• url / baseUrl were still the create-docusaurus placeholders (your-docusaurus-site.example.com, /). A project site is served under /<projectName>/, so baseUrl must be /tirith/ or every asset and link on the deployed site resolves to the wrong path.
• npm ci rather than yarn install, in both workflows: package-lock.json is the committed lockfile and there is no yarn.lock, so yarn ignored it and re-resolved the dependency tree on every deploy.
• New build_docs.yml builds the site on pull requests. The site sets onBrokenLinks: 'throw', so one bad cross-link fails the build — previously discoverable only after merging to main.

The homepage

It was the untouched scaffold: the hero rendered the single word "Tirith", and HomepageFeatures rendered nothing at all because its FeatureList was entirely commented out. It now carries the landing-page copy, derived from README.md so there is one source of truth. All prose lives in one content object apart from the JSX, so it can be edited without reading markup. The dead component is removed.

This supersedes #274, which put the same page in docs/index.html as a standalone file — one site is better than two, and this way the reference pages are reachable from it. I will close that PR when this merges.

The new pages

Directory	Pages
tirith-usage/	cli-reference, exit-codes, ci-integration, platform-check
tirith-providers/	overview + one page per provider, each with every operation type, its arguments, and what it returns
tirith-reference/	evaluators (all 13 condition types), eval-expressions
tirith-policies/	tirith-policy-reference (field-by-field schema), tirith-policy-cookbook (6 recipes)

Every claim comes from the code, and the examples were executed rather than written from memory — 6 cookbook recipes, 11 provider policies and roughly 88 evaluator probes were run against the real CLI, and the quoted output and exit codes are what came back. The observed exit codes:

Case	Exit
Passing policy, --fail-on-error	0
Failing policy, --fail-on-error	3
Unresolved variable	1
Every check skipped	1
Failing policy, no flag	0

Existing pages fixed

tirith-policy-variables.md was actively harmful. It used {{ max_epoch }}, but the engine's pattern is {{ var.NAME }}. A reader following that page got a policy that compared against the literal placeholder string — a check that looks like it passes while measuring nothing. Its policy JSON was also invalid (missing comma) and lacked the required eval_expression. The corrected version is one that was actually run, and the quoted output is its real output.

Cross-links now point at the .md file rather than the URL. Relative URLs resolve against the page's own directory, so ../tirith-reference/evaluators from a page at /docs/tirith-providers/x/ resolved to /docs/tirith-providers/tirith-reference/evaluators. Linking by file lets Docusaurus resolve through the file graph, which also survives a slug change. 30 links rewritten.

sidebars.js is a manual sidebar, so the new pages are registered under Using Tirith, Providers and Reference. Without an entry a page builds but is unreachable.

meta.enforcement

Documented as what it is: inert in the engine, and read by the layer above it. The CLI copies it through untouched and it never affects the exit code; the GitHub Action downgrades a failing policy to a warning for soft_mandatory and friends, and blocks on anything it does not recognise. Both statements are true of different layers, and a reader needs to know which one applies to them.

Verification

npm ci && npm run build passes locally — [SUCCESS] Generated static files in "build" — and the built site was served and spot-checked: homepage and pages from all four new directories return 200.

Bugs found and deliberately not fixed here

These are code changes, and do not belong in a docs PR:

1. ExitStatus.ERROR_TIMEOUT = 2 is unreachable. A platform-run timeout raises SGError → CheckError → ExitStatus.ERROR, so it exits 1. The enum, the README and docs/platform-check.md all document 2 for a timeout and nothing can produce it.
2. The kubernetes provider crashes on a single-document YAML — core unwraps a one-document YAML to a dict, but the handler iterates it as a list, giving TypeError: string indices must be integers. Documented as a caveat.
3. Infracost sums only the first project — return total_sum sits inside the for project in ... loop in both cost functions, so later projects are never counted.
4. sg_workflow silently returns "" for an unknown workflow_attribute, so a typo evaluates an empty string instead of erroring.
5. tests/providers/sg_workflow/policy.json fails against its own input.json, and tests/providers/policy.json / wfPolicy.json use argument names and unprefixed provider names that no longer match PROVIDERS_DICT.
6. Docstrings in equals.py, not_equals.py, greater_than*.py and less_than*.py claim values are "automatically cast to the same type" — no casting occurs.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sonarqubecloud]

❌ The last analysis has failed.

See analysis details on SonarQube Cloud