TenantAtlas/specs/215-website-core-pages/spec.md

Feature Specification: Website Information Architecture / Core Pages

Feature Branch: 215-website-core-pages
Created: 2026-04-19
Status: Draft
Input: User description: "Define the initial information architecture and core public pages for apps/website, including required pages, page roles, navigation, route model, optional surfaces, trust/legal/update rules, and explicit exclusion of apps/platform and page-level design."

Spec Candidate Check (mandatory - SPEC-GATE-001)

• Problem: apps/website currently risks inheriting its page inventory from theme defaults or ad hoc page requests instead of from a deliberate buyer journey and product-truth model.
• Today's failure: Early website work can produce too many thin pages, unclear navigation, buried trust signals, and premature prominence for pricing, docs, or content hubs before product understanding is solid.
• User-visible improvement: Visitors can understand what the product is, why it matters, why it is credible, and what to do next without navigating a bloated or immature sitemap.
• Smallest enterprise-capable version: Define a website-local information architecture with required public pages, clear page jobs, a small navigation model, route priorities, and explicit rules for optional and later surfaces.
• Explicit non-goals: Visual page design, hero or section composition, final copy, SEO strategy, CMS decisions, detailed docs IA, Filament or platform theming, platform IA, auth or app routing, pricing-model decisions, and full content drafting.
• Permanent complexity imported: A website-local IA vocabulary for core surfaces, optional surfaces, deferred surfaces, primary navigation, footer navigation, outcome explanation, trust claims, and discoverability rules.
• Why now: The website is early enough that route and navigation decisions can still be shaped before empty prestige pages and template-driven structure become expensive defaults.
• Why not local: Solving IA one page at a time cannot prevent cross-site navigation drift, cannot prioritize trust and buyer understanding consistently, and cannot stop placeholder routes from becoming normalized.
• Approval class: Core Enterprise
• Red flags triggered: New website-local taxonomy for public surfaces; risk of drifting into design-detail work; risk of accidental bleed into apps/platform expectations.
• Score: Nutzen: 3 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 1 | Wiederverwendung: 2 | Gesamt: 11/12
• Decision: approve

Spec Scope Fields (mandatory)

• Scope: workspace
• Primary Routes: Required core routes are /, /product, /trust, /changelog, the primary conversion route /contact, /privacy, and /imprint; the optional initial content surface for this feature is /resources; retained secondary supporting routes may include /legal, /terms, /solutions, and /integrations without core prominence; deferred route families include later /pricing, /docs, and any expanded dedicated solutions-hub structure.
• Data Ownership: Website-owned public IA contract only: page taxonomy, route priorities, navigation model, and public-surface rules. No tenant-owned records, platform data, or shared persistence are introduced.
• RBAC: None. This feature applies to public website surfaces and introduces no authorization model.

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: yes
• New persisted entity/table/artifact?: no
• New abstraction?: yes
• New enum/state/reason family?: no
• New cross-domain UI framework/taxonomy?: yes, but only within apps/website
• Current operator problem: Website contributors and reviewers do not yet have a shared rule set for which public pages deserve prominence, which routes are mandatory, and how product, trust, and next-step surfaces should relate to each other.
• Existing structure is insufficient because: Theme-provided pages and page-local decisions optimize local convenience but do not guarantee a coherent buyer journey, do not prevent empty prestige pages, and do not protect website work from drifting into platform concerns.
• Narrowest correct implementation: A website-only IA specification that defines required pages, optional pages, deferred pages, route priorities, and public-surface rules without prescribing page design or implementation details.
• Ownership cost: Future website work must align with this IA before adding routes, promoting new top-level links, or surfacing public claims that require supporting trust context.
• Alternative intentionally rejected: Allowing page inventory to emerge from theme defaults or from page-by-page requests was rejected because it would prioritize breadth over clarity and create avoidable credibility problems.
• Release truth: Current-release truth for apps/website; this spec must not be interpreted as a shared website-platform contract.

Testing / Lane / Runtime Impact (mandatory for runtime behavior changes)

