Working on web/

The hand-written landing page and Astro Starlight manual share design tokens and deploy to Firebase at https://eklavya-run.web.app. Read the root CLAUDE.md and .claude/skills/eklavya-design/SKILL.md before changing them.

File map

npm ci
npm run dev       # development at localhost:4321
npm run build     # production output plus SEO/link audit
npm run preview   # serve the built site

Keep documentation aligned with source

Behavior and documentation ship in the same PR. Check each factual claim against the implementation, not against another page. Guides teach a task; reference pages enumerate complete fields and commands. Keep a single canonical home for details and link to it from shorter introductions.

Every manual page has a row below. Add a row, sidebar entry, unique frontmatter description and incoming link with each new page. Moving a page requires fixing links and preserving useful anchors or adding a redirect.

Write for a developer's first week

Lead with the outcome, show the shortest working path, then separate optional routes and troubleshooting. Explain jargon once. Use second person, present tense, sentence case and concrete examples. Prefer short paragraphs, ordered steps for procedures and tables for repeated fields; avoid long bullet walls. Do not use emoji or unsupported performance/privacy promises.

Installation's primary page should get the reader installed and verified. Alternative hosts and development setup belong in installation-options; upgrades/removal in updates; complete flags in cli; complete settings in configuration. Do not grow the quick start back into an exhaustive reference.

Command examples must run as written; identify required replacements such as /path/to/eklavya and <topic>. Describe unverified host UI as the interactive /plugin menu rather than guessing subcommands. Exported rules and a standalone MCP connection do not provide another editor with Claude Code's ambient hooks.

Starlight supplies the title, table of contents and previous/next navigation. Use ##/###, <Steps>, restrained notes/tips/cautions, and code-fence titles for filenames. Keep warnings next to the action they affect.

Diagrams

Use DocFlow.astro for short ordered sequences or timelines. Keep stage labels brief and put conditions, branch outcomes and limitations in nearby prose. Meaning must survive without arrows, color or JavaScript; maintain a readable text order, accessible caption and narrow-screen layout. Update each flow with the behavior it depicts and inspect both themes.

EmbeddedDiagram.astro displays the detailed generated runtime architecture. prebuild/predev copy docs/eklavya-runtime.html through scripts/embed-diagram.mjs; do not edit the generated HTML or commit the public copy. Root guidance owns regeneration. The copy alone receives website icons, canonical/share metadata and noindex, follow; missing markers fail the build.

The embedded viewer is a noninteractive still picture with a real link to open the full viewer. Preserve disabled pointer events, fit/crop after fonts load, fallback when measuring fails, and theme synchronization. Supply an iframe title and explanatory caption; neither alone substitutes for the diagram's information in text.

Landing output and design invariants

The landing hero introduces Eklavya with its mascot on a dark ground. Keep the home page lean, with the launch film embedded at /#demo. Keep the faint bow-to-target animation in the first section's background. It repeats while the hero is visible and the browser is active; reduced motion shows still artwork. It must not obscure the copy, mascot or controls. Only the hero mascot has green eyes, using the hero's --spot role. Its pupils follow the mouse within the eye shapes and return to center when inactive. Keep them centered on touch screens and with reduced motion. Leave the shared mascot artwork and other instances unchanged. /demo/ redirects there for old links. How it works, dials, commands, dashboard and memory details stay in the manual.

Keep the compact name story at #legend, with the eyebrow "The name", the heading "The archer who taught himself", three short story columns and the bow, arrow and target artwork. The SVG is decorative. Its animation runs once each time the scene enters view, including after returning with Back; reduced motion shows a static scene. Preserve #legend and #legend-title on the home page instead of redirecting them to docs.

The demo is the 30-second launch film, public/demo/eklavya-launch.mp4 with eklavya-launch.jpg as poster, in a native <video controls id="demo">. It does not autoplay; keep the native controls, the caption and the play button (demo.js also pauses it when it scrolls out of view). Re-encode large source films (about 1280px wide, under 3 MB) before committing. assets/launch-film.jpg is the README's click-through poster.

Keep quoted output consistent with session-start.ts, statusline.ts and checkpoint-quiz.ts. Terminal commit gating requires the separate git-hook installer and project enforcement; never promise it from the default install alone.

• Use role tokens (--ink, --dim, --line, --spot, etc.), not raw colors or palette scale steps. The mascot hero keeps fixed dark roles.
• Override Starlight colors in both theme blocks. Check text against its own fill so token mistakes do not create invisible labels.
• Keep table cells at overflow-wrap: break-word, not anywhere; retain the first-column width floor. Code-containing grids need minmax(0, 1fr).
• Let rehype-brand and PageTitle.astro accent the product name; do not add manual spans. Lowercase eklavya remains a binary/key, not branded prose.
• Bump affected ?v=N queries when changing hand-written public assets.
• Preserve Firebase HTML revalidation and immutable fingerprinted assets in non-overlapping header rules. A second hosting path requires another build.

Before opening a PR

Build and require the SEO audit to pass. It checks internal pages, fragments, resources, metadata and README website links. Preview changed pages at 1280, 900 and 560px in both themes, with no horizontal page scroll, console errors, broken sidebar state or inaccessible controls. Check that the launch film fits each viewport, shows its poster, does not autoplay and plays with its controls. Check /#demo and the /demo/ redirect. Check the legend's heading, columns, in-page anchors, one-shot arrow animation and static reduced-motion view in both themes. Check the hero eyes against the brand accent, bounded mouse tracking, centered touch/reduced-motion eyes and unchanged mascots elsewhere. Report the actual checks, including any not run.

After changing shared identity, run npm run seo:refresh and commit the homepage update. The root README reuses public/brand/mark.svg directly; do not introduce another logo. After changing public/brand/mark.svg, run npm run icons and commit exports. Share cards derive from page title/description. Follow SEO.md for publishing checks; a local build is not proof of indexing or a production deployment. Site-only commits use docs: and do not cut a release.