TenantAtlas/specs/404-public-content-messaging/research.md

Phase 0 Research: apps/website Public Content Architecture & Messaging

Decision: Keep the Spec 402/403 Astro website foundation

Rationale: The active website is a standalone Astro app at /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website with Starlight docs, sitemap generation, Tailwind v4, Preline, Lenis, and Playwright smoke tests already in place. Spec 404 is a content architecture and messaging pass, not another rebuild.

Alternatives considered:

• Rebuild the public website foundation: rejected by scope and unnecessary after Spec 402.
• Introduce a new design system or content framework: rejected because this feature should stabilize copy before Spec 405 visual polish.
• Use apps/platform as a content source: rejected because the public /platform route is separate from the Laravel/Filament application and apps/platform is out of scope.

Decision: Treat content surfaces, CTAs, metadata, and claim posture as the contract

Rationale: This feature has no API endpoints or product runtime entities. The public behavior that matters is expressed through static pages, docs content, navigation/footer links, route metadata, CTA targets, FAQ/trust/pricing/contact copy, and generated public output.

Alternatives considered:

• Generate OpenAPI or GraphQL contracts: rejected because the public website exposes no feature API.
• Model messaging readiness as product runtime state: rejected because it would create unnecessary taxonomy or persistence.
• Leave the contract implicit in copy review comments: rejected because later layout work needs stable section intent and CTA rules.

Decision: Use a homepage narrative from category to evaluation

Rationale: The homepage should tell a coherent story when headings are read in order. The content sequence should move from product category, to buyer problem, to evidence-first governance model, to capability groups, to evaluation and next action.

Alternatives considered:

• Keep independent theme sections with similar claims: rejected because the spec identifies repetition and weak hierarchy as the core problem.
• Lead with pricing or feature grids: rejected because buyers first need category clarity and trust-safe product framing.
• Optimize layout before copy: rejected because section spacing should follow stable content.

Decision: Make /platform the deeper public product-model page

Rationale: The public /platform route should explain how backup, restore, drift, findings, evidence, auditability, exceptions, and reviews fit together as one operating model. It must remain public positioning and must not use or imply internal apps/platform runtime behavior.

Alternatives considered:

• Mirror homepage copy on /platform: rejected because the page should carry deeper product-model explanation.
• Reference admin implementation details: rejected because the public route must not be coupled to Laravel, Filament, Livewire, RBAC, tenant data, or Graph runtime code.
• Present previews as live tenant output: rejected because previews are static/demo content only.

Decision: Keep evaluation and pricing contact-led

Rationale: No self-serve billing, checkout, account creation, instant subscription, fixed entitlement, or automated scheduling workflow has been supplied. Pricing and evaluation language should therefore describe scoped conversations, rollout planning, and contact-led evaluation.

Alternatives considered:

• Publish fixed SaaS plan entitlements: rejected because entitlement and billing truth is not available.
• Use consumer-style pricing tables with strong contrast: rejected because this spec focuses on calm enterprise trust and content clarity, not fake commercial certainty.
• Hide pricing entirely: rejected because buyers still need evaluation expectations and a credible next step.

Decision: Build trust through explicit restraint, not fake proof

Rationale: The spec assumes no verified customer logos, testimonials, certifications, Microsoft partnership proof, uptime guarantees, recovery guarantees, or compliance guarantees. Trust content should explain what Tenantial is intended to help make reviewable and auditable without claiming proof that has not been supplied.

Alternatives considered:

• Use aspirational enterprise proof language: rejected because it creates public trust risk.
• Keep generic "trusted by" or certification placeholders: rejected unless removed or rewritten as neutral proof-safe language.
• Avoid all trust language: rejected because security-conscious buyers need careful explanations of claim boundaries.

Decision: Normalize CTA intent before changing labels

Rationale: CTA consistency should be based on buyer intent. Primary CTAs should lead to contact/demo/walkthrough intent, secondary CTAs should lead to product explanation, trust, pricing, or docs review, and no CTA should imply unavailable workflows.

Alternatives considered:

• Let each page invent local CTA language: rejected because CTA inconsistency is a stated problem.
• Use "Sign up", "Start trial", "Subscribe", "Login", or "Buy now": rejected unless those workflows actually exist.
• Route all CTAs to the same page: rejected because secondary educational CTAs should remain useful and contextual.

Decision: Keep docs exposure intentional

Rationale: Exposed docs routes must contain intentional Tenantial-specific content or be hidden from navigation. Docs must not imply product behavior, support commitments, or integration claims that are not available.

Alternatives considered:

• Leave placeholder docs visible: rejected because public placeholder content weakens trust.
• Remove all docs routes immediately: rejected unless review shows a route is not ready for intentional content.
• Treat non-navigation docs as irrelevant: rejected because emitted public routes still affect public perception and indexing.

Decision: Validate with website build, public smoke, manual browser/content review, and scope checks

Rationale: The current package scripts support corepack pnpm build:website and WEBSITE_PORT=4321 corepack pnpm --filter @tenantatlas/website test:smoke. These lanes prove the public static website without pulling in Laravel runtime cost. Manual review remains necessary for narrative quality and claim safety.

Alternatives considered:

• Run Laravel/Pest/Filament tests: rejected because this feature does not touch apps/platform.
• Rely only on copy review: rejected because public output still needs route, CTA, metadata, responsive, and smoke validation.
• Add new browser test families now: rejected unless implementation changes require them; existing smoke can be updated proportionally during tasks.

Current Source Observations

• Core public pages are under /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/pages.
• Shared public copy and constants are likely to involve /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/data_files/site-copy.ts, /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/data_files/constants.ts, /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/utils/navigation.ts, and /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/components/Meta.astro.
• Starlight/docs content is under /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/content/docs.
• Existing smoke tests live under /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/tests/smoke.
• Public route mirrors exist under /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/pages/en and should be reviewed consistently with German default routes where currently exposed.
• Placeholder content collections for blog, insights, and products exist in /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/content; any public exposure must stay intentional and claim-safe.