• Test purpose / classification: Browser
• Validation lane(s): fast-feedback
• Why this classification and these lanes are sufficient: This spec governs public route composition, navigation behavior, and discoverability on a static website surface. Build proof plus browser smoke coverage of representative public routes is the narrowest honest proof; no database, auth, tenant, or platform runtime setup is required.
• New or expanded test families: Focused website smoke coverage for required core routes, global navigation, footer navigation, primary CTA reachability, and optional-surface suppression when content is absent.
• Fixture / helper cost impact: low; browser smoke helpers may expand slightly, but no backend fixtures, seeds, memberships, providers, or session setup are needed.
• Heavy-family visibility / justification: none; validation stays in fast-feedback only.
• Special surface test profile: N/A
• Standard-native relief or required special coverage: Route-level smoke coverage is sufficient; no platform or operator-surface coverage is required.
• Reviewer handoff: Reviewers should confirm that required routes exist, trust remains top-level visible, one primary conversion path is obvious, optional content hubs are not promoted when empty, and no route or navigation obligation leaks into apps/platform.
• Budget / baseline / trend impact: none beyond small website smoke-suite growth.
• Escalation needed: document-in-feature
• Active feature PR close-out entry: Smoke Coverage
• Planned validation commands: corepack pnpm build:website and cd apps/website && corepack pnpm exec playwright test

User Scenarios & Testing (mandatory)

User Story 1 - Understand the product and next step quickly (Priority: P1)

A first-time evaluator can land on the website, understand what TenantPilot / TenantAtlas is, find the most relevant deeper pages, and identify a clear next step without being forced through pricing, docs, or thin placeholder pages.

Why this priority: Product understanding and next-step clarity are the primary purpose of the public website and the strongest reason to keep the IA small.

Independent Test: Review the homepage and global navigation and confirm that a first-time visitor can identify the product surface, trust surface, changelog surface, and primary conversion surface without needing any deferred routes.

Acceptance Scenarios:

1. Given a first-time visitor lands on /, When they review the homepage and primary navigation, Then they can identify what the product is, where to validate trust, and how to take the next step.
2. Given a visitor enters directly on /product, When they want more confidence or a sales path, Then they can reach /trust and the primary contact surface without navigating through unrelated pages.

---

User Story 2 - Validate trust and technical seriousness (Priority: P1)

A technical decision maker or security stakeholder can find a dedicated trust surface that supports public claims about security, isolation, hosting, and operating discipline without relying on vague marketing copy.

Why this priority: Trust is a first-class purchase filter for this product category and must be structurally visible, not buried as footer-only material.

Independent Test: Review /trust and confirm that public trust, hosting, or residency claims have one explicit supporting surface and are not scattered or implied without context.

Acceptance Scenarios:

1. Given a visitor sees a public claim about hosting region, isolation, or operational discipline, When they open /trust, Then they find that claim explained, bounded, or explicitly limited on that page.
2. Given the homepage keeps trust content intentionally concise, When a technical evaluator needs deeper reassurance, Then the IA routes them to /trust rather than forcing them to infer trust from unrelated marketing sections.

---

User Story 3 - See visible product progress (Priority: P2)

A returning visitor or existing follower can verify that the product is evolving by using a dedicated changelog surface instead of hunting across product pages or editorial content.

Why this priority: Visible product motion helps credibility, but it comes after basic product and trust understanding.

Independent Test: Review the core IA and confirm that a returning visitor has a direct route to dated product updates without depending on a blog or resource hub.

Acceptance Scenarios:

1. Given a returning visitor wants to know what changed recently, When they open /changelog, Then they see dated, concrete progress signals in one dedicated surface.
2. Given optional resources or later editorial content is not yet substantive, When the visitor uses primary navigation, Then the IA does not elevate an empty content hub in place of the changelog.

Edge Cases

• Optional /resources content is not ready yet, and the later editorial articles collection is still unpublished, so the website must remain coherent without promoting either surface in primary navigation.
• A public hosting or data-residency claim exists, but no supporting trust explanation is available yet; the claim must be removed or the trust surface must support it before publication.
• A separate /solutions hub is not launched initially, so homepage and product surfaces must still carry buyer-oriented outcome explanation.
• A future /demo route may exist eventually, but /contact remains the clear primary next-step path in the initial IA.
• Docs or pricing material may exist in partial form, but they must not be promoted as primary navigation until they are mature enough to support honest public expectations.

Requirements (mandatory)

