Skip to content

feat: website narrative restructuring and AI discoverability#408

Merged
aallan merged 5 commits into
mainfrom
feat/website-inference-discoverability
Mar 28, 2026
Merged

feat: website narrative restructuring and AI discoverability#408
aallan merged 5 commits into
mainfrom
feat/website-inference-discoverability

Conversation

@aallan

@aallan aallan commented Mar 28, 2026

Copy link
Copy Markdown
Owner

Summary

docs/index.html - AI discoverability and narrative improvements:

scripts/build_site.py - dynamic counts and updated content:

  • Replace hardcoded example/conformance counts with _count_examples() and _count_conformance() reading from filesystem
  • Add Inference to the algebraic effects list in llms.txt overview
  • Add EXAMPLES.md, DESIGN.md, HISTORY.md, KNOWN_ISSUES.md to llms.txt Compiler and Tooling section
  • Update Chapter 9 description to reflect current stdlib (maps, sets, decimals, JSON, HTML)
  • Add LLM Inference as a dedicated key feature in index.md

Test plan

  • All 22 pre-commit hooks pass
  • check_html_examples.py: 5 Vera blocks (safe_divide, fizzbuzz, classify_sentiment, safe_classify, research_topic), all pass parse+check+verify
  • check_site_assets.py: all generated docs/ files match build_site.py output
  • check_doc_counts.py: counts consistent

Generated with Claude Code

Summary by CodeRabbit

  • Documentation
    • Website docs updated with expanded feature descriptions: adds LLM inference, HTTP effects, constrained generics and additional built‑in types (JSON/HTML/Markdown/Map/Set/Decimal); “Typed Markdown” removed.
    • Examples and conformance counts now update automatically on site pages.
    • New navigation/pages added: Roadmap, Changelog, History and EXAMPLES.md; feature highlights and links revised for clarity.

