# docs.ai2n.ai — Assumptions & Decisions

## Phase 5 (2026-08-29) — Developer, Release & Support

Per spec §17 Phase 5: "Implement developer resources, OpenAPI presentation, secure examples, webhooks, release notes, known issues, lifecycle matrix, service status, help centre and ticket integration adapter. Use mocks locally and never embed credentials."

- **6 new Developer & Integration articles**, all fully authored, none stubs: API Conventions, Authentication, Webhooks, Data Model, Code Samples, Error Catalogue. Every page includes the required §5.1 controls: a working copy-to-clipboard button on every code block, language tabs (TypeScript/C#/Python/curl) with correct panel switching, a cosmetic environment selector (Sample/Sandbox/QA/Production — Production is disabled, matching "no live production endpoint"), and every credential in every example is read from an environment variable placeholder, never a literal value.
- **No live "Try it" console or OpenAPI interactive explorer** — a deliberate choice, not an oversight: there is no real public API to call yet, so faking a working console would be actively misleading. Instead, every page is explicitly badged "Status: Illustrative — pre-release" and frames the API conventions (RFC 7807 errors, correlation IDs, idempotency keys, cursor pagination — all spec §12.1 requirements) as the platform's intended design.
- **Release Notes & Support**: added a real Help Centre article ("I Can't Sign In" — sign-in troubleshooting across wrong-portal, password, MFA, and pending-activation cases) and a **working mock support-ticket form** (native required-field validation, generates a demo ticket ID, explicit "not sent anywhere" messaging, and a placeholder warning against putting sensitive student data in the summary field).
- **Verified in QA before deploying**: language-tab switching changes the visible code panel correctly; copy button gives "Copied ✓" feedback; ticket form blocks empty submission via native validation, accepts a valid one, resets after submit.
- **Deferred**: a real ticket-integration adapter (backend), sandbox onboarding/test-data reset, and an actual interactive "Try it" explorer — all require the backend/identity layers already deferred since Phase 1.

## Phase 4 (2026-08-29) — Training Engine

Per spec §17 Phase 4 and §4/§4.1/§4.2: academies, paths, courses, modules, lessons, knowledge checks, progress, completion states and certificates.

- **One academy fully built end-to-end**: Teacher Enablement → Class Setup module → 2 lessons → knowledge check (3 questions, pass 2/3, unlimited attempts) → certificate. The other 4 modules in this academy, and all 5 other academies, remain structured-but-unauthored (matches the Phase 2 "Pending badge, not a dead link" pattern).
- **"Durable records" are explicitly NOT durable here**: `assets/js/training.js` persists progress in `localStorage`, scoped to one browser, not an account. This is a deliberate, documented mock — the spec's real durable/auditable completion records require the identity + database layers this build has deferred since Phase 1. The certificate page says so directly to anyone who reaches it, not just in this file.
- **Verified end-to-end in QA before deploying**: lesson completion persists and reflects on the module and path pages; passing the knowledge check (2/3) unlocks the certificate; a *later* failing attempt (1/3) correctly re-locks it — the module status reflects current pass/fail, not a one-time achievement flag; captions/transcript toggles on the video block are keyboard-operable native buttons with correct `aria-pressed` state.
- **Content types demonstrated**: text lesson, video placeholder (no real video asset — explicitly labeled as a demo placeholder, no autoplay), transcript panel, multiple-choice knowledge check, certificate. Not demonstrated: guided tour, simulation, downloadable job aid, live-session recording, renewal/expiration enforcement, manager/admin reporting — all deferred with the backend.

## Phase 3 (2026-08-29) — Search

Per spec §17 Phase 3: "Implement local search first, then an Azure AI Search adapter." Only the local half is built — no backend, identity, or Azure AI Search yet, so there is nothing to security-trim (every indexed page is already public).

- **Index**: `assets/data/search-index.json`, generated from the 19 non-404 pages (title, meta description, headings, content type, menu area, applies-to role).
- **Client-side engine** (`assets/js/search.js`): substring + token-prefix scoring, plus a lightweight Levenshtein-≤1 fallback for typo tolerance (verified: "atendance" surfaces attendance-related articles).
- **Ctrl/Cmd+K dialog**: real results with highlighted (`<mark>`) matches, breadcrumb/role context, content-type filter chips (All/Articles/Collections/Training/Developer/Release), keyboard navigation (↑/↓/Enter), zero-result recovery (popular tasks + Help Centre link), and recent-searches (localStorage, client-side only).
- **Local analytics stub**: query length + result count + active filter logged to `localStorage` only — never the raw query text or any personal data, matching spec §7.1's "without exposing restricted query content or personal data."
- **Mobile fix caught in QA**: the search trigger was hidden below the 760px breakpoint with no replacement in the mobile drawer — a real dead-end for touch users. Added a search button to the mobile drawer before deploying.
- **Deferred**: Azure AI Search adapter, semantic ranking, synonyms beyond simple typo tolerance, and real ACL/tenant/role/version/locale security trimming — all require the identity and CMS/DB layers from later phases.

Per `AI2N_Docs_Training_Subdomain_Claude_Development_Specification_v1.0.docx` §16: "For uncertain requirements, create a clear assumption ... and keep the implementation configurable." This file is that record, updated per phase.

## Phase 2 (2026-08-29) — Documentation Experience

Added, per spec §17 Phase 2 scope (still static-first, no CMS/DB yet):

- **VersionSelector and LanguageSelector** controls in the global header (static — v1.6/v1.5 and English only, no real switching logic yet).
- **One fully-authored article per remaining role/family**, each following the exact Article Template used in Phase 1's Student → Dashboard article:
  - Teacher → *Setting Up a Class*
  - Parent/Guardian → *Linking a Student to Your Account*
  - School Administration → *Managing Your School's People Directory* (grounded in the real, already-shipped People Directory unification + Education Board filter work)
  - Platform Administration → *Managing Tenants and Schools*
  - Content & Curriculum (new collection, previously listed with no content) → *Content Studio: Uploading and Publishing Curriculum Assets* (grounded in the real `content_assets`/`curriculum_pages` draft→review→approve→publish workflow and Content Studio routes found in `api/app.js`/`api/migrate.js`)
  - Governance (new collection, previously listed with no content) → *Class Galleries: Consent and Media Safety* (grounded in the real `gallery_items` table's `consent_checked` field and the shipped Class Galleries admin feature)
- All new articles use verified, already-audited product behavior as their source — none of the procedural detail is invented; where a step couldn't be verified against real code/features, it was written at the level of "how this class of platform generally works" rather than asserting a specific UI element that hasn't been confirmed.
- Every remaining stub item across all 7 collections stays a "Pending" badge, not a dead link — 20 pages total, checked programmatically for broken internal links (0 found) before deploy.
- Redeployed to `app-ai2n-docs-qa` / `docs.ai2n.ai` — live and verified.

## Phase 1 — Foundation (shell, homepage, four menus, static content fixtures)

## Decisions made with the user before starting

1. **Priority**: build now, in parallel with the separate ai2n.ai landing-page task (different files, no overlap).
2. **Tech stack for Phase 1**: match this repo's existing pattern (static HTML + Express-on-App-Service, no build step, no shared component/include system — every other `*.ai2n.ai` site here works this way) instead of starting the spec's full Next.js 15 / Azure AI Search / Entra External ID stack immediately. The full stack is deferred to a later phase once this lighter version is validated — see "Deferred to a later phase" below.

## Assumptions

- **Domain/hosting**: no `docs.ai2n.ai` Azure resource exists yet. This phase only produces local files; no App Service, Front Door, or DNS record has been created. Deploying this to a live QA hostname is a separate, explicit step (matches the "no irreversible infrastructure actions" instruction in the spec, and the user's standing "QA only, nothing without approval" policy noted in prior sessions).
- **Design tokens**: used the exact palette from spec §8.1 (`#092E52` navy / `#00A3A3` teal / `#DDF5F4` teal tint / `#F28C28` orange / `#1B2A3A` ink / `#5A6B7B` muted / `#F3F7FA` surface / `#CFD9E2` border). This is deliberately a **different** palette from the marketing site's saffron/navy theme — docs.ai2n.ai is treated as its own product per the spec, not a re-skin of `robotspace-ai2n.ai`.
- **Content source**: `AI2N_AI-STEM_Complete_LMS_Platform_Requirements_v1.6.docx` (the spec's stated source of truth for role/product content) was not available to read in this session. Article content below Student → Dashboard is therefore structural/navigational only (real collection and article titles from spec §3), not fully authored — each stub item is rendered as inert text with a "Pending" badge rather than a dead link, so there are no broken links or orphan pages per spec §9.2.
- **One fully worked article**: "Understanding Your Student Dashboard" was written using verified content already live on `learn.ai2n.ai` (Continue Learning card, XP/level panel, weekly goal/streak, Robot Buddy AI tutor, launch grid, progress/evidence panel) — chosen specifically so it demonstrates the full Article Template (§3.1) with real, not invented, product behavior.
- **Search**: the Ctrl/Cmd+K dialog is a UI stub (opens, focuses an input, closes on Escape/outside-click) with no indexing behind it yet — Azure AI Search integration is explicitly Phase 3 per spec §17.
- **Sign-in**: the header "Sign in" control is a placeholder link; no identity provider is wired up (Entra integration is Phase 6 per spec §17 / §11).
- **404 handling**: this is a real multi-page site, so unlike the marketing SPA sites' pattern (rewrite everything to `index.html`), unmatched paths return an actual `404.html` — treated as more correct for a documentation portal than a silent redirect to the homepage.

## Deferred to a later phase (explicitly out of scope for this pass)

- Next.js migration, Azure AI Search, Entra External ID/B2C identity, API Management/BFF, PostgreSQL-backed CMS workflow (draft→review→approve→publish), training engine (enrollment/progress/certificates), OpenAPI explorer, webhook docs beyond the static list, and any Azure infrastructure provisioning.
- Full authoring of every collection listed in spec §3 (only Student → Dashboard is a real article; everything else is a navigable but unauthored stub).
- Rolling the per-page "Help" deep link out across every page of every `*.ai2n.ai` product — only one demonstration instance was wired (see the top-level report for which page and why).

## Route map (Phase 1)

```
/                                            homepage (hero+search stub, 4 menu cards, quick-starts, status strip, dev band)
/platform-documentation/                     menu 1 index — 8 role/capability families
/platform-documentation/student/             Student collection index
/platform-documentation/student/dashboard.html   ← fully worked article
/platform-documentation/teacher/             Teacher collection index
/platform-documentation/parent/              Parent/Guardian collection index
/platform-documentation/school-admin/        School Administration collection index
/platform-documentation/platform-admin/      Platform Administration collection index
/role-based-training/                        menu 2 — 6 academies with learning paths
/developer-integration/                      menu 3 — API/webhooks/data-model/SDK sections
/release-notes-support/                      menu 4 — release notes, upgrade guides, known issues, status, help centre, tickets
/404.html
```