Constitution alignment (required): This feature introduces no Microsoft Graph calls, no queueing, no long-running operations, no authorization changes, and no Filament operator surfaces. Its contract is explicitly local to apps/website and must not create obligations for apps/platform.

Constitution alignment (UI-SEM-001 / LAYER-001 / BLOAT-001): This feature intentionally introduces a website-local IA and surface-priority layer because ad hoc route growth and theme-driven page inventories are insufficient to produce a coherent enterprise website. The layer is scoped narrowly to public website surfaces and must not expand into platform IA or a shared website-platform taxonomy without a separate spec.

Implementation boundary: Any implementation under this specification MUST preserve the existing website working contract by keeping @tenantatlas/website, WEBSITE_PORT, and the root dev:website / build:website workflows intact, and it MUST NOT introduce runtime or package coupling to apps/platform.

Functional Requirements

• FR-001: The specification MUST define an initial public information architecture for apps/website that is explicitly local to the website and explicitly excludes apps/platform, platform IA, Filament theming, and app-auth routing decisions.
• FR-002: The initial required core surfaces MUST be Home, Product, Trust, the primary conversion surface /contact, Privacy, and Imprint.
• FR-003: The initial IA MUST classify Changelog as a strongly recommended public surface with a named role in the website journey.
• FR-004: The IA MAY classify Resources as an optional initial surface, but only when substantive content exists and the route is not a placeholder; any later blog/editorial surface MUST remain unpublished until a separate spec activates it.
• FR-005: Pricing, Customers or Case Studies, Careers, Compare or Alternatives, Status, a full Docs portal, and a dedicated Solutions hub MUST be treated as deferred surfaces rather than initial core requirements.
• FR-006: The homepage at / MUST act as a routing, positioning, and trust hub that explains the product at a high level and opens clear paths to Product, Trust, Changelog, and the primary conversion surface.
• FR-007: The homepage MUST include buyer-oriented outcome or use-case explanation and MUST NOT rely on feature taxonomy alone to explain why the product matters.
• FR-008: The product surface at /product MUST explain what TenantPilot / TenantAtlas is, what it is not, how its capability areas are grouped, and how those capabilities relate to buyer outcomes.
• FR-009: The product surface MUST cover, at an appropriate public level, Backup, Restore, Versioning, Audit, Inventory or Drift Detection, and Governance topics such as Baselines, Findings, Exceptions, Evidence, and Reviews.
• FR-010: The trust surface at /trust MUST exist as a first-class public page and MUST cover security and operating principles, a public-safe architecture overview, tenant isolation, credential or access handling, protection measures, update and operating discipline, and a path for deeper trust or security questions.
• FR-011: Any public claim about hosting region, data residency, tenant isolation, or security posture MUST be supported, bounded, or contextualized on /trust, and the website MUST NOT make absolute legal-compliance claims that it cannot responsibly qualify.
• FR-012: The changelog surface at /changelog MUST show dated, concrete product progress and MUST NOT be treated as a replacement for the product page or for long-form editorial content.
• FR-013: The website MUST expose /contact as the clear, low-friction primary conversion surface, and if a demo option exists later, it MUST remain secondary unless a future spec changes the primary conversion route.
• FR-014: The initial top-level navigation MUST remain intentionally small and SHOULD default to Product, Trust, Changelog, optional Resources only when substantive, and Contact, plus one primary CTA.
• FR-015: The brand or logo MUST route visitors to /.
• FR-016: No top-level navigation item or other prominent public link MAY point to a placeholder, thin-content, or template-only page.
• FR-017: Trust MUST remain visible in top-level navigation and MUST NOT be relegated to footer-only discoverability.
• FR-018: The footer MUST group product, trust or legal, contact, and optional content or docs links in a consistent public navigation model.
• FR-019: The initial URL model MUST use short, clear public paths and MUST avoid unnecessary early nesting, artificial segmentation, or mixing marketing routes with app routes.
• FR-020: The website MUST provide a buyer-oriented outcome or use-case explanation layer on the homepage, on the product page, or on both, even if a dedicated /solutions hub is not launched initially.
• FR-021: Docs MAY become discoverable once a minimal, credible documentation surface exists, but the IA MUST NOT force Docs into primary navigation before that threshold is met.
• FR-022: Pricing MAY be introduced later, but the IA MUST NOT force Pricing into primary navigation until packaging, expectations, and public framing are mature enough to be honest and coherent.
• FR-023: The page relationship model MUST support an entry route, a first-clarification phase, a deeper-exploration phase, and a clear action phase ending in Contact.
• FR-024: Public website language and page prioritization MUST favor product truth, trust, outcome understanding, and clear next steps over hype, fake maturity signals, or inflated enterprise theater.
• FR-025: The specification MUST define its deliverables explicitly: required core page list, role of each page, top-level navigation, footer navigation, route model, optional-surface rules, deferred-surface list, outcome-explanation rule, trust-claim rule, and docs-discoverability rule.
• FR-026: No requirement in this specification MAY be interpreted as a commitment to platform routing, platform design, or shared website-platform IA work.
• FR-027: Implementation work under this specification MUST preserve the website working contract by retaining @tenantatlas/website, WEBSITE_PORT, and the root dev:website / build:website workflows, and it MUST NOT introduce runtime coupling or shared-package obligations for apps/platform.

