Align AkôFlow documentation narrative and examples

[ovvesley]

The documentation previously mixed architecture into beginner tasks, overstated partial provider support, and included examples or navigation links that failed in practice. This PR gives readers a workflow → environment → plan → run → result path, separates user and developer explanations, makes the result-evidence path direct, and corrects claims against the current code and runnable examples.

The 61 authored pages have an editorial pass, consistent Desktop/API task headings, a complete functional Desktop route map, and a page inventory in docs/editorial-audit-2026-09-12.md. A verified Linux Desktop path creates a local environment, one-activity workflow, plan, and real run, then inspects the resulting file. The Showcase pins its API bundles to v1.0.8 and distinguishes verified local/Kind/SimGrid paths from unverified institutional HPC and live cloud use. GCP provisioning, AWS EC2, S3, and gs:// transfer limits are stated where readers choose infrastructure.

The API generator covers 125 endpoint pages, gives route-specific descriptions, labels inferred response shapes, and requires checked notes or runnable requests for mutating routes. The environment, planning, execution, artifact, provenance, and instance references now separate saved records from runtime observations and distinguish supported behavior from schema-only or partial features. A site-wide navigation fix changes 334 page links to stable /docs/... routes; the link check rejects relative page links that can navigate to 404s after hydration.

Recent claim corrections include identifying the v1.0.8 Windows EXE as portable from the release build order, keeping the SLURM login node unschedulable, verifying first-contact SSH host keys against the administrator's fingerprint, and explaining that factory reset clears the database and Kubernetes token directory but retains SSH/cloud credential files and artifact bytes. The Desktop reset also clears only its current browser profile's local storage. Desktop update notices are now distinguished from saved operation-completion notifications.

Validation: npm run typecheck, npm run build, npm run check:links (468 local links and 54 versioned Showcase downloads), npm run check:shell (120 Bash/sh blocks), and git diff --check pass. At 390 px, a browser pass clicked an internal link from each authored page and reached the compiled target. Targeted Desktop, Kind, SimGrid, and local API evidence is recorded in the audit.

The current iteration is assessed in docs/editorial-closeout-2026-09-13.md. This PR remains a draft because the documented completion gate is still open: clean-host and other-platform installation, live GCP/S3 and institutional SLURM validation, field-level coverage of all 125 endpoint contracts, and a final all-page claim/plain-language pass. The docs qualify these unverified paths; a green build does not certify them. See docs/quality-plan.md for the remaining work.