{
  "id": "2026-05-07-b2bea-org-surface-specs-f703217645",
  "scope": "redkey",
  "source_of_truth": "repo",
  "source_path": "docs/specs/2026-05-07-b2bea-org-surface-specs.md",
  "source_kind": "markdown",
  "visibility": "internal",
  "renderer_id": "design_doc.dreamborn-forge.generated.v1",
  "design_system": "dreamborn-design-system:forge",
  "generated_at": "2026-05-09T13:00:55.732Z",
  "artifact_type": "design_doc",
  "schema_version": "design_doc.generated.v1",
  "title": "B2BEA.org V1 Surface Specs",
  "summary": "B2BEA.org V1 Surface Specs Source of record: RedKey Supabase Studio artifact. Project: B2BEA.org Rebuild Project ID: a820dd0c 6cef 4133 bfbd d802fd806e44 Artifact: surface specs Artifact ID: 77853042 e7a4 48bd 91a4 6e48d0484b1b Version: 11 Status: draft Updated: 2026 05 07T15:35:22.233+00:00 Purpose Define the concrete public, admin, member, vendor, company,...",
  "format_source": "markdown",
  "sections": [
    {
      "title": "B2BEA.org V1 Surface Specs",
      "level": 1,
      "body": "Source of record: RedKey Supabase Studio artifact.\n\n- Project: `B2BEA.org Rebuild`\n- Project ID: `a820dd0c-6cef-4133-bfbd-d802fd806e44`\n- Artifact: `surface-specs`\n- Artifact ID: `77853042-e7a4-48bd-91a4-6e48d0484b1b`\n- Version: `11`\n- Status: `draft`\n- Updated: `2026-05-07T15:35:22.233+00:00`"
    },
    {
      "title": "Purpose",
      "level": 2,
      "body": "Define the concrete public, admin, member, vendor, company, auth, and publishing surfaces that implementation must build against after the current-site reverse-engineering and hardening specs."
    },
    {
      "title": "Status",
      "level": 2,
      "body": "draft"
    },
    {
      "title": "Basis",
      "level": 2,
      "body": "- Current-state research artifact maps existing Eleventy/Nunjucks layouts, partials, routes, and surface roles.\n- Capability map identifies carry-forward and gap capabilities across public, admin, member, vendor, and company workflows.\n- Design-system spec uses Lovable as the initial foundation/reference, while the hardened B2BEA design system is the V1 authority for non-excluded surfaces.\n- Publishing, data, entitlement, and company-workspace specs define source-of-truth and lifecycle boundaries."
    },
    {
      "title": "Revision Note",
      "level": 2,
      "body": "Linked draft survey-system-spec artifact."
    },
    {
      "title": "Global Decisions",
      "level": 2,
      "body": "| id | topic | decision |\n| --- | --- | --- |\n| SURF-DEC-001 | Surface separation | Public, auth/account, B2BEA admin, publishing/studio, member, vendor, and practitioner company workspace are separate surfaces sharing foundations, not one large page set. |\n| SURF-DEC-002 | Company public presence | Practitioner company accounts are private workspace only in V1. Do not build public practitioner company profiles or a public practitioner company directory. |\n| SURF-DEC-003 | Vendor public presence | Vendor public profiles and vendor directory remain V1 public surfaces. Vendor-authored/profile changes require B2BEA review before changing the public projection. |\n| SURF-DEC-004 | Design language | All in-scope surfaces use hardened B2BEA design-system component contracts. Home, intentionally editorial blog/resource pages, and approved custom HTML imports may be exceptions but still require accessibility, metadata, responsive, and QA compliance. |\n| SURF-DEC-005 | Source of truth | Sanity owns editorial/public page content; B2BEA Supabase owns application and operational data; HubSpot owns CRM/pipeline/sales activity and renewals. |\n| SURF-DEC-006 | Publishing control | Core admins can publish standard Sanity pages and approved custom HTML imports after preview and required metadata validation; external/vendor/company submissions route through review workflows. |"
    },
    {
      "title": "Surface Decisions",
      "level": 2,
      "body": "| id | topic | status | decision | rationale | decided_at | implications | v1_keep |\n| --- | --- | --- | --- | --- | --- | --- | --- |\n| SURF-OWNER-DEC-001 | Custom versus B2BEA design-system page treatment | approved_direction | Home, major campaign/resource landing pages, approved custom HTML imports, and explicitly marked signature editorial features may stay custom. All index, directory, search/filter, standard detail, gated download, operational, and authenticated surfaces use the hardened B2BEA design system. | This preserves flexibility for high-value custom storytelling while preventing the rebuild from recreating page-by-page drift across reusable page families and operational surfaces. | 2026-05-07T13:33:47.840Z | Page-template-spec must include an exception marker for custom/signature pages., Custom pages still require accessibility, responsive, metadata, analytics, and QA compliance., Default implementation path for blog/resource indexes, standard details, directories, filters, downloads, forms, and portals is B2BEA design-system components. |  |\n| SURF-OWNER-DEC-002 | Private workspace route prefixes | approved_direction | V1 private workspace prefixes are /vendor for vendor users and /company for practitioner company users. Both are authenticated surfaces. /company has no public company profile or public directory behavior in V1. | Short actor-aligned prefixes are clearer than /portal/vendor or /workspace/company and avoid implying a generic portal architecture before it is needed. | 2026-05-07T13:35:10.892Z | /vendor/* routes are vendor-authenticated workspace routes, separate from public vendor profile/directory pages., /company/* routes are private practitioner company workspace routes only., Route guards and navigation must not expose /company as a public profile or directory surface., Page-template-spec should use /vendor and /company as canonical private prefixes. |  |\n| SURF-OWNER-DEC-003 | Admin and publishing shell structure | approved_direction | V1 uses a single authenticated admin shell. Publishing/Studio is an admin module inside /admin rather than a separate top-level /studio shell. | B2BEA admin users can manage operations and publishing from one control plane. This reduces navigation fragmentation while preserving publishing-specific workflows and components as a distinct module. | 2026-05-07T13:35:53.103Z | /admin is the canonical authenticated admin shell., Publishing routes should live under an admin module such as /admin/studio or /admin/publishing unless route inventory exposes a stronger existing convention., Current /studio routes should be treated as legacy/current-state routes to migrate, redirect, or mount under /admin., Publishing keeps its lifecycle model: draft, preview, scheduled, published, archived, rolled_back., Page-template-spec should define admin module navigation rather than a separate Studio shell. |  |\n| SURF-OWNER-DEC-004 | V1, deferred, and removed route classification rule | approved_direction | V1 keeps the public content/discovery/membership surfaces, auth/account surfaces, a single /admin shell, /vendor private workspace, /company private workspace, and member profile/dashboard surfaces. V1 defers public practitioner company profiles/directories, advanced certification/event/survey/form/notification/export systems unless required by launch. Legacy duplicate or one-off routes are removed or redirected into canonical page families during route inventory. | Classifying by surface first gives route inventory a clear working rule without prematurely deciding every individual route before the actual route scan. | 2026-05-07T13:37:50.795Z | Route-family inventory should tag each current route as v1_keep, defer, remove, or redirect., Every v1_keep route must map to a page family or approved custom exception., Deferred routes should retain rationale and dependencies, not disappear silently., Removed/redirected routes need canonical target or explicit no-replacement decision. | Public core pages: home, about, join/contact, topic pages, Public content: blog, insights, resources, guides, reports, Public directories: vendors/exchange, people, careers/jobs, courses, events, Auth/account: login, signup, confirm email, checkout/upgrade, Single /admin shell including publishing/studio module, /vendor private vendor workspace, /company private practitioner company workspace, Member profile/dashboard/account surfaces |\n| SURF-OWNER-DEC-005 | Maturity assessment versus general survey system | approved_direction | Current maturity assessment stays in V1 as a bounded special assessment flow and the first reusable maturity-assessment pattern. Future maturity assessments for other areas should reuse this pattern. A broader standard survey/form engine is still needed but remains a separate capability/spec. |  | 2026-05-07T13:54:48.203Z | Do not defer /assessments/maturity routes solely because the general survey system is not ready., Do not force maturity assessments into the generic survey builder before modeling the maturity-specific UX/data/scoring pattern., page-template-spec should include maturity_assessment_special_flow., survey-system-spec remains a next artifact for standard surveys/forms. |  |"
    },
    {
      "title": "Surface Catalog",
      "level": 2,
      "body": "| id | name | actors | purpose | acceptance | exclusions | page_families | required_patterns |\n| --- | --- | --- | --- | --- | --- | --- | --- |\n| public_site | Public Site | anonymous_visitor, authenticated_member, vendor_prospect, practitioner_prospect, search_engine, ai_crawler | Marketing, editorial, discovery, directories, resources, academy previews, events, jobs, public people profiles, and public vendor profiles. | Each public route maps to one page family or an approved exception., Public vendor profiles render from reviewed/published vendor projection only., Protected resource/course access is checked server-side through entitlement rules., Directory filters, search, and cards share one reusable contract across people/vendors/jobs/courses/resources where practical., Archived or draft public content is absent from navigation, search index, and sitemap. | public practitioner company profile pages, public practitioner company directory, ungated protected resource downloads through client-side state only | marketing_home_or_landing, standard_content_page, editorial_index, editorial_detail, directory_index, profile_detail, resource_index, resource_detail_or_download, course_catalog, course_preview_or_lesson_gate, job_board, job_detail, event_index, event_detail, topic_hub, custom_html_import | global navigation and search modal, standard page header with B2BEA design-system page title scale unless marked editorial/custom, directory filter/search bar with stable mobile controls, profile/detail card pattern, resource download/gating state pattern, auth-aware CTA pattern, empty/loading/error states for client-backed lists, SEO/GEO/social metadata per publishable page |\n| auth_account | Auth And Account | anonymous_visitor, authenticated_user, member, vendor_user, company_user, admin | Login, signup, email confirmation, password/magic-link/OAuth, account routing, and shared access failure states. | A user with multiple roles can reach the correct surfaces without role overwrite., Account and membership status is explainable from entitlement evaluator output., Client state cannot grant protected resource/course/vendor/company/admin access. |  | auth_form, email_confirmation, account_settings, checkout_or_upgrade, access_denied_or_upgrade_gate | single auth layout, role-aware post-login routing, return URL preservation, clear denied/expired/upgrade states, server-side access verification for protected actions |\n| b2bea_admin | B2BEA Admin | justin, brett, sarah, b2bea_admin | Single authenticated admin control plane for operational records, review workflows, publishing/studio modules, users, vendors, companies, academy, jobs, categories, media, dashboard metrics, and system governance. | Admin pages do not use large public marketing hero patterns., Every reviewable external submission has status, owner, timestamp, decision, and audit trail., Admin direct-publish capabilities are limited to core admins and still require metadata validation., Admin can see why a member/vendor/company has access before changing entitlements. |  | admin_dashboard, admin_table_index, admin_record_detail, admin_create_edit_form, admin_review_queue, admin_settings_or_taxonomy, admin_metrics_panel, admin_publishing_dashboard, standard_page_editor, custom_html_import_registry, media_library, preview_publish_panel, metadata_editor | compact operational layout, admin nav and breadcrumbs, table/list with filters and saved status pills, drawer/detail/edit workflow, review queue states: submitted, changes_requested, approved, rejected, published, archived, audit/event side panel for sensitive records, empty/loading/error states, bulk actions only where policy permits, module navigation for operations versus publishing, publishing lifecycle states: draft, preview, scheduled, published, archived, rolled_back, metadata validation before publish, preview/publish/archive/rollback controls |\n| admin_publishing_module | Admin Publishing Module | justin, brett, sarah, content_admin | Publishing/content production module inside the single /admin shell. | Core admins can publish standard Sanity pages without developer intervention., Custom HTML import cannot bypass header/footer/metadata rules unless explicitly marked full-custom., Every published item has canonical URL, metadata, preview evidence, and rollback/archive path. |  | content_dashboard, standard_page_editor, custom_html_import_registry, media_library, preview_publish_panel, metadata_editor | content status lifecycle: draft, preview, scheduled, published, archived, custom HTML lifecycle: draft, preview, published, archived, rolled_back, required SEO/GEO/social metadata validation before publish, preview URL for all publishable items, asset validation and approved external URL handling, rollback/archive controls for custom imports |\n| member_portal | Member Portal And Profile | member, pro_member, author, community_leader | Member dashboard, profile/account editing, member/pro resources, academy progress, community identity, and career profile management. | Members see only their own profile/account/progress data unless data is intentionally public., Pro member and standard member access are visibly and server-testably different., Profile visibility settings control public projection and search exposure. |  | member_dashboard, profile_editor, resource_library, academy_progress, career_profile, settings_or_billing_status | personal dashboard summary, profile completion and visibility controls, membership/pro entitlement display, course progress and certificate state display, resource gate with upgrade/expired/access-denied states, account-safe edit/save/error patterns |\n| vendor_portal | Vendor Portal | vendor_admin, vendor_member, b2bea_admin | Vendor workspace for profile management, team access, leads, sponsorship/content/resource/course/event submissions, and own-account analytics. Public vendor profile remains public but reviewed. | Vendor-authored changes do not alter public profile until reviewed by B2BEA admin., Vendor users cannot access another vendor account by URL or client state changes., Exports are bounded to own-account aggregates and permitted lead details only., Public vendor profile URL and metadata remain stable across private workspace edits. |  | vendor_dashboard, vendor_profile_editor, vendor_team_management, vendor_submission_queue, vendor_leads_analytics, vendor_billing_membership | private vendor dashboard, public profile preview and submitted-change review flow, team member roles and invitation states, own-lead and own-analytics views only, submission workflow for resources/courses/events/sponsorships, billing/membership status display or HubSpot/Stripe handoff state |\n| company_workspace | Practitioner Company Workspace | company_admin, company_employee, b2bea_admin | Private company account surface for employees, seats, academy assignments, company-created job submissions, entitlements, and own-company reporting. | No practitioner company workspace data is exposed on a public profile route in V1., Company admins can invite/remove employees and seat access changes affect entitlements through the evaluator., Company-created jobs cannot become public without B2BEA admin approval., Company exports include only own-company data and exclude platform-wide comparisons or sensitive user-level data unless explicitly consented and permitted. | public company profile pages, public company directory, company-owned CRM pipeline | company_dashboard, company_roster, company_invites, company_seats_entitlements, company_academy_assignments, company_jobs_review_status, company_analytics_exports, company_settings | private-only workspace shell, employee invite/accept/remove lifecycle, seat assignment/revocation state display, academy assignment and progress reporting, job submission status: draft, submitted_for_review, changes_requested, approved, published, expired, archived, own-company analytics/export controls, audit trail for employee, seat, academy, job, export, and settings changes |"
    },
    {
      "title": "Shared Contracts",
      "level": 2,
      "body": "```json\n{\n  \"design\": [\n    \"Use B2BEA design-system tokens and page/header/control/card/table/form contracts for all in-scope surfaces; Lovable remains the starting reference only.\",\n    \"Admin/portal surfaces use compact operational hierarchy, not public marketing heroes.\",\n    \"Cards do not nest inside decorative cards; tables and filters use stable dimensions on mobile.\",\n    \"Exceptions require explicit page family marker and still pass accessibility/responsive/metadata QA.\"\n  ],\n  \"navigation\": [\n    \"Public nav must not expose private workspace routes unless authenticated and entitled.\",\n    \"Admin/vendor/company/member surfaces use surface-specific navigation with a clear return path to public site.\",\n    \"Cross-surface links preserve return URL when auth is required.\"\n  ],\n  \"permissions\": [\n    \"Server-side guard is required for all protected actions and protected data reads.\",\n    \"Client UI can hide controls but cannot be the source of authorization.\",\n    \"Entitlement decisions must be traceable to subject, resource, entitlement key, source record, and reason.\"\n  ],\n  \"state_model\": [\n    \"Every data-backed surface defines loading, empty, error, unauthorized, expired, draft, published/active, archived, and deleted/removed states as applicable.\",\n    \"External submissions use review statuses instead of direct public mutation.\",\n    \"Archived records are hidden from public discovery by default.\"\n  ],\n  \"publishing_and_metadata\": [\n    \"Every public route has a canonical URL and metadata contract.\",\n    \"Draft/preview/scheduled content is not indexed or linked publicly.\",\n    \"Slug changes require redirect handling.\",\n    \"Custom HTML imports must declare owner, route, status, metadata, asset bundle, preview URL, and rollback/archive path.\"\n  ]\n}\n```"
    },
    {
      "title": "Qa Release Readiness",
      "level": 2,
      "body": "```json\n{\n  \"summary\": \"Release readiness gates for route conformance, design-system conformance, permission boundaries, publishing safety, responsive/browser smoke, data/migration safety, and final release acceptance.\",\n  \"version\": 1,\n  \"artifact_id\": \"b523c55c-a22a-4ba6-94c0-d306656e57f7\",\n  \"artifact_type\": \"qa-release-readiness-spec\",\n  \"blocks_build_until_plan_review\": true\n}\n```"
    },
    {
      "title": "Hard Stops Before Build",
      "level": 2,
      "body": "- Do not start rebuild implementation until surface specs, page-template-spec, core data/entitlement specs, and implementation plan are reviewed.\n- Do not build public practitioner company profiles or a public practitioner company directory in V1.\n- Do not let vendor/company/member client state grant access or publish public records.\n- Do not preserve page-specific CSS for shared controls, cards, forms, filters, nav, tables, or page headers.\n- Do not let Sanity, Supabase, and HubSpot own the same operational record without a documented source-of-truth boundary."
    },
    {
      "title": "Acceptance Criteria",
      "level": 2,
      "body": "- Each V1 surface has named actors, purpose, route families, page families, data sources, required patterns, exclusions, and acceptance checks.\n- Surface boundaries align with current design, publishing, data, entitlement, and company-workspace specs.\n- Page-template-spec can be produced from this artifact without resolving major surface ownership questions.\n- Implementation agents can tell whether a route belongs to public, auth/account, admin, publishing/studio, member, vendor, or company workspace.\n- All P0 public/private exposure decisions are explicit, especially vendor public profiles versus private practitioner company workspaces."
    },
    {
      "title": "Next Artifacts",
      "level": 2,
      "body": "- qa-release-readiness-spec\n- plan\n- sanity-schema-spec\n- custom-html-import-spec\n- notification-spec\n- academy-certification-spec\n- vendor-portal-workflow-spec"
    },
    {
      "title": "Linked Artifacts",
      "level": 2,
      "body": "```json\n{\n  \"qa_release_readiness_spec\": {\n    \"id\": \"b523c55c-a22a-4ba6-94c0-d306656e57f7\",\n    \"version\": 1\n  }\n}\n```"
    },
    {
      "title": "Source Artifacts",
      "level": 2,
      "body": "| id | status | version | artifact_type |\n| --- | --- | --- | --- |\n| 0555c2b6-6f1f-41e5-bacb-7ca169b32fd5 | draft | 1 | blueprint |\n| c889a1fe-c3ce-4b0d-873c-af4e0ec8dfe4 | draft | 5 | capability-map |\n| 05e0ed7c-416a-4d8f-853a-bc3dfa3d64f6 | draft | 1 | company-workspace-data-spec |\n| 2f473004-9063-4fe9-8290-5cbd1b19dfb4 | draft | 1 | data-model-spec |\n| 4c3651ac-9a69-4117-a355-750b61f540c9 | draft | 2 | design-system-spec |\n| 355b3249-3af9-45a4-9c45-67777bd2d72d | draft | 1 | entitlement-model-spec |\n| a7044f26-904f-430a-a3c6-219f392c3a2b | draft | 1 | feature-ux-spec |\n| c97be414-3dde-4085-9f57-fc38632d2de0 | draft | 1 | intent |\n| dcfc8620-9f28-4019-aeeb-de3e279fd7a7 | draft | 3 | permission-lifecycle-matrix |\n| 80328220-3deb-4cf9-a68f-d440b41a38da | draft | 3 | production-readiness-gap-register |\n| a9636e2f-a4be-4586-82dd-c1a7bf3199fa | draft | 1 | publishing-model-spec |\n| f6210edd-8414-41e9-a5d2-2e3d49ae4b18 | draft | 2 | research |"
    },
    {
      "title": "Page Template Spec Artifact",
      "level": 2,
      "body": "```json\n{\n  \"status\": \"draft\",\n  \"version\": 1,\n  \"artifact_id\": \"427c04a9-40b7-4e55-a642-65b2aee20b2b\",\n  \"family_count\": 26,\n  \"generated_at\": \"2026-05-07T14:36:17.481Z\",\n  \"artifact_type\": \"page-template-spec\"\n}\n```"
    },
    {
      "title": "Survey System Spec Artifact",
      "level": 2,
      "body": "```json\n{\n  \"status\": \"draft\",\n  \"version\": 1,\n  \"artifact_id\": \"823d14d7-5992-42f3-a2f4-f4738a045f7c\",\n  \"generated_at\": \"2026-05-07T15:32:18.075Z\",\n  \"artifact_type\": \"survey-system-spec\"\n}\n```"
    },
    {
      "title": "Route Family Inventory Artifact",
      "level": 2,
      "body": "```json\n{\n  \"status\": \"draft\",\n  \"version\": 1,\n  \"artifact_id\": \"2cec821e-07ba-4aca-81fb-078f163adf44\",\n  \"route_count\": 97,\n  \"generated_at\": \"2026-05-07T13:44:29.161Z\",\n  \"artifact_type\": \"route-family-inventory\",\n  \"by_disposition\": {\n    \"defer\": 4,\n    \"v1_keep\": 90,\n    \"redirect\": 3\n  },\n  \"by_target_surface\": {\n    \"b2bea_admin\": 11,\n    \"public_site\": 70,\n    \"auth_account\": 8,\n    \"member_portal\": 7,\n    \"vendor_portal\": 1\n  }\n}\n```"
    }
  ],
  "html_path": "artifacts/2026-05-07-b2bea-org-surface-specs-f703217645.html",
  "json_path": "artifacts/2026-05-07-b2bea-org-surface-specs-f703217645.json"
}