Docs/promote landing pages

[Akshat0694]

Pull Request Template

Description

• What changes are being made?

  • Promotes the landing-page prototype to the published site. The pages built in
    tirith-internal under documentation/new-landing-page/ become documentation/
    itself. Only documentation/ is built by deploy_docs.yml, so this is what makes
    them the published site rather than a preview nothing runs. Five routes replace one:
    / (landing), /learn/ (six lessons and a browser playground), /at-scale/
    (commercial), /origins/ (the name and the mark), /roadmap/. The paths the preview
    used to reach across a folder boundary (../docs, ../sidebars.js, ../static)
    become the site's own.
  • Adds the agent skill pack (.claude/skills/tirith-policies/, 11 files) and
    .cursor/rules/tirith-policies.mdc. The Skills page instructs readers to curl these
    from this repository's main branch and links every file it lists; neither existed
    here, so those install commands returned 404.
  • Adds LLM and search optimisation: llms.txt, llms-full.txt (all 26 doc pages in
    one file), ai.txt, robots.txt, JSON-LD (SoftwareApplication +
    SoftwareSourceCode + Organization site-wide, FAQPage on /at-scale/), and 26
    per-page markdown endpoints at each route plus .md.
    scripts/generate-llms-full.py generates the last three from the doc sources so they
    cannot drift, and fails if a doc is added without being placed in its order list.
  • Adds agent mode to the landing page: a HUMAN | AGENT toggle that replaces the
    page with its machine-readable form. It renders llms.txt through a generated module,
    so the page and the crawler file are the same text.
  • Documentation updates: editor-and-local.md (new, marked in development),
    Bitbucket/Jenkins/pre-commit sections in ci-integration.md, 1.2.0 install pins, and
    issue-template links.
  • Marks unshipped features rather than implying they work. tirith lint is not in
    the released CLI, and the pre-commit hook and VS Code task file are not in this
    repository. Every affected snippet has the lint line commented (# in dev, not in 1.2.0), the docs page carries a warning admonition and an (in dev) sidebar label,
    and the landing-page section that depended on them is switched off.
  • deploy_docs.yml gains the optional PostHog and HubSpot environment. Unset, the
    analytics script never loads.
  • Also: documentation/.gitignore now excludes the stray yarn.lock Docusaurus writes,
    and one TUI banner string changed in src/tirith/tui/app.py.

• Why are these changes necessary?

  • The published site was a single-page landing built on the old prototype. The replacement
    pages were finished in tirith-internal but sat in a folder no workflow built, so they
    could never ship from where they were.
  • The Skills page and the CI docs told readers to run commands that could not work: files
    that were not in this repository, and a tirith lint subcommand the released package
    does not have. That is worse than a missing page, because it fails after the reader has
    committed to trying.
  • Nothing on the site was written for machine readers, and the facts an assistant gets
    wrong about Tirith are specific and costly: pip install tirith fetches an unrelated
    project, and exit 1 and exit 3 mean different things on purpose.

• Which issues or tickets does this PR close or relate to?

  • Related issue: #

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Other (please specify): replaces the published documentation site; adds
  .claude/ and .cursor/ agent instruction files at the repository root

Checklist

• Code has been linted.
  npm run build passes with onBrokenLinks: 'throw', which is what proves every
  internal link resolves. No Python source changed except one TUI banner string.
• Documentation has been updated (if needed).
  documentation/README.md rewritten (it was the stock Docusaurus scaffold telling
  readers to use yarn, which contradicts the committed package-lock.json and both
  workflows). DESIGN-NOTES.md and brand/README.md added.
• Tests have been added or updated (if needed).
  No test changes. Nothing here touches the engine; src/tirith/tui/app.py changes one
  banner string. Site correctness is enforced by the build itself: broken links throw,
  and the llms generator fails on an unlisted doc.
• Any breaking changes have been communicated to the team.
  None to the CLI. Two things reviewers should know: the published site's URLs change
  (the old single page becomes five routes), and /logo/ was renamed /origins/
  before ever being published, so no live link breaks.

Screenshots or Recordings (if applicable)

Additional Information

Known limitations, deliberate:

• robots.txt and ai.txt will not be read as published. Crawlers fetch those only from a
  host root, and this is a GitHub Pages project site, so they land at
  /tirith/robots.txt. Both say so at the top. The llms.txt half is mitigated by a
  <link rel="alternate"> in every page head. The real fix is a custom domain such as
  tirith.stackguardian.io, which would make all of them root-relative at once.
• Two pages are switched off rather than deleted: the Skills route (excluded via
  pages.exclude in docusaurus.config.js) and two landing-page sections ({false && …}
  guards). Each carries a comment saying exactly how to restore it. Skills is excluded
  because it advertises tirith lint.
• llms-full.txt, the 26 .md endpoints and src/data/agentBrief.js are generated and
  committed. Re-run python3 documentation/scripts/generate-llms-full.py after editing docs.

Worth a reviewer's attention:

• documentation/static/img/platform/ holds three StackGuardian product screenshots taken
  from stackguardian.io. They are currently referenced only by a switched-off section.
  If they are not wanted in an Apache-2.0 repository, deleting the three files and the
  asset entries in VIEWS is the whole change.
• Claims on the pages were checked against source, not assumed: 13 condition types against
  EVALUATORS_DICT, 5 providers against src/tirith/providers/, exit codes against
  status.py, the version and Python floor against setup.py. There is no CloudFormation
  provider, so the site does not claim one.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

Files with missing lines	Coverage Δ
src/tirith/tui/app.py	95.16% <100.00%> (ø)

🚀 New features to boost your workflow:

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

[AkashS0510]

Review: 10 confirmed findings

All verified against source at tag 1.2.0, origin/main, and the PR head. The theme worth noting: the PR's stated goal is "marks unshipped features rather than implying they work" — and the worst findings are exactly that failure mode.

Blocking

1. The tirith-lint pre-commit instructions can never work — documentation/docs/tirith-usage/ci-integration.md:223
The new pre-commit section says "Tirith publishes a tirith-lint hook" with a copy-paste config pinned to rev: 1.2.0, but no .pre-commit-hooks.yaml exists at that tag (or anywhere in the repo) and the released CLI has no lint subcommand. Anyone who copies it gets tirith-lint is not present in repository — unfixable at that immutable tag. It also contradicts this PR's own llms.txt, and the claim is replicated 11 times into the generated llms-full.txt, so answer engines will confidently repeat it.

2. Exit code 2 is documented two opposite ways inside this PR
.claude/skills/tirith-policies/reference/verdicts.md:17 and docs/tirith-usage/exit-codes.md:22 say exit 2 = platform-check timeout; SKILL.md:44, .cursor/rules/tirith-policies.mdc:37 and static/llms.txt:24 say ERROR_TIMEOUT=2 is declared but never returned. Source confirms the latter: a platform timeout raises SGError → CheckError and platform/cli.py:260-264 returns 1. A pipeline branching on exit 2 per verdicts.md is dead code, and an agent loading the skill pack gets opposite claims depending on which of its own files it reads.

Should fix before merge

3. The /learn/ playground inverts the verdict on the concept it teaches — documentation/src/data/tirithLite.js:313 and :302

• evalExpression propagates a skipped evaluator's null through &&/||/!, so skipped && passed → final_result: null → exit 1. The real engine (core.py RemoveNoneConstantAndName + FixBoolOp) removes skipped ids, so the same expression reduces to passed → exit 0 — the semantics the eval-expressions truth table and the error-tolerance lesson teach. The lesson's own scenario gives the wrong answer in the playground.
• An eval_expression id naming no evaluator is a fatal error in the playground (exit 1); the real engine removes undefined ids and continues (eval-expressions.md says so explicitly).
• Neither is listed in the file's KNOWN DIVERGENCES header, and the comment at L260-262 presents the wrong behavior as intended.

4. The skill-install snippet reintroduces the bug this PR fixed elsewhere — documentation/docs/tirith-usage/editor-and-local.md:113
It creates .claude/skills/tirith-policies/reference/ but curls only SKILL.md — none of the ten reference/*.md files — so every reference pointer inside SKILL.md dangles. This is the exact "earlier draft" bug skills.js:40-45 documents as found and fixed on the Skills page. Also ships in the generated mirror and llms-full.txt.

5. Deep links to files that exist in no ref — documentation/docs/tirith-usage/ci-integration.md:190,219 and editor-and-local.md:86
examples/ci/bitbucket-pipelines.yml and examples/ci/Jenkinsfile — there is no examples/ directory at PR head or main. .vscode/tasks.json — .vscode/ holds only settings.json. onBrokenLinks: 'throw' validates only internal routes, so these external GitHub 404s pass the build.

Smaller, still real

6. documentation/scripts/generate-llms-full.py:101 — the unlisted-doc guard compares str(p.relative_to(DOCS)) against forward-slash ORDER entries, so on Windows every nested doc gets backslashes and the script always exits 1 with ~25 false errors. Needs .as_posix(). (Related: rglob('*.md') silently exempts any future .mdx doc from the guard.)

7. documentation/src/pages/index.js:675 — the hero renders <p className={styles.cost}>{hero.cost}</p> but hero defines no cost field (the copy was folded into the lede), so an empty <p> with margin: 0 0 2rem ships a dead 2rem gap in the hero.

8. documentation/docusaurus.config.js:253 — the navbar link to the hosted Policy Builder (still live, HTTP 200) was dropped from site chrome with no note, while this PR's own DESIGN-NOTES.md:230 still specifies "Policy Builder · GitHub on the right". Looks like an accidental omission rather than a decided deprecation; it now survives only as one inline link in getting-started-with-tirith.md.

9. documentation/src/data/tirithLite.js:274 — four further undeclared engine divergences: no whitespace trim in tokenize (trailing space in eval_expression is a fatal parse error; Python ignores whitespace); getValues uses part in node, walking the prototype chain (key_path: "constructor" evaluates an inherited function instead of "not found"); provider errors land in the top-level errors array (real tirith populates it only from the eval-expression pass) without Python's (severity: 2) suffix; RegexMatch serializes non-string haystacks with JSON.stringify while Python matches str(input) (single quotes, True/None) — so a \"private\" pattern against a list passes here and fails in real tirith.

Minor / mentions

• No CI step re-runs generate-llms-full.py + git diff --exit-code, so the 28 committed generated files drift silently on the next doc edit.
• 1.2.0 is hand-pinned in 14 files; only README is covered by the existing currency test.
• The Slack community invite was removed from both docs pages that solicit feedback and survives only in the landing Colophon.
• Favicon changed PNG → SVG with no fallback rel="icon" head tag; Safari renders no icon.
• analytics.js:21's NOTE names its own path as the "diverged sibling" (should name the older site's src/lib/analytics.js); 29 of 37 EVENTS constants are never fired.

One candidate was checked and dropped: the unrendered EnquiryForm is kept deliberately and documented in the diff (at-scale.js:851).

---

Reviewed with Claude Code — findings verified against src/tirith/ source, tag 1.2.0, and both refs before reporting.

[sonarqubecloud]

❌ The last analysis has failed.

See analysis details on SonarQube Cloud