> Original design reference. The current PHP implementation adds MySQL persistence, server-enforced accounts, Groq workflows and PDF export. See [current implementation](IMPLEMENTATION.md) for the release scope.

# Administration, access and SEO build specification

## Admin MVP screens
1. Sign-in: admin identity verification, invalid credentials, rate limiting, MFA challenge and recovery. The prototype only simulates a known sample identity.
2. Overview: active/invited/suspended accounts, pending requests, product availability and recent activity.
3. Demo users: searchable list, pagination, account creation/invitation and filtering.
4. User detail: identity, company, status, per-product grants, expiry and audit trail.
5. Product access: global availability plus user-specific entitlements. Define what happens to existing sessions when access changes.
6. Requests: pending/approved/rejected lifecycle; deduplicate by normalised email and workspace; approval creates or updates an account and an entitlement.
7. Traffic: date range, page visits, demo starts, authenticated usage and conversion definitions; label data source and freshness.
8. Activity: access and administrative changes, actor, target, outcome and timestamp; export only for authorised administrators.
9. Settings: default demo duration, retention, notification preferences and programme ownership.

## Prototype behaviour
Admin: `admin@cynaris.example` / `AdminDemo2026!`.
Demo user: `maya@demo.example` / `Demo2026!`.
All created sample demo accounts use `Demo2026!`; these are public demonstration credentials, not secrets. Access checks are client-side design simulations and do not protect data. Accounts, requests and local events live only in sessionStorage for the current tab.

Product access requires an active, unexpired user, an assigned product and globally enabled availability. The sample administrator can preview all products. Suspension, expiry and missing entitlement produce an explanatory login error. No invites or reset emails are sent. No passwords, IP addresses or fingerprints are recorded in the event log.

The traffic report contains explicitly labelled fictional totals. Its local-events section records only events observed in the current tab. It is not an aggregate report of real visitors.

## Production authentication and authorisation
- Use a supported identity service or securely implemented server sessions. Keep sessions in Secure, HttpOnly cookies with an appropriate SameSite policy and CSRF protection.
- Hash passwords on the server when passwords are owned by the application; never store plaintext passwords or client-side verification tables.
- Enforce admin MFA and rate-limit sign-in, invitation and recovery operations.
- Verify identity before granting access; invitations use expiring, single-use tokens.
- Every protected endpoint checks workspace membership, role, account status, product entitlement and expiry. UI checks are only convenience.
- Revoke or re-evaluate sessions when accounts are suspended or entitlements expire.
- Audit administrative changes, including previous/new scope, without storing secrets.
- Separate product owner, tenant administrator and platform administrator capabilities; do not give customers platform-wide administration.

## Suggested endpoints
- `POST /auth/login`, `POST /auth/logout`, `GET /auth/session`, `POST /auth/recovery`.
- `GET/POST /admin/demo-users`, `GET/PATCH /admin/demo-users/:id`.
- `PUT /admin/demo-users/:id/entitlements`, `POST /admin/demo-users/:id/invitations`.
- `GET/PATCH /admin/products/:product/availability`.
- `POST /demo-access-requests`, `GET /admin/demo-access-requests`, `POST /admin/demo-access-requests/:id/review`.
- `GET /admin/analytics/summary?from=&to=`, `GET /admin/analytics/pages`, `GET /admin/audit-events?cursor=`.
- `POST /events` for consent-appropriate product events; reject unrecognised event names and sensitive arbitrary payloads.

## Analytics definitions
- Page view: a deduplicated navigation event, not every rerender.
- Demo start: first authorised product entry in a session.
- Active demo user: a unique authenticated user with at least one qualifying event in the selected window.
- Conversion: successful demo starts divided by eligible visits within a defined attribution window. Do not mix counts from different time windows.
- Traffic source: derive from allowed campaign/referrer data, not guessed user identity.
- Data retention and consent: agree on business purpose, collection basis, expiry, deletion and access. Separate marketing analytics from security audit logs.

## SEO strategy
Public marketing pages should be discoverable; account, admin and authenticated application pages should not be indexed. Search visibility must not expose user or business records.

Implemented preparation:
- Unique, descriptive titles and meta descriptions.
- Semantic HTML and crawlable links, with useful product and solution content present in the initial HTML.
- Canonical URLs built from a configured origin.
- WebSite/Organization identity and BreadcrumbList structured data where appropriate; no fabricated ratings, reviews or offers.
- Open Graph and Twitter title/description metadata without invented imagery.
- XML sitemap of public canonical pages and a robots file.
- `noindex` on app, admin, sign-in and design-handoff pages.
- The private preview remains `noindex` on all routes; production publishing can enable indexing for public pages only.

Run `python3 scripts/prepare_seo.py --origin https://cynaris.ai --production` only when preparing the approved production deployment. It should not be used to make the private prototype publicly indexable. The default command keeps preview noindex and uses the current preview domain.

Production launch checklist:
1. Confirm final domain, HTTPS, canonical host and redirects from old URLs.
2. Ensure private endpoints require real authentication; robots/noindex are not access security.
3. Remove preview noindex only from approved public pages and publish the correct sitemap.
4. Validate structured data and response status codes; return real 404s for missing pages.
5. Check mobile layout, image/font delivery, loading stability and Core Web Vitals using measured data.
6. Verify the domain in Search Console and submit the sitemap after launch.
7. Add verified customer evidence and maintain genuinely useful product content; do not fabricate SEO claims or guarantee rankings.

Primary references:
- https://developers.google.com/search/docs/fundamentals/seo-starter-guide
- https://developers.google.com/search/docs/appearance/title-link
- https://developers.google.com/search/docs/appearance/snippet
- https://developers.google.com/search/docs/crawling-indexing/control-what-you-share
- https://developers.google.com/search/docs/crawling-indexing/javascript/javascript-seo-basics