Out of Scope

• Visual design of individual pages
• Hero or section composition
• Final production copy
• SEO keyword planning
• CMS selection
• Detailed documentation IA
• Filament or apps/platform theming
• Platform IA
• Auth or app-routing behavior
• Pricing-model decisions
• Full content drafting for each page

Assumptions

• apps/website must work for enterprise buyers, MSPs, technical decision makers, security or governance stakeholders, and returning followers without creating separate website tracks for each audience in the initial IA.
• Outcome and use-case explanation can live inside Home and Product initially without requiring a dedicated Solutions hub.
• Legal basics must be present from the start, while Docs and Pricing can remain deferred until their public substance is strong enough.
• The initial website should favor a small number of durable public routes over a broad marketing sitemap.
• For Spec 215 execution, the optional content surface standardizes on /resources; the existing editorial articles collection remains unpublished until a later blog/editorial spec activates it.
• Existing /legal, /terms, /solutions, and /integrations pages may remain published as secondary supporting surfaces, but they MUST NOT displace the required core IA in top-level navigation or buyer flow.

Key Entities (include if feature involves data)

• Core Surface: A required initial public page that carries one named job in the buyer journey and is part of the minimal credible website.
• Optional Initial Surface: A page family such as Resources that is allowed in the initial IA only if substantive content exists at launch.
• Deferred Surface: A public page family intentionally excluded from the initial core website until its content, claims, or business model are mature enough.
• Trust Surface: The dedicated public page that supports technical seriousness, trust claims, and bounded public statements about hosting, residency, isolation, and operating discipline.
• Outcome Explanation Layer: The buyer-oriented explanation of operational or business problems solved by the product, expressed without depending on a dedicated Solutions hub.
• Primary Conversion Surface: The main next-step path, Contact in the initial IA, that converts public understanding into a clear action.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: The IA defines 100% of required initial core routes: /, /product, /trust, /changelog, the primary conversion route /contact, /privacy, and /imprint.
• SC-002: 100% of top-level navigation items in the initial IA map to named core or approved optional surfaces with explicit roles, and 0 prominent links point to placeholder or thin-content pages.
• SC-003: From each core entry route (/, /product, /trust, and /changelog), a visitor can reach the primary conversion surface in no more than 2 clicks.
• SC-004: 100% of public hosting, residency, isolation, or security claims in the initial IA have a designated supporting or bounding surface on /trust, or the claim is excluded from the public website.
• SC-005: Reviewers can map the four core buyer questions - what is it, who is it for, why trust it, and what next - to explicit public surfaces without requiring an initial Pricing page, Docs portal, or dedicated Solutions hub.
• SC-006: The initial informational top-level navigation exposes no more than 5 public route entries plus one primary CTA, preserving a deliberately small public IA.

Planned Follow-on Specs

• Spec 216 - Homepage Structure and Section Model
• Spec 217 - Product Page Structure
• Spec 218 - Trust Surface
• Spec 219 - Contact / Demo Flow
• Spec 220 - Changelog Surface
• Spec 221 - Blog / Resources Surface, if activated
• Spec 222 - Solutions / Use-Case Surfaces, if activated later
• Spec 223 - Pricing Surface, if activated later