docs/index.html:
- Add three link discovery tags for llms.txt, llms-full.txt, and index.md
  (closes #397)
- Add "documentation" field to ComputerLanguage JSON-LD schema entry,
  pointing to veralang.dev/llms.txt (closes #399)
- Merge LLM Integration section into "What Vera Looks Like" with five-example
  narrative arc: safe_divide, fizzbuzz, classify_sentiment, safe_classify,
  research_topic — building from pure functions through to Http+Inference
- Promote "For Agents" from h3 subsection to standalone h2 section
  (partial progress on #400)

scripts/build_site.py:
- Replace hardcoded example/conformance counts with dynamic filesystem reads
  (_count_examples(), _count_conformance()) so counts stay accurate
- Add Inference to the algebraic effects list in llms.txt overview
- Add EXAMPLES.md, DESIGN.md, HISTORY.md, KNOWN_ISSUES.md to llms.txt
- Update Chapter 9 description to include maps, sets, decimals, JSON, HTML
- Add LLM Inference as a key feature in index.md with dedicated bullet

Regenerate: docs/llms.txt, docs/index.md, docs/sitemap.xml

Co-Authored-By: Claude <noreply@anthropic.invalid>
@coderabbitai

coderabbitai Bot commented Mar 28, 2026

Copy link
Copy Markdown

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 6500a63f-81a3-4718-a9b7-ced656639c8b

📥 Commits

Reviewing files that changed from the base of the PR and between 63a2039 and aad775e.

⛔ Files ignored due to path filters (1)
  • docs/llms-full.txt is excluded by !docs/**
📒 Files selected for processing (1)
  • scripts/build_site.py

📝 Walkthrough

Walkthrough

Adds cached helper counters for example and conformance files to the site build script, and uses those counts to update generated docs (llms.txt, llms-full.txt, index.md) while rewriting feature/capability text and navigation links.

Changes

Cohort / File(s) Summary
Site generation script
scripts/build_site.py
Added _count_examples() and _count_conformance() helpers; updated build_llms_txt(version), build_llms_full_txt(version), and build_index_md(version) to interpolate {n_examples} / {n_conformance} and to rewrite feature/effects text and navigation links (EXAMPLES.md, Roadmap, Changelog, History).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

Suggested labels

ci

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'feat: website narrative restructuring and AI discoverability' directly and accurately captures the main focus of the PR, which centres on restructuring documentation presentation and adding AI agent discoverability features (link tags and JSON-LD metadata).
Linked Issues check ✅ Passed The PR fully addresses both linked issues: #397 (adding discovery tags to docs/index.html) and #399 (adding JSON-LD structured data with documentation field pointing to llms.txt).
Out of Scope Changes check ✅ Passed All changes are scoped to the stated objectives: HTML link/schema additions, dynamic count computation in build_site.py, and content updates to generated documentation files (llms.txt, llms-full.txt, index.md). No unrelated modifications detected.
Docstring Coverage ✅ Passed Docstring coverage is 85.71% which is sufficient. The required threshold is 80.00%.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/website-inference-discoverability

Comment @coderabbitai help to get the list of available commands and usage tips.

@codecov

codecov Bot commented Mar 28, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.30%. Comparing base (b9cabf2) to head (aad775e).
⚠️ Report is 6 commits behind head on main.

Additional details and impacted files
@@           Coverage Diff           @@
##             main     #408   +/-   ##
=======================================
  Coverage   90.30%   90.30%           
=======================================
  Files          49       49           
  Lines       19100    19100           
  Branches      220      220           
=======================================
  Hits        17248    17248           
  Misses       1848     1848           
  Partials        4        4           
Flag Coverage Δ
javascript 50.58% <ø> (ø)
python 95.31% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@scripts/build_site.py`:
- Around line 59-60: The call to _count_examples() is duplicated (once in main()
and again inside build_index_md()), causing redundant filesystem scans; modify
the code to compute example/conformance counts once in main() (using
_count_examples() and _count_conformance()) and pass those values as parameters
into build_index_md(count_examples, count_conformance) (or implement a simple
module-level cache in _count_examples() that returns a stored value on
subsequent calls), then update build_index_md() to consume the passed counts (or
read from the cache) so the filesystem is scanned only once.
- Around line 40-60: check_doc_counts.py currently validates counts in
TESTING.md but not the generated site artifacts, so stale counts can be
committed; extend the validation to parse and verify docs/llms.txt and
docs/index.md (or add a CI step that runs build_llms_txt and diffs generated
files) by reusing the same dynamic counting logic (_count_examples,
_count_conformance) used in build_llms_txt and adding checks that the numbers in
docs/llms.txt and docs/index.md match the computed values; update
check_doc_counts.py to locate and read those files, extract the documented
counts, and fail the check on mismatch (alternatively add a pipeline job to run
build_llms_txt and compare outputs to the checked-in docs).
- Around line 45-51: The _count_conformance() function reads the
tests/conformance/manifest.json using (ROOT / "tests" / "conformance" /
"manifest.json").read_text() without specifying encoding; update that
read_text() call in _count_conformance to include encoding="utf-8" to match
other reads in this file (so _count_conformance uses the same UTF-8 explicit
read as the rest of the script).
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: aa34f398-dca8-43b9-bda4-396804ad5e6b

📥 Commits

Reviewing files that changed from the base of the PR and between b9cabf2 and a87899b.

⛔ Files ignored due to path filters (4)
  • docs/index.html is excluded by !docs/**
  • docs/index.md is excluded by !docs/**
  • docs/llms.txt is excluded by !docs/**
  • docs/sitemap.xml is excluded by !docs/**
📒 Files selected for processing (1)
  • scripts/build_site.py

Comment thread scripts/build_site.py
Comment thread scripts/build_site.py
Comment thread scripts/build_site.py
- Add @lru_cache(maxsize=None) to _count_examples() and _count_conformance()
  so repeated calls within the same build invocation hit the cache rather
  than rescanning the filesystem (addresses CodeRabbit review comment)
- Add encoding='utf-8' to manifest.json read_text() call in
  _count_conformance() to match all other read_text() calls in this file

Note: check_doc_counts.py count validation of docs/ files not added --
check_site_assets.py already does a byte-for-byte diff of the generated
files against fresh build output, which is a stricter guarantee.

Co-Authored-By: Claude <noreply@anthropic.invalid>

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@scripts/build_site.py`:
- Around line 41-47: Replace the use of functools.lru_cache(maxsize=None) with
functools.cache for the _count_examples function: update the decorator on the
_count_examples definition to use `@cache` and ensure functools.cache is imported
(replace or add the import of cache alongside or instead of lru_cache) so the
function uses the simpler built-in cache decorator.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: b32ed7a8-a878-44e4-998b-97a5bbb5de1d

📥 Commits

Reviewing files that changed from the base of the PR and between a87899b and 8d015d5.

📒 Files selected for processing (1)
  • scripts/build_site.py

Comment thread scripts/build_site.py Outdated
aallan and others added 2 commits March 28, 2026 11:30
The version string 'v0.0.101' was duplicated in the status section of
docs/index.html, creating another place to update on every release.
Dropping the version prefix while keeping the description text.

Co-Authored-By: Claude <noreply@anthropic.invalid>
functools.cache is the idiomatic alias for lru_cache(maxsize=None)
available since Python 3.9. The project requires 3.11+, so this is
a straightforward simplification. Applied to both count functions.

Co-Authored-By: Claude <noreply@anthropic.invalid>

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@scripts/build_site.py`:
- Around line 136-149: build_llms_full_txt currently compiles only SKILL.md,
AGENTS.md, FAQ.md, error codes and grammar but the site now links additional
docs (README, EXAMPLES, DESIGN, CHANGELOG, ROADMAP, HISTORY, vera/README,
TESTING.md, KNOWN_ISSUES.md), so update scripts/build_site.py's
build_llms_full_txt to include those newly linked documents in its source list
(use the same RAW path expansion used elsewhere), concatenate them into
llms-full.txt in the intended order, and ensure the “complete documentation”
claim matches the actual contents if you prefer not to include a file; also
apply the same inclusion or claim-narrowing to the other related
functions/blocks referenced in the review (the other build paths noted in the
comment).
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: dc1ff738-6fe2-4ad7-8c83-5d426d1676a2

📥 Commits

Reviewing files that changed from the base of the PR and between 8d015d5 and 63a2039.

⛔ Files ignored due to path filters (1)
  • docs/index.html is excluded by !docs/**
📒 Files selected for processing (1)
  • scripts/build_site.py

Comment thread scripts/build_site.py
The header and docstring claimed 'complete Vera documentation' but the
file only contains SKILL.md, AGENTS.md, FAQ, error codes, and grammar —
not the 13 spec chapters, README, EXAMPLES.md, DESIGN.md, or the other
docs linked from llms.txt.

Narrow the claim to 'core language documentation' and point readers to
llms.txt for the full index. Adding spec chapters to llms-full.txt
(251 KB, ~13 files) is a deliberate architectural decision that warrants
its own PR.

Co-Authored-By: Claude <noreply@anthropic.invalid>
@aallan aallan merged commit bcf22f9 into main Mar 28, 2026
17 checks passed
@aallan aallan deleted the feat/website-inference-discoverability branch March 28, 2026 12:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add JSON-LD structured data to veralang.dev landing page Add <link> discovery tags to docs/index.html for AI agents

1 participant