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.