Skip to content

docs: the OSS landing page and adopter docs, served from the app - #78

Open
adamstankiewicz wants to merge 14 commits into
docs/agents-mdfrom
docs/landing-and-docs
Open

docs: the OSS landing page and adopter docs, served from the app#78
adamstankiewicz wants to merge 14 commits into
docs/agents-mdfrom
docs/landing-and-docs

Conversation

@adamstankiewicz

@adamstankiewicz adamstankiewicz commented Aug 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

What & why

The project's public front door, one branch: the a2learn landing (docs/index.html, also served at /open.html) in the warm-minimal register — agent-session hero, interactive loop demo, manifesto, what-we-won't-claim, prior-art spanning H5P/xAPI/LTI/STACK/Numbas and the OpenTelemetry/Sentry/Home Assistant playbooks — plus Diátaxis-shaped adopter docs (Learn/Guides/Reference/Project) served from the app at /docs via a slug whitelist over the same markdown GitHub renders. Framework-first per the positioning rule: the registry API leads; built-in kinds are seed content. The messaging guide (claim-hygiene rules, boilerplate) ships in the Project section.

Type of change

  • Docs

Breaking or contract changes

None — new routes and static files only. docs/mcp-tools.md follows the audience rename downstack: audience is the documented argument and the gradeHint row stays, marked as the alias show_widget shipped with, so a reader of the deployed tool finds it rather than assuming the doc is stale. Docs describing branch-resident features (#75, #76, #79) mark them as planned/merging; merge this last so the docs are literally true on arrival.

How it was verified

  • pnpm lint and rm -rf .next && npx tsc --noEmit
  • pnpm build — all /docs/* routes prerender; slug whitelist 404s unknown paths (no filesystem walk)
  • Every doc claim cross-checked against code during the staleness pass (maintainership, A2UI "drafted as a profile" wording, planned-vs-shipped labels)
  • Landing checked in light/dark; the artifact version is the same content

Authorship

  • I understand every line of this diff
  • Agent-assisted or agent-authored: authored by Claude working interactively with @adamstankiewicz across design-crit and research checkpoints
  • No package.json / pnpm-lock.yaml changes

🤖 Generated with Claude Code

@vercel

vercel Bot commented Aug 30, 2026 •
edited
Loading

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
interactive-learning-experiences Ready Ready Preview Aug 31, 2026 12:39am

Request Review

@adamstankiewicz
adamstankiewicz changed the base branch from main to docs/agents-md August 30, 2026 18:49
@adamstankiewicz adamstankiewicz mentioned this pull request Aug 30, 2026
Open
adamstankiewicz and others added 14 commits August 30, 2026 20:38
@adamstankiewicz @claude
docs: the OSS landing page and adopter docs
f587211 
One branch carrying the project's public front door:

- docs/index.html — the a2learn landing in the warm-minimal register
  (Geist + Source Serif, warm paper, verification green as the only
  accent): agent-session hero, interactive loop demo, manifesto, lineage
  section (H5P, xAPI/Caliper, LTI, open platforms), named activity types.
- docs/README.md — the adopter docs index and the two ground rules.
- docs/quickstart.md — connector setup, self-hosting, and the full
  configuration reference.
- docs/registry.md — the centerpiece: the widget registry API. The
  two-registry design and why, WidgetCatalogEntry and WidgetGenerator
  contracts, who reads the registry, the add-a-kind recipe, and the
  hand-maintained-union limitation, stated plainly.
- docs/mcp-tools.md — show_widget and score_draft as shipped, the widget
  shell, and the planned v0.1 surface (find_activity, MCP_ACCESS_TOKEN,
  /api/v0) labeled as planned.
- docs/evidence.md — the interaction event contract, its honesty rules,
  what reads it, the student-identity boundary, and the universal
  WidgetResult direction.
- docs/architecture.md — the four seams and where student data cannot go.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@adamstankiewicz @claude
feat: serve the docs from the app
1875e59 
/docs renders the markdown under docs/ through a whitelist of slugs (no
filesystem walk), with GitHub-relative links rewritten to their app
routes or GitHub blob URLs. The static landing ships as /open.html.
Pages are prerendered; unknown slugs 404.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@adamstankiewicz @claude
docs: cross-vertical lineage on the landing page
50fe9ad 
Two additions from the comparables research: STACK/Numbas as the proof the
open-practice-engine category works and lasts, and the OpenTelemetry /
Sentry / Home Assistant playbooks (neutral contract governance, SDK-first
adoption, registry-as-contribution-ladder). The open-beats-owned creed item
now cites observability's version of the same experiment.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@adamstankiewicz @claude
docs: Diátaxis IA, pedagogy grounding, and a sidebar docs layout
22a7b22 
- New Learn section: the-loop.md (practice as a tool call, the three
  return edges, the unbuilt edge named) and pedagogy.md — the
  learning-science lineage of every structural choice (backward design,
  gradual release, retrieval practice, worked examples, formative loops,
  feedback discipline, rich evidence, structural review) plus the roadmap
  for deeper grounding, under the no-folklore-claims policy.
- Configuration reference extracted from the quickstart into its own page.
- Docs home rewritten audience-first (tutor builders, evaluators,
  educators, contributors) with a grouped Learn/Guides/Reference TOC.
- /docs route gains a sticky grouped sidebar on desktop; small screens
  keep the wrapped nav row.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@adamstankiewicz @claude
docs: active learning is why the project exists; evidence is how the …
2de4230 
…loop closes

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@adamstankiewicz @claude
docs: PBL positioning and the Reich cautions in the pedagogy page
c9a940f 
Where this sits relative to project-based learning (the scaffolding layer
projects need, per the guided-instruction critique — never claimed as PBL
support), and the Failure to Disrupt warnings the design answers or
honestly cannot: routine assessment, the Matthew effect, the pedagogy of
poverty. Teacher Moments noted as kindred OSS.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@adamstankiewicz @claude
docs: framework-first framing on the landing
825434c 
Per the positioning steer: the registry API and custom experiences are
the product; the sixteen built-ins are seed content. The hero meta says
'extensible activity registry' instead of a count, the full kind gallery
compresses to four examples plus a dashed '+ your kind · one file' chip,
and a new bullet names the extension API before the collection.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@adamstankiewicz @claude
docs: the messaging guide — brand hardened into claim-hygiene rules
f0acd88 
One sentence in three registers, the two approved category attachments,
the enemy (passive consumption, with the PNAS fact phrased exactly so it
can't drift), one move per audience, the NOT-list, voice rules including
framework-first, an approved/banned claims table, the proof hierarchy,
and boilerplate for About fields and announcement leads. Published
openly, in a new Project section of the docs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@adamstankiewicz @claude
docs: build_pathway, the agent-as-sequencer pattern, and the report c…
4976f33 
…hannel

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@adamstankiewicz @claude
docs: the A2UI surface is drafted as a profile — say so
d366151 
The app's own wire format maps to it at the boundary and conformance is
tracked openly; an evaluator who greps for A2UI should find the claim
matching the code.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@adamstankiewicz @claude
docs: the landing's status paragraph matches governance — maintainer …
f98e763 
…group forming, not one maintainer

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@adamstankiewicz @claude
docs: the semantic-discovery embedding knobs
2a0d814 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@adamstankiewicz @claude
docs: the tool reference documents audience, and the alias it kept
880836d 
Follows the rename downstack. `audience` is the documented argument; the
row for `gradeHint` stays so a reader of the deployed tool finds it and
learns it is an alias rather than guessing the doc is stale.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@adamstankiewicz @claude
docs: the tool reference catches up with reality
4902df1 
audienceHint replaces the bare name in show_widget's table, matching
c3cacf3's boundary rule — audience stays reserved for the scheme-scoped,
verified manifest field. find_activity graduates out of the planned
section: it merged to main and answers on the production endpoint, so
documenting it as unshipped had become the dishonest direction. Its new
section states the ranking honesty contract (semantic vs lexical).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@adamstankiewicz