docs: add Docus documentation site for @please-auth

[amondnet]

Summary

• Add Docus v4-based documentation site in apps/docs/
• Landing page with hero section and package cards
• Getting Started section (introduction, installation)
• Waitlist plugin docs (server options, client helpers, API endpoints, error codes, schema)
• Firestore adapter docs (configuration, field mapping, transactions, capabilities)
• Navigation with section icons and sidebar grouping

Test plan

• Run cd apps/docs && bun run dev to verify dev server starts
• Verify landing page renders with hero and package cards
• Navigate through all documentation pages
• Check sidebar navigation and table of contents

---

Summary by cubic

Adds a Docus-based docs site for @please-auth in apps/docs, with a landing page and docs for @please-auth/waitlist (including client helpers and reactive atoms) and @please-auth/firestore. Installation notes now include @better-auth/core; Firestore docs clarify db is TypeScript-optional but required at runtime, and the OR query docs are corrected.

• New Features

  • Docs app in apps/docs (Nuxt + docus) with landing page, sidebar nav, on-page TOC, SEO, and GitHub links.
  • Getting Started and Installation, now including @better-auth/core as a peer dependency.
  • @please-auth/waitlist docs: server options, client helpers + reactive atoms, endpoints, error codes, schema.
  • @please-auth/firestore docs: configuration, field mapping, transactions, corrected OR query behavior, and clarified db requirement.
  • Removed duplicate GitHub social link; rely on github config for header/footer icon.

• Dependencies

  • Pin docus to ^5.8.1; add nuxt; bump better-sqlite3 to ^12.5.0 in apps/docs; update bun.lock.

^{Written for commit a3f6fb1. Summary will update on new commits.}

[cubic-dev-ai]

2 issues found across 16 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/docs/package.json">

<violation number="1" location="apps/docs/package.json:11">
P2: Avoid using the `latest` tag for dependencies; pin to a specific version range to keep builds reproducible.</violation>
</file>

<file name="apps/docs/content/docs/3.adapters/1.firestore.md">

<violation number="1" location="apps/docs/content/docs/3.adapters/1.firestore.md:127">
P2: The docs incorrectly state that Firestore does not natively support OR across different fields. Update this wording to avoid spreading incorrect platform limitations.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant User as Developer / Browser
    participant Docus as apps/docs (Nuxt/Docus)
    participant Client as @please-auth/waitlist/client
    participant Server as Better Auth Server
    participant Plugin as @please-auth/waitlist (Plugin)
    participant Adapter as @please-auth/firestore (Adapter)
    participant DB as Cloud Firestore

    Note over User,Docus: NEW: Documentation Access Flow
    User->>Docus: GET /docs/getting-started
    Docus-->>User: Rendered Markdown Content

    Note over User,DB: NEW: Waitlist Gating & Firestore Persistence Flow

    User->>Client: waitlist.join({ email })
    Client->>Server: POST /waitlist/join
    Server->>Plugin: Process Join Request
    Plugin->>Adapter: Create Waitlist Entry
    Adapter->>Adapter: CHANGED: Map camelCase to snake_case
    Adapter->>DB: setDoc(waitlist_entries, { email, status: 'pending' })
    DB-->>Server: Success
    Server-->>User: 200 OK (lookupToken)

    Note over User,DB: Registration with Interception

    User->>Server: POST /sign-up/email (with inviteCode)
    
    rect rgb(240, 240, 240)
        Note right of Plugin: NEW: Request Hook Interception
        Server->>Plugin: onBeforeRequest (interceptPaths)
        Plugin->>Adapter: verifyInviteCode(inviteCode)
        Adapter->>DB: getDoc(waitlist_entries)
        DB-->>Plugin: Entry Found & Approved
        Plugin-->>Server: Allow Proceed
    end

    Server->>Server: Create User Session
    
    rect rgb(240, 240, 240)
        Note right of Plugin: NEW: Database Hook (Secondary Gate)
        Server->>Plugin: onAfterUserCreation
        Plugin->>Adapter: updateStatus(email, 'registered')
        Adapter->>Adapter: NEW: Field Mapping (e.g. userId -> user_id)
        Adapter->>DB: updateDoc (Transactions supported)
    end

    Server-->>User: 200 OK (Authenticated)

    alt NEW: Invalid or Missing Invite Code
        Plugin-->>Server: Throw WAITLIST_ERROR_CODES.NOT_APPROVED
        Server-->>User: 403 Forbidden
    end

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}