docs: Local UI verification + add markdownlint gate script

Fleet smoke stanza on AGENTS.md. Add scripts/lint-md.sh, config, and pin
markdownlint-cli2 so gate_begin_commit can lint staged markdown.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: jsolly

.markdownlint-cli2.jsonc

@@ -0,0 +1,28 @@
+{
+	// Respect .gitignore — never lint generated/gitignored markdown (dist/, .astro/, .vercel/, .venv/, MEMORY.md, generated seeds, node_modules, etc.).
+	"gitignore": true,
+	"config": {
+		// Enable the full default rule set; overrides below opt specific rules out/in.
+		"default": true,
+		// MD013 (line-length): disabled — allow long lines / no hard wrap.
+		"MD013": false,
+		// MD033 (no-inline-html): disabled — permit raw HTML in Markdown.
+		"MD033": false,
+		// MD041 (first-line-h1): disabled — file need not start with a top-level heading.
+		"MD041": false,
+		// MD024 (no-duplicate-heading): only flag duplicate headings under the same
+		// parent, so repeated section names (e.g. "Usage") across different sections are OK.
+		"MD024": { "siblings_only": true }
+	},
+	"ignores": [
+		"node_modules/**",
+		// Archival planning/spec records — not active content, not lint-gated.
+		"docs/plans/**",
+		"docs/specs/**",
+		// Vendor runtime dir (never tracked) — not repo content.
+		".claude/**",
+		// CLAUDE.md is a symlink to its sibling AGENTS.md (already linted) — skip to avoid double-linting.
+		"CLAUDE.md",
+		"**/CLAUDE.md"
+	]
+}

AGENTS.md

@@ -14,15 +14,15 @@ Local gate before push: `npm run check && npm run build` (full gate also runs in
 
 When starting the dev server, use background mode:
 
-```
+```bash
 astro dev --background
 ```
 
 Manage the background server with `astro dev stop`, `astro dev status`, and `astro dev logs`.
 
 ## Documentation
 
-Full documentation: https://docs.astro.build
+Full documentation: <https://docs.astro.build>
 
 Consult these guides before working on related tasks:
 
@@ -32,3 +32,10 @@ Consult these guides before working on related tasks:
 - [Adding or managing content](https://docs.astro.build/en/guides/content-collections/)
 - [Adding styles or using Tailwind](https://docs.astro.build/en/guides/styling/)
 - [Supporting multiple languages](https://docs.astro.build/en/guides/internationalization/)
+
+## Local UI verification
+
+No auth — public UI only. Follow `rules/frontend-verification.md` (fleet smoke: desktop + mobile screenshots, console clean).
+
+- **Dev server:** `astro dev --background` (manage with `astro dev status` / `astro dev logs` / `astro dev stop`). Default local URL is the Astro dev host printed on start (typically <http://localhost:4321>).
+- **Auth:** none — public pages only. No `DEFAULT_USER` / `DEFAULT_PASSWORD`.

README.md

@@ -25,7 +25,7 @@ User progress is stored only in the browser with `localStorage`. There is no dat
 
 ## Hosting
 
-Production: https://learnthefar.com (Vercel, Git-connected to this repo).
+Production: <https://learnthefar.com> (Vercel, Git-connected to this repo).
 
 Vercel builds the app with `npm run build` and serves the generated `dist/` directory. The deployment settings are captured in `vercel.json`. Pushes to `main` trigger a production deploy automatically.