[folathecoder]

Summary

Rewrites agentling.dev for Agentling 0.2.0 as the documentation of an agent engine, gives the site a homepage, and restyles the whole site. The docs move from four sections and 17 pages written for 0.1.1 to five sections and 30 pages:

• a tutorial that builds one program from a first agent to a harness;
• how-to guides that each answer one task;
• concepts that explain the reasoning behind the design;
• a reference with one page per module.

CI now runs every Python block on the site, and every old URL redirects to its new page. / is a homepage instead of a redirect to the docs, and every page has new colours, Mona Sans and a new homepage finish. The site also gets Agentling's new black and white logo, with its favicon, app icons and social images.

Ticket

ENG-521. Closes ENG-521 once it deploys after 0.2.0 is on PyPI, and ENG-522 (the homepage). The two tickets ship as one PR so the site can be reviewed and tested as a whole.

Changes

Content (content/)

• Five sections: Getting started, Tutorial, How-to guides, Concepts and Reference. core-concepts/ and guides/ are deleted.
• Getting started: the introduction says what an engine and a harness are, and has a "You bring, Agentling brings" table, a diagram, a "What it is not" list and the Aldwin link. The install page has a "Using 0.1.1?" note. The first agent runs on ScriptedModel with no key.
• Tutorial: seven chapters. Each ends with a complete program that the next chapter starts from: stream events, handle failures, memory and resume, skills, connect a real model (checked against a recorded fixture), test your agent, build a harness.
• How-to: write a model adapter, run a local model, tools from a JSON Schema or MCP, interrupt from a UI, persist sessions, trim context, and migrate from 0.1 (the full MIGRATING.md, with every "after" snippet executed).
• Concepts: the agent loop (the new SVG plus the step-by-step diagram), the model contract (its seven rules and check_model's eight), design decisions, and security and trust.
• Reference: nine pages, one per module. Signatures, defaults and errors are checked against the source.
• Other pages: changelog/0.2.0.md is new. pages/contributing.md is rewritten with the Python checks and the # not executed marker. "Framework" is removed from privacy.md and the 0.1.0 changelog. The terms.md links are pinned to v0.2.0.

Site code

• Positioning: site.ts has the new tagline and VERSION = "0.2.0", and seo.ts the new DEFAULT_TITLE. llms.txt, the layout keywords, the OG image titles and the creator page now say "agent engine". The OG image titles are a text change only.
• Raw HTML: the Markdown pipeline passes raw HTML (rehype-raw, already a dependency) so the inline SVG renders. Content is written in this repository, so it's trusted.
• Section-aware lookups: the ticket gives tutorial/skills and reference/skills the same slug, so doc pages are now looked up by section and slug.
  • Changed callers: getDocPage, the doc page, its OG image, llms-full.txt and the search index. Search ids are now doc:<section>/<slug>.
  • The validator checks that slugs are unique within a section.
• Redirects: next.config.ts has permanent redirects for the 13 moved pages and the two old section indexes.

Checks

• scripts/validate-content.mjs: fails on "framework" (except the migration page's rename sentence), a list of filler words, title-case headings and links to the agentling repo at main. It now reports file line numbers, not body line numbers.
• pyproject.toml, uv.lock, tests/:
  • test_examples.py runs every python block in its own process from the repository root, with a 30 s limit. A block that starts with # not executed: <reason> is skipped, and the reason can't be empty.
  • test_redirects.py checks the redirect table against live pages.
  • Fixtures copied from agentling: tests/fixtures/openai_chat.jsonl and ollama_native.jsonl.
• CI: a new examples job checks out Agentling for examples.providers, then runs ruff, mypy and the examples. The existing checks job is unchanged.

Homepage and design (ENG-522)

• src/app/page.tsx renders the homepage. All copy lives in one COPY constant. Metadata: DEFAULT_TITLE as an absolute title, SITE_TAGLINE, canonical /.
• src/components/install-command.tsx (new, client): pip install agentling in a code block with a copy button that shows a tick and "Copied" for 2 s, plus "or uv add agentling" beneath.
• src/components/icons/copy.tsx (new): the copy and tick icons, shared by the install command and copy-code-buttons.tsx, which now imports them instead of holding its own markup.
• src/components/logo.tsx links to /.
• src/app/docs/page.tsx keeps its redirect to the introduction.
• No new dependencies or animation. The only state change on the page is the copy button.

Site-wide restyle

Added at the owner's request during the build. Every page keeps its layout and gets a new look.

• Colours: new light and dark tokens in globals.css. THEME_COLORS in src/lib/theme.ts matches them.
• Fonts: Mona Sans replaces IBM Plex Sans, and code uses the system monospace stack instead of JetBrains Mono. The official Mona Sans v2.0.27 files are self-hosted with next/font/local in src/assets/fonts/mona-sans/, with the OFL beside them: the variable face with its optical-size axis, and Mona Sans Mono for labels. The OG images still render with the bundled IBM Plex and JetBrains Mono files.
• Type and shapes: UI text is 14px and docs body text 16px at line height 1.5. Radii are 6px, with 12px for overlays. The version chip is an outlined pill.
• Buttons: buttonClass has three medium variants: ghost, outline and a solid primary.
• Docs text: underlined h1 and h2, a grey inline-code pill, bordered tables with striped rows, quotes, and five alert colours for callouts.
• Code blocks: they follow the site theme, with one shiki theme for light and one for dark, instead of staying dark in both.
• Header: a tinted header bar, and an orange underline under the current nav item.
• Homepage:
  • framing rules down both sides and a fading graph-paper background;
  • an eyebrow pill above the headline, which is set at weight 440 with the display cut;
  • 48 px buttons, the primary solid in the text colour;
  • Mona Sans Mono uppercase labels (.brand-label);
  • a plain rule between the hero and the doors, and a coloured corner on each door.
• Colour on the homepage: each door has one hue (teal, indigo, orange) as its corner and as a muted hover tint, with separate light and dark values.
• Fix: text-base resolved to the base colour token instead of the 16 px size, so anything using it was painted in the background colour. The size token is now text-md.

New logo

The old mark, three bars of decreasing length, read as an align-left icon next to the header controls. The new symbol is a lowercase a whose stroke runs on along the baseline and out of the loop. Its counter is round on three sides and square in the corner where the stroke leaves. It is black and white only: black on light grounds, white on dark.

• Header: src/components/icons/mark.tsx is one path in currentColor, using the heavier small-size cut drawn for 24 px and below. The accent prop is gone; logo.tsx never passed it.
• Favicon: src/app/icon.svg is black in light mode and white in dark mode.
• App icons: scripts/generate-icons.mjs draws the white mark on a black tile, because a raster can't follow the theme. favicon.ico, apple-icon.png and the three PWA icons are regenerated from it.
• Social card: src/lib/og-image.tsx draws the new mark and uses the site's light tokens: a white ground, ink text and a black section label instead of the old indigo.
• Shared path: the mark's path lives once in src/lib/brand-mark.ts, imported by mark.tsx and the OG card.
• Brand files: public/brand/ holds the outlined symbol and lockups in black and white, PNGs, and profile images and banners for LinkedIn, X and GitHub, with a README.md saying which file goes where. They're served from agentling.dev, so the Agentling README can link them.
• README: the logo sits at the top and switches between black and white with the reader's colour scheme.

Review fixes

A lunar-pr-review pass checked the code, and a separate reviewer read every page against the Agentling 0.2.0 source and re-ran each example against its shown output. The fixes:

• Code:
  • Sidebar rows grow when a title wraps, instead of overlapping the next item.
  • The left-bar active style is gone.
  • Element rules and the small recipes (.chip, .eyebrow, .brand-label, .bg-graph) sit in @layer base and @layer components, so utilities win. The version chip and the search shortcut now hide on phones as intended. Prose and code-block rules stay outside a layer so they still beat the typography plugin's defaults.
  • Mona Sans Mono is no longer preloaded on every page.
  • External links say "(opens in a new tab)" to screen readers.
  • The section eyebrow is keyed to the five new sections: Tutorial, How-to guide, Concept and Reference. Getting started mixes modes, so it has none. Before this, the old keys left most pages without one and labelled Getting started "Tutorial".
  • The creator page describes the 0.2.0 model story (copy a reference adapter or implement the Model protocol) instead of a built-in OpenAI adapter, and says "agent stacks" and "abstraction" instead of "framework".
  • The creator page's examples link and the sidebar's licence link are pinned to v0.2.0 instead of main.
  • Filler comments are trimmed, and comments that named another design system as the source are reworded to state what the code does.
• Docs:
  • Interrupts: a run clears the interrupt flag, and is_running turns true, at its first step rather than at run(). The pages now say so and give the safe UI pattern.
  • Approvals: the harness chapter's approval hook is async.
  • Recording: record.py is described as it actually works, with a RecordingTransport example for your own adapter.
  • Tutorial: each chapter says what it drops from the previous chapter's program.
  • Examples: the quickstart step runs from a main().
  • Trimming: trim-context skips the loop's own notes.
  • Smaller corrections: the docstring summary, the format 2 Usage fields, provider_data on a delta, shared tool state, and the streaming render.

How it was tested

• Content and site checks: npm run validate reports "Content OK: 30 doc pages in 5 sections, 3 releases, 3 site pages". npm run lint, npx tsc --noEmit and npm run build are clean.
• Examples: uv run pytest -q gives 93 passed and 5 skipped, against agentling==0.2.0 from PyPI and the v0.2.0 tag for the reference adapters. uv run ruff check tests and uv run mypy tests are clean.
• Validator probe (TC-07 to TC-09): a test page with "Build A Harness Quickly", "framework", "robust" and a blob/main link fails on all four, with the right line numbers.
• Production server: I checked next start locally:
  • /docs/reference/openai-model and /docs/core-concepts/skills return 308 to their new pages. /docs still redirects to the introduction.
  • /docs/tutorial/skills and /docs/reference/skills both return 200 with their own titles.
  • /llms.txt says "agent engine" and doesn't contain "framework".
  • /search-index.json lists all 30 pages and none of the old ones.
  • The introduction renders the SVG with its aria-label.
• Not executed: 5 blocks (under the limit of 15):
  1. tutorial/connect-a-model.md:36: needs an OpenAI API key.
  2. how-to/write-a-model-adapter.md:102: needs an API key.
  3. how-to/run-a-local-model.md:30: needs a running Ollama server.
  4. how-to/tools-from-a-schema-or-mcp.md:102: needs the mcp package and an MCP server.
  5. concepts/the-model-contract.md:13: the shape of the protocol.
     The marker in pages/contributing.md is inside a text block that explains it, so it isn't counted.
• TC-12, a fresh reader following the tutorial on a clean machine, hasn't been done yet.

Homepage and design

• npm run validate, npm run lint, npx tsc --noEmit and npm run build: clean.
• Against a local server, with Playwright:
  • TC-01: GET / is 200, no redirect. TC-02: GET /docs is 308 to the introduction. TC-03: the logo on a docs page has href="/".
  • TC-04: clicking the copy button sets its label to "Copied" and reverts after 2 s. The headless browser refuses clipboard reads, so the clipboard contents were not checked by script.
  • TC-05: tab order is the header controls, the GitHub and PyPI rail links, the copy button, the three doors, then the footer. Doors have a visible focus outline.
  • TC-06: at 375 px the doors stack with rules between, the headline wraps to two lines, and scrollWidth equals the viewport.
  • TC-07: at 1440 px, light and dark, the three columns have vertical rules. Screenshots are attached.
  • TC-08: exactly one h1, text "Bring your model. Run the loop."
  • TC-09: grep -i framework src/app/page.tsx finds nothing.
  • TC-10: /opengraph-image is 200; the sitemap lists /.
• The layout was measured against lunarstack.co at 1440 and 375 px (display size, line heights, tracking, rail and bracket positions, card size, padding and the offsets of label, title, copy and action inside each card). Ours matches within a few pixels; the remaining differences are the fonts and palette, which are the site's own.
• Not done: TC-11 (Lighthouse) and TC-12 (a browser holding the old cached 308 for /).

Logo

• npm run validate, npm run lint and npx tsc --noEmit are clean, and CI's build passes.
• node scripts/generate-icons.mjs regenerated every raster icon.
• On the dev server, the header mark renders at 18 px in light and dark, /icon.svg serves the new mark, and /brand/logo/agentling-horizontal-black.svg returns 200.
• The symbol was checked at 16, 32 and 64 px, in one colour and reversed, and against the closest letter marks in a reference library of 1,400 logos. None is close.

Notes for reviewers

• Agentling 0.2.0 is released. The examples depend on agentling==0.2.0 from PyPI, and the CI job checks out the v0.2.0 tag for the reference adapters. Links to blob/v0.2.0 in the agentling repo resolve.
• The 0.1.1 note links agentling-docs at tag v0.1.1, which doesn't exist yet. Create it on the pre-rewrite main commit 8267953 before merging.
• Changelog date: changelog/0.2.0.md has releaseDate: 2026-11-03, the day 0.2.0 was published.
• Aldwin link: the introduction links Aldwin's core/agent.py on main, and says it may still use the 0.1 API until ENG-508.
• Departures from the ticket:
  • Slugs are unique per section, not site-wide. This is needed for FR-4's two skills pages.
  • The migration page's "before" snippets are text blocks, because they're 0.1 code.
  • The harness chapter carries only add and a new save_note tool rather than every earlier tool, so it only partly meets FR-5's "previous program is the starting point".
• Problems found in Agentling's own docs, for ENG-507:
  • README.md:318 says the loop raises ModelOutputError for unparseable tool calls; it actually raises ModelError after two corrections.
  • ModelBadRequestError's docstring lists only some of the 4xx codes the adapters map to it.
  • AgentSession.step_callbacks isn't documented.
  • Step callbacks don't run for a plain-text final answer.

Homepage and design

• Reference changed. The ticket describes the anoma.ly layout. The owner switched the reference to lunarstack.co during the build, so FR-3 (a centred wordmark hero with an attribution line) and FR-4 (a 72 px headline with three claims on the right) don't apply as written. What shipped instead: a bottom-anchored 120 px headline in regular weight with the second line's first word in the tertiary colour, a GitHub and PyPI icon rail, and a corner bracket with the kicker "Agent engine for Python". The three claims from FR-4 are not on the page.
• The doors are whole-card links, as on the reference, rather than a section with a link at the foot.
• The display sizes use Tailwind arbitrary values; globals.css is unchanged.
• The hero's upper half is empty by design (the reference fills it with a faint ambient image, which would be a new asset).

Logo

• No trademark search has been run on the new mark.
• The OG card still renders with IBM Plex and JetBrains Mono. Moving it to Mona Sans needs TTF builds of the fonts, so it's left for a follow-up.
• The Agentling README links the logo at https://agentling.dev/brand/logo/, in a separate PR on the agentling repo. Those images load once this site is deployed.