docs: web platform + clean URLs + dark/light mode (#37)

* chore(docs): replace d2 diagram pipeline with mermaid

Remove docs/_diagrams/ and d2 build step from Makefile. The HTML
template already initialises mermaid.js; diagrams are now inline
code fences rendered client-side.

* docs(architecture): add mermaid diagram + web/CDP platform docs

Replace SVG img tag with inline mermaid flowchart showing both native
(Maestro sidecar + in-app SDK) and web (Chrome CDP) paths. Update
Processes, Transports table, and per-step cycle sections.

* docs(design-principles): update principles 1-4 for web platform

Principles 1, 2, 3, and 4 referenced Maestro and native-only concepts.
Add web/CDP context and update driver-is-an-interface to name both
sidecar and chrome implementations.

* docs(manual): add web prerequisites and folio-web example

Update --platform flag to list android, ios, web. Add web prerequisites
section (Chrome, no SDK needed) and folio-web quick-start to
getting-started.

* chore(gitignore): untrack inspect dist/index.html build artifact

index.html is regenerated by vite on every build with a new content hash,
making it permanently dirty. Only .gitkeep is needed for //go:embed to
compile on a fresh checkout. Also remove duplicate dist/* line and stale
d2 diagram ignore entries.

* feat(docs): click-to-zoom for mermaid diagrams

* docs(architecture): change diagram layout from LR to TB

* docs(getting-started): link npm and Maven Central package headers

* update docs root

* docs(spec): rewrite npm package README

Update usage example to current API, drop stale version-compatibility
and license sections.

* build(docs): output pages as pagename/index.html for clean URLs

Split DOCS_OUT into INDEX_OUT (index.md files stay as index.html) and
PAGE_OUT (all other pages become pagename/index.html). The __ROOT__
depth computation already handles the extra directory level correctly.

* chore(docs): update sidebar links to directory-style URLs

* docs: update cross-links from .html to directory-style paths

* ci(docs): remove d2 install step

* feat(docs): dark/light mode toggle

Add theme toggle button (top-right, fixed). Persists preference in
localStorage; falls back to prefers-color-scheme. Flash-free via inline
script in <head> that sets data-theme before first paint.

* fix(docs): fix inspect image path broken by directory URL restructure

* feat(docs): click-to-fullscreen for all article images

* fix(inspect): allow AssetsFS override in ServerOptions; drop unused request param from serveIndex

* fix(inspect): use in-memory FS in tests so TestAssets_FallbackToIndexHTML passes without web build

Makefile

@@ -11,11 +11,13 @@ SIDECAR_EMBED := internal/sidecar/assets/sidecar-all.jar
 SDK_AAR := sdk/android/build/outputs/aar/sdk-android-release.aar
 SANDERLING_BIN := bin/sanderling
 
-DOCS_SRC := $(shell find docs -type f -name '*.md' -not -path 'docs/_*')
-DOCS_OUT := $(patsubst docs/%.md,build/site/%.html,$(DOCS_SRC))
+DOCS_SRC      := $(shell find docs -type f -name '*.md' -not -path 'docs/_*')
+INDEX_SRC     := $(filter %index.md,$(DOCS_SRC))
+PAGE_SRC      := $(filter-out %index.md,$(DOCS_SRC))
+INDEX_OUT     := $(patsubst docs/%.md,build/site/%.html,$(INDEX_SRC))
+PAGE_OUT      := $(patsubst docs/%.md,build/site/%/index.html,$(PAGE_SRC))
+DOCS_OUT      := $(INDEX_OUT) $(PAGE_OUT)
 DOCS_TEMPLATE := docs/_template/page.html
-DIAGRAM_SRC := $(shell find docs/_diagrams -type f -name '*.d2' 2>/dev/null)
-DIAGRAM_OUT := $(patsubst docs/_diagrams/%.d2,build/site/_assets/diagrams/%.svg,$(DIAGRAM_SRC))
 
 INSPECT_DIST := internal/inspect/dist
 WEB_DIST := inspect-ui/dist
@@ -84,24 +86,27 @@ test-kotlin:
 test-spec-api:
 	cd pkg/spec && npm test --silent
 
-docs: $(DOCS_OUT) build/site/_assets $(DIAGRAM_OUT)
-	@echo "built $(words $(DOCS_OUT)) pages, $(words $(DIAGRAM_OUT)) diagrams to build/site"
+docs: $(DOCS_OUT) build/site/_assets
+	@echo "built $(words $(DOCS_OUT)) pages to build/site"
 
 build/site/_assets: docs/_assets
 	@mkdir -p build/site
 	@rm -rf $@
 	@cp -R $< $@
 
-build/site/_assets/diagrams/%.svg: docs/_diagrams/%.d2
-	@mkdir -p $(dir $@)
-	@d2 --theme 301 --pad 20 $< $@
-
-build/site/%.html: docs/%.md $(DOCS_TEMPLATE)
+define build_page
 	@mkdir -p $(dir $@)
 	@pandoc $< --from=gfm --to=html5 --standalone \
 	  --highlight-style=tango --template=$(DOCS_TEMPLATE) -o $@
 	@rel=$$(echo $(patsubst build/site/%,%,$@) | awk -F/ '{for(i=1;i<NF;i++)printf "../"}'); \
 	  sed -i.bak "s|__ROOT__|$$rel|g" $@ && rm $@.bak
+endef
+
+$(INDEX_OUT): build/site/%.html: docs/%.md $(DOCS_TEMPLATE)
+	$(build_page)
+
+$(PAGE_OUT): build/site/%/index.html: docs/%.md $(DOCS_TEMPLATE)
+	$(build_page)
 
 clean:
 	$(GO) clean