` | Container | `

Group of elements

` | | `` | *** ## CSS: The Style CSS (Cascading Style Sheets) controls how HTML elements look. ### Adding Styles ```html theme={null} ``` ### CSS Selectors ```css theme={null} /* Select by element */ h1 { color: blue; } /* Select by class */ .card { background: white; } /* Select by ID */ #header { height: 60px; } ``` > [!TIP] > > **Beginner Tip**: Use **classes** (`.classname`) for styles you'll reuse. Use **IDs** (`#idname`) for unique elements. ### The Box Model Every HTML element is a box with **4 layers**. Think of it like a package: ```mermaid theme={null} graph LR subgraph Box["📦 The Box Model"] direction LR M["Margin"] --> B["Border"] --> P["Padding"] --> C["Content"] end style M fill:#fef3c7,stroke:#f59e0b,color:#000 style B fill:#dbeafe,stroke:#3b82f6,color:#000 style P fill:#dcfce7,stroke:#22c55e,color:#000 style C fill:#fce7f3,stroke:#ec4899,color:#000 ``` ![The CSS Box Model](https://mintcdn.com/tuturuuu/LKHVwofYjE5PdgBy/images/workshops/nextjs/box-model.png?fit=max\&auto=format\&n=LKHVwofYjE5PdgBy\&q=85\&s=891c5945fbdf3961e95e939e700d3189) | Layer | What it is | CSS Example | | - | - | - | | 📝 **Content** | Your text, images, etc. | `width: 200px` | | 🧸 **Padding** | Space inside the border | `padding: 20px` | | 🖼️ **Border** | The visible edge | `border: 2px solid black` | | 📦 **Margin** | Space outside the border | `margin: 10px` | **Real-world analogy:** * 📝 **Content** = The gift inside the box * 🧸 **Padding** = Bubble wrap protecting the gift * 🖼️ **Border** = The cardboard box itself * 📦 **Margin** = Space between boxes on the shelf *** ## JavaScript: The Behavior JavaScript makes websites interactive. ### Your First Script ```html theme={null} ``` ### JavaScript Basics ```javascript theme={null} // Variables let name = 'Alice'; const age = 20; // Functions function greet(person) { return `Hello, ${person}!`; } // Calling a function console.log(greet(name)); // "Hello, Alice!" ``` > [!TIP] > > **Beginner Tip**: Use `const` for values that don't change, and `let` for values that might change. Avoid using `var`. ### DOM Manipulation JavaScript can change HTML elements: ```javascript theme={null} // Find an element const heading = document.querySelector('h1'); // Change its content heading.textContent = 'New Title!'; // Change its style heading.style.color = 'red'; ``` *** ## Putting It All Together ```html theme={null} My Interactive Page

Welcome!

Click the button below.

``` *** ## Key Takeaways > **HTML = Structure** > > Defines what content appears on the page > **CSS = Style** > > Controls how content looks > **JS = Behavior** > > Makes content interactive *** ## Learn More > **[HTML Tutorial](https://www.w3schools.com/html/)** > > W3Schools HTML Guide > **[CSS Tutorial](https://www.w3schools.com/css/)** > > W3Schools CSS Guide > **[JavaScript Tutorial](https://www.w3schools.com/Js/)** > > W3Schools JS Guide *** **Next up**: [Tailwind CSS →](/learn/workshops/nextjs-workshop/02-tailwind-css) # Part 2: Tailwind CSS Source: https://docs.tuturuuu.com/learn/workshops/nextjs-workshop/02-tailwind-css Modern, utility-first CSS for rapid UI development > [!NOTE] > > ⏱️ **Duration**: 15 minutes | Learn how to build beautiful UIs without writing custom CSS. ## What is Tailwind CSS? Tailwind CSS is a **utility-first CSS framework**. Instead of writing custom CSS, you apply pre-built classes directly in your HTML. **It's like building with LEGO instead of carving from scratch! 🧱** ```mermaid theme={null} graph LR A["😫 Traditional CSS"] --> B["Write .card class"] B --> C["Switch to CSS file"] C --> D["Write styles"] D --> E["Back to HTML"] E --> F["Repeat forever..."] G["😎 Tailwind"] --> H["Write classes inline"] H --> I["Done! ✅"] style A fill:#fee2e2,stroke:#ef4444,color:#000 style G fill:#dcfce7,stroke:#22c55e,color:#000 ``` ### Traditional CSS vs Tailwind ```css Traditional CSS theme={null} .card { background-color: white; border-radius: 8px; padding: 24px; box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1); } .card-title { font-size: 20px; font-weight: bold; color: #1f2937; } ``` ```html Tailwind CSS theme={null}

Card Title

``` > [!TIP] > > **Why do developers love Tailwind?** You never leave your HTML file. No more context-switching, no more inventing class names like `.card-wrapper-container-inner-box` 😅 > [!NOTE] > > **🤯 Did you know?** Tailwind CSS has over **80,000+ GitHub stars** and is used by Netflix, OpenAI, Shopify, and NASA! *** ## Core Utilities ### Spacing (Padding & Margin) Tailwind uses a simple numbering system for spacing: | Class | Size | Example | | - | - | - | | `p-1` | 4px | `

` | | `p-2` | 8px | `

` | | `p-4` | 16px | `

` | | `p-6` | 24px | `

` | | `p-8` | 32px | `

` | **Variants:** * `p-4` = padding on all sides * `px-4` = padding left and right * `py-4` = padding top and bottom * `pt-4` = padding top only * `m-4` = margin (same pattern) ### Colors Tailwind provides a beautiful color palette: ```html theme={null}

Gray text

Blue text

Red text

White background

Light gray

Blue background

``` **Try it! 👇** Mix and match Tailwind classes: Background Border Color Text Size Font Weight Text Align Rounded Padding: Margin: Border Width: Hello, Tailwind! ### Typography ```html theme={null}

Small

Base (default)

Large

Extra large

2X large

Normal

Medium

Semibold

Bold

``` *** ## Layout with Flexbox Flexbox is incredibly easy with Tailwind: ```html theme={null}

Item 1

Item 2

Item 3

I'm centered!

Left

Right

``` *** ## Building a Card Component Let's build a beautiful card step by step: ```html theme={null}

Card Title

This is a beautiful card built with Tailwind CSS. No custom CSS needed!

``` **Try it! 👇** Click the like button: ![Card](https://picsum.photos/seed/workshop/400/200) ### Interactive Card This card is built with Tailwind CSS. Try the like button below! likes *** ## Responsive Design Add breakpoint prefixes for responsive styles: | Prefix | Screen Width | | - | - | | `sm:` | 640px+ | | `md:` | 768px+ | | `lg:` | 1024px+ | | `xl:` | 1280px+ | ```html theme={null}

Card 1

Card 2

Card 3

``` > [!TIP] > > **Beginner Tip**: Tailwind is "mobile-first". Write styles for mobile, then add `md:` or `lg:` for larger screens. *** ## Hover and Focus States Add interactivity with state prefixes: ```html theme={null} ``` *** ## Quick Reference | What you want | Tailwind class | | - | - | | Rounded corners | `rounded-lg` | | Shadow | `shadow-md` | | Flex row | `flex` | | Flex column | `flex flex-col` | | Center items | `items-center justify-center` | | Full width | `w-full` | | Fixed height | `h-64` (256px) | | Hide on mobile | `hidden md:block` | | Show only on mobile | `block md:hidden` | *** ## Learn More > **[Tailwind CSS Docs](https://tailwindcss.com)** > > The official Tailwind CSS documentation with all utilities. *** **Next up**: [TypeScript →](/learn/workshops/nextjs-workshop/03-typescript) # Part 3: TypeScript Source: https://docs.tuturuuu.com/learn/workshops/nextjs-workshop/03-typescript JavaScript with superpowers - catch bugs before they happen > [!NOTE] > > ⏱️ **Duration**: 15 minutes | Learn how TypeScript helps you write safer, more reliable code. ## Why TypeScript? TypeScript is **JavaScript with types**. It helps you catch errors before running your code. **Think of it as spell-check for your code! 📝✅** ```mermaid theme={null} graph LR A["You write code"] --> B{"TypeScript checks it"} B -->|"❌ Error found"| C["Fix before running"] B -->|"✅ All good"| D["Run with confidence!"] style B fill:#4f46e5,stroke:#3730a3,color:#fff style C fill:#fef3c7,stroke:#f59e0b,color:#000 style D fill:#dcfce7,stroke:#22c55e,color:#000 ``` > [!NOTE] > > **Fun Facts**: > > * TypeScript was created by **Microsoft** and is used by Google, Airbnb, and Slack > * TypeScript is **built with TypeScript** (it compiles itself! 🤯) > * **TypeScript Native v7** is coming soon—rewritten in **Golang** for \~10x faster performance! ### The Problem with JavaScript ```javascript theme={null} // JavaScript - no error until runtime! 💥 function greet(user) { return "Hello, " + user.name; } greet("Alice"); // Runtime error: user.name is undefined ``` ### The TypeScript Solution ```typescript theme={null} // TypeScript - error caught immediately! ✅ function greet(user: { name: string }) { return "Hello, " + user.name; } greet("Alice"); // ❌ Error: string is not assignable to { name: string } greet({ name: "Alice" }); // ✅ Works! ``` > [!TIP] > > **Beginner Tip**: TypeScript acts like a spell-checker for your code. It catches mistakes as you type! *** ## Basic Types ### Primitive Types ```typescript theme={null} // String let name: string = "Alice"; // Number let age: number = 20; // Boolean let isStudent: boolean = true; // Array of strings let hobbies: string[] = ["coding", "gaming", "reading"]; // Array of numbers let scores: number[] = [95, 87, 92]; ``` ### Type Inference TypeScript is smart! It can often figure out types automatically: ```typescript theme={null} // TypeScript knows these types automatically let name = "Alice"; // string let age = 20; // number let isActive = true; // boolean // But you can still add types for clarity let email: string = "alice@example.com"; ``` *** ## Objects and Interfaces ### Typing Objects ```typescript theme={null} // Inline object type let user: { name: string; age: number } = { name: "Alice", age: 20, }; ``` ### Using Interfaces (Recommended) ```typescript theme={null} // Define a reusable type interface User { name: string; age: number; email: string; } // Use it const alice: User = { name: "Alice", age: 20, email: "alice@example.com", }; const bob: User = { name: "Bob", age: 22, email: "bob@example.com", }; ``` ### Optional Properties ```typescript theme={null} interface User { name: string; age: number; email?: string; // Optional (the ? makes it optional) } // Valid - email is optional const user: User = { name: "Alice", age: 20, }; ``` *** ## Functions ### Typed Parameters and Return Values ```typescript theme={null} // Parameters and return type function add(a: number, b: number): number { return a + b; } // Arrow function const multiply = (a: number, b: number): number => { return a * b; }; // Usage add(5, 3); // ✅ Returns 8 add("5", 3); // ❌ Error: string is not a number ``` ### Functions with Objects ```typescript theme={null} interface Product { name: string; price: number; } function getTotal(products: Product[]): number { return products.reduce((sum, p) => sum + p.price, 0); } const cart = [ { name: "Book", price: 15 }, { name: "Pen", price: 2 }, ]; console.log(getTotal(cart)); // 17 ``` *** ## Union Types A variable can be one of several types: ```typescript theme={null} // Can be string or number let id: string | number; id = "abc123"; // ✅ id = 123; // ✅ id = true; // ❌ Error // Useful for optional values let username: string | null = null; username = "alice"; // ✅ ``` *** ## Type Aliases Create custom type names: ```typescript theme={null} // Simple alias type ID = string | number; // Object alias type Point = { x: number; y: number; }; // Usage const userId: ID = "user_123"; const location: Point = { x: 10, y: 20 }; ``` > [!NOTE] > > **Interface vs Type**: Both can define object shapes. Use `interface` for objects you might extend later, `type` for everything else. *** ## Real-World Example ```typescript theme={null} // Define types for a todo app interface Todo { id: number; title: string; completed: boolean; dueDate?: string; } // Type-safe function function toggleTodo(todo: Todo): Todo { return { ...todo, completed: !todo.completed, }; } // Type-safe array operations function getCompletedTodos(todos: Todo[]): Todo[] { return todos.filter((todo) => todo.completed); } // Usage const myTodos: Todo[] = [ { id: 1, title: "Learn TypeScript", completed: true }, { id: 2, title: "Build an app", completed: false }, ]; const completed = getCompletedTodos(myTodos); console.log(completed); // [{ id: 1, title: "Learn TypeScript", completed: true }] ``` *** ## TypeScript in 60 Seconds | Concept | Syntax | Example | | - | - | - | | Basic type | `: type` | `let x: number = 5` | | Array | `type[]` | `let arr: string[]` | | Object | `interface` | `interface User { name: string }` | | Optional | `?` | `email?: string` | | Union | `\|` | `string \| number` | | Function | `(params): return` | `(x: number): number` | *** ## Key Takeaways > **Catch Bugs Early** > > TypeScript finds errors before you run your code > **Better Autocomplete** > > Your editor knows what properties and methods are available > **Self-Documenting** > > Types act as documentation for your code > **Refactor Safely** > > Change code confidently - TypeScript tells you what breaks *** ## ☕ Break Time! Great job making it this far! Take a 5-minute break before we dive into React. *** **Next up**: [React Basics →](/learn/workshops/nextjs-workshop/04-react) # Part 4: React Basics Source: https://docs.tuturuuu.com/learn/workshops/nextjs-workshop/04-react Component-based UI development with the most popular JavaScript library > [!NOTE] > > ⏱️ **Duration**: 20 minutes | Learn how React revolutionizes UI development. ## What is React? React is a JavaScript library for building user interfaces. It lets you create **reusable components** that manage their own state. **Ever noticed how Netflix updates smoothly without reloading the whole page?** That's React! 🎬 > [!NOTE] > > **Fun Fact**: React was created by **Meta (Facebook)** in 2013 and now powers billions of users on Facebook, Instagram, and WhatsApp! The engineer who created it, Jordan Walke, built the first version in just a few weeks! ### Why React? ```mermaid theme={null} graph LR subgraph Traditional["❌ Traditional"] direction TB A[Write HTML] --> B[Write JS] B --> C[Manually Sync] C --> D[🐛 Bugs!] end subgraph React["✅ React"] direction TB E[Write Component] --> F[State Changes] F --> G[Auto Update!] G --> H[🎉 It Works!] end Traditional ~~~ React style Traditional fill:#fee2e2,stroke:#ef4444,color:#000 style React fill:#dcfce7,stroke:#22c55e,color:#000 ``` | Traditional Approach | React Approach | | - | - | | Manually update HTML | Components update automatically | | Copy-paste code | Reusable components | | Hard to track state | Clear state management | | DOM manipulation | Declarative UI | > **[React Official Tutorial](https://react.dev/learn)** > > Learn React step-by-step with the official interactive tutorial *** ## Components Components are the building blocks of React apps. Think of them as custom HTML elements. ### Your First Component ```tsx theme={null} // A simple component function Greeting() { return

Hello, World!

; } // Using the component function App() { return (

); } ``` > [!TIP] > > **Beginner Tip**: Component names must start with a capital letter! `Greeting` not `greeting`. *** ## JSX: HTML in JavaScript JSX lets you write HTML-like code in JavaScript: ```tsx theme={null} function WelcomeCard() { const name = "Alice"; const isStudent = true; return (

Welcome, {name}!

{isStudent &&

Student discount available!

}

); } ``` ### JSX Rules | HTML | JSX | | - | - | | `class` | `className` | | `for` | `htmlFor` | | `style="color: red"` | `style={{ color: 'red' }}` | | Self-closing: `` | Must close: `` | *** ## Props: Passing Data Props let you pass data to components: ```tsx theme={null} // Component that accepts props interface UserCardProps { name: string; age: number; isActive?: boolean; } function UserCard({ name, age, isActive = false }: UserCardProps) { return (

{name}

Age: {age}

{isActive && ● Online}

); } // Using the component with props function App() { return (

); } ``` *** ## State: Making Things Interactive State is data that changes over time. Use `useState` to add state: ```tsx theme={null} import { useState } from 'react'; function Counter() { // Declare state: [value, setterFunction] const [count, setCount] = useState(0); return (

{count}

); } ``` **Try it yourself! 👇** − * > [!WARNING] > > **Important**: Never modify state directly! Always use the setter function. > > ```tsx theme={null} > // ❌ Wrong > count = count + 1; > > // ✅ Correct > setCount(count + 1); > ``` *** ## Handling Events React makes event handling easy: ```tsx theme={null} function LoginForm() { const [email, setEmail] = useState(''); const [password, setPassword] = useState(''); const handleSubmit = (e: React.FormEvent) => { e.preventDefault(); // Prevent page refresh console.log('Logging in:', email); }; return ( ); } ``` *** ## Rendering Lists Use `.map()` to render arrays of components: ```tsx theme={null} interface Todo { id: number; title: string; completed: boolean; } function TodoList() { const [todos, setTodos] = useState([ { id: 1, title: 'Learn React', completed: true }, { id: 2, title: 'Build an app', completed: false }, { id: 3, title: 'Deploy to Vercel', completed: false }, ]); return (

{todo.completed ? '✅' : '⬜'} {todo.title}

); } ``` > [!TIP] > > **Beginner Tip**: Always add a unique `key` prop when rendering lists. Use IDs, not array indices. *** ## Conditional Rendering Show different content based on conditions: ```tsx theme={null} function UserStatus({ isLoggedIn }: { isLoggedIn: boolean }) { // Method 1: Ternary operator return (

{isLoggedIn ? (

Welcome back!

) : (

Please log in.

)}

); } function Notification({ count }: { count: number }) { // Method 2: && operator (render if true) return (

{count > 0 && ( {count} )}

); } ``` **Try it! 👇** Toggle login state: *** ## Complete Example: Task Manager ```tsx theme={null} import { useState } from 'react'; interface Task { id: number; text: string; done: boolean; } function TaskManager() { const [tasks, setTasks] = useState([]); const [input, setInput] = useState(''); const addTask = () => { if (!input.trim()) return; setTasks([ ...tasks, { id: Date.now(), text: input, done: false } ]); setInput(''); }; const toggleTask = (id: number) => { setTasks(tasks.map(task => task.id === id ? { ...task, done: !task.done } : task )); }; return (

Tasks

{/* Add task */}

setInput(e.target.value)} onKeyDown={(e) => e.key === 'Enter' && addTask()} placeholder="New task..." className="flex-1 p-2 border rounded" />

{/* Task list */}

toggleTask(task.id)} className={`p-3 rounded cursor-pointer ${ task.done ? 'bg-green-100 line-through text-gray-500' : 'bg-gray-100' }`} > {task.text}

); } ``` **Try it! 👇** Add tasks and click to toggle: Add

...

}` | *** **Next up**: [Next.js →](/learn/workshops/nextjs-workshop/05-nextjs) # Part 5: Next.js Source: https://docs.tuturuuu.com/learn/workshops/nextjs-workshop/05-nextjs The React framework for production - build full-stack web applications > [!NOTE] > > ⏱️ **Duration**: 25 minutes | This is the core technology powering rmitnct.club! ## What is Next.js? Next.js is a **React framework** that gives you everything you need for production. **If React is a sword, Next.js is the entire armory! ⚔️🛡️** | What you get | Benefit | | - | - | | 🗂️ **File-based routing** | Create a file = create a page | | ⚡ **Server-side rendering** | SEO-friendly, fast loads | | 🔄 **API routes** | Backend in the same project | | 📦 **Built-in optimizations** | Images, fonts, scripts | > [!NOTE] > > **Fun Fact**: Next.js was created by **Vercel** and is used by TikTok, Nike, Notion, Anthropic, LG, and Tuturuuu. It powers both [rmitnct.club](https://rmitnct.club) and [Neo League 2025](https://nova.ai.vn/competitions/neo-league/prompt-the-future/about)! *** ## Creating a Next.js Project The fastest way to create a Next.js app: ```bash theme={null} # Option 1: Using npx (Node.js) npx create-next-app@latest my-app # Option 2: Using bunx (Bun - faster!) bunx create-next-app@latest my-app # Navigate into the project cd my-app # Start the development server bun dev # or: npm run dev ``` When prompted, select these options for this workshop: * ✅ TypeScript * ✅ Tailwind CSS * ✅ App Router * ❌ src/ directory (optional) > [!TIP] > > Open [http://localhost:3000](http://localhost:3000) to see your app! > **[Next.js Templates](https://vercel.com/templates/next.js)** > > Browse 100+ ready-to-use templates for blogs, e-commerce, dashboards, and more! *** ## Project Structure ``` my-app/ ├── app/ # 👈 Your pages and layouts │ ├── layout.tsx # Root layout (shared UI) │ ├── page.tsx # Home page (/) │ └── globals.css # Global styles ├── public/ # Static files (images, etc.) ├── package.json # Dependencies └── tailwind.config.ts # Tailwind configuration ``` *** ## File-Based Routing In Next.js, **files become pages**. Create a file, get a route! | File Path | URL | | - | - | | `app/page.tsx` | `/` | | `app/about/page.tsx` | `/about` | | `app/blog/page.tsx` | `/blog` | | `app/blog/[slug]/page.tsx` | `/blog/hello-world` | ![How page.tsx creates routes](https://mintcdn.com/tuturuuu/LKHVwofYjE5PdgBy/images/workshops/nextjs/page.png?fit=max\&auto=format\&n=LKHVwofYjE5PdgBy\&q=85\&s=161e1e09826d2bc7f324e09c78cf9400) ### Creating Your First Page Create `app/about/page.tsx`: ```tsx theme={null} export default function AboutPage() { return (

About Us

Welcome to our Next.js app!

); } ``` Now visit [http://localhost:3000/about](http://localhost:3000/about)! *** ## Layouts Layouts wrap pages with shared UI (navbars, footers, etc.). ### Root Layout (`app/layout.tsx`) ```tsx theme={null} import './globals.css'; export default function RootLayout({ children, }: { children: React.ReactNode; }) { return ( {/* Navigation bar */} {/* Page content */}

{children}

{/* Footer */} ); } ``` ![How layouts wrap pages](https://mintcdn.com/tuturuuu/LKHVwofYjE5PdgBy/images/workshops/nextjs/layout.png?fit=max\&auto=format\&n=LKHVwofYjE5PdgBy\&q=85\&s=0c226e7ecb86eb4a8f13bf28617953ee) *** ## Server vs Client Components Next.js has two types of components: | Server Components | Client Components | | - | - | | Run on the server | Run in the browser | | Can access databases directly | Can use `useState`, `useEffect` | | Default in Next.js | Add `'use client'` at top | | Great for static content | Great for interactivity | ### Server Component (Default) ```tsx theme={null} // app/users/page.tsx // This runs on the server! async function getUsers() { const res = await fetch('https://api.example.com/users'); return res.json(); } export default async function UsersPage() { const users = await getUsers(); return (

Users

{user.name}

); } ``` ### Client Component ```tsx theme={null} 'use client'; // 👈 This makes it a client component import { useState } from 'react'; export default function Counter() { const [count, setCount] = useState(0); return ( ); } ``` > [!WARNING] > > **Rule of Thumb**: Keep components as Server Components unless they need interactivity (`onClick`, `useState`, etc.). *** ## Navigation with Links Use the `Link` component for navigation: ```tsx theme={null} import Link from 'next/link'; export default function Navbar() { return ( ); } ``` > [!TIP] > > **Why Link?** It enables client-side navigation without full page reloads - much faster! *** ## Dynamic Routes Create pages with dynamic parameters: ### File: `app/blog/[slug]/page.tsx` ```tsx theme={null} interface BlogPostProps { params: Promise<{ slug: string }>; } export default async function BlogPost({ params }: BlogPostProps) { const { slug } = await params; return (

Blog Post: {slug}

Content for {slug}...

); } ``` Now `/blog/hello-world` will show "Blog Post: hello-world"! *** ## API Routes Build your API in the same project: ### File: `app/api/hello/route.ts` ```typescript theme={null} import { NextResponse } from 'next/server'; export async function GET() { return NextResponse.json({ message: 'Hello from the API!', timestamp: new Date().toISOString(), }); } export async function POST(request: Request) { const body = await request.json(); return NextResponse.json({ received: body, status: 'success', }); } ``` Now visit [http://localhost:3000/api/hello](http://localhost:3000/api/hello)! *** ## Building for Production ```bash theme={null} # Build the app bun run build # Start production server bun start ``` Or deploy to **Vercel** with zero configuration: ```bash theme={null} # Install Vercel CLI bun add -g vercel # Deploy vercel ``` *** ## Complete Example: Blog ```tsx theme={null} // app/page.tsx import Link from 'next/link'; const posts = [ { slug: 'getting-started', title: 'Getting Started with Next.js' }, { slug: 'react-basics', title: 'React Basics for Beginners' }, { slug: 'tailwind-tips', title: 'Tailwind CSS Tips and Tricks' }, ]; export default function HomePage() { return (

My Blog

{posts.map((post) => (

{post.title}

))}

); } ``` *** ## Next.js Cheat Sheet | Feature | Syntax | | - | - | | Create page | `app/[path]/page.tsx` | | Create layout | `app/[path]/layout.tsx` | | Client component | `'use client'` at top of file | | Navigation | `` | | Dynamic route | `app/blog/[slug]/page.tsx` | | API route | `app/api/[path]/route.ts` | | Use params | `{ params }: { params: Promise<{ slug: string }> }` | *** ## Learn More > **[Next.js Docs](https://nextjs.org/docs)** > > Complete documentation > **[Next.js Learn](https://nextjs.org/learn)** > > Free interactive course *** **Next up**: [Vercel AI SDK →](/learn/workshops/nextjs-workshop/06-ai-sdk) # Part 6: Vercel AI SDK Source: https://docs.tuturuuu.com/learn/workshops/nextjs-workshop/06-ai-sdk Build AI-powered features with text and structured data generation > [!NOTE] > > ⏱️ **Duration**: 10 minutes | Add AI superpowers to your Next.js apps! ## What is Vercel AI SDK? The **Vercel AI SDK** is a TypeScript library for building AI-powered applications. It works with multiple AI providers and makes it easy to integrate AI into your apps. > **[AI SDK Documentation](https://ai-sdk.dev)** > > Official documentation for the Vercel AI SDK *** ## The Journey of AI: From Games to Gemini Before we dive into code, let's understand how AI got here. It's a fascinating story! ```mermaid theme={null} graph LR A["🎮 1980s: Pacman AI"] --> B["♟️ 1997: Deep Blue"] B --> C["🎯 2016: AlphaGo"] C --> D["💬 2022: ChatGPT"] D --> E["✨ 2024: Gemini"] style A fill:#fef3c7,stroke:#f59e0b,color:#000 style B fill:#dbeafe,stroke:#3b82f6,color:#000 style C fill:#dcfce7,stroke:#22c55e,color:#000 style D fill:#fce7f3,stroke:#ec4899,color:#000 style E fill:#4285f4,stroke:#2d6bce,color:#fff ``` **The foundation of AI is search.** Think about it: * 🎮 **Pacman ghosts** search for the best path to catch you * ♟️ **Chess AI** searches millions of moves to find the best one * 💬 **ChatGPT** searches through patterns in language * ✨ **Gemini** searches across text, images, video, and code > [!NOTE] > > **Why Google leads AI**: Google is the world's best at **search**—the foundation of AI. This is why they're state-of-the-art across text generation, math reasoning, image generation, video generation, and more. When you use Gemini, you're using decades of search innovation! ### 🎬 Want to Learn More? Watch These! > **[AlphaGo - The Movie](https://youtu.be/WXuK6gekU1Y)** > > The documentary that shows how AI beat the world's best Go player > **[The Thinking Game](https://youtu.be/d95J8yzvjbQ)** > > Google DeepMind's journey to create AI that thinks > **[Hacking Google](https://youtu.be/aOGFY1R4QQ4)** > > How Google protects billions of users (cybersecurity series) > **[Google Gemini History](https://en.wikipedia.org/wiki/Google_Gemini)** > > The full story of Gemini's development ### AI Providers Today ```mermaid theme={null} graph LR A["Your App"] --> B["AI SDK"] B --> C["Google Gemini"] B --> D["OpenAI"] B --> E["Anthropic"] B --> F["And More..."] style A fill:#000,stroke:#333,color:#fff style B fill:#4f46e5,stroke:#3730a3,color:#fff style C fill:#4285f4,stroke:#2d6bce,color:#fff style D fill:#10a37f,stroke:#0d8a6a,color:#fff style E fill:#d97706,stroke:#b45309,color:#fff ``` *** ## Getting Started ### Install Dependencies ```bash theme={null} bun add ai @ai-sdk/google zod ``` ### Get Your API Key (Free!) > **[Google AI Studio](https://aistudio.google.com/apikey)** > > Get a free API key with generous usage limits ### Environment Variables Create `.env.local` in your project root: ```bash theme={null} GOOGLE_GENERATIVE_AI_API_KEY=your-api-key-here ``` > [!WARNING] > > **Never commit API keys!** Add `.env.local` to your `.gitignore` file. *** ## Text Generation The simplest way to use AI is generating text. Let's start here! ```mermaid theme={null} graph LR A["📝 Prompt"] --> B["🤖 AI Model"] B --> C["💬 Text Response"] style A fill:#dbeafe,stroke:#3b82f6,color:#000 style B fill:#4f46e5,stroke:#3730a3,color:#fff style C fill:#dcfce7,stroke:#22c55e,color:#000 ``` ### Your First AI Call ```typescript theme={null} import { generateText } from 'ai'; import { google } from "@ai-sdk/google"; const { text } = await generateText({ model: google("gemini-2.5-flash"), system: 'You are a professional writer. ' + 'You write simple, clear, and concise content.', prompt: `Summarize the following article in 3-5 sentences: ${article}`, }); console.log(text); ``` > [!TIP] > > **Why Gemini?** Google offers **free API access** with generous limits—perfect for learning and prototyping! > **[Text Generation Docs](https://ai-sdk.dev/docs/ai-sdk-core/generating-text)** > > Learn more about text generation options *** ## Structured Data Generation Text is great, but what if you need **data** you can use programmatically? ### The Problem with Plain Text ```mermaid theme={null} graph LR A["Ask AI for recipe"] --> B["Get text blob"] B --> C["Parse manually? 😰"] C --> D["Regex nightmares 💀"] style A fill:#dbeafe,stroke:#3b82f6,color:#000 style B fill:#fef3c7,stroke:#f59e0b,color:#000 style C fill:#fee2e2,stroke:#ef4444,color:#000 style D fill:#fee2e2,stroke:#ef4444,color:#000 ``` ```typescript theme={null} // ❌ Unstructured text - hard to use programmatically const response = "Here's a recipe: Lasagna. You'll need pasta, cheese, sauce..."; // How do you extract the ingredients? The steps? 🤔 ``` ### The Solution: Structured Output ```mermaid theme={null} graph LR A["Ask AI for recipe"] --> B["Define schema"] B --> C["Get typed data ✨"] C --> D["Use directly! 🎉"] style A fill:#dbeafe,stroke:#3b82f6,color:#000 style B fill:#fef3c7,stroke:#f59e0b,color:#000 style C fill:#dcfce7,stroke:#22c55e,color:#000 style D fill:#dcfce7,stroke:#22c55e,color:#000 ``` ```typescript theme={null} // ✅ Structured data - easy to use! const recipe = { name: "Lasagna", ingredients: [ { name: "pasta sheets", amount: "12 sheets" }, { name: "ricotta cheese", amount: "2 cups" }, { name: "tomato sauce", amount: "3 cups" }, ], steps: [ "Preheat oven to 375°F", "Layer sauce, pasta, and cheese", "Bake for 45 minutes", ], }; ``` *** ## Using `generateObject` The `generateObject` function generates structured data from a prompt: ```typescript theme={null} import { generateObject } from 'ai'; import { google } from '@ai-sdk/google'; import { z } from 'zod'; // Define the shape of your data with Zod const recipeSchema = z.object({ name: z.string(), ingredients: z.array( z.object({ name: z.string(), amount: z.string(), }) ), steps: z.array(z.string()), prepTime: z.string(), }); // Generate structured data const { object: recipe } = await generateObject({ model: google('gemini-2.5-flash'), schema: recipeSchema, prompt: 'Generate a recipe for chocolate chip cookies.', }); // TypeScript knows the exact shape! console.log(recipe.name); // "Chocolate Chip Cookies" console.log(recipe.ingredients[0].name); // "flour" ``` *** ## Zod Schemas [Zod](https://zod.dev) defines the shape of your data with TypeScript-first validation. ```mermaid theme={null} graph TB subgraph Zod["Zod Schema"] A["z.object()"] --> B["z.string()"] A --> C["z.number()"] A --> D["z.array()"] A --> E["z.boolean()"] end style Zod fill:#fef3c7,stroke:#f59e0b,color:#000 ``` ### Common Schema Types ```typescript theme={null} import { z } from 'zod'; // Basic types const stringSchema = z.string(); const numberSchema = z.number(); const booleanSchema = z.boolean(); // Arrays const arraySchema = z.array(z.string()); // Objects const userSchema = z.object({ name: z.string(), age: z.number(), email: z.string().email(), }); ``` ### Adding Descriptions (Important!) Descriptions help the AI understand what you want: ```typescript theme={null} const flashcardSchema = z.object({ flashcards: z.array( z.object({ front: z.string().describe('The question on the flashcard'), back: z.string().describe('The answer on the flashcard'), }) ).describe('Array of 10 flashcards'), }); ``` *** ## Complete Example: AI Flashcard Generator ### API Route: `app/api/flashcards/route.ts` ```typescript theme={null} import { generateObject } from 'ai'; import { google } from '@ai-sdk/google'; import { z } from 'zod'; import { NextResponse } from 'next/server'; const flashcardSchema = z.object({ flashcards: z.array( z.object({ front: z.string().describe('Question'), back: z.string().describe('Answer'), }) ), }); export async function POST(request: Request) { const { topic } = await request.json(); const { object } = await generateObject({ model: google('gemini-2.5-flash'), schema: flashcardSchema, prompt: `Generate 5 flashcards about: ${topic}`, }); return NextResponse.json(object); } ``` ### Frontend Component ```tsx theme={null} 'use client'; import { useState } from 'react'; export default function FlashcardGenerator() { const [topic, setTopic] = useState(''); const [flashcards, setFlashcards] = useState([]); const [loading, setLoading] = useState(false); const generate = async () => { setLoading(true); const res = await fetch('/api/flashcards', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ topic }), }); const data = await res.json(); setFlashcards(data.flashcards); setLoading(false); }; return (

AI Flashcard Generator

setTopic(e.target.value)} placeholder="Enter a topic..." className="flex-1 p-2 border rounded" />

{flashcards.map((card, i) => (

{card.front}

{card.back}

))}

); } ``` *** ## Key Takeaways > **Start with Text** > > Use `generateText` for simple AI responses > **Level Up with Schemas** > > Use `generateObject` for structured data > **Google Gemini** > > Free API access for learning and prototyping > **Type-Safe AI** > > Zod schemas give you TypeScript types automatically *** ## Learn More > **[Text Generation](https://ai-sdk.dev/docs/ai-sdk-core/generating-text)** > > Complete text generation guide > **[Structured Data](https://ai-sdk.dev/docs/ai-sdk-core/generating-structured-data)** > > Complete structured data guide *** **Next up**: [Next Steps & Resources →](/learn/workshops/nextjs-workshop/07-next-steps) # Part 7: Next Steps Source: https://docs.tuturuuu.com/learn/workshops/nextjs-workshop/07-next-steps Continue your learning journey and contribute to NCT Club projects > [!NOTE] > > ⏱️ **Duration**: 5 minutes | Congratulations on completing the workshop! 🎉 ## 🎉 What You've Learned In just 2 hours, you've covered: | Topic | What You Learned | | - | - | | **Web Fundamentals** | HTML structure, CSS styling, JavaScript interactivity | | **Tailwind CSS** | Utility-first styling, responsive design | | **TypeScript** | Type safety, interfaces, catching bugs early | | **React** | Components, props, state, event handling | | **Next.js** | File-based routing, server/client components, API routes | | **AI SDK** | Structured data generation with Zod schemas | *** ## 📚 Continue Learning > **[Next.js Learn](https://nextjs.org/learn)** > > Free, interactive course - highly recommended! > **[Next.js Docs](https://nextjs.org/docs)** > > Complete reference documentation > **[Tailwind CSS](https://tailwindcss.com/docs)** > > All utilities and components > **[AI SDK Guide](https://ai-sdk.dev/docs)** > > Build more AI-powered features > **[React Docs](https://react.dev)** > > Official React documentation > **[TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/)** > > Deep dive into TypeScript *** ## 🛠️ Tools & Resources ### Development Tools | Tool | Purpose | Link | | - | - | - | | **Bun** | Fast JavaScript runtime & package manager | [bun.sh](https://bun.sh) | | **VS Code** | Recommended code editor | [code.visualstudio.com](https://code.visualstudio.com) | | **Vercel** | Deploy Next.js apps easily | [vercel.com](https://vercel.com) | ### Recommended VS Code Extensions * [Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) * [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) * [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) * [TypeScript Hero](https://marketplace.visualstudio.com/items?itemName=rbbit.typescript-hero) *** ## 🚀 Contribute to Open Source Ready to apply your skills? Both RMIT NCT and Tuturuuu are open for contributions! ### RMIT NCT Hub > **[RMIT NCT Hub](https://github.com/rmit-nct/hub)** > > The official NCT Club platform repository ```bash theme={null} # Clone NCT Hub git clone https://github.com/rmit-nct/hub.git cd hub && bun install && bun dev ``` > [!NOTE] > > **Our Mission**: Help NCT become the **best technology club at RMIT**. Every contribution you make helps fellow students learn, grow, and become the best versions of themselves. Together, we're building something that matters! *** ### Tuturuuu Platform > **[Tuturuuu Platform](https://github.com/tutur3u/platform)** > > The platform that powers tuturuuu.com ```bash theme={null} # Clone Tuturuuu Platform git clone https://github.com/tutur3u/platform.git cd platform && bun install && bun dev ``` > [!NOTE] > > **Our Vision**: Tuturuuu aims to **build a better world for everyone, everywhere**—starting with how you work. By contributing, you're not just writing code; you're helping shape the future of productivity and collaboration. 🌏 *** ### Good First Issues Look for issues labeled `good first issue` on GitHub - these are perfect for newcomers! > **[NCT Hub Issues](https://github.com/rmit-nct/hub/issues)** > > Find issues on NCT Hub > **[Tuturuuu Issues](https://github.com/tutur3u/platform/issues)** > > Find issues on Tuturuuu *** ## 🏗️ Project Ideas Build these to practice your skills: > **Personal Portfolio** > > Showcase your projects with Next.js and Tailwind > **To-Do App** > > Practice React state management > **Blog** > > Build with Next.js file-based routing > **AI Flashcard Generator** > > Combine AI SDK with structured data *** ## 📢 Stay Connected ### RMIT SGS Neo Culture Technology Club > **[Website](https://rmitnct.club)** > > Visit our platform > **[GitHub](https://github.com/rmit-nct)** > > Follow our open-source work ### Tuturuuu > **[Website](https://tuturuuu.com)** > > Learn more about Tuturuuu > **[GitHub](https://github.com/tutur3u/platform)** > > Explore the codebase *** ## 💡 Quick Reference Card Save this for later: ``` # Create a Next.js app bunx create-next-app@latest my-app # Start development cd my-app && bun dev # Project structure app/page.tsx → Home page app/about/page.tsx → /about page app/api/*/route.ts → API routes # Key packages bun add tailwindcss → Styling bun add ai zod → AI SDK ``` *** ## 💼 Join Tuturuuu Interested in what we're building for the future of work? > **[Tuturuuu Careers](https://tuturuuu.com/careers)** > > Explore open positions and join our team Send your CV to **[careers@tuturuuu.com](mailto:careers@tuturuuu.com)**. We can't wait to see what's next for you, Tuturuuu, and potentially, **us**. ✨ *** ## 🙏 Thank You! Thank you for joining this workshop! Remember: > **"The best way to learn is by building."** Start with small projects, make mistakes, learn from them, and keep building. We can't wait to see what you create! *** > [!NOTE] > > **Questions?** Reach out to your club officers or join the community Discord. We're here to help! **[← Back to Workshop Overview](/learn/workshops/nextjs-workshop/overview)** # Master Modern Web Development with Next.js Source: https://docs.tuturuuu.com/learn/workshops/nextjs-workshop/overview A 2-hour beginner-friendly workshop by Tuturuuu × RMIT SGS Neo Culture Technology Club > [!NOTE] > > 📅 **Tuesday, December 16, 2025** | ⏰ **1:45 PM – 4:00 PM** > > **Duration**: \~2 hours of content + time for Q\&A and free exploration | **Level**: Beginner-friendly ## 🤝 A Collaboration This workshop is a collaboration between **[Tuturuuu](https://tuturuuu.com)** and **[RMIT SGS Neo Culture Technology Club](https://rmitnct.club)**. Next.js is the core technology powering the club's digital infrastructure. This workshop is an essential step for any member who wishes to dive deep into advanced web development and eventually contribute to the club's open-source projects. ## 🏆 Powered by Next.js Next.js is trusted by industry leaders worldwide: > **[Global Brands](https://nextjs.org/showcase)** > > TikTok, Nike, Notion, Anthropic, LG, and many more. > **[Tuturuuu](https://tuturuuu.com)** > > Extensively uses Next.js across all its products and platforms. > **[rmitnct.club](https://rmitnct.club)** > > NCT Club's official platform—a fork of [tutur3u/platform](https://github.com/tutur3u/platform). > **[Neo League 2025](https://nova.ai.vn/competitions/neo-league/prompt-the-future/about)** > > NCT Club's **first-ever scale-3 event** on Nova. ## 👨‍🏫 Your Instructor ![Vo Hoang Phuc with NCT Club](https://mintcdn.com/tuturuuu/LKHVwofYjE5PdgBy/images/workshops/nextjs/vo-hoang-phuc-with-nct-club.png?fit=max\&auto=format\&n=LKHVwofYjE5PdgBy\&q=85\&s=13b3d2a8b435a9ae96d80621deca987b) **Vo Hoang Phuc** * Chairman, Founder & CEO @ [Tuturuuu](https://tuturuuu.com) * Former Technical Vice President (Generation 6) @ RMIT SGS Neo Culture Technology Club > [!NOTE] > > **A Personal Story**: *"I started my journey the hard way—jumping straight into Next.js, skipping HTML, CSS, and JavaScript entirely! I built my first personal website [vohoangphuc.com](https://vohoangphuc.com), which slowly inspired me to build something for everyone else: [tuturuuu.com](https://tuturuuu.com). By the end of my first year, what started as humble steps turned into a platform. Today, you're learning the foundations I wish I had learned first!"* ## 🎯 What You'll Learn By the end of this 2-hour session, you'll understand: * **Web fundamentals**: How HTML, CSS, and JavaScript work together * **Modern styling**: Building beautiful UIs with Tailwind CSS * **Type safety**: Writing reliable code with TypeScript * **Component-based development**: Building UIs with React * **Full-stack framework**: Creating production-ready apps with Next.js * **AI integration**: Generating structured data with Vercel AI SDK ## ⏱️ Session Timeline | Actual Time | Topic | Offset | Duration | | - | - | - | - | | 1:45 PM | Welcome & Setup | 0:00 | 10 min | | 1:55 PM | [Web Fundamentals](/learn/workshops/nextjs-workshop/01-web-fundamentals) | 0:10 | 15 min | | 2:10 PM | [Tailwind CSS](/learn/workshops/nextjs-workshop/02-tailwind-css) | 0:25 | 15 min | | 2:25 PM | [TypeScript](/learn/workshops/nextjs-workshop/03-typescript) | 0:40 | 15 min | | 2:40 PM | ☕ Break | 0:55 | 5 min | | 2:45 PM | [React Basics](/learn/workshops/nextjs-workshop/04-react) | 1:00 | 20 min | | 3:05 PM | [Next.js](/learn/workshops/nextjs-workshop/05-nextjs) | 1:20 | 25 min | | 3:30 PM | [AI SDK](/learn/workshops/nextjs-workshop/06-ai-sdk) | 1:45 | 10 min | | 3:40 PM | [Next Steps](/learn/workshops/nextjs-workshop/07-next-steps) | 1:55 | 5 min | | 3:45 PM | 🎯 Q\&A & Free Exploration | 2:00 | 15 min | ```mermaid theme={null} graph LR A["🌐 Web Basics"] --> B["🎨 Tailwind"] B --> C["📝 TypeScript"] C --> D["☕ Break"] D --> E["⚛️ React"] E --> F["▲ Next.js"] F --> G["🤖 AI SDK"] G --> H["🚀 Next Steps"] style A fill:#e34c26,color:#fff style B fill:#38bdf8,color:#fff style C fill:#3178c6,color:#fff style E fill:#61dafb,color:#000 style F fill:#000,color:#fff style G fill:#4f46e5,color:#fff style H fill:#22c55e,color:#fff ``` ## 🛠️ Prerequisites **All you need is a laptop!** We'll guide you through everything else. ### Recommended Setup Before the workshop, please install: 1. **[Bun](https://bun.sh)** - A fast JavaScript runtime and package manager ```bash theme={null} curl -fsSL https://bun.sh/install | bash ``` 2. **[Visual Studio Code](https://code.visualstudio.com)** - Our recommended code editor 3. **VS Code Extensions** (optional but helpful): * [Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) * [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) * [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) ## 📚 Resources Throughout this workshop, we'll reference these resources: ### Beginner Tutorials (W3Schools) | Technology | Tutorial | | - | - | | HTML | [w3schools.com/html](https://www.w3schools.com/html/) | | CSS | [w3schools.com/css](https://www.w3schools.com/css/) | | JavaScript | [w3schools.com/js](https://www.w3schools.com/Js/) | ### Official Documentation | Technology | Documentation | | - | - | | TypeScript | [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html) | | Next.js | [nextjs.org/docs](https://nextjs.org/docs) | | Tailwind CSS | [tailwindcss.com](https://tailwindcss.com) | | Vercel AI SDK | [ai-sdk.dev](https://ai-sdk.dev) | | Bun | [bun.sh](https://bun.sh) | ## 🚀 Ready? Let's begin with [Web Fundamentals →](/learn/workshops/nextjs-workshop/01-web-fundamentals) # Agent Operating Manual Source: https://docs.tuturuuu.com/overview/agent-operating-manual Field guide summarizing the AGENTS.md policies for autonomous contributors inside the Tuturuuu monorepo. > [!NOTE] > > Web and satellite Next.js apps are active. Docker setup is inactive, the Docker > cron runner is retired, and Rust/TanStack Start are paused and not in use. Do not > run their implementation tests/builds or update source, manifests, dependencies, > or version references until explicitly resumed. Root AGENTS.md owns current > cross-cutting rules; use [active runtime](/build/devops/active-runtime) and > [development without Docker](/build/development-tools/without-docker). This page distills the canonical rules defined in [AGENTS.md](https://github.com/tutur3u/platform/blob/main/AGENTS.md). Treat the original document as the source of truth. The root file is now a hard-policy index; detailed reusable implementation patterns live in the repo-local Tuturuuu Codex plugin skills under `plugins/tuturuuu/skills/*/references/`. ## Core Principles * **Least privilege** – Touch only the files required for the task and keep changes scoped. * **Shared worktree discipline** – Assume humans or other agents may have dirty files in the same checkout; inspect before editing and never clean up work you do not own. * **Deterministic & reproducible** – Generated artefacts must come from scripted commands; rerunning the workflow should produce the same result. * **Security first** – Never surface secret values. Reference environment variables by name and keep sensitive flows audited. * **Document product decisions** – Record customer-facing rules in the relevant platform feature page with scope, default, affected apps, and exceptions; check active implementation and docs before delivery; paused Rust/TanStack sources remain frozen. * **Authorized completion** – Continue the requested implementation, relevant checks, fixes, and delivery. Ask only for a missing decision, permission, or access. * **Focused knowledge** – Add durable gotchas to the narrowest plugin skill reference instead of expanding the root operating manual by default. ## Capability Matrix | Domain | You May | You Must | Never | | - | - | - | - | | **Code (TS/JS)** | Build Next.js App Router routes, React server/client components, shared packages | Add/adjust tests & types, update related docs | Ship breaking public API changes without a `BREAKING` note | | **Code (Python)** | Modify apps under `apps/*` (python) with env isolation | Maintain pinned requirements / lockfiles | Blend unrelated refactors into feature work | | **Database (Supabase)** | Author migrations in `apps/database/supabase/migrations`, run typegen | Commit regenerated `@tuturuuu/types` output | Hand-edit generated type files | | **AI Endpoints** | Add handlers under `app/api/...` using Vercel AI SDK | Enforce auth + feature flags, validate payloads | Expose provider keys or skip validation | | **Tooling** | Adjust configs (`biome.json`, `turbo.json`, etc.) | Document the rationale | Remove caching or security settings silently | | **Docs** | Update `.md`/`.mdx` for accuracy | Cross-link neighbouring guides | Invent behaviour that is not implemented | | **Dependencies** | `cd && bun add ` / remove deps | Prefer `workspace:*` for internal packages | Add duplicate versions already satisfied | ## Mandatory Guardrails 1. Finite local setup, tests, and builds needed to validate authorized work may run without repeated confirmation. Start long-lived servers only when requested or needed for explicitly requested runtime verification. Deployment authorization remains separate. 2. **Supabase apply is user-only** – prepare migrations, but the user runs `bun sb:push` / `bun sb:linkpush`. 3. Run formatters and checks required for files you changed, but keep auto-fixes scoped to your owned paths. 4. Avoid committing noisy logs; add diagnostics only when they materially aid debugging. 5. Never commit credentials, tokens, destructive migrations, or unrelated worktree changes. 6. Do not stage, rename, delete, or format unknown dirty/untracked files; treat them as human-owned or other-agent-owned until confirmed. 7. Do not manually bump release versions for ordinary authored work. Release Please owns package versions, changelogs, and the account-gated web badge version. Keep release-please annotations intact. ## Decision Boundaries Ask when a concrete action exceeds the requested scope, needs missing access, or requires an unresolved product decision. File counts and SQL line counts alone do not require approval. Prepare the reviewable change before requesting approval for an external action. Preserve existing authorization for routine retries and fixes; never infer permission for broader production scope. Fetch before production sync and inspect the promotion range: if main advanced with unrelated commits, use the supported pinned-SHA path or obtain authorization for the expanded range. Read only the focused skill and reference sections relevant to the task. Keep AGENTS.md constraints concise; preserve detailed app lessons in skill references. Define completion from the request and carry authorized work through the required checks and fixes. A read-only CLI operation needs its diagnostic procedure, not the implementation test suite; a local UI change needs its owning surface, not a full application audit. See [focused agent guidance](/build/development-tools/codex-plugin#maintaining-focused-agent-guidance). ## Canonical Workflows (Cheat Sheet) * **Add/Update dependency** – scope → `cd && bun add ` → ensure types/docs → run targeted build. * **New shared package** – scaffold under `packages/`, add `package.json` + `tsconfig`, export via `src/index.ts`, add tests & README, then build/test. * **Next.js API route** – implement under `app/api/.../route.ts`, enforce auth, validate with Zod, add tests or docs. * **AI structured endpoint** – define schema in `packages/ai`, use `generateObject`/`streamObject`, guard feature flags, redact secrets, handle errors gracefully. * **Supabase migration** – run `bun sb:new`, author additive SQL, apply locally and regenerate types via `bun sb:typegen`; production pushes remain user-only, commit regenerated files together. See `plugins/tuturuuu/skills/tuturuuu-platform/references/repository-workflows.md` for task-specific commands and route ownership. ## Focused Skill References Use the repo-local Tuturuuu Codex plugin for detailed pattern catalogs: * `$tuturuuu-platform` for web/API/shared UI patterns. * `$tuturuuu-web-release` for version badge metadata, `PLATFORM_BUILD_*`, and release-please-managed `TUTURUUU_PLATFORM_VERSION` updates. * `$tuturuuu-database` for Supabase, protected-table API, and storage patterns. * `$tuturuuu-ci-docs` for docs, CI, and Docker blue/green deployment runbooks. * `$tuturuuu-development-tooling` for root scripts, plugin validation, and CI/tooling behavior. * `$tuturuuu-agent-coordination` for shared worktrees, active notes, handoffs, and commit-window coordination. * `$tuturuuu-commit` for scoped commits, exact staging, and commit-window claim/wait/release. * `$tuturuuu-mobile-task-board` for Flutter mobile task-board and mobile UX patterns. ## Collaboration Protocol * Roles: Execution (ship code/docs), Review (verify lint/type/test/build), Architecture (cross-cutting improvements), Knowledge (docs & schema sync). * Hierarchy and budget: director, project integration owner (sole main/release writer), team leads and workers share one subagent allocation; see the [agent operating model](/build/development-tools/agent-operating-model). * Only one agent modifies a file set at a time; reviewers work read-only unless paired. * Prefer linear history (rebases) and group commits by concern (schema vs code vs docs). * For behavior spanning apps, assign one owner to the product decision and its feature page. Each implementation lane reports the surfaces it checked and any intentional difference; the integrator compares those reports with the live apps before merging; do not update paused migration paths. ### Open Pull Request Worktrees Every open Tuturuuu pull request must be reviewed, fixed, validated, and prepared for merge in an isolated checkout under `.worktrees/`. Do not switch the shared main checkout onto the PR branch. Immediately run `bun install` after creating the worktree. Do not run `bun setup` on agent machines: it includes local builds. Builds run in CI for the exact commit. Keep the worktree and its local task branch for as long as the PR remains open. After GitHub confirms the PR merge is present on `main` and required post-merge verification is complete, remove the completed worktree and delete its local task branch. Do not use that cleanup as permission to remove unrelated worktrees, branches, or unmerged work. When a user authorizes ongoing integration rather than a single PR, checkpoint completed lanes periodically. Integrate a scoped commit onto current `main`, wait until every workflow for that exact main SHA is green, run `bun git-sync`, and verify production before removing the completed worktree and its local task branch. Retain dirty, blocked, unmerged, user-owned, and other-agent-owned lanes. Triage disk space with `ttr storage status`, `analyze` and `suggest`, and reclaim it only through the dry-run-first `ttr storage prune`, which delegates Rust `apps/backend/target` space to the bounded `bun rust-cache` commands. Never delete source, held paths, or a dirty or unmerged worktree as cache cleanup. See [Machine storage health](/build/development-tools/machine-storage-health). ### Shared Worktree Coordination Use `tmp/agent-coordination/` as the ignored, in-worktree conversation space for agent-to-agent coordination. This is not source-controlled and should not be committed. Before editing, run `git status --short`. If dirty or untracked files already exist, record which ones are unrelated and leave them alone. If `tmp/agent-coordination/` exists, inspect top-level notes marked `working`, `blocked`, or `handoff` before choosing files. Stale active notes still count as ownership signals until checked against the current worktree. Use exact `Status:` values in coordination notes: `working`, `blocked`, `handoff`, or `done`. Put details such as `committed`, `done with concerns`, or follow-up context in `Needs`, `Verification`, or `Risks`. Treat missing or noncanonical statuses as active until resolved. Completed context should move out of the active scan path. Use `tmp/agent-coordination/archive//.md` for notes that are already marked `done` and no longer need top-level visibility. Search the archive with targeted keywords when a task mentions prior work or a workflow decision needs history; archived notes explain context, verification, and residual risks, but they are not active ownership claims. Create a note named `tmp/agent-coordination/-.md` when the worktree is dirty, active notes touch a nearby area, the task is long-running, or the task changes coordination, commit, validation, CI, deployment, plugin, or skill behavior. Each note should include: * `Agent`: stable name or session id if available. * `Intent`: one-line task summary. * `Owned paths`: files or directories the agent expects to edit. * `Observed dirty paths`: relevant pre-existing paths the agent will not touch. * `Status`: `working`, `blocked`, `handoff`, or `done`. * `Needs`: specific question or response requested from other agents. * `Commit window`: `not needed`, `claimed`, `waiting`, `blocked`, or `released` when a commit may be needed. * `Verification`: commands already run, when available. * `Risks`: remaining overlap or validation risk, when relevant. If two agents need the same file set, do not race. Reply in `tmp/agent-coordination/`, choose a disjoint slice, or ask the human partner to arbitrate. Do not edit another agent's note unless explicitly asked. Before the final response or handoff, update your own note to `done`, `handoff`, or `blocked` with verification and residual risks. Archive only your own completed `done` note unless the human partner explicitly requests broader cleanup. When committing, stage explicit paths only and never stage coordination notes or archived coordination notes. If a repo-wide check or commit hook fails because of another agent's files, do not fix those files just to satisfy the hook; report the blocker and keep your own diff scoped. For parallel subagent work, split lanes before spawning workers. Each worker needs a narrow owned path set, forbidden overlap, validation commands, and a handoff contract; workers should not stage or commit unless that is their explicit lane. Make the lane contract explicit: owner, mode, owned paths, excluded paths, generated outputs, validation, handoff shape, lifecycle (`pending`, `active`, `handoff`, `integrated`, or `closed`), and commit authority. Do not overlap implementation worker write paths unless the parent note records an explicit takeover or continuation. In Codex, use either a typed worker/explorer prompt with explicit lane context or a full-history fork without a role override; combining both is rejected by the subagent harness. The coordinator owns integration: review worker diffs, regenerate shared artifacts such as route trees, route manifests, route overrides, OpenAPI snapshots, docs navigation, sorted translations, or generated DB types after inputs are stable, then stage exact paths. After each integrated slice, refresh status, close completed subagents in the harness, mark their lanes integrated or closed in the parent note, list validation and unrelated blockers, and choose the next lane from current worktree state. Existing staged files belong to the staging agent or coordinator until explicitly reassigned; if a path is `MM`, review both staged and unstaged portions before committing. When unrelated dirty files touch shared generated inputs or outputs such as route trees, migration manifests, `packages/internal-api/src/index.ts`, generated DB types, message bundles, or `bun.lock`, default new implementation work to an isolated worktree or read-only audit unless the write set is clearly disjoint and no generator or root formatter will scan those files. If you must generate from a dirty shared checkout, use a clean tree or explicit input/output paths and record the base commit, scanned globs, copied lane inputs, generator command, copied-back artifacts, cleanup, and proof that no untracked or other-lane files leaked into the output. ### Git Commit Window Use `bun git-commit-window` to serialize Git index and commit operations in a shared checkout. The lock lives at `tmp/agent-coordination/git-commit-window.lock.json`, which is ignored by Git. It is advisory: it does not grant ownership of files and does not allow broad staging. Claims default to 10 minutes, may only be 5-10 minutes, and should be held only for focused staging and commit work. Claim the window immediately before staging, unstaging, committing, amending, rebasing, or commit-and-push work: ```bash theme={null} bun git-commit-window claim --owner "" --scope "" ``` If another agent owns the window and waiting is appropriate, use `wait`. It sleeps until the current lock is released or expires, then atomically claims the window before notifying the waiting agent. The wait timeout can be longer than the claim TTL, but the claim received after waking is still limited to 5-10 minutes: ```bash theme={null} bun git-commit-window wait --owner "" --scope "" ``` Use `status` to inspect, `check --token ` before committing if needed, and `release --token ` after the commit operation succeeds or aborts. Do not put tokens in coordination notes. For commits made in a dirty shared checkout, record a closeout packet in the parent note: staged path list, validation results for the staged set, hook result or proof-gated `--no-verify` rationale, commit hash, release confirmation, and remaining dirty-path summary. ## Tooling & Environment Rules * Single package manager: **Bun**. Use workspace filters (`bun --filter ...`) to target apps/packages. * Use `bun validate:now` when you need to cancel queued or running repo-root `bun validate` invocations for the current workspace and start a fresh pass immediately. * Supabase lifecycle via scripts: `sb:start`, `sb:stop`, `sb:new`, `sb:up`, `sb:typegen` (user applies pushes). * Do not invent new cache stores; rely on Turborepo, Bun, BuildKit, and Cargo caches plus the documented bounded cleanup wrappers. * Python services (`apps/discord/`) maintain their own pinned dependencies and README instructions. ## Testing & Quality Expectations * Test meaningful affected behavior and required repository gates. Once checks pass, repeat or broaden only for new changes, failures, or unresolved risks. Pure documentation edits do not need application test suites. * For DB changes, apply migrations locally when feasible, then generate and verify types. Production pushes remain user-only. * Performance-sensitive changes should document rationale in-code (≤3 lines) plus PR notes. * For `html2canvas`-based preview exports, inline critical SVG brand marks (or use raster assets) and provide a solid export background color so downloaded images do not lose logos or pick up transparent-edge artifacts. For deeper detail—such as React Query policy, toast usage rules, or Tailwind dynamic color guidance—refer directly to [AGENTS.md](https://github.com/tutur3u/platform/blob/main/AGENTS.md#readme). ## Share local validation capacity Before heavy local validation, check `ttr resources status --json` and use the `tuturuuu-cli-resources` skill. Run broad tests, builds, type checks, Supabase setup and browser suites through `ttr resources run -- `. The per-user queue spans registered projects and linked worktrees, so concurrent agents can keep editing while heavy stages run sequentially. Prefer a verified remote runner for broad validation. Do not bypass live queues or stop another session's services to free capacity. See the SDK reference for setup, diagnosis, and rollback. If the installed CLI lacks the command, report its version and keep heavy local work serial with explicit worker limits until upgraded. # Documentation Organization Guide Source: https://docs.tuturuuu.com/overview/organization-guide Understand the Tuturuuu documentation structure and how to extend it. # Documentation Organization Guide Welcome to the reorganized Tuturuuu documentation space. This guide explains the new structure so you can find information quickly and add new content with confidence. ## 🧭 Top-Level Map | Section | Purpose | Key Entry Points | | - | - | - | | **Overview** | Vision, mission, and company playbooks | [Vision & Mission](/overview/vision), [Agent Operating Manual](/overview/agent-operating-manual) | | **Platform** | Product experience, AI systems, shared components, personalization | [Platform Overview](/platform/overview) | | **Build** | Local setup, monorepo workflows, CI/CD | [Build & Ship](/build/overview) | | **Learn** | Examples, experiments, prompt engineering | [Learn & Experiment](/learn/overview) | | **Reference** | Stable APIs and integration contracts | [Reference Home](/reference/overview) | Each section contains focused subpages that keep related content together. Navigation in the sidebar follows this same hierarchy. ## 📂 Directory Layout ```text theme={null} apps/docs/ ├── overview/ # Company vision and organizational guides ├── platform/ # Product experience, AI, components, personalization ├── build/ # Development tooling and workflows ├── learn/ # Examples, experiments, prompt engineering └── reference/ # API contracts and schemas ``` Assets such as images remain in `apps/docs/images/`. Shared assets for navigation (logo, favicon) sit alongside `docs.json`, which is the single source of truth for sidebar navigation, theme, and grouping (Mintlify reads it on build). Adding a file to one of the directories above does **not** publish it until you also register it in `docs.json`. ## ✍️ Adding New Content 1. **Pick a Section** – Choose the directory that matches your topic. When in doubt, align with how end users will search for the information. 2. **Create the File** – Use front matter with `title`, `description`, and `updatedAt` fields. Example: ```mdx theme={null} --- title: 'My Guide' description: 'Brief purpose statement.' updatedAt: '2026-06-21' --- ``` Set `updatedAt` to the date you last meaningfully changed the page (`YYYY-MM-DD`). Keep the single-quote style to match the rest of the docs set. 3. **Cross-Link Thoughtfully** – Prefer absolute links such as `/platform/features/command-center-dashboard` so moves do not break references. 4. **Update Navigation** – Add the new page to `apps/docs/docs.json` in the appropriate group. ## ✅ Conventions to Remember * **Navigation** is defined in `apps/docs/docs.json` and should mirror the directory layout; keep related pages together. * **Diagrams** use Mermaid syntax (rendered by Mintlify). * **Images** belong in `apps/docs/images/` and are referenced with absolute paths (`/images/...`). * **Internal links** use absolute documentation paths (for example `/build/overview`, not `/overview`) so moving files does not break references. * **Linting** — Markdown and MDX are explicitly excluded from Biome (`biome.json` ignores `**/*.md` and `**/*.mdx`), so `bun validate` does not lint these pages. Validate docs by previewing them with the Mintlify CLI and checking that links resolve and front matter is present, rather than relying on Biome formatting. Need inspiration for structuring a new guide? Browse the [Platform Overview](/platform/overview) and [Build & Ship](/build/overview) pages—they demonstrate the preferred narrative pattern (context → diagrams → next steps). If anything feels missing or confusing, open an issue with the `docs` label so we can continue improving the experience together. # Start here Source: https://docs.tuturuuu.com/overview/start-here Find product guides, daily workflows, integration contracts, and operating runbooks. Tuturuuu brings workspace productivity, business operations, learning, creative publishing, AI assistance, and developer tooling into a shared account ecosystem. Start with the task you want to accomplish. Availability depends on the app, workspace permissions, access flags, account eligibility, and configured providers. ## Choose your path | You want to… | Start here | Then explore | | - | - | - | | Choose an app | [Product directory](/platform/applications/overview) | [Apps gateway](/platform/applications/apps) | | Create or join a workspace | [Workspace getting started](/platform/guides/getting-started) | [Workspaces and permissions](/platform/architecture/workspaces-permissions) | | Organize the workday | [Daily workflows](/platform/guides/workflows) | [Tasks](/platform/applications/tasks), [Calendar](/platform/applications/calendar), [Track](/platform/applications/track) | | Run business operations | [Contacts](/platform/applications/contacts) | [Finance](/platform/applications/finance), [Inventory](/platform/applications/inventory), [Storefront](/platform/applications/storefront) | | Teach or learn | [Teach](/platform/applications/teach) | [Learn](/platform/applications/learn), [Nova](/platform/applications/nova) | | Collaborate and create | [Chat](/platform/applications/chat) | [Meet](/platform/applications/meet), [Drive](/platform/applications/drive), [Tulletin](/platform/features/lettin), [Colab](/platform/features/colab) | | Use AI | [AI Studio](/platform/ai/ai-studio) | [Rewise](/platform/applications/rewise), [Model catalog](/platform/ai/model-catalog), [Memory](/platform/ai/memory-service) | | Integrate an application | [SDK](/reference/packages/sdk) | [API introduction](/reference/api-reference/introduction), [Satellite auth](/platform/architecture/satellite-apps) | | Develop without extra runtimes | [Without Docker](/build/development-tools/without-docker) | [Versions](/reference/repository/versions) | | Operate or troubleshoot | [Active runtime map](/build/devops/active-runtime) | [Troubleshooting](/platform/guides/troubleshooting), [GitHub Actions](/build/devops/github-actions-runbook) | | Locate a source implementation | [Repository catalog](/reference/repository/catalog) | The app's route reference and package exports | ## What is active The maintained application path uses Next.js Web and satellite apps, shared TypeScript packages, hosted Supabase, and the owning hosted/Worker services. The Docker cron runner is retired. Docker setup, the Rust backend, and TanStack Start are not in use and are not required to learn, develop, or operate the live Next.js products. Their retained source is historical or future-resumption material. TanStack **Query** is still the active client data library; it is separate from the paused TanStack **Start** frontend. ## Read product claims correctly A public marketing page explains a product; it does not grant access to its private workspace data. A source route describes an implementation; it does not prove deployment or entitlement. Research surfaces and vision documents are identified separately from supported workflows. For source-derived versions, use the [version reference](/reference/repository/versions); for the version a browser is actually serving, use its platform build metadata. # Vision & Mission Source: https://docs.tuturuuu.com/overview/vision The north star for Tuturuuu—why we exist and the future we are building. ![Hero](https://mintcdn.com/tuturuuu/mFGDFuN77oMS85eY/images/hero.png?fit=max\&auto=format\&n=mFGDFuN77oMS85eY\&q=85\&s=3c84d64bc305f494f88550c404cbbad1) # Tuturuuu: Official Company & Product Documentation ### Executive Summary: The Third Era of Technology Tuturuuu is not merely another productivity startup; it is our answer to a fundamental question: **What if technology existed to serve human potential instead of harvesting attention?** We are building the world's first intelligent, open-source operating system for modern work and life, with the ambition to become the "Google" of Vietnam and a global benchmark for transformative technology. Powered by Mira—our proactive AI companion and the JARVIS we envisioned—the Tuturuuu platform unifies calendars, tasks, communications, and knowledge to eliminate digital friction and return focus to the people doing the work. This is the dawn of the **Third Era of technology: the Age of Partners**, where the impossible becomes possible for everyone, everywhere. * **Vision Slogan:** Unlocking Human Potential. * **User-Benefit Slogan:** Your Life, In Sync. * **Product Category Slogan:** The Intelligent OS for Modern Work. ### Our Manifesto: Core Beliefs Driving Tuturuuu * **Focus is the new superpower.** In a world engineered for distraction, the ability to sustain deep work is the defining competitive advantage. * **Technology must be an extension of human will, not a cage for our attention.** Engagement-driven platforms erode our best selves; we build software to reverse that trend. * **Radical transparency and open communities win.** Foundational technology should never be a black box. Our open-source philosophy creates trust, improves security, and accelerates innovation. * **Impact over activity.** Productivity is not about doing more; it is about creating more value. Tuturuuu exists to give people the mental space for their next breakthrough idea. * **Potential has no postcode.** We champion a future in which brilliant ideas can emerge from any street, village, or classroom—because access to world-class tools should never be limited by geography or status. ### Mission and Vision * **Mission (What):** Wage war on digital noise by building an intelligent, unified, and open platform that automates administrative work and eliminates context-switching friction. * **Vision (Why):** Create a future where technology unlocks humanity's potential—liberating our collective focus so we can solve the world's most important challenges while making world-class innovation accessible to everyone, everywhere. ### The Problem We Solve: The Costs of Digital Friction Modern professionals are hired for their minds but trapped in low-value administrative work—a silent epidemic we call the Great Betrayal of Modern Work. Digital friction exacts three distinct costs: 1. **Financial Cost:** Over **21 hours per knowledge worker each week** vanish into "work about work"—a trillion-dollar drag on global productivity. 2. **Cognitive Cost:** Fragmented tools force constant context-switching, imposing a mental tax that slashes productive output by **up to 40%** and fuels burnout. 3. **Innovation Cost:** The next breakthrough is suffocated by inboxes, status meetings, and spreadsheets. Our collective future is lost to noise. ### The Tuturuuu Solution: Entering the Age of Partners The First Era produced passive tools; the Second Era birthed attention-harvesting platforms. Tuturuuu inaugurates the Third Era: proactive ecosystems that amplify human potential. In this paradigm the user becomes the **Visionary**, and AI acts as the intelligent **Partner**—anticipating needs, automating busywork, and protecting focus. ### Competitive Landscape: A Category of One | | **Fragmented & Reactive (Era 2)** | **Integrated & Proactive (Era 3)** | | :- | :- | :- | | **Description** | A "Frankenstein stack" of separate apps requiring manual stitching and constant commands. | A unified nervous system where AI anticipates needs and orchestrates workflows. | | **Examples** | Slack + Asana + Google Drive + Notion | **Tuturuuu** | | **User Experience** | High cognitive load, relentless context-switching. | Seamless flow state with preserved focus. | | **Our Moat** | Point solutions compete feature-by-feature. | We deliver a 10× integrated experience anchored by Aurora's growing context graph. | ### Product & AI Ecosystem: How We Deliver the Future #### Application Layer — Tools for Flow A cohesive suite that behaves like one organism: * **Tuturuuu Calendar (Smart Calendar):** AI auto-scheduling that allocates time by deadlines, priorities, and personal work rhythms. * **Tuturuuu Tasks (Smart Tasks):** Centralized task hub capturing actions from email, chat, and meetings, then scheduling them in Tuturuuu Calendar. * **Tuturuuu Meet (Smart Meetings):** End-to-end meeting solution featuring collaborative planning, location voting, and AI-generated summaries with tracked actions. * **TuMail & TuChat (Smart Communications):** Integrated communications hub where AI surfaces commitments and routes them to Tuturuuu Tasks and Tuturuuu Calendar. * **TuDrive (Unified Storage):** Secure cloud storage woven through tasks, documents, and conversations for effortless knowledge flow. * **TuTrack (Mindful Time Tracking):** Lightweight tracking with Pomodoro rhythms to encourage focused work and healthy breaks. For a deep dive into our GTD-aligned daily experience, explore the [Command Center Dashboard](/platform/features/command-center-dashboard). #### AI Core — Architecture of Intelligence * **Mira (Soul & Voice):** The empathetic conversational interface—translating complex capabilities into a warm, trustworthy partner. * **Aurora (Nervous System):** The contextual engine that links related emails, tasks, files, and events, creating our primary data moat. * **Rewise (Collective Mind):** Aggregator of leading AI models (OpenAI, Gemini, Anthropic, and more) to ensure Mira always draws from the best knowledge. * **Nova (Conscience & Forge):** Our prompt-engineering and alignment platform, shaping how Mira reasons and guarantees safety. * **Crystal (Bridge to Humanity):** Multi-modal embodiment of Mira enabling real-time collaboration via voice, video, and screen sharing. ### Long-Term Vision: The Tuturuuu Ecosystem Our roadmap stretches far beyond productivity checklists. We are assembling an ecosystem where every component—people, agents, data, and services—cooperates to help anyone transform ambition into reality. #### Mira (Codename Jarvis): The Life Operating System * **Mira** is the next-generation companion we envisioned as JARVIS—an autonomous guardian that plans, reasons, and acts on your behalf so you can simplify life and accomplish more. * Mira synchronizes calendars, goals, finances, communications, and personal knowledge, surfacing proactive recommendations instead of passive reminders. * She learns from context, understands intent, and orchestrates the right Tuturuuu tools—or external services—without requiring manual hand-offs. #### Multi-Agent Intelligence Fabric * Specialized agents (planning, finance, research, wellness, creative) collaborate through Mira to deliver end-to-end outcomes. * Agents talk to each other via shared context graphs, ensuring that insights collected in one domain (e.g., research) immediately inform actions in another (e.g., scheduling or budgeting). * The ecosystem adapts dynamically, deploying the minimal number of agents necessary to solve a problem while maintaining full user oversight. #### Learning Loops & Continuous Improvement * **AI memories** capture outcomes, preferences, and feedback, allowing the system to anticipate needs with greater precision over time. * A **data crawler** and **internal knowledge base** ingest documents, conversations, and educational content, grounding every action in trusted information. * **Reinforcement learning playgrounds** and Nova's prompt-engineering workflows close the loop between customer challenges and product enhancements, turning every interaction into a learning opportunity. * Metrics, scoring, and feedback dashboards quantify impact, guiding both automated improvements and human-crafted iteration. #### Execution & Automation Layer * **Aurora** coordinates cloud code execution, Cron jobs, and real-time integrations so agents can take decisive, auditable actions. * External APIs, partner platforms, and even physical devices connect through unified orchestration, ensuring Mira (our Jarvis) can reach beyond Tuturuuu when a task demands it. * Guardrails keep automation transparent and reversible, reinforcing trust while delivering tangible outcomes. #### Democratizing Breakthroughs * Educational pathways and community programs share the system's capabilities with schools, startups, and enterprises, nurturing the next generation of builders. * By lowering the barrier to world-class technology, Tuturuuu enables creators everywhere—from Ho Chi Minh City to remote villages—to solve local problems with global-grade tools. * This long-term vision is how we intend to make the impossible possible for everyone, everywhere. ### Visualizing the Tuturuuu Ecosystem #### End-to-End Interaction Lifecycle ```mermaid theme={null} graph LR A[Visionary] -->|State goal| B[Mira] B -->|Plan & delegate| C[Agent Mesh] C -->|Fetch context| D[Aurora] D -->|Get knowledge| E[Rewise] C -->|Validate| F[Nova] C -->|Execute| G[Apps] G -->|Updates| A C -->|Log outcomes| H[Feedback Loop] H -->|Improve| B style B fill:#4f46e5,stroke:#3730a3,color:#fff style C fill:#4f46e5,stroke:#3730a3,color:#fff ``` #### Continuous Learning Loop ```mermaid theme={null} graph TD Start([Start]) --> Capture[Capture Intent] Capture --> Contextualize[Contextualize] Contextualize --> Plan[Plan Strategy] Plan --> Execute[Execute Actions] Execute --> Reflect[Reflect on Results] Reflect --> Improve[Improve Models] Improve --> Capture Reflect --> End([Goal Satisfied]) style Capture fill:#4f46e5,stroke:#3730a3,color:#fff style Plan fill:#4f46e5,stroke:#3730a3,color:#fff style Improve fill:#4f46e5,stroke:#3730a3,color:#fff ``` #### Layered Architecture Overview ```mermaid theme={null} graph TB subgraph Experience["Experience Layer"] Mira["Mira & Crystal"] Apps["Tuturuuu Apps"] end subgraph Intelligence["Intelligence Layer"] Agents["Agent Mesh"] Aurora["Aurora Context"] Nova["Nova Alignment"] Rewise["Rewise Knowledge"] end subgraph Data["Data Layer"] Memory["AI Memories"] KB["Knowledge Base"] end subgraph Infra["Infrastructure"] Cloud["Cloud Execution"] Integrations["Integrations"] end Mira --> Agents Apps --> Agents Agents --> Aurora Aurora --> Rewise Aurora --> Nova Nova --> Agents Aurora --> Memory Memory --> KB KB --> Agents Cloud --> Agents Integrations --> Cloud style Agents fill:#4f46e5,stroke:#3730a3,color:#fff style Aurora fill:#4f46e5,stroke:#3730a3,color:#fff ``` ### Technology Stack & Architecture * **Frontend:** Next.js, React, TypeScript, Tailwind CSS. * **Backend & Database:** Postgres, Supabase. * **Infrastructure & Deployment:** Vercel. * **Architecture:** Turborepo + Bun monorepo that accelerates collaboration, code sharing, and deterministic deployments. Browse the source at [https://github.com/tutur3u/platform](https://github.com/tutur3u/platform). ### Business Model & Growth Strategy: The Community Flywheel 1. **Open-Source Core:** Publishing our codebase invites global contributors, builds trust, and establishes transparent security practices. 2. **Bottom-Up Adoption (Free Tier):** A generous individual plan seeds Tuturuuu organically inside thousands of organizations. 3. **Product-Led Expansion (Pro & Business Tiers):** Teams upgrade to unlock pooled resources, expanded AI usage, and advanced controls. 4. **Top-Down Value (Enterprise & Platform API):** Broad adoption paves the way for enterprise engagements and a high-margin API exposing Nova, Rewise, and future services. Plan tiers at a glance: * **Free:** Mass adoption and community growth. * **Pro:** Power users and freelancers with increased AI allowances and storage. * **Business:** Team-centric controls, pooled usage, and enhanced security. * **Platform API (Future):** B2B access for companies building on Tuturuuu's AI primitives. ### Team & Culture: Building for the Third Era * **Builders, not employees.** Each teammate acts like a founder within their domain. * **Pragmatic optimism.** We pair bold ambition with rigorous execution. * **Relentless ownership.** Decisions come with accountability for outcomes. * **Transparency by default.** Internal operations mirror our open-source ethos. * **Vietnam-rooted, globally ambitious.** We build from Southeast Asia with the conviction that world-class technology can originate anywhere. ### Company Information * **Legal Name:** CÔNG TY CỔ PHẦN TUTURUUU (TUTURUUU JOINT STOCK COMPANY). * **Abbreviated Name:** TUTURUUU JSC. * **Tax Code:** 0318898402. * **Date of Operation:** 02 April 2025. * **Registered Address:** Tầng 14, Tòa Nhà HM Town, 412 Nguyễn Thị Minh Khai, Phường 05, Quận 3, Thành phố Hồ Chí Minh, Việt Nam. * **Tax Address:** Tầng 14, Tòa Nhà HM Town, 412 Nguyễn Thị Minh Khai, Phường Bàn Cờ, TP Hồ Chí Minh, Việt Nam. * **Founder, CEO & Chairman:** Võ Hoàng Phúc. * **Website:** [https://tuturuuu.com](https://tuturuuu.com). * **Contact:** [contact@tuturuuu.com](mailto:contact@tuturuuu.com). * **GitHub:** [https://github.com/tutur3u/platform](https://github.com/tutur3u/platform). ## Setting up The first step to getting started with Tuturuuu is to set up your development environment. > **[Development Setup](/build/development-tools/development)** > > Learn how to set up your development environment. # AI Agent Deployment Source: https://docs.tuturuuu.com/platform/ai/ai-agent-deployment Operate apps/web-hosted Discord and Zalo AI agents backed by Chat SDK and AI SDK. The internal Infrastructure → AI Agents module manages root-only agent configs that are served by `apps/web` webhook routes. It is the first production path for bidirectional agent presence across Discord and Zalo. ## Runtime Boundary Deploying an agent enables an `apps/web` webhook endpoint: ```txt theme={null} /api/v1/webhooks/ai-agents/:adapter/:channelId ``` `apps/web` loads the channel config from root `workspace_secrets`, creates a Chat SDK runtime through `@tuturuuu/ai/chat-sdk`, and runs the response loop with AI SDK `ToolLoopAgent`. Production deployments use Redis so thread subscriptions, dedupe, and locks survive cold starts and multiple instances. Runtime resolution checks, in order: 1. Root workspace secret `AI_AGENT_CHAT_SDK_STATE_REDIS_URL`. 2. Environment variables `AI_AGENT_CHAT_SDK_STATE_REDIS_URL`, `REDIS_URL`, or `DOCKER_WEB_REDIS_URL`. 3. The bundled blue/green Docker Redis service at `redis://redis:6379` when a blue/green runtime mount or Docker SRH URL is present. Local development may use the Chat SDK memory state adapter when no durable Redis runtime is configured. Agent response loops and manual external-chat draft generation use the shared Tuturuuu AI memory layer. Memory is scoped to the operator or channel actor plus the channel workspace, then stored through the first-party memory sidecar using the `ai_agents` product metadata. Do not add agent-specific browser memory calls; all recall, writes, and deletes must stay behind the server-owned `@tuturuuu/ai/memory` boundary and workspace memory APIs. Webhook URLs are generated from the canonical public platform origin, not the incoming request host. Set `AI_AGENT_WEBHOOK_ORIGIN` for an explicit override; otherwise `WEB_APP_URL`, `NEXT_PUBLIC_WEB_APP_URL`, `NEXT_PUBLIC_APP_URL`, `PLATFORM_BUILD_DEPLOYMENT_URL`, and production fallback `https://tuturuuu.com` are used before local request-origin fallback. ## Configuration Storage Agent configuration stays under root workspace secrets: ```txt theme={null} AI_AGENT_REGISTRY::meta AI_AGENT_REGISTRY::instructions AI_AGENT_REGISTRY::channel::meta AI_AGENT_REGISTRY::channel::secret: AI_AGENT_IDENTITY::zalo:: AI_AGENT_ZALO_PERSONAL_ENABLED ``` Admin APIs redact channel secrets. One-time generated values are shown only after rotation. Feature flags for this surface are also root workspace secrets. Experimental personal Zalo account support is enabled by default only for the internal root workspace. Other workspaces require `AI_AGENT_ZALO_PERSONAL_ENABLED = true`; do not gate it with process environment variables. Phone-history transfer sends one approval request and uses deliberately low-cadence, cancellable polling to avoid notification and API spam. External chat history is mirrored separately in the `private` schema: ```txt theme={null} private.ai_agent_external_threads private.ai_agent_external_messages ``` Only server-owned `apps/web` routes call the private RPCs for listing, syncing, drafting, and sending. Browser clients never read these private tables directly. ## Chat Discovery The shared chat UI displays mirrored external AI-agent threads as read-only AI conversations in the workspace selected for the agent channel. This works in `apps/web` and the standalone `apps/chat` app. Chat users can inspect mirrored history there, while root AI-agent admins can use the setup, operations, and manual-response controls from Infrastructure > AI Agents or the `apps/chat` agent details sidebar. The root workspace may still show enabled agent channel setup entries so operators can jump to channel configuration. Those setup entries are not the message mirror; mirrored external threads use `ai-agent-thread-` conversation IDs. Root AI-agent admins can also manage those setup entries from the standalone `apps/chat` internal workspace. The `internal` workspace resolves to `ROOT_WORKSPACE_ID`, and admin-visible setup conversations include the minimum agent/channel IDs needed by the sidebar operations panel. Non-admin chat viewers still receive scrubbed setup metadata. ## Manual Response Console Infrastructure > AI Agents is the full setup and operations surface: * Configure Discord and Zalo credentials, workspace mapping, auto-response, and history sync per channel. * Inspect mirrored external threads and messages. * Trigger an on-demand external history sync when the adapter supports it, including phone-approved transfer sync for personal Zalo accounts. * Generate a draft with a custom operator prompt and mirrored history context. * Send the reviewed draft back to the external platform exactly as edited. Discord can fetch recent thread/channel history through the Chat SDK adapter when the bot token has the required scopes. Official Zalo channels still rely on webhook/runtime events. Personal Zalo channels can import Zalo Web-visible history through **Sync history** and can request phone-approved mobile transfer history through **Sync phone** when older messages are only present on the paired mobile device. The same external-thread operations are available from `apps/chat` for root AI-agent admins when an external AI-agent thread is selected: sync external history, draft a manual response, send the reviewed response, and refresh the mirrored conversation. ## Testing From Apps/Chat Use `apps/chat` as the operator smoke-test surface after deployment: 1. Open the `internal` workspace and select the AI-agent setup conversation. 2. Confirm setup data loads instead of the metadata-hidden notice. 3. Run **Test** as a readiness check for required credentials and channel status. The diagnostics list should pass for agent enabled, channel enabled, deployed status, required secrets, webhook URL, workspace mapping, adapter account mapping, and recent error state. This does not replace a live external-platform round trip. 4. For Discord, set the generated webhook URL as the Interactions Endpoint URL so Discord performs its endpoint verification. Then install the app and send a live mention/message in the mapped channel. The official references are [Discord interactions](https://docs.discord.com/developers/interactions/overview) and the [Discord quickstart](https://docs.discord.com/developers/quick-start/getting-started). 5. For personal Zalo, set the channel to `Personal account`, open the operations tab, run **Pair QR**, scan the QR code from the Zalo mobile app, then run **Validate**, **Sync history**, **Sync phone**, **Deploy**, and **Start**. Approve the transfer-sync prompt on the phone when **Sync phone** requests it. Use a second Zalo account or group sender for the live inbound-message test. 6. From the setup conversation, open the **Thread** tab to list recent mirrored external threads for the selected agent channel. Use **Sync external thread** from that list when a mirrored thread exists. 7. Select a mirrored `ai-agent-thread-` conversation and use **Sync external thread**. A zero-message result means the adapter found no newer messages. 8. Draft and send a manual response from the thread panel, then confirm the mirrored conversation refreshes. ## Discord And Zalo Setup For Discord, configure the app with the generated webhook URL, then store the application ID, public key, bot token, guild ID, and optional mention role IDs on the Discord channel. Discord message events require Gateway delivery. For a self-hosted watcher, run `apps/discord/ai_agent_gateway_watcher.py` with: ```txt theme={null} DISCORD_AI_AGENT_GATEWAY_BOT_TOKEN= DISCORD_AI_AGENT_GATEWAY_PLATFORM_URL=https:// DISCORD_AI_AGENT_GATEWAY_WATCHER_SECRET= ``` Store the same `AI_AGENT_DISCORD_GATEWAY_WATCHER_SECRET` value as a root workspace secret in apps/web. The watcher calls the deployed apps/web watcher config endpoint to discover enabled, deployed Discord channel webhooks, and apps/web only returns channels mapped to `ROOT_WORKSPACE_ID`. Set `DISCORD_AI_AGENT_GATEWAY_CHANNEL_ID` when one watcher should pin a single root-internal Discord channel. The watcher forwards raw Gateway packets using the Chat SDK Discord forwarding contract (`GATEWAY_` JSON plus `x-discord-gateway-token`) so apps/web continues to own AI-agent runtime, identity mapping, mirroring, and responses. Gateway-token forwarded webhook requests are rejected for non-root workspaces; normal Discord HTTP interactions still use the configured channel webhook path. Keep the bot token value in runtime secrets only. For local smoke tests, `DISCORD_AI_AGENT_GATEWAY_WEBHOOK_URL` may be set to one generated Discord channel webhook URL instead of using auto-discovery. For Zalo, configure the bot webhook URL in the Zalo Bot dashboard, set the secret token to the channel's `webhookSecret`, and store the bot token plus OA ID on the Zalo channel. For experimental personal Zalo account testing, set the Zalo account mode to `Personal account`, then use **Pair QR** from the `apps/chat` setup conversation or the shared AI-agent operations panel. The QR flow runs `zca-js` `loginQR()` server-side, stores `personalCookieJson`, `personalImei`, and `personalUserAgent` as channel secrets, and records `zaloPersonalOwnId` after confirmation. The browser receives only QR/session status, never raw cookies, IMEI, or user agent values. Manual cookie JSON, IMEI, and user agent entry remains a fallback for local debugging. After either setup path, use **Validate** to confirm login, then use **Sync history** to import Zalo Web-visible personal user and group threads into Tuturuuu Chat. When the mobile device owns additional history, use **Sync phone** and approve the transfer-sync request in the Zalo mobile app. The phone-transfer action is owned by `apps/web`; `apps/chat` reaches it only through the internal API proxy, and the browser never receives cookies, IMEI, user agent values, private transfer keys, or raw transfer payloads. Historical sync walks the available Zalo user and group history and upserts it idempotently, so operators can rerun it to resume older imports without duplicating conversations or messages. It never triggers AI auto-responses for old messages. Supported image, video, audio, and file attachments are copied to the channel workspace's configured Drive provider under `AI Agent Imports`. Chat exposes those files through its authenticated attachment route instead of retaining expiring Zalo CDN links. Apply the corresponding private-schema media migration before enabling attachment imports in production. Deploy the channel and use **Start**/**Stop** for the live listener lifecycle. Personal Zalo channels do not receive webhooks, and only one Zalo Web listener can be active per personal account at a time. Use test accounts only; the upstream `zca-js` package is an unofficial Zalo Web automation API and can trigger account locks or bans. For experimental root-internal external chatbots, choose the explicit `Internal` workspace option in the AI-agent workspace picker. It stores `workspaceId = ROOT_WORKSPACE_ID` on the channel and keeps the runtime, test, deploy, and mirror paths scoped to the internal workspace. ## Mapped User Requirement Agents never write as a global service user in v1. Each inbound external user must map to a Tuturuuu workspace user before task or calendar tools can run. Discord uses the existing `discord_guild_members` mapping for the configured guild. Zalo uses root secret identity links: ```txt theme={null} AI_AGENT_IDENTITY::zalo:: = ``` The mapped Tuturuuu user's permissions are enforced. Task writes require `manage_projects`; calendar writes require `manage_calendar`. If permissions are missing, the agent replies with a permission-aware message instead of writing. ## Tool Allowlist V1 exposes only workspace context, members, task handoff, and calendar tools. Finance, time tracking, memory, image generation, web search, delete tools, and broad marketplace tool selection stay out of scope until there is a separate approval and audit model. # AI Studio Source: https://docs.tuturuuu.com/platform/ai/ai-studio Operate Tuturuuu AI Studio policies, credentials, traces, and workspace credit metering. AI Studio is the workspace-scoped development surface at `https://ai.tuturuuu.com`. It is a registered satellite app and uses the same workspace session, permissions, settings, and billing context as other Tuturuuu apps. ## Provider availability and step timing Check model availability with the provider, not only the internal catalog: retired image models can remain listed. A gateway model-not-found response is exposed as `model_not_found` so clients can stop retrying artwork without treating it as a broken sponsorship connection. Step timings are rounded to whole milliseconds at persistence; fractional SDK timings must not be sent to the integer `latency_ms` column. Credit and cost precision is preserved. ## Workspace sections Each section is its own route under `/`; there is no catch-all section route. | Group | Section | Route | Requires | | - | - | - | - | | — | Overview | `/` | `use_ai_studio` | | Build | Playground | `/playground` | `use_ai_studio` | | Build | Prompts, Agents, Datasets | `/prompts`, `/agents`, `/datasets` | `use_ai_studio` | | Governance | API keys | `/api-keys` | `manage_ai_keys` | | Governance | Model policy | `/model-policy` | read with `use_ai_studio`, edit with `manage_ai_policy` | | Observe | Runs | `/runs` | `use_ai_studio` | | Observe | Usage | `/usage` | `use_ai_studio` | | Observe | Credits | `/credits` | `use_ai_studio` | | — | Developer docs | `/developer-docs` | `use_ai_studio` | `/logs` used to render the same activity explorer as `/runs` and now permanently redirects there. Every observability filter — range, custom from/to, model, feature, status, and the expanded run — is stored in the URL, so a filtered view can be shared or bookmarked. Evaluations and experiments are not shipped. They are absent from navigation and routing until they have a backing implementation, rather than rendering a placeholder. ## Access and issuance controls Workspace members with `use_ai_studio` can review settled credit deductions, Studio-metered runs, provider cost, and the applicable personal or workspace credit status. Observability and execution do not depend on a global or workspace Studio enablement switch. Model execution still requires the requested model to be enabled and granted by the global catalog, workspace policy, plan, and credential scope. Ordinary callers must also have enough workspace credits and remain within request, budget, rate, payload, and abuse limits. Verified registered external apps keep their temporary zero-credit integration policy while remaining fully audited. Root administrators configure global defaults and workspace overrides in Infrastructure → AI Studio. Workspace administrators manage existing keys, retention, and model restrictions from AI Studio. Creating or rotating a `ttr_ai_` key additionally requires a standing workspace grant from a platform administrator. Removing that grant blocks new issuance and rotation but does not revoke existing keys. ## Model policy `//model-policy` is the self-serve editor for the workspace row in `private.workspace_ai_studio_policies`. Members with `use_ai_studio` see the current policy read-only; `manage_ai_policy` is required to save. * **Allowed models** — empty means "no workspace allow list"; every model the platform catalog and the workspace plan permit stays callable. A non-empty list restricts execution to exactly those model ids. * **Denied models** — evaluated before the allow list, so a denied model is blocked even when it is also allowed. * **Requests per minute** and **monthly credit budget** — per-credential ceilings; leave empty for unlimited. * **Capture**, **content retention**, and **metadata retention** — leave on *Inherit* to follow `private.ai_studio_global_settings`. The editor shows the current platform default beside each field. * **No training** — keep enabled unless a signed agreement says otherwise. The form enforces the same bounds as the `PATCH` schema (content retention 1–365 days, metadata retention 30–2555 days, rate 1–10000/min, budget above zero), so an out-of-range value is rejected before the request is sent. ## AI-only keys Studio keys use the `ttr_ai_` prefix. The plaintext key is revealed once; only its SHA-256 digest is stored. A key is a workspace service credential, not a human session, and it cannot authorize non-AI Tuturuuu APIs. Keys can be limited by environment, model, expiry, request rate, and credit budget. Rotate or revoke a key immediately when its value may have been exposed. Never write plaintext keys to logs, database columns, issue trackers, or committed configuration. The key page remains available to workspace key managers when issuance is not approved so they can inspect and revoke existing credentials. Rotation is treated as new key issuance and is therefore approval-gated. Approved key managers can quick-create a development key from either the key page or Playground. The one-time secret can be handed to Playground through browser session storage; it is removed when read and is never sent through a dashboard URL or persisted by the Studio application. ## Production Playground Playground calls `https://ai.tuturuuu.com/v1/models`, `/v1/responses`, and `/v1/chat/completions` with the supplied AI-only key. It therefore exercises the same authentication, model policy, credit reservation and settlement, budgets, rate limits, abuse controls, and logging as an external production client. It does not use a privileged dashboard proxy. Text generation uses the AI SDK Google provider and the `GOOGLE_GENERATIVE_AI_API_KEY` configured on the AI Studio deployment. Public API, policy, and observability records keep the canonical `google/...` model ID; only the provider adapter receives the bare Gemini model name. Vercel AI Gateway credentials and routing are not used for this execution path. The workbench supports bounded AI SDK tool loops with the safe calculator and current-time demonstration tools. Tool loops are limited to eight model steps. The response shows a sanitized execution trace; the observability run table can expand that trace after settlement. ## Metering lifecycle Ordinary Studio keys and non-external callers follow one transactionally guarded lifecycle: 1. authenticate the session or AI-only key; 2. resolve the global, workspace, plan, and key policy intersection; 3. reserve the maximum permitted credits; 4. execute the provider call; 5. persist the run and trace metadata; and 6. settle exact provider usage and release unused credits. Provider failures and aborted streams still settle billable usage. Runs record model, key, prompt or agent version, latency, first-token latency, token or media units, provider cost, billed credits, status, and a stable request ID. The dashboards combine these Studio runs with unmatched deductions from the shared AI credit ledger, so AI features outside Studio remain visible without double-counting deductions already linked to a run. Logs expose only sanitized metering fields, never raw prompts, outputs, tool payloads, or provider errors. AI SDK model and tool lifecycle callbacks additionally write ordered run steps. Each step stores its type, safe tool or model name, status, latency, token counts, and settled cost. Inputs, tool arguments, tool results, generated text, provider metadata, and unredacted errors are excluded from the step record. Registered external apps are the only temporary billing exception. Their short-lived token must include `workspace:session` plus `ai:use` or `tts:use`, the app must remain enabled and linked to the requested workspace, and the user must still be a current workspace member. These calls reserve no workspace credits, but they still enforce model and workspace policy, workspace request limits, abuse controls, payload limits, and full run/provider-cost auditing. ## Trace retention Run metadata is retained for 365 days by default. Prompt content, model output, tool arguments, and tool results are not captured unless the workspace explicitly enables content capture. Captured content defaults to 30 days and must be redacted before persistence. Customer AI content is not used for general-purpose model training by default. Provider-specific no-training and data-control options should be enabled when the provider supports them. ## Curated tools Agents can use only tools declared in the root tool catalog and explicitly enabled for the workspace. Tools must enforce workspace scope and normal Tuturuuu permissions. Arbitrary HTTP requests, undeclared data access, and code execution are not supported. ## Local verification ### Colab sponsorship accounting The Colab endpoint deduplicates billing using the validated workshop job ID and provider-call sequence. Sponsored models must have a positive known price before any reservation or generation starts. A pricing failure during settlement finalizes the run as failed and releases the reservation; it does not represent free successful usage. Inspect `pricing_status: unavailable` and `reconciliation_required: true` in run metadata, restore model pricing, and reconcile the retained token counts before treating sponsorship totals as complete. Step pricing failures likewise do not create misleading priced-zero steps. Apply and test the private-schema migrations before running the app: ```bash theme={null} bun sb:up cd apps/database node scripts/run-supabase.js test db supabase/tests/ai-studio-foundations.sql ``` Then run the focused checks: ```bash theme={null} bun --filter @tuturuuu/ai-studio test bun --filter @tuturuuu/ai-studio type-check bun --filter @tuturuuu/ai-studio build ``` Keep model grants, budgets, rates, capture policy, and legal publication controls conservative while expanding API-key issuance workspace by workspace. # ChatGPT subscriptions Source: https://docs.tuturuuu.com/platform/ai/chatgpt-subscriptions Use a personal ChatGPT plan for eligible chat requests in a local or self-hosted Tuturuuu installation. Local and self-hosted installations can connect personal ChatGPT accounts through [OpenAI's open-source plan-sharing flow](https://developers.openai.com/siwc/token-sharing-open-source). The hosted Tuturuuu service does not enable this integration. Hosted support needs OpenAI's separate access path; open-source licensing does not establish hosted eligibility. ## Enable your installation Use a Node.js web runtime with persistent, private filesystem storage. Set these server environment variables and restart the web app: ```sh theme={null} export TUTURUUU_DEPLOYMENT_MODE=self-hosted export OPENAI_CHATGPT_ENABLED=true export CHATGPT_SUBSCRIPTIONS_DIR=/absolute/private/path/chatgpt ``` Mount that directory persistently for containers. Restrict it to the runtime owner; directories use `0700` and credential files use `0600` on Unix. The default path is `~/.config/tuturuuu/chatgpt`. Never place it inside public assets, source control, logs, analytics, backups accessible to workspace members, or browser storage. Serverless installations with ephemeral filesystems are not supported by this flow. ## Connect your account Sign in to Tuturuuu and open **ChatGPT plan** beside the chat model picker. Expand the connection instructions to get a command containing your Tuturuuu user UUID. From the repository root on the computer running your browser: ```sh theme={null} bun scripts/chatgpt-connect.ts --user ``` The utility opens the system browser at OpenAI's **Continue with ChatGPT** flow. It binds a random-port callback to `127.0.0.1`, checks state, PKCE, signature, issuer, audience, expiration and nonce, and verifies ChatGPT plan permission. It does not require an OpenAI API key or client secret. Never paste tokens into Tuturuuu's browser UI or support conversations. Each account/workspace registration has its own issued client ID and credential record. To reconnect a saved registration, add `--client `. Do not copy one account's client ID onto another account's tokens. For a remote self-hosted server, complete OAuth locally, transfer the protected credential file over SSH to a private temporary path, then run the import utility on the server with the same Tuturuuu user UUID: ```sh theme={null} bun scripts/chatgpt-connect.ts --user --import-file /private/transferred-file.json ``` The credential filename is the SHA-256 digest of the Tuturuuu user UUID followed by `.json` in `CHATGPT_SUBSCRIPTIONS_DIR`. The import preserves the server's own host ID. Securely remove the temporary transfer file after import. Stop using the local session so only the server refreshes the imported rotating refresh token. OpenAI currently does not offer host-specific revocation for transferred sessions. ## Use your plan Refresh the **ChatGPT plan** menu and select an account and model. The catalog is read from OpenAI with that account's OAuth token; gateway plan allowlists do not filter the subscription catalog. **Using ChatGPT plan** remains visible near the composer, with a link to [Manage usage](https://chatgpt.com/settings/usage). ChatGPT mode supports streaming chat with text and compatible image/file inputs. Models use their default reasoning settings. It sends the required conversation history to the public Responses API with `store: false` and `stream: true`. It does not use ChatGPT's private backend API. ChatGPT mode currently does not run Mira workspace tools, memory-provider calls, web search, voice, transcription, or image generation. Select a Tuturuuu model explicitly to use those existing features. Unsupported audio/video uploads are filtered before upload, existing thread audio/video files are excluded, and explicit audio/video inputs are rejected before subscription inference. Subscription requests bypass Tuturuuu model allocation, credit preflight, output credit caps, memory-provider wrappers, and credit deductions. New conversations get a local title derived from their first message, without a hidden AI title call. History stays in Tuturuuu under its existing user ownership checks. The request's captured model selects both the endpoint and authentication, even if the composer selection changes while sending. The funded endpoint rejects `chatgpt/` models before authentication, model fallback, persistence, or credit work. Regression coverage lives in `mira-chat-transport.test.ts` and `subscription-route.test.ts`. ChatGPT plan and app limits still apply. A failed, incomplete, or interrupted stream is not a completed answer. Tuturuuu never automatically retries it using Tuturuuu-funded AI. Follow **Manage usage**, reconnect the account if necessary, or explicitly choose another model. Disconnect clears that registration's local tokens and attempts remote refresh-token revocation. If revocation is not confirmed, disconnect the app in ChatGPT Settings too. ## Operations and verification Filesystem locks serialize refreshes across workers sharing the directory. If a process dies while holding a `.lock` directory, requests fail closed after thirty seconds. Confirm no server worker or connection utility is using that registration before removing only its stale lock directory. Do not delete credential files to clear a lock. Use a shared filesystem that provides atomic directory creation and rename; separate containers with copied sessions must not independently refresh. Focused checks: ```sh theme={null} ttr resources run -- bun run --cwd apps/web test src/lib/chatgpt ttr resources run -- bun run --cwd packages/ai test src/chat/google/stream-finish-persistence.test.ts ``` Require type-check, lint, test, and the owning web build in CI for the exact commit; do not run `bun validate` or builds locally. Mocked tests and a successful CI build do not establish real subscription eligibility. Complete a real OAuth connection, choose an account-specific model, receive a completed streamed answer, verify persisted history, and confirm that Tuturuuu credits were not charged before claiming live provider verification. # AI Memory Service Source: https://docs.tuturuuu.com/platform/ai/memory-service How Tuturuuu uses first-party pgvector memory for cross-product AI memory. Tuturuuu AI memory is backed by an internal Postgres/pgvector sidecar through the server-only `@tuturuuu/ai/memory` boundary. Product routes must not call the sidecar from the browser and must not create product-specific memory stores. ## Scope Memory scope is always `user + workspace`. The shared helper builds a stable container tag from those two identifiers and stores product, surface, route, locale, timezone, conversation, and workspace metadata on each write. Default recall is cross-product within that `user + workspace` container. Use metadata filters only when a route needs a narrower product or surface view. ## Runtime Use `withAiMemory` for AI SDK calls when the route has a user and workspace. Use `ingestAiMemoryEvent`, `buildAiMemoryContext`, and the Mira-compatible tool executors for explicit memory reads and writes. Reads fail open by default, and writes are best effort. Every embedding used for memory add/search is generated through the metered `@tuturuuu/ai` embedding helper before the sidecar is called. If credits, pricing, token counting, or billable attribution cannot be verified, the memory operation skips before calling Google. Structural metering failures disable memory for the user scope. Keep `SUPERMEMORY_FAIL_OPEN=true` unless a product explicitly requires strict persistence. Required server-side env: ```txt theme={null} SUPERMEMORY_ENABLED=true SUPERMEMORY_BASE_URL=http://supermemory:8787 SUPERMEMORY_API_KEY=... SUPERMEMORY_TIMEOUT_MS=1500 SUPERMEMORY_FAIL_OPEN=true SUPERMEMORY_DATABASE_URL=postgres://... ``` For Docker blue/green and watcher deployments, the Docker helper auto-generates and injects the internal API key, bundled Postgres password, database URL, internal base URL, fail-open setting, and timeout. Use `DOCKER_SUPERMEMORY_API_KEY`, `DOCKER_SUPERMEMORY_POSTGRES_PASSWORD`, `DOCKER_SUPERMEMORY_DATABASE_URL`, or `DOCKER_SUPERMEMORY_ENABLED=false` only when an operator needs to override that generated runtime. An explicit false value also removes the sidecar from Docker blue/green support builds and health gates. `SUPERMEMORY_API_KEY` is internal infrastructure configuration. Never expose it through browser-visible env vars or client responses. ## User Controls Workspace settings live behind: ```txt theme={null} GET/PATCH /api/v1/workspaces/:wsId/ai/memory/settings GET /api/v1/workspaces/:wsId/ai/memory/items DELETE /api/v1/workspaces/:wsId/ai/memory/items/:memoryId POST /api/v1/workspaces/:wsId/ai/memory/export ``` These first-class API handlers forward the incoming request to authentication, so mobile Bearer credentials and browser cookies use the same current-user and MEMBER workspace checks. Export and deletion remain available while collection is disabled; that does not enable collection or authorize another actor. The settings dialog exposes enable/disable, product toggles, search/list, delete, and export controls. API routes call private schema RPCs through the server-side Supabase admin client. ## Migration Legacy `mira_memories` rows are imported with the admin-only backfill endpoint: ```txt theme={null} POST /api/v1/admin/ai/memory/backfill-mira ``` Backfill is idempotent through stable `customId` values. Rows without a legacy workspace are imported into the user's default or personal workspace and tagged with `legacy_mira` metadata. ## Self-Hosting The Docker fleet runs the first-party memory sidecar as an internal support service named `supermemory` for compatibility with existing base URL, API key, watcher, and Compose wiring. The sidecar stores 3072-dimensional `gemini-embedding-2` vectors in `extensions.halfvec(3072)` with HNSW cosine indexes, plus GIN indexes for metadata and full-text hybrid search. The `supermemory-db-migrate` service applies `apps/supermemory/db` schema changes before the runtime starts. The watcher and cron recovery path use the same generated Docker env, so recreating `web-blue-green-watcher` does not require manually exporting memory service secrets. There is no `SUPERMEMORY_IMAGE` enterprise-image contract. Connectors such as Google Drive, OneDrive, and Notion are disabled for the first rollout. Product ingestion should persist concise summaries only; do not ingest raw files or binaries unless the source is user-owned, enabled, and explicitly appropriate for memory. ## Mobile Assistant Settings The mobile Assistant settings hub separates personal assistant identity from workspace memory. Name, tone, personality, and boundaries update the current user's existing Mira soul. Memory controls address that user's current workspace and list Mira memories only. Opening settings never changes consent. The global memory toggle preserves all existing product overrides; an existing disabled Mira override remains visible rather than implying that the global toggle enables Mira. An unavailable consent read is shown as unavailable, with retry, rather than inventing an enabled or disabled state. Memory viewing, confirmed deletion, and explicit export use the existing internal API. A row disappears only after the server confirms deletion. Export is shared only after the request completes within the same authorized settings scope. These controls create no offline privacy replay or separate memory store. Meet's separate opt-in memory remains independent. Central Settings and the Assistant settings action open the same settings hub. Personality opens a dedicated page listing Assistant name, Tone, Response length, Personality, and Boundaries. Each row opens its own settings editor; saving updates that field against the latest confirmed personal soul and returns to Personality. Failed saves retain the draft for an explicit retry. Existing custom tone and response-detail values remain selectable. These pages and individual memory editors share the hub's single title and floating back action, with scrollable content and the frame kept above the keyboard. System back and dock back return one level without submitting an edit. Opening a memory row reads its canonical content and revision through the existing Mira memory API. Saving uses that revision; a conflict retains the draft and requires reviewing the latest version before explicitly saving again. A confirmed receipt updates the list. An audit warning keeps the editor open, says the change is saved, and disables resubmitting the same content. Editors cancel on account or workspace transitions, including switching away and back during a pending read, review, or save. They never approximate editing by deleting and recreating a memory, and do not change collection consent. Settings retain prior confirmed values when a write fails and expose a localized retryable error. Account or workspace changes invalidate delayed reads, writes, and exports. Returning from settings refreshes the assistant soul from the server; request generations and the page's actor epoch prevent older responses and account/workspace ABA transitions from replacing the current assistant identity. Regression coverage lives in `assistant_personal_settings_repository_test.dart`, `assistant_personal_settings_cubit_test.dart`, `assistant_personal_settings_section_test.dart`, `assistant_routed_editors_test.dart`, `assistant_personality_route_scope_test.dart`, `assistant_memory_editor_section_test.dart`, `assistant_memory_editor_scope_test.dart`, `settings_assistant_entrypoint_checks.dart`, and `assistant_soul_refresh_test.dart`. These tests cover API receipts, product preservation, delayed scope changes, English/Vietnamese controls, and large text with a visible keyboard; they do not establish native-device or deployed runtime proof. ## Consolidating Mira memories The `merge_memories` tool preserves source memories until the sidecar confirms that the replacement has persisted (`done` with a memory ID). Skipped, queued, missing, or failed replacement receipts never authorize original deletion. A successful replacement does not imply that every deletion succeeded: the result includes its replacement ID/key, confirmed deleted keys, and retained keys. Retry only retained keys; never claim the whole merge completed when any deletion remains unconfirmed. Duplicate source keys are processed once, and the replacement key is never deleted. This rule applies to Mira's existing user/workspace memory tool. It does not admit background consolidation or combine Meet's separately opted-in private Live memory with workspace memory. Regression coverage lives in `packages/ai/src/tools/executors/memory.test.ts`. ## Settings lookup failures Consent-checked memory operations deny admission when the current user/workspace/product settings RPC reports an error or throws. No metered embedding or sidecar read/write starts from that failed lookup. Existing separately authorized memory-management routes that explicitly bypass collection settings retain their current permissions; the repair does not change that management exception. A successful lookup with no settings row retains the existing enabled defaults; explicit disabled global or product settings still deny admission. This distinction changes outage behavior, not the existing missing-row consent policy. It does not introduce consent for background dreaming or merge Meet's separately opted-in memory. The failure path returns a skipped memory operation so an optional memory outage does not make the surrounding chat depend on embedding or storage availability. Regression coverage in `packages/ai/src/memory/operations-consent.test.ts` uses the real settings/admission flow with synthetic RPC error and exception boundaries, asserting no embedding or sidecar access. Positive missing-row and disabled/product cases distinguish this rule from a blanket change to successful lookups. ## In-place edit foundation The private first-party sidecar exposes scoped read and revision-CAS update primitives for existing active memories. The service must have an API key configured for these new surfaces. Every read/update matches the memory ID, container, metadata user, workspace, product, and `done` status. This foundation alone does not expose a web/mobile editing API or a new assistant tool. The opaque revision is computed in PostgreSQL from the full-precision timestamp and stored content/metadata plus the PostgreSQL tuple version, before JavaScript can round timestamp precision. The tuple component fences same-content updates within one transaction. PostgreSQL documents that the [tuple version changes on update or `VACUUM FULL`](https://www.postgresql.org/docs/current/ddl-system-columns.html); table maintenance can require a fresh scoped read even when content is unchanged; it does not change the logical memory ID. It is a concurrency token, not an authorization token. Updates replace text and its fresh 3072-dimensional vector atomically, clear the old derived summary, and preserve the ID, original custom ID, creation time and provenance metadata. Forgotten memories are never revived. A stale update receives a conflict instead of overwriting the winner. The service operation preflights ownership and revision before metered embedding. Default operation admission still honors memory collection settings; the existing explicit management exception must be passed deliberately by an authorized future API. A stale preflight starts no embedding. Another edit or deletion can win while embedding is underway: that CAS conflict may occur after credits were used. Retrying the same stale revision is rejected before another embedding, but there is no persistent idempotency key or guarantee of idempotent charging. Do not retry using a newly loaded revision without reviewing the current content. Regression coverage uses the actual sidecar route and emitted parameterized SQL with a synthetic database boundary, plus operation/client tests with synthetic network and embedding boundaries. This is source evidence, not live PostgreSQL, provider, deployment or device proof. Proper edit-audit recording and the public API/mobile editor remain dependent packets; no existing audit action is relabeled and no background dreaming is dispatched. ### Authenticated in-place editing The live workspace memory item route provides `GET`/`HEAD` for an uncached `id`, `content`, and opaque `revision` projection, and `PATCH` for a strict `value`/`revision` body with the product in the query. Bearer and cookie sessions both resolve the current actor, normalized workspace, and MEMBER admission before private memory access. Another actor's memory is unavailable; unknown products are rejected rather than silently mapped to a different product. Explicit owner editing remains available when automatic memory collection is disabled, matching manual creation/deletion. This exception does not authorize background consolidation or automatic dreaming. A stale revision returns `409`; callers preserve unsaved text and reread the current revision before retrying. Embedding may already be metered when a concurrent edit wins the final CAS. Confirmed edits record the distinct `edit` audit action with revision-only metadata, never memory content or private provenance. If audit recording fails after the durable edit, the response remains `updated: true` with `auditRecorded: false` and `warning: "audit_failed"`; callers must not treat it as a rolled-back edit or repeat the mutation. A missing audit receipt also counts as an audit failure. GET responses do not expose source metadata or custom IDs. Regression coverage: the item route and internal API client tests cover admission, validation, conflicts, safe projections, and partial audit receipts. The `ai-memory-edit-audit.sql` pgTAP fixture exercises the actual audit RPC and CHECK, prior actions, membership and service-only access; the existing Programming database contract workflow runs it after complete schema replay. Local wiring checks are not PostgreSQL execution proof. Exact-head CI schema replay, typegen, and web build remain required; the mobile editor is a separate dependent packet. ### Mobile memory editor Mira's Assistant Settings memory list opens a dedicated settings page with keyboard-safe scrollable content and the shared title and floating back action. Opening an item reads canonical content and its current opaque revision; the list preview is not the mutation source of truth. Editing preserves the original ID and uses the scoped PATCH route, without delete-and-create replacement. Manual editing does not enable automatic collection or expand Meet memory scope. A conflict preserves the draft and requires a successful reread of the saved version before an explicit retry. Permission and missing-item failures remain visible. A confirmed save with an unconfirmed audit record stays open with a warning and does not resubmit the unchanged content. Text typed while a save is pending remains editable against the returned revision. Closing the editor does not promise cancellation of an already admitted server write. Account/workspace changes cancel the route, including a switch away and back. Once its route is dismissed, a late response cannot update the list or pop the underlying page. Confirmed list updates preserve newer consent/personality state and fence older list reads. Regression tests cover these held-response boundaries, conflict review, audit warnings, English/Vietnamese labels, enlarged text and 48-pixel actions. Actual native paste gestures run through the global keyboard wrapper on Android/iOS widget targets; these are not physical-device proof. # Model Catalog Source: https://docs.tuturuuu.com/platform/ai/model-catalog How Tuturuuu publishes, browses, and syncs AI gateway model metadata. The public model catalog is served from `apps/web` at: ```txt theme={null} GET /api/v1/infrastructure/ai/models ``` Without pagination parameters, the route keeps the legacy response shape and returns an array of language models. For catalog pages and sync jobs, prefer the paginated contract: ```txt theme={null} GET /api/v1/infrastructure/ai/models?format=paginated&type=all&page=1&limit=60 ``` The paginated response is: ```ts theme={null} { data: Model[]; pagination: { page: number; limit: number; total: number; }; } ``` Supported filters include `type`, `provider`, `tag`, `enabled`, `ids`, `q`, and `search`. Use `type=all` when a caller needs language, image, embedding, and video models. Selection UIs must use server-side search plus paginated "load more" behavior instead of preloading a fixed first page and filtering locally. The root-admin AI credits route has the same paginated model browsing contract: ```txt theme={null} GET /api/v1/admin/ai-credits/models?page=1&limit=50&q=flash&type=language&enabled=true ``` Use `ids=provider/model-a,provider/model-b` to pin selected defaults or allowlist rows while the visible search page changes. In development, the AI credits admin model sync defaults to the Tuturuuu production public catalog before falling back to the Vercel AI SDK model source. This keeps local catalogs close to production while preserving the explicit Vercel source for refreshing upstream gateway metadata. Gemini 3.1 Flash Lite is stable under `gemini-3.1-flash-lite` and `google/gemini-3.1-flash-lite`. Runtime callers should normalize the retired `gemini-3.1-flash-lite-preview` aliases before model resolution so stored preferences and older clients keep working without sending the preview ID to providers. `private.ai_gateway_models` stores provider-owned catalog metadata, so its text fields are exempt from the global strict text-field length trigger and generated text check constraints. JSON payload fields on the same table still keep the standard payload-size checks. # Omni-Channel Chat SDK Source: https://docs.tuturuuu.com/platform/ai/omni-channel-chat-sdk How packages/ai wires Chat SDK adapters for agentic presence workflows. `packages/ai` exposes the Vercel Chat SDK through `@tuturuuu/ai/chat-sdk`. Use it when a Tuturuuu agent needs to operate across external channels and internal product surfaces with one normalized thread and message contract. The target workflow is: ```txt theme={null} Input <-> Omni-channel <-> Tuturuuu Digest <-> Coordinator <-> Internal Apps <-> End users ``` ## Package Boundary Import the Chat SDK boundary from: ```ts theme={null} import { createChatSdkRuntime, createChatTools } from "@tuturuuu/ai/chat-sdk"; ``` The boundary re-exports Chat SDK core types and the `chat/ai` tool helpers, then adds Tuturuuu registry helpers for platform and state adapters. ## Adapter Coverage The adapter registry mirrors the Chat SDK adapter directory. Official platform adapters: * Slack: `@chat-adapter/slack` * Microsoft Teams: `@chat-adapter/teams` * Google Chat: `@chat-adapter/gchat` * Discord: `@chat-adapter/discord` * GitHub: `@chat-adapter/github` * Linear: `@chat-adapter/linear` * Telegram: `@chat-adapter/telegram` * WhatsApp Business Cloud: `@chat-adapter/whatsapp` * Messenger: `@chat-adapter/messenger` * Web: `@chat-adapter/web` Vendor-official platform adapters: * Beeper Matrix: `@beeper/chat-adapter-matrix` * Photon iMessage: `chat-adapter-imessage` * Resend: `@resend/chat-sdk-adapter` * Zernio: `@zernio/chat-sdk-adapter` * Liveblocks: `@liveblocks/chat-sdk-adapter` Community platform adapters: * Webex: `@bitbasti/chat-adapter-webex` * Baileys WhatsApp: `chat-adapter-baileys` * Sendblue iMessage: `chat-adapter-sendblue` * Blooio iMessage/RCS/SMS: `chat-adapter-blooio` * Zalo: `chat-adapter-zalo` * Mattermost: `chat-adapter-mattermost` State adapters: * Memory: `@chat-adapter/state-memory` * Redis: `@chat-adapter/state-redis` * ioredis: `@chat-adapter/state-ioredis` * PostgreSQL: `@chat-adapter/state-pg` * Cloudflare Durable Objects: `chat-state-cloudflare-do` * MySQL: `chat-state-mysql` ## Runtime Construction Create a runtime by selecting only the adapters a route or worker owns. Passing `true` means the adapter should read credentials from its documented environment variables. Passing an object forwards that object to the adapter factory. ```ts theme={null} const chat = await createChatSdkRuntime({ userName: "mira", adapters: { slack: true, zalo: { botToken: process.env.ZALO_BOT_TOKEN, webhookSecret: process.env.ZALO_WEBHOOK_SECRET, }, }, state: { id: "redis", config: { url: process.env.REDIS_URL }, }, }); ``` Always choose a production state adapter for deployed bots. Chat SDK state persists thread subscriptions, webhook dedupe, cache entries, and distributed locks. The memory adapter is only appropriate for local development and tests. Cloudflare Durable Objects state is declared in the registry, but its package imports `cloudflare:workers`; load it only in a Cloudflare Workers runtime. ## Agent Tools Expose the selected chat runtime to AI SDK calls with Chat SDK tools: ```ts theme={null} const tools = createChatTools({ chat, preset: "messenger", }); ``` Use the `reader` preset for analysis-only agents, `messenger` for normal posting and DM workflows, and `moderator` for destructive operations such as editing and deleting messages. Keep approval gates enabled by default for visible writes unless the workflow has an explicit unattended execution policy. ## External Chat Mirror Apps/web AI agents mirror inbound and outbound Discord/Zalo messages through server-owned private RPCs. Runtime handlers persist webhook events as soon as they arrive, then persist any automatic or manual outbound response after the Chat SDK adapter accepts the post. When an operator clicks sync in Infrastructure > AI Agents, apps/web creates the configured Chat SDK runtime, opens the external thread handle, and consumes recent `thread.messages` when the adapter supports history fetch. Discord can return recent messages with the right bot scopes. Official Zalo behaves as a webhook-first adapter, so the mirror is populated by received events. Personal Zalo channels use the experimental `zca-js` listener and can fetch group chat history when the personal account session supports it. The personal adapter also normalizes supported media messages into Chat SDK attachments. The mirror stores those binaries in the workspace Drive provider, records only private attachment metadata, and serves authenticated links from the same conversation API used by native Chat attachments. ## Inbound Attachment Download Limits External chat mirroring selects at most 10 attachments per message, processes them sequentially, and accepts at most 25 MiB of actual bytes per attachment. Generic attachment URL downloads and the concrete personal Zalo media callback enforce the limit while reading the response stream, including when Content-Length is missing or understates the body. Existing response-status checks and 30-second fetch signals remain in place. Empty bodies remain zero-byte attachment data. In-memory Buffer and Blob sizes are checked before copying or materializing their bytes. Other injected attachment callbacks are checked after returning; their internal work and allocations are outside this streamed-reader guarantee. Personal Zalo attachment downloads retain User-Agent but do not forward channel cookies to message-selected media URLs. Media that requires those cookies can fail closed. Provider/channel login remains unchanged. This policy does not establish a URL allowlist, redirect policy, DNS pinning or general SSRF protection; those need separate product admission. Regression coverage lives in `packages/utils/src/read-bounded-response.test.ts`, `packages/ai/src/chat-sdk/zalo-personal-attachment.test.ts` and `apps/web/src/lib/ai-agents/external-chat-attachment-limits.test.ts`. ## Teams MSAL Security Compatibility The root dependency override pins `@azure/msal-node` to 7.1.1 for GHSA-xcx6-jx8p-x3h5. The direct Microsoft package already uses the patched major; Teams apps 2.1.1 still requests `^5.6.0`, including through Chat SDK's Teams adapter 4.43.0. Both are the latest published versions checked for this upgrade. Remove the override only when the upstream Teams dependency range resolves a patched MSAL version without it. Teams' token manager uses confidential client credentials with a tenant specific authority. It does not enable `instanceAware`, request `instance_aware`, or use interactive `responseMode`. MSAL 7 removes interactive response-mode selection and rejects instance-aware confidential clients; retain those rejections rather than enabling legacy behavior for the adapter. `scripts/teams-msal-compatibility.test.js` follows the installed Teams ancestry, requires the patched version, and exercises the actual Teams token manager and MSAL client-credentials exchange using a fixture network transport. It also checks the interactive and instance-aware rejection boundaries. Run it with `node --test scripts/teams-msal-compatibility.test.js` after dependency changes. These fixtures do not establish hosted Azure credential acceptance, managed identity, or federated identity behavior. Require exact-commit CI and independent security review before integration. Upstream references: [MSAL advisory](https://github.com/AzureAD/microsoft-authentication-library-for-js/security/advisories/GHSA-xcx6-jx8p-x3h5) and [MSAL v7 migration guide](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/v7-migration.md). # AI Structured Data Source: https://docs.tuturuuu.com/platform/ai/structured-data Learn how to use Vercel AI SDK for structured data generation in Tuturuuu. > [!NOTE] > > **Prerequisite**: You should have followed the [Development](/build/development-tools/development) and > [Local Supabase Development](/build/development-tools/local-supabase-development) setup guides. ## Overview Tuturuuu leverages the [Vercel AI SDK](https://sdk.vercel.ai/docs/foundations/overview) to generate structured data from large language models (LLMs). This approach enables type-safe AI responses, improved reliability, and consistent data structures for features like flashcards, quizzes, and learning plans. This guide covers how to use AI structured data generation in the Tuturuuu development workflow. ## Key Concepts ### What is Structured Data Generation? While text generation can be useful, many applications require generating structured data. For example, you might want to: * Extract specific information from text * Generate quizzes or flashcards from learning material * Create complex objects like learning plans or task lists * Ensure AI responses follow a consistent format The AI SDK standardizes structured object generation across model providers with the `generateObject` and `streamObject` functions. You can use Zod schemas to specify the shape of the data that you want, and the AI model will generate data that conforms to that structure. ## Architecture in Tuturuuu Tuturuuu's AI features follow this high-level architecture: 1. **Frontend UI** - React components that display and interact with AI-generated content 2. **API Routes** - Next.js routes that handle AI requests and responses 3. **AI SDK** - Vercel AI SDK that manages model providers and generates structured data 4. **Supabase** - Backend database for authentication, authorization, and storing AI-generated content ### Mira Chat Attachments Dashboard chat attachments are uploaded to Supabase Storage before the user message is sent. New chats may first place files under `{wsId}/chats/ai/resources/temp/{userId}` and then move them into `{wsId}/chats/ai/resources/{chatId}` once the chat exists. Tools that read those attachments, such as `convert_file_to_markdown`, should resolve bare filenames and stale same-workspace attachment paths against the current chat folder. They must still reject full paths from another workspace. ### Attachment conversion URL policy Both MarkItDown `/markitdown` endpoints in `apps/discord` accept signed Storage URLs only at the configured Supabase origin. Host comparison is case-insensitive and IDNA-normalized; userinfo, other hosts, unconfigured ports, and redirects are rejected before content is downloaded. HTTPS is the default. Local development may use HTTP only when the selected Supabase URL explicitly configures HTTP on `localhost`, `127.0.0.1`, `::1`, or `host.docker.internal`, with its matching port. The existing Supabase environment-variable precedence remains unchanged. Signed paths must retain the raw Storage signing prefix and contain no encoded slash/backslash or literal/encoded dot segments, including before URL normalization. This policy trusts the operator-configured hostname and its DNS; it does not resolve and filter private addresses. Keep that configuration and DNS under operator control. Signed downloads retain the 60-second timeout, Content-Length check, 50 MiB streaming cap, and temporary-file cleanup, including cancellation. Temporary-file suffixes come from supported extension constants; unknown or unsafe suffixes are omitted. The retained direct YouTube conversion path accepts video links on the existing YouTube host allowlist, extracts an 11-character video ID, and fetches a canonical HTTPS watch page on `www.youtube.com` without redirects. The response URL returned to callers is canonical. Transcript retrieval remains owned by MarkItDown's YouTube integration. This does not change Mira's Gemini-native YouTube routing. Regression coverage: `apps/discord/tests/test_markitdown_service.py` and `apps/discord/tests/test_markitdown_security.py`. ### Mira Dashboard Chat Agent Loop The dashboard Mira chat keeps the main assistant in fast mode by default. New sessions should ignore stale stored `thinking` preferences unless the user manually opts into the toolbar's deep-check mode for that active session. Assistant text should stream as soon as it is useful, then tool calls may run inline, followed by more assistant text in the same response. Keep every assistant text surface on the shared Streamdown wrapper, including text rendered inside compact tool UIs, so code blocks, tables, Mermaid, math, and CJK spacing stay consistent. Mira enables Streamdown math with `singleDollarTextMath` because model output commonly uses `$...$` inline LaTeX. Keep `@streamdown/math` in the Tailwind source scan alongside the base Streamdown dist files, and keep `katex/dist/katex.min.css` imported from the chat renderer path. While the request is submitted but no assistant text has arrived yet, the chat should render a lightweight assistant activity bubble with rotating status copy. Hide that placeholder as soon as real assistant text streams, and keep it separate from markdown/tool rendering so status cycling does not re-render heavy message content. Keep the first optional-tool model step lean. Unless a workflow must force a specific tool before answering, expose only `select_tools` and `no_action_needed` on the first step so the model can stream direct answers without carrying every tool schema. Stream smoothing should not add artificial per-chunk delay on the dashboard chat path; perceived smoothness belongs in the client activity state, not in delayed server chunks. Do not force `select_tools` as the universal first step. Force tool selection only when the workflow cannot answer safely before a tool runs, such as current web lookups, workspace context switching, workspace member lookups, file conversion, or writes. Complex verification, risk review, planning checks, or conflicting evidence should use `run_parallel_checks`, which delegates to bounded `ToolLoopAgent` subagents in parallel and returns a compact summary to the main assistant. Any Mira tool that spawns additional model calls must use `MiraToolContext.creditWsId ?? wsId`, resolve the plan model for that billed workspace, preflight AI credits, apply the workspace output-token cap, and deduct the subcall usage before exposing the generated result. ## Schema Definitions Schemas define the structure of the data that will be generated by the AI models. In Tuturuuu, these are defined in `packages/ai/src/object/types.ts` using [Zod](https://github.com/colinhacks/zod). Here are some examples of schemas used in Tuturuuu: ### Flashcard Schema ```typescript theme={null} export const flashcardSchema = z.object({ flashcards: z.array( z.object({ front: z.string().describe('Question. Do not use emojis or links.'), back: z.string().describe('Answer. Do not use emojis or links.'), }) ), }); ``` ### Quiz Schema ```typescript theme={null} export const quizSchema = z.object({ quizzes: z.array( z.object({ question: z.string().describe('Question. Do not use emojis or links.'), quiz_options: z.array( z.object({ value: z.string().describe('Option. Do not use emojis or links.'), explanation: z .string() .describe( 'Explain why this option is correct or incorrect, if it is incorrect, explain possible misconceptions and what made the option wrong with respect to the question, if it is correct, explain why it is correct. Be as detailed as possible.' ), is_correct: z.boolean().describe('This option is a correct answer.'), }) ), }) ), }); ``` ### Year Plan Schema ```typescript theme={null} export const yearPlanSchema = z.object({ yearPlan: z.object({ overview: z .string() .describe( 'A high-level overview of the year plan and how the goals will be achieved' ), quarters: z .array(quarterSchema) .describe('List of quarters in the year plan'), recommendations: z .array(z.string()) .describe('Additional recommendations, tips, or considerations'), start_date: z .string() .describe('Start date of the year plan (ISO date string)'), end_date: z .string() .describe('End date of the year plan (ISO date string)'), }), }); ``` ## Creating an API Endpoint To create an API endpoint that generates structured data, follow these steps: ### 1. Create a new route file Create a new route file in the appropriate Next.js app, for example: ```typescript theme={null} // app/api/ai/flashcards/route.ts import { google } from '@ai-sdk/google'; import { flashcardSchema } from '@tuturuuu/ai/object/types'; import { createAdminClient, createClient, } from '@tuturuuu/supabase/next/server'; import { streamObject } from 'ai'; export async function POST(req: Request) { // Implementation... } ``` ### 2. Implement authentication and validation Use Supabase to authenticate the user and validate their permissions: ```typescript theme={null} // createAdminClient() is synchronous; do not await it. const sbAdmin = createAdminClient(); const { wsId, context } = await req.json(); // Validate input if (!wsId) return new Response('Missing workspace ID', { status: 400 }); if (!context) return new Response('Missing context', { status: 400 }); // Authenticate user const supabase = await createClient(); const { data: { user } } = await supabase.auth.getUser(); if (!user) return new Response('Unauthorized', { status: 401 }); // Check feature flag const { count, error } = await sbAdmin .from('workspace_secrets') .select('*', { count: 'exact', head: true }) .eq('ws_id', wsId) .eq('name', 'ENABLE_CHAT') .eq('value', 'true'); if (error) return new Response(error.message, { status: 500 }); if (count === 0) return new Response('You are not allowed to use this feature.', { status: 401 }); ``` #### Fast session auth for Mira and assistant routes Session-authenticated AI routes may accept the `x-tuturuuu-ai-temp-auth` header as an optimization before falling back to Supabase `getUser()`. The browser mints this token through `POST /api/ai/temp-auth/token` after the normal session, workspace normalization, membership, and selected billing workspace checks succeed. Tokens live only in memory on the client, expire after 60 seconds, and are stored in Redis only as SHA-256 digests. Revocation is version-based: `ai:temp-auth:user-version:{userId}` is bumped before logout or account removal, so any token minted under the old version is rejected. Redis is not authoritative for security; when Redis is unavailable or a token is missing/invalid, routes fall back to the existing Supabase session path. A revoked token returns `401` and does not fall back. Credit availability snapshots are also Redis-backed under `ai:credits:snapshot:{billingWsId}:{userId}`. They are UI/status hints only and must not authorize model execution. AI preflight must call the authoritative Postgres allowance RPC so daily credit limits, daily request limits, and feature-specific request limits are enforced before every model run. Actual reservations, deductions, and ledger writes remain in Postgres, and successful commits invalidate the snapshot. ### 3. Generate structured data Use the AI SDK to generate structured data based on the schema: ```typescript theme={null} const result = streamObject({ // Use a current default model ID. Active callers in `packages/ai/src` // (calendar, chat title generation, search wrapper) use // `gemini-3.1-flash-lite`. See "Supported Models" below for how the // catalog is resolved dynamically at runtime. model: google('gemini-3.1-flash-lite', { safetySettings: [ { category: 'HARM_CATEGORY_DANGEROUS_CONTENT', threshold: 'BLOCK_NONE', }, // Other safety settings... ], }), prompt: `Generate 10 flashcards with the following context: ${context}`, schema: flashcardSchema, }); // Stream the response to the client return result.toTextStreamResponse(); ``` ## Supported Models Tuturuuu supports multiple AI models through the Vercel AI SDK. There is **no static model array** anymore — the catalog is sourced dynamically from the AI gateway and stored in the `ai_gateway_models` table (synced by `packages/ai/src/credits/sync-gateway-models.ts`). The browsable catalog is served from `apps/infrastructure`: * **API**: `GET /api/v1/infrastructure/ai/models` (`apps/infrastructure/src/app/api/v1/infrastructure/ai/models/route.ts`) * **Docs**: see [Model Catalog](/platform/ai/model-catalog) for how metadata is published, browsed, and synced. The set of provider integrations the SDK can wire up lives in `packages/ai/src/supported-providers.ts`: ```typescript theme={null} export const supportedProviders = [ 'google', 'google-vertex', 'openai', 'anthropic', ] as const; ``` For per-workspace plan resolution (which model a billed workspace is allowed to run), use the helpers under `packages/ai/src/credits/` such as `resolve-plan-model.ts` and `cap-output-tokens.ts`, rather than hard-coding a model ID. To use a different model in your endpoint, change the model reference. Active callers default to `gemini-3.1-flash-lite`: ```typescript theme={null} const result = streamObject({ model: google('gemini-3.1-flash-lite', { // Configuration... }), // Other parameters... }); ``` ## Calling from the Frontend To call your AI endpoint from the frontend, you can use the appropriate hooks or fetch API: ```typescript theme={null} // Example using fetch async function generateFlashcards(workspaceId: string, context: string) { const response = await fetch('/api/ai/flashcards', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ wsId: workspaceId, context, }), }); if (!response.ok) { const error = await response.text(); throw new Error(error); } // For streaming responses const reader = response.body?.getReader(); const decoder = new TextDecoder(); while (reader) { const { done, value } = await reader.read(); if (done) break; const chunk = decoder.decode(value); // Process the chunk (partial object) console.log(JSON.parse(chunk)); } } ``` ## Integration with Supabase Tuturuuu's AI features are tightly integrated with Supabase for several purposes: ### TypeScript Types Supabase-generated TypeScript types are available at `packages/types/src/supabase.ts`. These types are automatically generated when you run `bun sb:typegen` or `bun sb:reset` and are accessible to all apps that have the `@tuturuuu/types` package installed. You can use these types to ensure type safety when working with Supabase data in your AI features: ```typescript theme={null} import type { Database } from '@tuturuuu/types'; // Type-safe access to workspace_secrets table const { data, error } = await supabase .from< Database['public']['Tables']['workspace_secrets']['Row'] >('workspace_secrets') .select('*') .eq('ws_id', wsId) .eq('name', 'ENABLE_AI'); // Type-safe access to specific columns const { data: workspace } = await supabase .from('workspaces') .select('id, name, handle') .eq('id', wsId) .single(); // TypeScript knows the structure of 'workspace' with proper types const workspaceName: string = workspace?.name; ``` ### Short-hand Type Access For more convenient access to common table types in your AI features, Tuturuuu also provides short-hand type definitions in `packages/types/src/db.ts`. These are easier to use and remember than the full database type paths: ```typescript theme={null} import type { AIChat, AIPrompt, WorkspaceDocument } from '@tuturuuu/types'; // Use short-hand types directly for AI-related tables const { data: chats } = await supabase .from('ai_chats') .select('*') .eq('creator_id', user.id); // Types are properly inferred chats?.forEach((chat: AIChat) => { console.log(chat.id, chat.title); }); // Store AI-generated content with proper types const document: WorkspaceDocument = { id: uuidv4(), ws_id: wsId, name: 'AI Generated Document', content: generatedContent, created_at: new Date().toISOString(), creator_id: user.id, }; await supabase.from('workspace_documents').insert(document); ``` The short-hand types can also include extended client-side properties that aren't in the database schema, making them perfect for your AI feature implementations. This ensures that your AI features correctly interact with the database schema, reducing runtime errors and improving development experience. ### Authentication and Authorization Before making AI requests, ensure the user is authenticated and authorized to use the feature: ```typescript theme={null} // Get the current user const { data: { user } } = await supabase.auth.getUser(); if (!user) return new Response('Unauthorized', { status: 401 }); // Check workspace membership const { data: member, error: memberError } = await sbAdmin .from('workspace_members') .select('*') .eq('ws_id', wsId) .eq('user_id', user.id) .single(); if (memberError || !member) return new Response('You are not a member of this workspace', { status: 403 }); ``` ### Feature Flags Use the `workspace_secrets` table to enable or disable AI features for specific workspaces: ```typescript theme={null} // Check if the AI feature is enabled for this workspace const { count, error } = await sbAdmin .from('workspace_secrets') .select('*', { count: 'exact', head: true }) .eq('ws_id', wsId) .eq('name', 'ENABLE_AI') .eq('value', 'true'); if (error) return new Response(error.message, { status: 500 }); if (count === 0) return new Response('AI features are not enabled for this workspace', { status: 403 }); ``` ### Storing Results You can store AI-generated content in Supabase for future use: ```typescript theme={null} // Store the generated flashcards const { error } = await sbAdmin .from('flashcard_sets') .insert({ ws_id: wsId, creator_id: user.id, name: 'Generated Flashcards', description: context.substring(0, 100) + '...', cards: result.object.flashcards, }); if (error) return new Response(error.message, { status: 500 }); ``` ## Best Practices ### Schema Design When designing schemas for AI-generated content: 1. **Be specific** - Use the `.describe()` method to provide clear instructions to the AI model 2. **Keep it simple** - Break complex schemas into smaller, nested objects 3. **Add validations** - Use Zod's validation methods (`.min()`, `.max()`, `.regex()`, etc.) 4. **Use enums** - For fields with a fixed set of values, use `.enum()` Example of a well-designed schema: ```typescript theme={null} const taskSchema = z.object({ title: z.string().min(3).max(100).describe('A concise title for the task'), description: z .string() .min(10) .describe('Detailed description of what needs to be done'), priority: z .enum(['high', 'medium', 'low']) .describe('Priority level of the task'), due_date: z.string().describe('Due date in ISO format (YYYY-MM-DD)'), estimated_hours: z .number() .min(0) .max(100) .describe('Estimated hours to complete'), }); ``` ### Error Handling Implement robust error handling for AI-generated content: ```typescript theme={null} try { const result = streamObject({ // Configuration... }); return result.toTextStreamResponse(); } catch (error) { console.error('AI generation error:', error); // Return a friendly error message return NextResponse.json( { message: 'Failed to generate content. Please try again later.', error: error.message, }, { status: 500 } ); } ``` ### Response Processing For complex AI-generated content, you may need to post-process the response: ```typescript theme={null} // Example: Filtering out inappropriate content const filteredFlashcards = result.object.flashcards.filter((card) => { // Remove cards containing inappropriate words const inappropriateWords = ['inappropriate1', 'inappropriate2']; return !inappropriateWords.some( (word) => card.front.includes(word) || card.back.includes(word) ); }); ``` ## Local Development and Testing ### Setting Up API Keys To test AI features locally, you need to set up the appropriate API keys in your environment: 1. Create a `.env.local` file in the root of your Next.js app 2. Add the necessary API keys: ``` GOOGLE_GENERATIVE_AI_API_KEY=your-google-ai-key OPENAI_API_KEY=your-openai-key ``` 3. Restart your development server ### Testing AI Endpoints You can test your AI endpoints using tools like Postman or simple cURL commands: ```bash theme={null} curl -X POST http://localhost:3000/api/ai/flashcards \ -H "Content-Type: application/json" \ -d '{"wsId":"00000000-0000-0000-0000-000000000000","context":"The process of photosynthesis converts light energy into chemical energy that can be used by plants and other organisms."}' ``` ## Troubleshooting ### Common Issues 1. **API Key Issues**: Ensure your API keys are correctly set in your environment 2. **Model Unavailability**: Some models may be unavailable in certain regions 3. **Token Limits**: Large prompts may exceed token limits 4. **Schema Validation Errors**: The AI might generate content that doesn't match your schema ### Debugging Tips 1. **Log the prompt**: Print the full prompt being sent to the AI model 2. **Start with simple schemas**: Begin with simple schemas and gradually increase complexity 3. **Check response format**: Verify the raw response from the AI model before schema validation ## Further Resources * [Vercel AI SDK Documentation](https://sdk.vercel.ai/docs/foundations/overview) * [Zod Documentation](https://zod.dev/) * [Supabase Documentation](https://supabase.com/docs) * [Google Generative AI Documentation](https://ai.google.dev/docs) ### Dashboard assistant settings receipts Dashboard Soul metadata belongs to the verified account, independently of the selected workspace. Reads and edits use the shared internal API adapter, an account-specific query key, and a committed session lease. Account departure cancels requests and removes that account's cached Soul; a later same-account session must receive fresh server admission. An abandoned React render does not revoke the currently committed lease. A failed optimistic edit may restore its previous value only while its intent, query instance and publication revision are still current. It must preserve a newer confirmed tool or settings publication. Malformed or foreign-owner Soul receipts are errors, rather than successful default values. Displayed names use the trimmed custom name, with Mira as the fallback for an empty name; this does not change the server's existing name contract. Only definitive successful `update_my_settings` outputs in the current submitted conversation invalidate the current account's Soul metadata. Failed, preliminary, duplicate, restored-history and departed account/workspace/chat outputs do not trigger a settings refresh. This read-side admission leaves real transport and persistence errors intact. It adds no server compare-and-swap or offline reconciliation guarantee; mobile pending-name policy is separate. Regression coverage lives in the dashboard `use-mira-soul` and `use-mira-soul-scope` hook tests, `mira-settings-receipts` tests, and the shared `mira-soul` adapter tests. These source regressions do not establish production or authenticated browser delivery. # Apps Gateway Source: https://docs.tuturuuu.com/platform/applications/apps Central launcher and redirect gateway for routable Tuturuuu web apps. ## Overview `apps/apps` serves `apps.tuturuuu.com`, the central public gateway for routable Tuturuuu web apps. It is a launcher and redirect layer, not a reverse proxy. The gateway exposes app cards for the routable web apps in `apps/` and redirects users to each app's canonical domain: * `/calendar` redirects to `calendar.tuturuuu.com` * `/qr` redirects to `qr.tuturuuu.com` * `/tasks/personal/tasks` redirects to `tasks.tuturuuu.com/personal/tasks` * query strings are preserved during redirects It intentionally excludes infrastructure-only or non-web app directories such as `apps/database`, `apps/mobile`, `apps/redis`, `apps/discord`, `apps/storage-unzip-proxy`, and `apps/hive-realtime`. ## Routing Contract * `/`: public app directory. * `/{appSlug}`: redirect to the target app root. * `/{appSlug}/{path...}`: redirect to the same path on the target app. `apps.tuturuuu.com` must not own auth callbacks, protected APIs, cross-app token exchange, or app-session cookies. Those flows remain owned by the canonical app or by `apps/web` for central login. The gateway layout uses `@tuturuuu/satellite/providers` so the public launcher supports `system`, `light`, and `dark` theme switching through the shared `next-themes` shell. ## Local Development * `bun dev:apps` starts the gateway through Portless. * Local app origin: `https://apps.tuturuuu.localhost`. * Direct fallback port: `7818`. The gateway uses hidden locale routing, so old locale-prefixed paths such as `/vi/calendar` should canonicalize to `/calendar` while storing `NEXT_LOCALE`. ## CI/CD Preview and production deployments use dedicated Vercel workflows: * `.github/workflows/vercel-preview-apps.yaml` * `.github/workflows/vercel-production-apps.yaml` Both workflows are registered in `tuturuuu.ts` and use the shared `ci-check.yml` switchboard with affected-path gating. They require environment-scoped Vercel credentials: * preview environment: `vercel-preview-apps` * production environment: `vercel-production-apps` * project secret: `VERCEL_APPS_PROJECT_ID` * shared secrets: `VERCEL_TOKEN` and `VERCEL_ORG_ID` The app-specific project secret should live in those GitHub Environments, not in workflow-level `env`. ## Validation Use these focused checks when changing the gateway: ```bash theme={null} bun type-check:apps bun --cwd packages/utils test src/__tests__/app-url.test.ts node --test scripts/portless-config.test.js node --test scripts/ci/check-workflow-config.test.js scripts/ci/release-workflows.test.js ``` Require the applicable test, type-check, lint and real application build workflows to pass for the exact commit. Follow the repository resource policy for focused local checks; release builds run in CI. ## Native renderer verification The native renderer candidate uses an explicit Start entry. Its request middleware preserves the framework-default CSRF checks for server functions; an empty Start instance suppresses that fallback and must not replace this policy. The entry also lets the owning generator reference its configuration in the typed route footer. Generate route glue through the admitted CI build and retain the authentic supplier bytes. Commit the recovered output, then require fresh clean generation-drift, compiler, behavior and Worker artifact checks. Do not hand-edit generated imports or relax unused-code checks to make a bootstrap artifact pass. Source acceptance and a successful build do not establish canonical traffic or hosted acceptance. The native workflow retains `native-emitted-config-apps.json` even when emitted configuration qualification fails. The diagnostic records source HEAD separately from the event SHA, hashes and redacted field shapes. It contains no raw config, resource identifiers or secret values and grants no artifact acceptance. Review the actual receipt before changing a strict configuration predicate; retain the source, resource, archive, restore and deployment gates. ## Native Worker release identity On the admitted native Worker, `/api/build-info` exposes public bundled release metadata (app, full source SHA and environment) before session middleware. It is no-store and accepts GET/HEAD/OPTIONS only; other methods return 405. Other API routes retain their existing authentication/authorization policies. Apps checks its canonical-host fence before this endpoint as well. Legacy Vercel deployments retain their existing behavior until explicit cutover. `scripts/ci/wave1-native-publishers.test.js` covers path/method/cache behavior; CI original/restored workerd acceptance checks the actual bundled identity. See the [native publisher runbook](/build/devops/wave1-native-publishers). # Calendar Source: https://docs.tuturuuu.com/platform/applications/calendar Calendar behavior across Web, standalone Calendar, and mobile. ## Public authentication completion document Standalone Calendar renders its existing `/verify-token`, `/en/verify-token` and `/vi/verify-token` completion screen as a public SSR document for GET and HEAD requests with no `token` query parameter. The default is English; an explicit supported locale prefix, then `NEXT_LOCALE`, then browser language resolves the document language. These documents do not redirect solely to canonicalize the locale prefix, and their page model does not resolve an actor or workspace data. The normal Calendar auth proxy, auth-cookie cleanup and response security policy still apply. Rendering this screen does not create or prove an authenticated session; the existing client completion flow normalizes its next destination. This rule applies only to these exact Calendar paths and document methods. A present `token` parameter, including an empty value, retains the existing shared server verification and safe redirect behavior. Token-bearing success propagates verifier cookies; failure retains the safe fallback and cookie cleanup. Other methods, protected pages, shared auth defaults and other satellite apps are unchanged. Web and mobile Calendar surfaces are outside this rule's scope. `apps/calendar/src/runtime/public-completion.test.ts` covers the real proxy, shared token consumer, locale resolution, anonymous page model, security policy, cookie cleanup and token-bearing/protected negative controls. The emitted Worker suite separately requires 200 EN/VI HTML, hydration assets and framing protection; source tests do not establish hosted or restored-artifact acceptance. ## Browser language fallback Standalone Calendar filters wildcard and invalid BCP 47 language ranges before matching browser preferences. A wildcard-only, zero-quality-only or otherwise empty usable language list falls back to English. Remaining valid ranges retain Negotiator's quality ordering and the existing English/Vietnamese best-fit matching, including regional tags. An explicit supported path locale takes precedence over a valid `NEXT_LOCALE` cookie, followed by browser preferences. This applies to Calendar document/native-function locale resolution and the browser-language default used by its existing login middleware. Token verification, authenticated routes and callback redirects retain their existing authentication contracts. Web, mobile and other apps use their own locale rules. `apps/calendar/src/runtime/request-locale.test.ts` and `apps/calendar/src/runtime/public-completion.test.ts` cover wildcard/malformed ranges, regional and quality preferences, precedence, the real public proxy and login locale middleware. Hosted request headers and Worker acceptance require separate evidence. ## Calendar editor timezone Calendar display and the built-in event editor use the same resolved Calendar settings. Explicit personal timezone takes precedence over workspace timezone; when neither is explicit, the canonical resolver detects the browser timezone. The editor's date/time picker inherits those settings instead of resolving its own browser timezone. This applies to the shared Calendar surface in Web and the standalone Calendar app. It does not change saved user or workspace settings. Timed edits represent an instant and serialize as UTC ISO timestamps. A date-only all-day choice represents midnight in the resolved calendar timezone with an exclusive end boundary. A browser in another timezone must still display the chosen calendar date, including when its local date is the previous day. Existing Google-backed events are patched immediately using their stored external event identifier. Imported recurring occurrences retain the provider's instance identifier; changing an occurrence must preserve that identifier and calendar source. The patch sends updates to guests. Verify the stored event and the same Google occurrence independently after an edit; a local toast is not provider read-back evidence. The current Google write mapper uses `dateTime` fields and does not provide native Google date-only all-day writes. Native Tuturuuu all-day events do not require that provider path. ## Tasks and Calendar planning Calendar and Tasks keep cross-product API calls on the active browser origin so host-only app cookies remain available. Their `beforeFiles` rewrites forward only the other product's API families, before Tasks' API catch-all can intercept them. The source proxy refreshes the host session and forwards its signed bearer token; Calendar routes explicitly accept Calendar and Tasks audiences while retaining workspace membership and permission checks. Do not route these APIs through Web: Web no longer owns the Calendar events or Tasks endpoints. Tasks' session verifier also accepts Calendar for routes that explicitly accept Tasks, including labels, projects, task detail dependencies, and workspace task preferences. It preserves required scopes and does not widen unrelated app audiences. Calendar forwards `/api/v1/users/me/workspaces/:wsId/configs/*` to Tasks so those preferences use the verified planning actor and membership guard. Collection rewrites must have an exact path before their `/:path*` variant. Vercel can retain a trailing slash when the wildcard is empty, causing the owning app to return a 308 to the same browser URL and loop. Verify both collection and nested resource requests on the deployed host. Both satellite apps expose local planning views without changing workspace or requiring a cross-app login handoff: | Host | Calendar | Tasks | | - | - | - | | Tasks | `/{wsId}/calendar` | `/{wsId}/tasks` (default board) | | Calendar | `/{wsId}` | `/{wsId}/tasks` (editable task list) | The shared sidebar retains locale and personal/internal workspace aliases, including on mobile. Calendar also serves `/tasks/boards`, `/tasks/boards/{boardId}`, and `/tasks/{taskId}` within the workspace. Task views hide the calendar-only mini-month sidebar to leave more room for task work. Tasks' embedded calendar uses the shared scheduling, connection, event, and task controls and enforces `manage_calendar`. Each host resolves its own app-session actor. Keep the task route context and dialog manager prefix aligned: Tasks uses an empty prefix, while Calendar and Web use `/tasks`. Tasks already owns a dialog provider, so its embedded calendar disables the additional dialog wrapper. When validating this integration, check both locales, personal and team workspace links, board/task detail return paths, and mobile navigation with the sidebar closed. Mutations continue through the existing protected product APIs. ## Overview `apps/calendar` and the Calendar experience inside `apps/web` are paired Calendar hosts. They must stay 1:1 for product features, data behavior, mutations, permissions, and user-facing workflow updates. * Calendar UI and logic should live in shared packages, primarily `@tuturuuu/ui/calendar-app/*`, with app route files acting as thin auth and workspace-context wrappers. * Task-aware Calendar controls (task creation, task scheduling, habits, and task time tracking) live in `@tuturuuu/tasks-ui/calendar/*`. The generic Calendar shell accepts those controls through typed component seams, keeping `@tuturuuu/ui` independent from task-only code and preserving narrow Turbo rebuilds. * `apps/calendar` owns its standalone workspace shell, local `/login`, and local `/verify-token` completion route. * `apps/web /{wsId}/calendar` renders the same shared Calendar product surface inside the normal platform dashboard shell. * Dashboard navigation in `apps/web` should link to the local `/{wsId}/calendar` route, not to the standalone Calendar origin. ## Auth Model Calendar does not create local Supabase Auth sessions. It uses central `apps/web` login plus a Calendar app-session cookie: 1. `/login` in `apps/calendar` normalizes a safe `next` path. 2. If both the Calendar app-session cookie and Web-issued app-session cookie are already present, `/login` redirects to that local `next` path immediately. 3. Otherwise `/login` redirects to `apps/web /login` with a return URL pointing back to Calendar `/verify-token?nextUrl=...`. 4. `/verify-token` posts the handoff token to the Calendar-local verifier, which validates through central Web and sets host-local app-session cookies. Calendar proxy responses should clear stale `sb-*-auth-token` cookies. A valid Calendar session is represented by Tuturuuu app-session cookies, not by a local Supabase browser session. ## Calendar timezone boundaries Event start/end values are UTC instants. Display and picker controls resolve personal calendar timezone first, workspace timezone second, and device timezone when both inherit with `auto`. A browser-local `Date` used by a date-only calendar widget is a calendar-day carrier, not an event instant: project its year, month and day in the resolved timezone before passing selection, today or bounds. Compare end-time options on that same calendar day and derive minimum/maximum clock values in the same timezone. This matters when the browser and calendar are on different dates, for example Los Angeles and Ho Chi Minh City. Quick previews use the same resolved timezone and clock format as the event form, localized to the current locale. Date/time edits must round-trip the requested wall time; nonexistent DST times must not silently normalize into another hour. Reselecting an unchanged ambiguous time or date preserves the original UTC instant. Tests cover these boundaries; they do not establish exhaustive correctness for every IANA history or changed ambiguous-time choice. Native all-day persistence and the outer calendar Today/header date contract remain separate concerns. Do not infer all-day intent solely from a 24-hour elapsed duration, and do not publish a DST duration helper in isolation from the persistence/rendering contract. Imported recurring provider events require exact-instance and neighboring-instance readback after an authorized UI edit. Never use real user calendar screenshots as public regression fixtures. ## API Ownership `apps/calendar` owns the Calendar product APIs. Its local handlers cover events and calendars, categories and preferences, hours and default sources, scheduling and sync, Calendar connections, Google and Microsoft provider OAuth, Calendar media/generation helpers, and Calendar-owned cron work. Host-local auth/session and build-info routes are local as well. * Exact local handlers win before the fallback `/api/:path*` rewrite. The fallback remains for cross-product routes that Calendar uses but does not own, including workspace encryption and task, board, habit, and time-tracking families; typed task helpers may target the Tasks app directly. * Central platform login, social-provider callbacks, and cross-app token issuance remain Web-owned. Calendar-provider OAuth initiation and callbacks are Calendar-local, even though their configured redirect origins retain Web compatibility for existing provider registrations. * Calendar-only routes use `targetApp: 'calendar'`. Shared cross-product routes must name the exact accepted app audiences, such as `targetApp: ['calendar', 'tasks']`, rather than accepting generic satellite sessions. * Keep workspace membership checks and Calendar/task permissions on the owning route before admin-backed reads or writes. The Calendar proxy guard and app-session refresh do not replace route-level authorization. * Prefer typed `packages/internal-api` helpers. Browser calls remain same-origin so Calendar-local handlers are selected first; server calls to a different owning app must use its configured API base URL with forwarded authentication. ### Calendar settings authorization Personal/workspace settings use shared validation and explicit workspace edit permissions. Native preferences default directly to Web; Calendar browser clients and older mobile gateway clients retain their existing adapters. See [Native Calendar preferences](/platform/features/native-calendar-preferences) for the product decision, quotas, exceptions and regression evidence. ## OAuth Token Safety Calendar OAuth credentials live in `calendar_auth_tokens`. RLS restricts selects to `user_id = auth.uid()`, but admin/service-role reads bypass RLS. Calendar server pages must therefore: * Check `manage_calendar` before loading calendar integration state. * Scope token reads to both `ws_id` and the authenticated `user_id`. * Never pass `access_token` or `refresh_token` into client components. SSR props should use the shared `fetchUserWorkspaceCalendarGoogleTokenForClient()` helper from `@tuturuuu/utils/calendar-auth-token`, which projects only connection metadata (`id`, account email/name, provider, active state, expiry). * Keep token refresh and provider API calls on Calendar-local server routes; never expose provider credentials to client components. When adding a new Calendar host route, reuse the helper instead of `select('*')` on `calendar_auth_tokens`. When adding new Calendar UI that needs protected data, update the shared Calendar component or helper first, then wire both host wrappers in the same change. Extend the route family in its owning app and expose a typed `packages/internal-api` seam instead of creating a host-local product API fork or adding direct client Supabase reads. ## Calendar OAuth And Connections Google Calendar OAuth initiation and callback handlers are owned by `apps/calendar`. The local `/api/v1/calendar/auth` route builds its callback URL from a browser-safe configured origin and ignores wildcard listener addresses such as `0.0.0.0` or `::`. Existing provider registrations may still configure `GOOGLE_REDIRECT_URI`; otherwise production uses the Calendar `BASE_URL` (see below), and local development falls back to the configured Web origin. Valid local development callback URLs such as `http://localhost:7803/api/v1/calendar/auth/callback` may still be configured through `GOOGLE_REDIRECT_URI`, but wildcard listener URLs must never be emitted as Google `redirect_uri` values or browser redirects. Google and Microsoft connections share these security rules (regression coverage lives beside the routes under `apps/calendar/src/app/api/v1/calendar/auth/` and in `apps/calendar/src/lib/calendar/calendar-oauth-*.test.ts`): * The OAuth `state` is signed, expires after 10 minutes, and binds the flow to the initiating user and workspace. Callbacks reject forged, swapped, expired, other-user and non-member states before exchanging the authorization code. * Each state is single-use. The callback consumes its nonce through the service-role-only RPC `private.consume_calendar_oauth_state_nonce`, which inserts into `private.calendar_oauth_state_nonces` (RLS forced, no client policies or grants) and treats an existing row as a replay. The same call purges at most 100 rows that expired over an hour ago. If the ledger is unavailable (for example the migration has not been applied), the callback fails closed with `503` before exchanging the code. * Google uses S256 PKCE derived from the signed state. Microsoft uses S256 PKCE with an HttpOnly verifier cookie. * After connecting (or on a provider error), the browser is redirected to the Calendar app's workspace page, `{BASE_URL}/{wsId}`, which is where the Calendar satellite serves each workspace calendar. `BASE_URL` (`apps/calendar/src/constants/common.ts`) resolves `CALENDAR_APP_URL` or `NEXT_PUBLIC_CALENDAR_APP_URL` against the registered Calendar domain and otherwise defaults to `https://calendar.tuturuuu.com` in production. The origin is never taken from the request URL, Host or forwarded headers. Without a verified workspace the redirect goes to the origin root. * In production the Google `redirect_uri` is `GOOGLE_REDIRECT_URI` when set, otherwise `{BASE_URL}/api/v1/calendar/auth/callback`. The Web-origin and forwarded-header fallbacks apply only outside production, for local proxies. * No environment variables beyond the existing provider credentials are required. The nonce ledger ships as a migration through the gated production migration workflow. To exercise the ledger against a disposable local Supabase with migrations applied, run the env-gated integration test from `apps/calendar` with `CALENDAR_OAUTH_NONCE_IT_SUPABASE_URL`, `CALENDAR_OAUTH_NONCE_IT_SERVICE_ROLE_KEY` and `CALENDAR_OAUTH_NONCE_IT_USER_ID` (a synthetic local auth user): `bunx vitest run src/lib/calendar/calendar-oauth-nonce-store.integration.test.ts`. It is skipped when those variables are absent. Never point it at a shared or remote project. Normal Google Calendar connect and reconnect URLs request `access_type=offline` and `include_granted_scopes=true`, but they must not force `prompt=consent` by default. Google may return a refresh token only during the first authorization, so the callback must preserve an existing stored `refresh_token` when a reconnect returns only a new access token. If neither the callback nor the existing token row has a refresh token, the flow must fail before saving an active Google connection because provider sync cannot refresh offline. Standalone `apps/calendar` also exposes the shared Calendar connections manager inside its settings dialog under Calendar -> Integrations. It should fetch the initial connection state through `@tuturuuu/internal-api/calendar` and render the shared Calendar connections UI inside `CalendarSyncProvider` rather than forking host-local connection controls. ## CI And Deployment Calendar deploys through dedicated GitHub Actions workflows, not Vercel-owned GitHub auto-builds: * Preview deployments use `.github/workflows/vercel-preview-calendar.yaml`. * Production deployments use `.github/workflows/vercel-production-calendar.yaml`. * The Vercel project id is provided through the environment-scoped `VERCEL_CALENDAR_PROJECT_ID` secret. * `apps/calendar/vercel.json` must keep `git.deploymentEnabled` and `github.enabled` set to `false` so GitHub Actions builds with `vercel build` and deploys prebuilt artifacts with `vercel deploy --prebuilt`. Vercel hosts the Calendar schedules in `apps/infrastructure/vercel.json`. Infrastructure authenticates the scheduler and forwards through the private Calendar gateway; Calendar validates the scheduler credential again. After qualification, collect `native-emitted-config-calendar.json` even on failure. Keep the actual source HEAD separate from the event SHA. Retain pointer and config hashes and a redacted key-shape inventory, never raw configs, resource identifiers, or secret values. Unavailable or overflow diagnostics remain failures. The receipt provides no acceptance, allowlist approval, or rollback proof. Inspect the actual receipt before qualifying unexpected `queues` or `configPath` fields. Preserve the strict resource, saved-pointer, native-relative-base, restore, and deployment gates. ## Provider Sync Infrastructure hosts the provider-sync schedule (`*/15 * * * *`). Both apps' proxies recognize validated cron credentials independently of browser sessions; invalid credentials still fail authentication. If hosted runs return 401 before Calendar logs a request, check the Infrastructure proxy and matching production `CRON_SECRET` configuration before investigating provider tokens. The Calendar cron wrapper invokes Calendar's workspace sync handler locally, preserving cron authentication, running locks, cooldown behavior and `calendar_sync_dashboard` audit rows. It must not send sync requests to the former Web owner through `INTERNAL_WEB_API_ORIGIN` or a protected preview URL. Both Tasks and Calendar show **Sync needs attention** beside the calendar picker when a sync stalls, data becomes stale, a provider needs reconnection, or status cannot be loaded. Open it for a persistent explanation and a **Sync now**, **Check again**, or provider-specific **Reconnect** action. Stored events remain visible during provider outages. Ordinary access-token expiry is not itself a reconnection failure: Google refreshes those tokens automatically. Sync health polls every 30 seconds (every 5 seconds during a run or cooldown). A running entry older than five minutes is stalled; a successful sync older than 45 minutes is stale. Partial provider failures are recorded as failed runs rather than successful syncs. Successful runs use the database's `completed` status; completion writes must be checked so a constraint failure cannot leave a run stuck at `running`. Provider rate limits and transient outages offer retry, while authentication failures offer reconnection. Operators should inspect the Calendar cron execution and dashboard run when retries continue to fail. ### Bounded cron execution and revoked consent The provider cron returns HTTP 200 when dispatch completes, including recorded provider failures. Inspect `ok`, `failed`, `deferred`, and workspace summaries; HTTP 200 alone does not establish successful synchronization. Authentication and workspace-enumeration failures retain their 401/500 responses. Dashboard rows use `failed` only for actual provider failures; successful admitted work is `completed` even when summaries report deferred accounts or connections. Google `invalid_grant` disables only the rejected account, conditional on its saved refresh credential still matching the attempted credential. Sibling calendars skip further calls in that run; healthy accounts continue. Reconnecting reactivates consent through the normal OAuth flow. Transient errors do not disable accounts. Microsoft refresh failures are isolated by account and retain the existing revoked-consent disable behavior, including reconnect-required refresh classification. Calendar-scoped Microsoft errors retain failure diagnostics while sibling calendars continue; auth and rate-limit errors stop that account. Deletion runs only after successful fetching, reconciliation and upsert. These rules apply to manual and background inbound sync; stored events remain visible. Background runs admit at most 10 workspaces, 20 Google connections and 20 Microsoft connections per workspace, with a rotating selection across ticks. Workspace enumeration stops at 10,000 active token rows and fails visibly if the scan is incomplete. Tokens without enabled inbound connections do not dispatch workspace sync. Google snapshots stop at 20 pages without applying an incomplete snapshot; Microsoft retains its existing pagination guards. Excess work is reported as deferred, rather than counted as synchronized or failed. The scan accepts exactly 10,000 rows and probes one additional row to reject overflow. A shared 210-second cancellation signal bounds provider work below the private Infrastructure gateway's 240-second timeout and the function's 300-second limit. Provider and database requests have a 10-second transport timeout; completion writes use a separate five-second budget so cancellation can still record a failed run. Queued workspaces and unattempted Google connections are deferred on cancellation; an in-flight Google failure remains failed. Microsoft stops without creating provider-failure entries for aborted calendars and defers the unfinished account plus later accounts. Earlier observed calendar failures remain failed. Google, Graph and Microsoft refresh transport do not retry within a cron invocation; the existing 15-minute schedule owns subsequent attempts. Never substitute a detached promise timeout that leaves provider work running, and do not log provider error objects, headers, tokens, or event payloads. Regression coverage lives in the provider cron route tests, the workspace sync route tests, and `google-inbound-sync`, `microsoft-inbound-sync`, `provider-sync-budget`, and `provider-sync-network` tests under Calendar. Use `ttr resources run -- bun run --cwd apps/calendar test `; local verification does not require building workspace dependencies. Require the Calendar build, tests, lint and type checks in CI for the submitted commit before release. This policy does not change the cron cadence or authorize a native Worker cutover. ### Recovering individual calendar failures The warning names each failed Google calendar after a sync attempt. **Pause sync for this calendar** turns off only its inbound import; it preserves its saved events and visibility, and does not disconnect the account or affect other calendars. This action is available during the manual retry cooldown. Restore provider access when applicable, then re-enable inbound sync from the calendar's sync controls. **Sync now** retries the remaining enabled calendars. The sync handler stores sanitized version-1 `failedCalendars` diagnostics in the existing `calendar_sync_dashboard.error_stack_trace` text field. Each entry has only `connectionId`, `calendarName`, and a classified `code`. Never store OAuth credentials, provider response payloads, or headers there. The status API parses this format, filters disabled/paused connections, and returns `failedCalendars`; it never returns the raw diagnostic field. Older unstructured errors still show an aggregate warning and gain calendar-specific details on the next attempt. Per-calendar failure diagnostics and the pause shortcut currently cover Google inbound sync. Microsoft failures retain account-level reconnect/retry guidance; individual Microsoft calendar failure identification is not yet available. ## Views and keyboard support Calendar views share behavior across Calendar, Tasks, and embedded Web calendars. Use D, 4, W, M, Y, or A for day, four days, week, month, year, or agenda. These page shortcuts are inactive inside editors, menus, and dialogs, during input composition, or alongside Cmd/Ctrl/Alt. Month selection updates the host's controlled state and is restored from the saved view preference. Month provides event previews and day details; year opens the selected month or day; agenda searches titles and locations across its 30-day window. Event queries must cover the entire year or all 30 agenda days, not just the first day. The event route reads ordered 1,000-row pages so busy years are not truncated by the database response limit. Shared settings list the shortcuts alongside command search, app launcher, and sidebar commands. Verify modified shortcuts in Calendar and Tasks and check typing, modifiers, modal focus, and mobile overflow when changing these views. Global command/app launchers remain available while editing. Calendar view shortcuts are intentionally suppressed throughout editor descendants, including non-editable embedded content, to prevent unexpected view changes while working in an editor. ## Two-Way Sync Controls Calendar sync has two layers of user control: * Workspace-user preferences in `private.calendar_user_workspace_preferences` enable or disable inbound imports, outbound Tuturuuu-to-provider mirroring, the default outbound provider calendar, and the conflict policy. * `calendar_connections` controls each external calendar's import, outbound write, and provider-delete behavior. Outbound mirroring is opt-in. When enabled, native Tuturuuu event creates and edits mirror to the selected writable Google or Microsoft connection, and the local event stores provider identity so future updates and deletes propagate externally. Manual or cron sync with `direction: "outbound"` or `"both"` may also catch up local-only or previously failed Tuturuuu events in the active sync window. Inbound provider deletes are controlled per connection through `sync_delete_enabled`. User-initiated deletion of a synced external event still deletes the provider event directly because it is explicit CRUD, not passive provider import cleanup. After adding or changing two-way sync columns, prepare migrations in `apps/database`; do not run production Supabase push commands from agent sessions. Apply locally with `bun sb:up` when feasible, then regenerate database types only after the local schema reflects the migration. ## Installation and caching Calendar and Tasks serve their own `/serwist/sw.js` workers and installable app manifests. Client instrumentation captures the install event before hydration; these hosts explicitly transpile `@tuturuuu/ui` for that bootstrap entry point. The **Settings → Install app** control uses the browser prompt when available and gives Home Screen instructions otherwise. `/offline.html` is a public, bilingual fallback that bypasses authentication middleware. These productivity hosts use `cacheNavigations: false` and `staticAssetsOnly: true`: private HTML, APIs, and private images are never persisted by the worker. Installation precaches only the fallback, icons, and manifest. Hashed Next assets cache on demand, with at most 160 runtime entries. This avoids downloading the entire application at installation. Loaded data remains available in an open app through memory caches. Calendar snapshots are keyed by workspace and date range and limited to 12 ranges; event lookups pre-index date intervals and memoize at most 400 day results. Private snapshots are not persisted across app restarts. Reopening a workspace, syncing, and saving changes require connectivity; this release does not add a durable offline write queue. The offline indicator communicates that limitation. Verify worker registration, install manifest, cached asset reuse, offline fallback, and the absence of API/private-page entries in Cache Storage on both Calendar and Tasks. Re-run both app builds when changing the worker routes or tracing configuration. ### Calendar regression tests Calendar owns a workspace `test` script, so `bun test` and CI coverage include its provider, authorization, cron and event-route suites automatically. Run `ttr resources run -- bun run --cwd apps/calendar test --maxWorkers=2` for the complete focused suite. Manual provider smoke tests supplement these regressions; they do not replace the automated suite or prove that closed-client scheduling is active in production. ### Invitation delivery API Explicit invitations use the events collection POST with an `invitation` containing guest email addresses, optional-attendee flags and an IANA time zone, plus a UUIDv7 `requestId`. Choose a writable connected Google or Microsoft calendar. Provider-owned RSVP status is never accepted as organizer input. The same request ID must survive retries. The server binds it to the actor, workspace, source and complete invitation details. It reserves an encrypted local event before sending, then records the provider identity. Google uses a stable event ID and a private request fingerprint; Graph uses `transactionId`. A duplicate Google event with a different fingerprint is rejected. A timeout does not authorize a fresh send or a new request ID. Calendar requires server-only `CLOUDFLARE_COORDINATION_URL` and `CLOUDFLARE_COORDINATION_TOKEN` for its Durable Object request lease. The token has an encrypted backup in the Infrastructure vault. Missing storage fails closed. Only request hashes and completion state enter the Durable Object; provider credentials and guest lists do not. New reservations are accepted for 15 minutes, with one minute of forward clock tolerance. An older request can only resume its existing actor-bound reservation with identical details and the original provider idempotency key. This also recovers pending delivery after provider exceptions or missing responses; an expired request never recreates a deleted reservation. A 409 or ambiguous failure must leave the client in a review/retry state. Check the calendar before creating a replacement request. Pending deliveries cannot be edited or deleted through the event API. POST `/api/v1/workspaces/:wsId/calendar/events/:eventId/response` accepts `accepted`, `declined` or `tentative`. The selected connected account must actually be an attendee; organizer identity, provider concurrency and workspace authorization are checked before writing. Native clients use the authenticated infrastructure gateway, which permits only POST on this route. Responses are private and uncached. This is the delivery foundation. Scheduling surfaces and assistant tools must present the exact meeting and recipients for user confirmation before calling the send operation. These API tests do not establish live Gmail/Outlook delivery; verify invitations and RSVP updates using explicitly authorized test accounts before claiming provider interoperability. ### Google color identity and inheritance Google inbound sync preserves the provider's explicit event color ID, calendar-scoped label ID, inherited-color intent and resolved opaque RGB in `scheduling_metadata.google_color`. The existing canonical event-color foreign key remains a compatibility value, not an exact Google color definition. Google labels take precedence over legacy event color IDs; an event with neither inherits the connected calendar's current RGB color. Calendar custom RGB takes precedence over its calendar palette ID, which belongs to a different palette from event IDs. Active sync refreshes the matching connection's source color even when no events changed. Missing provider metadata remains unresolved and observable rather than inventing a custom color. Label-definition changes without an event delta can leave an explicit event's resolved RGB snapshot stale until the event is fetched again. Unrelated title/time updates read the current Google event, preserve its exact color or label identity and use its ETag to reject concurrent changes. Native creates map their canonical color argument to the Google event palette. The capability-gated shared web picker uses exact event IDs, calendar-scoped label IDs, and inherited color; its choices preserve opaque provider RGB. Microsoft and disabled-candidate surfaces keep their canonical palette. These source paths require the recovery schema and exact-commit build validation before activation. Sync never rewrites a calendar's label array or implicitly publishes a private native calendar to Google. ### Recoverable Google color operation development Exported-route overlap tests model the authoritative provider-series read-only RPC separately from operation-ledger RPCs. A writable fixture returns `false`; read-only and unavailable states must still reject PUT/DELETE before reservation or provider dispatch. `google-color-operations/route-overlap.test.ts` covers these states alongside delayed-request fencing and recovery. When adding an admission lookup, update shared route fixtures to its actual result contract so a fixture failure cannot masquerade as a provider or operation conflict. The same-calendar color-write followup has a server-only operation ledger, immutable prepared patch/ETag and private operation marker. Conditional replay uses the original ETag; it never refreshes an old operation's precondition. A provider 412 fences the old attempt, then current provider state is fetched and settled by its operation marker. Matching color alone is not completion proof. An authorized resumption must recheck Calendar management permission, connection owner and exact token/calendar/event identity. Only definitely-unsent reserved or prepared operations can cancel. Local commit failures remain recoverable. This is an unpublished implementation stage. A bounded route slice now connects same-calendar color PUT, encrypted content/time/local-lock PUT and conditional DELETE to reservation, immutable conditional dispatch and atomic finalization. The generic operation stores sensitive request content only in an authenticated encrypted journal. Finalization encrypts the authoritative provider projection; route callers do not perform a second local write. Conditional deletion settles habit skips and task/habit links in the same transaction and retains an authorized tombstone for recovery after the event row is gone. Dedicated authenticated `color-operation` GET/POST/DELETE handlers expose only operation ID/phase, execute recovery, or safely cancel an unsent operation. Recovery bodies accept only `operationId`; source, generation, prepared patches and force-clear overrides are never caller inputs. Reservation state is private and never added to generic event scheduling metadata. The candidate slice is disabled unless the server-only `CALENDAR_GOOGLE_COLOR_OPERATIONS_ENABLED` setting is `true`. That candidate mode supports same-source color, content/time/local-lock edits, invitation responses and deletion through the shared generation boundary. RSVP uses only the authenticated connected account's self attendee, seals the response against the original provider version, and projects the resulting event before reporting delivery. Cancelled meetings and superseded responses return a conflict. Supported source movement uses the durable provider saga described below. Unsupported move types return 409 before side effects. A pending operation blocks content, color and delete successors. Attendee updates are `all` for content/time edits and deletion; color/local-lock-only edits use `none`. Recovery executes the server-stored operation kind and original conditional request, never a new caller-supplied mutation. Status GET may accept a strict `operationId` query to reauthorize an already-deleted event's retained operation. Native/Microsoft routes retain their existing behavior. This mode remains disabled by default and is not approved for normal production mutation behavior: every provider writer must cooperate before enabling it; mixed enabled/disabled API versions are unsafe. The private RPC and transaction capability atomically merge Google color into latest metadata and commit sync/completion together. Generation persists after completion. Prepared import changes capture it before provider GET/list, apply through guarded transactions and durably defer conflicting identities before a sync token advances. Deferred replay captures again and fetches fresh provider state, rather than saving old content or credentials. The new SQL/types and combined route/import contracts still require isolated validation. Do not release either migration or enable the candidate setting on its own. Complete adoption by Web, Tasks, outbound sync, RSVP and all other competing writers, plus the source move/create saga, before enabling writes. Regression evidence is in `mutation-routes.test.ts`, `route-overlap.test.ts`, the encrypted mutation executor/provider suites and `calendar-google-mutation-replay.sql`. The sync coordination cooldown is not a lock. Google ETags are opaque equality tokens, not sortable revisions. Google moves lack a documented conditional fence and remain a separate recovery scope. Synthetic controlled overlapping routes demonstrate the intended ordering against an atomic storage double; they do not substitute for SQL, import, owning build or deployment proof. ### Event rendering and provider identity Web event surfaces render opaque provider fills with the higher-contrast black or white foreground. Mobile agenda, day/three-day/week cards, all-day chips and month indicators blend the same read-only provider hue into the active theme. Completed mobile events (end at or before the shared projected wall clock) use a weaker background tint and accent; foreground text remains fully opaque with at least 4.5:1 contrast. All-day ends remain exclusive, so an event stays active until its final midnight boundary. A shared minute clock refreshes completion styles while the Calendar screen is visible. This presentation never changes the stored provider RGB, explicit/inherited intent or event times. Persisted `google_color` RGB is used when available; only known inherited intent uses a valid current source RGB. Authenticated list/item reads join the current stored connection RGB only for a persisted source calendar link in the actor's active Google accounts. Unbound legacy rows, mismatched source links, and ambiguous or unavailable account matches retain the event snapshot. Active sync refreshes that connection even without an event delta. This read join does not fetch or mutate Google and does not infer intent for legacy rows. Native and legacy events without resolved provider metadata retain their canonical event color. Rendering does not infer old color intent, fetch a provider palette, or rewrite events. Web timed, all-day, agenda, month/year, location and drag previews use the same read-only color policy. Past web events fade with an overlay over their opaque fills; optimistic/preview status uses outlines. Hovering an overlapped lower card hides upper cards instead of blending their fills, and restores them when the hover ends. Focus/drag/resize states retain opaque backgrounds. The existing `preservePastEventOpacity` adapter option suppresses this fade. Past external provider events follow the same policy; previews, pending writes and active drag/resize states keep full intensity. Regression coverage for the policy and hover treatment lives in `past-event-treatment.test.ts` and `event-card.test.tsx`. Mobile source RGB survives date projections and local cache serialization. Regression coverage lives in `calendar-event-colors.test.ts`, `event-card.test.tsx`, `calendar-views.test.tsx`, `dynamic-island.test.tsx` and mobile `event_colors_test.dart`. These checks do not establish full palette editing, legacy-row refresh, or completed Google write reconciliation. ## Calendar navigation dates and query boundaries The legacy calendar treats its selected date and visible grid dates as calendar days: their local year, month, and day fields identify the selection. An explicit `YYYY-MM-DD` navigation value preserves that day when the effective timezone changes. Timestamp navigation values and Today project the actual instant into the resolved calendar timezone. The Calendar host supplies that timezone to its navigation provider; shared calendar content also supplies it to the event sync provider. Web's calendar route redirects to the Calendar host. Deep links apply once using the first available resolved timezone so later settings updates cannot reset a user selection. A timestamp link applied before personal settings finish loading retains that initially projected day; following the pending instant until settings settle needs a separate selection ownership contract. Headers, sidebar selection, day/week/month/year/agenda labels, and Today markers use these day fields consistently. A shared minute clock updates Today and the current-time indicator without changing the selected day. Timed event lookup projects event instants into the resolved timezone before grouping by day. Fetch ranges independently construct the first day's midnight and the midnight after the last day in the effective timezone. This supports 23-hour and 25-hour days across daylight-saving changes. Calendar cache keys include the timezone and the selected calendar-day fields, so a timezone change cannot reuse a range from another timezone. These changes preserve existing event storage, recurrence, and all-day identity contracts. All-day lookup uses the same canonical civil dates as the all-day strip, so month/year and agenda grouping agree with the configured-zone bar for legacy midnight payloads and zoned DST spans. All-day bar drag and location create/resize/split callbacks retain their existing timestamp conversion: their inferred all-day classification cannot safely represent zoned 23-hour or 25-hour midnight spans without a persistent intent contract. They do not establish a persistent all-day intent flag or verify live provider writes. Focused mounted tests exercise navigation, labels, grouping, and fetch boundaries; deployed browser verification and exact-head CI remain separate release checks. ### Recoverable creation and calendar transfers The candidate mode remains disabled by default. New event, label, and inherited provider-color commands return 409 while it is disabled. The shared web picker reads `providerColorWrites` from the actor-scoped color-options response and shows the legacy native palette until that capability is enabled; unsupported Microsoft sources retain the legacy palette. Color-only saves send only their color command and do not notify guests. Native mobile resolves the Google connection from fresh, uniquely matching canonical source options. Its full palette requires the same capability; provider-color commands are online only, and combined content/date/color changes must be saved separately. Missing or ambiguous source mapping preserves the legacy mobile palette. Activation requires draining existing legacy writer activity after the schema and retained guards are deployed. Its routes support deterministic Google creation, source-only movement between two calendars of the same Google account, native-to-Google creation, and conditional Google-to-native transfer. Google move preserves the provider event identity and iCalendar UID; a move may include a local lock change, but combined content/color/time changes return 409 before provider effects. A lost move response remains ambiguous: a matching ID and UID at the destination cannot distinguish this operation from an independent copy. Only a successful response from the attempted move permits that invocation to finalize; resumption never attributes an unmarked destination to the operation. Google-to-native transfers reject recurring masters and instances before admission because a single native snapshot cannot preserve the source recurrence. Cross-account copy/delete and Microsoft sagas return 409 before admission because their retry and compensation fences are not established. Google-to-Google moves of events with a calendar-scoped label also return 409 before key resolution or admission because that label cannot be carried safely to another calendar. This restriction applies to legacy and candidate moves. Creation uses a UUIDv7 request ID retained across retries for the same draft. That ID owns the local event, encrypted intent and deterministic Google event ID. The manual draft and every generated draft each retain a separate ID in state. An uncertain draft cannot reuse its ID after edits; recover the submitted intent before deliberately starting a new draft. Independent creation calls allocate new IDs unless their caller supplies an explicit retry ID. An unresolved existing calendar source never defaults to another account during an ordinary edit. Reusing an ID for a different payload is a conflict. Recovery exposes only the operation ID and phase, including terminal native transfers and deleted placeholders, and never returns sealed intent. Retained event generations are consulted independently of the feature flag. A pending generation blocks competing writes; a completed native transfer uses a native generation comparison for subsequent edits and deletion. Disabling the candidate cannot reopen legacy provider writes for a retained event. Legacy batch sync preflights every event before dispatch, and invited creation and automatic outbound mirroring remain blocked in candidate mode until they adopt the same boundary. With candidate mode disabled, ledgerless ordinary native behavior remains unchanged. When enabled, native edits use generation zero as their initial compare-and-set fence, so a concurrently admitted transfer rejects the stale edit. Native-to-Google admission compares the complete stored native row under the event lock before creating its retained generation. A concurrent ledgerless edit returns a conflict without a provider write, without depending on a native mutation timestamp. The transient encrypted row comparison never enters the public binding or persisted journal; route/service regressions and `calendar-provider-saga.sql` cover stale rejection and fresh admission. Synthetic Google acceptance established stale-version delete and move rejection, identity-preserving movement, duplicate insert rejection, and rejection of late recreation after a tombstone. This does not establish Microsoft behavior or permission on customer events. Source regressions cover stable draft request IDs, lost-response retry, unsupported operation rejection before keys/admission, and public native recovery without private intent. The admission and provider adapter label-move regressions live in `provider-saga-request-service.test.ts` and `provider-saga-adapter.test.ts`. ### Mobile wall-clock display and timezone preference recovery Mobile parses offset-bearing API timestamps into UTC instants once, then projects those instants into the selected Calendar timezone once. Agenda labels consume the projected wall-clock fields directly, including when the device timezone differs; they must not call native `toLocal` on a projected event. Existing UTC date-only all-day identity and DST-aware midnight bounds remain unchanged. Regression coverage lives in `agenda_view_test.dart`, `calendar_date_time_test.dart` and `calendar_event_presentation_test.dart`. Personal and workspace timezone preferences load independently. A successfully loaded scope remains editable if the other scope or the native timezone lookup fails. Saving a named personal preference can resolve Calendar without a device lookup. Workspace saving still requires permission and a loaded workspace scope. Failed reads retain Unknown with an explicit retry; they never imply an automatic preference or cause an implicit save. Failed saves retain the prior preference and allow retry. Account/workspace changes invalidate in-flight replies and editors. Mobile only marks a timezone resolved after the bundled timezone database accepts the effective personal, workspace or native identifier. The full IANA database accepts native aliases such as `Asia/Saigon`. Calendar, reminder scheduling, Settings offsets and Inventory period eligibility share one lazy, idempotent resolver; opening Inventory never resets the configured device-local zone. Compact timezone data is excluded from application imports. Unsupported identifiers remain a recoverable settings failure rather than throwing from Calendar or the personal Agenda clock. An acknowledged save retains its saved value even if its new inherited timezone cannot resolve. Existing initialized device-local timezone configuration is preserved. `calendar_timezone_failure_test.dart` covers invalid saved/native identifiers, rejected writes and acknowledged-save recovery. `timezone_settings_http_contract_test.dart` and `timezone_settings_http_widget_test.dart` exercise production gateway paths, Bearer serialization, failure/retry and explicit saving with synthetic data. Those checks do not prove a real provider session or explain a particular user's failed authenticated request without runtime evidence. Calendar's local authentication rejections classify existing IP blocks as `ip-already-blocked` and upstream authentication backpressure as `backend-auth-rate-limit`. The native gateway preserves these fixed categories for safe timezone diagnostics. Each branch names its policy; unknown caller/window fields stay Unknown. Unclassified responses distinguish absent metadata from unsupported values. Status 429, Retry-After, authentication, bans and quotas retain their existing behavior. `api-auth-rate-diagnostics.test.ts` exercises the real personal preference GET and gateway; `api_rate_limit_local_auth_test.dart` checks the safe mobile copy. These classifications do not establish the cause of a past rejection without an exact deployed runtime receipt. Mobile Calendar completion styling refreshes at wall-clock minute boundaries. Timed events without an end use the same 30-minute fallback as rendered cards. Timezone retry repeats a failed explicit save for its original scope; read failures reload preferences. Unknown device zones stay unresolved until native lookup succeeds, including after workspace changes during rate-limit cooldown. `calendar_minute_clock_test.dart` and the HTTP settings tests cover these rules. The shard-zero mobile test job additionally runs `agenda_view_test.dart` with `TZ=Asia/Ho_Chi_Minh` and `CALENDAR_NATIVE_TZ_REGRESSION=1`; its explicit native UTC+07 offset assertion prevents a UTC runner from silently weakening the wall-clock double-conversion regression. Creation recovery on the shared Calendar form keeps the original submitted request ID and body immutable after an uncertain failure. Automatic original retry is available only when the initially submitted Google source advertised durable provider writes; legacy/native or unknown-capability failures require checking the calendar first. An unavailable capability cannot later turn an uncertain legacy create into a retry. The original retry action preserves the edited form. Only a confirmed creation ID allows its next explicit Save to update that event; edited drafts never silently start another creation. This applies to shared web Calendar forms; legacy creation payloads keep optional IDs while explicit recoverable Google payloads require a UUIDv7 ID validated at enabled admission. Regression: `use-calendar-draft-save.test.tsx` and `calendar-creation-request.test.ts`. For copy-delete compensation, authoritative fresh absence at both bound endpoints settles a persisted `target-removed` checkpoint as a superseded tombstone under the current generation. Linked habits and cascading links are skipped. Retained generation and retired identities prevent a stale import from recreating the event. Regression: `calendar-provider-saga.sql` and provider saga projection tests. ## Mobile continuous dates and offline refresh Mobile Day, Three days, and Week timelines scroll through adjoining dates with one continuous horizontal offset. Date headers, all-day rows, and time columns move together; the time gutter stays fixed. A bounded backing window recenters only after scrolling settles, preserving the visible dates and pixel position. Date picking and Today still move to the requested date. Month and Year retain their calendar-grid navigation. The mobile Calendar displays its actor/workspace-scoped encrypted snapshot first, then awaits a fresh repository read even when that snapshot is still fresh. Transport failures retain authorized events and pending edits. Pagination stores its extended range for offline revisits. Account/workspace changes fence pending responses and cache writes; definitive access denial clears Calendar snapshots, while MFA verification challenges preserve the last authorized snapshot. Regression coverage: `continuous_date_scroll_test.dart` and `calendar_cubit_test.dart` cover intermediate drag offsets, synchronized columns, fresh revalidation, workspace races, revoked access, and MFA retention. Exact commit mobile CI and authenticated device verification remain required for release evidence. ## Native recurring series The Calendar API stores native Tuturuuu recurring events as one canonical series and a bounded set of exceptions. It expands instances for the requested viewport; it does not pre-create duplicate event rows or stop at a materialization horizon. Daily, weekly, monthly and yearly rules use a named timezone and preserve local wall-clock dates across daylight-saving changes. All-day ends are exclusive. Counts include cancelled occurrences, but exclude nonexistent DST times. `/api/v1/workspaces/{wsId}/calendar/series` creates and lists native series. A viewport read supplies `from`, `to` and optional `limit` (maximum 1,000). Reads reject oversized results instead of returning a silently incomplete list. The detail endpoint adds `/{seriesId}`. All routes require workspace membership and `manage_calendar`, including after a permission or membership change. A mutation supplies a unique `requestId`, the last `expectedRevision`, and `scope` (`this`, `all`, or `future`). Instance scopes additionally supply the immutable `originalStartLocal`, even if that instance has moved. Revision conflicts return 409; repeating the same completed request returns its receipt without another write. Encryption is applied to titles, descriptions and locations. Missing encryption keys fail closed instead of exposing encrypted strings. An edit to `this` changes only the exception at its original slot. An edit to `all` changes the master; changing the generating rule or anchor resets its exceptions. A `future` edit splits the series transactionally, preserves remaining COUNT, and resets exceptions at and after the split, returning their discarded count. A first-occurrence `future` edit behaves as `all`. Deletes use the same scope and concurrency contract. This API stage accepts native series only. Google and Outlook imports and writes retain their existing behavior until their recoverable series integration ships; unsupported provider rules must remain preserved and read-only. The canonical Google RRULE and Microsoft Graph adapters explicitly reject lossy conversions. Regression evidence: `calendar-native-recurrence.sql` tests authorization, idempotency, revision conflicts and atomic splitting. `recurrence/service.test.ts` and `calendar-recurrence-edit.test.ts` cover encrypted retries, immutable identity, DST slot counts, cancellation, exception edits and truthful bounded reads. ### Outlook snapshot completeness Outlook calendar synchronization follows every `calendarView` continuation before reconciling removed events. Reads request UTC on every page and preserve the provider's opaque continuation query. Duplicate event identities across pages collapse to the latest returned version. A failed, malformed, looping or oversized snapshot fails the sync; a partial snapshot must never authorize deletion. Reads are bounded to 50 pages and 25,000 distinct events. Continuations must remain on the same Microsoft Graph calendar collection. This applies to existing Outlook single events, recurring occurrences and moved exceptions; it does not enable canonical series writes by itself. Regression coverage: `packages/microsoft/src/calendar/pagination.test.ts`. ### Recoverable provider series admission The provider operation endpoints reserve an encrypted, actor-bound intent before remote effects and publish the canonical native result only after every provider step has a durable checkpoint. They preserve Google event IDs and Outlook immutable IDs, use revision preconditions, and keep original occurrence slots separate from moved start times. A partial “this and future” operation resumes from its completed trim instead of blindly repeating both provider writes. `POST /api/v1/workspaces/{wsId}/calendar/series/provider-operations` accepts `requestId`, `source` (`provider` and `connectionId`), `action`, and the native series creation or mutation fields. An update/delete also supplies `seriesId`. `GET .../provider-operations/{operationId}` returns actor-scoped status; `POST` to that detail endpoint retries the retained intent. A pending operation returns HTTP 202 with its `operationId`, not a false success. An applied operation returns the hydrated result. Journals, OAuth credentials and raw SDK errors never appear in those responses. Workspace membership, `manage_calendar`, current connection ownership and outbound-sync permission are checked again during recovery. Native mutation routes cannot bypass provider-bound series or a pending provider operation. New admission defaults to disabled unless `CALENDAR_PROVIDER_SERIES_OPERATIONS_ENABLED=true`. Keep it disabled until the canonical inbound reconciliation and provider UI integration have shipped and been verified together; the operation protocol alone is not full provider parity. Retained operations remain readable/retryable when new admission is disabled. Unsupported provider patterns are rejected rather than converted lossily; mailbox timezone support remains authoritative. Provider delivery and organizer receipts still require authenticated Google/Outlook verification. Regression evidence: `calendar-provider-series.sql`, provider `plan.test.ts` and `writer.test.ts`, plus `calendar-provider-series.test.ts` in Internal API cover permission revocation, leases, publication ordering, idempotent create recovery, revision conflicts, immutable identities, scope splitting and pending status. ### Provider inbound recurrence observations Canonical provider import uses the same default-disabled admission flag as recoverable external series operations. When enabled for verification, the live Google and Outlook sync paths reconcile supported recurring masters before persisting ordinary expanded instances. This is a staged integration, not a claim that provider editing or full recurrence parity is enabled in production. Google reads complete non-expanded `iCalUID` exception lists, including cancelled and moved instances outside the viewport. Outlook expands master exceptions and reads complete bounded immutable-ID views twice. Separate occurrence snapshots and the master revision are compared before publication. Windows timezone names use CLDR's default territory mapping to IANA; unknown/custom names and nonzero fractional occurrence precision fail closed. There is no machine-timezone fallback. Reconciliation rechecks the token-owning actor, workspace membership, `manage_calendar`, source ownership and inbound permission throughout the read and before commit. The transaction compares the captured local binding ETag and defers while an outbound operation is pending. It publishes encrypted native fields and actor/source-bound encrypted provider metadata before suppressing explicitly represented legacy identities. Other calendars and unrepresented provider rows remain untouched. Outlook cancellations proven inside the complete view replace that covered range; known cancellations outside it survive if their original slots still belong to the current rule. Deleted bound masters are rechecked even when the Outlook view contains no remaining occurrences. Unsupported masters retain encrypted raw snapshots and visibly read-only projections; a previous canonical rule is hidden until safely supported again. Incomplete reads reject the refresh; see [read-only rules](/platform/features/native-calendar-recurrence#unsupported-provider-rules). Keep admission disabled until metadata-preserving future splits, full legacy identity suppression across ranges, provider UI, and authenticated Google/Outlook verification are completed together. Regression evidence: `calendar-provider-reconciliation.sql` applies the actual migration and covers actor/source revocation, pending-operation deferral, stale observations, replay, deletion, rollback and scoped legacy suppression. Provider inbound reader/connection/service tests cover complete snapshots, independently changed exceptions, immutable identity bridging, encrypted metadata, cancellation coverage and the disabled default. Microsoft pagination/timezone and shared recurrence-edit tests cover continuation authorization, Windows zones and DST interval boundaries. ### Future provider split metadata A provider **this and following** edit reads and revision-checks the fresh master before reserving its trim. It retains supported writable metadata in the encrypted create step: guest identities/options, reminders, visibility/privacy, free-busy, Google guest rights and non-operation custom properties, or Outlook categories and response-request settings. Old organizer IDs, attendee RSVP replies, provider IDs and recovery markers are not copied to the new invitation. Outlook HTML notes keep their content type when unchanged; an explicitly edited description uses text. The current preflight rejects Google conferences, attachments, special event types, omitted attendee lists or a non-organizer copy, and Outlook online meetings, attachments, hidden guests or a non-organizer copy. It rejects malformed metadata instead of silently replacing privacy/reminder settings with provider defaults. These exceptions are rejected **before any trim**. Other edit scopes patch the existing provider event and do not create a replacement metadata copy. New external admission remains disabled; provider UI and authenticated end-to-end verification are still required before rollout. Regression evidence: `create-metadata.test.ts`, `future-admission.test.ts` and provider `writer.test.ts` cover preserved metadata, omitted replies/identities, HTML notes, strict journal shape, preflight-before-reservation, revision conflicts, source mismatch and actual provider create payloads. Recovery fingerprints include the retained metadata so retries cannot silently substitute a different tail. ### Google future-series attachment references A future split preserves up to 25 Google attachment references from the freshly read organizer-owned master. The replacement event uses Google's `supportsAttachments` request option and excludes read-only file IDs. This copies links and display metadata, not file content or Drive permissions. Incomplete references fail before the original series is trimmed. Google conference reuse remains blocked because it can change access and expose meeting details; Outlook attachment and online-meeting splits also remain blocked. Provider editing admission stays disabled until the remaining parity checks pass. Regression coverage: `create-metadata.test.ts`, `future-admission.test.ts`, and `writer.test.ts` verify reference validation, preflight ordering, and create request options. See the [Google event resource](https://developers.google.com/workspace/calendar/api/v3/reference/events) for attachment limits and conference reuse restrictions. ### Outlook legacy recurring-instance identity verification When provider-series admission is explicitly enabled, inbound reconciliation verifies older stored Outlook IDs outside the current viewport against their exact connected calendar. The bounded read-only pass selects IDs only, reads up to 1,000 source rows in batches of 20 with at most three batches in flight, and uses an explicit regular-to-immutable ID translation before requesting event and master identities. The translation requires the already requested `User.Read` Microsoft scope. Current source authorization is checked before each batch. Only explicitly verified IDs join the existing atomic canonical publication and legacy cleanup; single events, other masters, and missing remote resources are not attributed to the series. An incomplete batch, permission failure, throttling, or source overflow fails closed without publishing a partially verified series. This performs no provider mutation or calendar-wide deletion and does not enable provider editing. Regression coverage: `graph-legacy-identities.test.ts` verifies source filters, old-slot linkage, permission revocation, receipt completeness, foreign-master isolation, provider failures, and batch bounds. ### Editable monthly and yearly weekday patterns The shared web recurrence editor supports first, second, third, fourth, or last weekday patterns for monthly and yearly native series. Yearly patterns have an explicit month. Selecting multiple weekdays uses the earliest matching date in the selected ordinal week, following the canonical Google/Outlook adapter semantics ([Graph recurrence patterns](https://learn.microsoft.com/en-us/graph/api/resources/recurrencepattern?view=graph-rest-1.0)); the initial local date must match the pattern. The form does not silently move the first occurrence when the pattern changes. Absolute month-day rules offer skipping missing dates or using the month's last day. Details-only edits preserve imported month-end behavior, yearly month and weekly week-start boundaries without adding optional normalization that would reset exceptions. This-occurrence edits do not modify the rule; future edits retain the remaining occurrence count and immutable original slot. Unsupported provider rules stay read-only, and outbound provider admission remains disabled. Regression coverage: `native-recurrence-pattern-model.test.ts` checks all five ordinals against both provider serializers, multi-weekday patterns, inclusive end dates, imported week boundaries and month-end behavior, invalid input, and edit scopes. `native-recurrence-pattern-fields.test.tsx` covers the interactive monthly, yearly, month-end and weekly controls. ### Smart-scheduling startup enrichment Calendar server startup loads the current actor's accessible tasks first. Once those IDs are known, list/workspace metadata and actor-scoped scheduling settings are read concurrently. Empty task sets do not trigger broad enrichment reads; missing settings and list metadata retain their existing defaults. This removes one sequential database stage without changing task visibility or provider admission. The actual production latency benefit still requires authenticated post-deployment timing; focused tests are not a browser performance measurement. Regression coverage: `load-smart-scheduling-tasks.test.ts` holds list metadata unresolved while proving that actor-filtered scheduling settings have already started, verifies accessible IDs and deduplicated lists, and covers empty/missing responses, settings defaults, and rejected reads. Calendar's dashboard permission check uses the UUID returned by the verified workspace read while retaining the exact satellite actor. This avoids resolving `personal` again inside the permission helper. Membership, roles and default permissions still use the same helper; denied navigation retains its URL slug. The page's scheduling reads begin only after workspace and permission verification. Coverage: dashboard `page.test.tsx` exercises aliases/UUIDs, actor preservation, verification ordering, permission denial, missing records and rejected reads; workspace-helper tests verify that UUID normalization needs no alias lookup. For notification/event deep links, the page starts token and scheduling reads alongside the scoped event-date lookup after permission verification. A valid explicit date skips the lookup as before; invalid or missing dates use a valid stored event instant when available. Date-query errors retain their original precedence, and concurrent resource failures are handled while that lookup is pending. No resource reads begin before authorization. Coverage: `page-date-loading.test.tsx` uses an unresolved event response to verify overlap, actor/workspace filters, date-only and DST-offset links, fallbacks and both error paths. Browser latency improvement still requires post-deployment measurement. ## Mobile continuous schedule geometry Mobile three-day and week timelines retain their continuous buffered date window. Dragging remains continuous; releasing settles header, all-day strip and timed grid on the same day boundary. Selected-date navigation and window recentering preserve that alignment without replacing the loaded event range or cache. Timed event widths use connected overlap groups with half-open time intervals. Transitive overlaps share columns; an event starting exactly when a group ends belongs to a new group. Isolated groups receive the full available date-column width. This shared layout also applies to the mobile day timeline. All-day span backgrounds retain their date extent while their title and optional working-location icon stay inside the span's intersection with the current viewport, clear of the fixed time gutter. Labels truncate when the visible portion is narrow; offscreen spans do not expose duplicate visible labels. All-day rows reserve enough height for the current text scale. These are display rules and do not change event dates, actor permissions, recurrence, providers or cache scope. Regression coverage: `calendar_viewport_test.dart`, `date_snap_scroll_physics_test.dart` and `continuous_date_scroll_test.dart` cover connected groups, visible clipped labels, native scroll settling, synchronized surfaces, continuous month traversal and programmatic date navigation. Widget coverage is separate from native-device gesture and provider verification. ## Mobile timeline overlap geometry Mobile day and multi-day timelines reserve columns for the painted minimum card height as well as timestamp overlap. This keeps adjacent short events and their tap targets separate, including enlarged text, while isolated groups still use the full column width. Card positions and durations retain sub-minute precision so rounded pixels cannot create an untracked overlap. Event timestamps, recurring rules, and provider writes remain unchanged. The fixed all-day gutter label stays on one ellipsized line; the complete localized label remains available to accessibility services. `calendar_rendered_overlap_test.dart` checks actual card bounds and bottom-edge taps at normal and enlarged text sizes, and the fixed all-day gutter. These widget checks require device gesture verification after delivery. ### Mobile timeline zoom Day, three-day, and week timelines support smooth two-finger pinch zoom from 65% to 250%, defaulting to 100%. The fractional time under the pinch stays under the fingers; shell-owned Timeline zoom controls offer accessible zoom in, zoom out, and reset actions with the same anchored geometry. Reduced motion applies control zoom and initial time positioning immediately, preserving the time/date anchor. One-finger scrolling, date snapping, event taps, timestamps and column widths retain their behavior. Completed zoom is stored in the existing account/workspace-scoped Calendar cache and reused across timeline modes and dates. Workspace/account switches cancel unfinished pinches and reject retained control callbacks, including return-to-same scope and logout races; unavailable preference storage leaves zoom usable locally. Month, year, and agenda views retain their existing layout. Shared minimum card height remains part of both painting and overlap grouping at every zoom level. `calendar_timeline_zoom_test.dart`, `calendar_zoom_lifecycle_test.dart`, and `calendar_timeline_zoom_state_test.dart` cover gestures, anchors and scoped restoration; `calendar_reduced_motion_test.dart` covers immediate positioning and interrupted animation. ## Day highlighting, all-day spans and past events Mobile multi-day headers, timeline columns, month and year date fills highlight only the current civil calendar day in the resolved timezone. The first visible or selected navigation day remains neutral when it is not today; selection still drives navigation. All-day materials retain occurrence identity through row and viewport changes, using workspace, event identifier and start/end boundaries so recurring instances with reused provider identifiers stay distinct. Web and mobile preserve the stored UTC calendar dates of untagged legacy UTC-midnight all-day imports. Their original provider dates/timezone are absent from the current API. Other all-day boundaries project into the resolved display timezone; the end remains exclusive, including 23/25-hour DST days and long spans. Month, year, agenda and day/week lookup share those civil bounds with the all-day strip: the browser timezone never shifts a UTC-midnight import to the previous day, and an event is excluded from its exclusive end date. This rendering policy does not rewrite provider data or claim date-only provider write support. Past events fade consistently across native, Google and Microsoft providers on Web using an overlay over the opaque fill when their end is at or before the current instant. All-day spans fade at their displayed exclusive end midnight in the selected calendar timezone, including merged spans, using the shared calendar clock. Explicit adapter preservation, interaction, previews and pending optimistic writes remain exceptions. Mobile keeps its existing past-event presentation. Regression coverage is `calendar_day_identity_test.dart`, `calendar_viewport_test.dart`, `all-day-event-layout.test.ts`, `calendar-event-lookup.test.ts` (cross-browser zones and both DST transitions) and `past-event-treatment.test.ts`. ## Mobile selected-view reset Tapping the selected floating Calendar view item resets its date and scroll position without changing the exact view mode. Day and three-day views start at today. Week starts at the current week's boundary using the effective first-day preference (personal, workspace, then locale); it does not force today into the first column. Timed views restore the current-time viewport. Agenda returns to today, month to the current month, and year to the current year. The reset and Today action use Calendar's projected timezone clock for both date selection and range loading. Repeated taps while already at today still reset scroll position. Reduced-motion settings use immediate scroll positioning. Other apps retain the shell's existing scroll-first and section-reset behavior; Calendar's existing explicit section reset still restores its default view. Coverage: `calendar_view_reselect_test.dart` exercises the real Calendar page and shared floating shell; `calendar_scroll_reset_test.dart` covers repeated resets, week preferences, timezone/year boundaries, reduced motion, and disposal. These source checks do not establish native-device or deployed runtime verification. ## Native invitation replies Accept, Decline and Tentative use the invited account's native provider protocol. Google replies patch only the self attendee, with `attendeesOmitted`, `sendUpdates=all` and the fresh event's `If-Match` version. Missing versions fail with a private HTTP 409 before dispatch; stale versions are not automatically retried. The recoverable Google path seals the same response and version for replay. Graph replies use the account's native response action with `sendResponse=true`. `meeting-provider-response.test.ts`, `meeting-provider-protocol.test.ts` and the response route tests cover these boundaries. The protocol fixture uses the real Google SDK serializer with an injected transport and synthetic responses. It proves serialized requests and failure handling, not Google acceptance or organizer receipt. [Google's conditional modification contract](https://developers.google.com/workspace/calendar/api/guides/version-resources) defines the version precondition. Native provider delivery remains unverified until an authorized dedicated sandbox has an invited account, a separate organizer, a recurring event and an exact deployed source identity. Verify all three replies on the organizer's provider record, including occurrence identity and retained other attendees. A successful mutation response or HTML mail link is insufficient evidence. This does not enable the separately gated recurrence editor. ## Mobile event descriptions Mobile Calendar details render provider HTML paragraphs, line breaks, headings, lists, emphasis and safe links through the existing native Markdown renderer. Markdown and plain descriptions use the same display path. Timed agenda cards and dashboard Calendar rows show a readable two-line text preview; the full formatting remains in event details. Malformed HTML retains recoverable text. Inline HTML code normalizes line breaks to spaces; preformatted code keeps its multiline content. Script, style and embedded executable content are omitted, remote images remain alt text, and links use the existing mobile launcher scheme and host policy. Theme and system text scaling apply; long detail content scrolls. This is display-only for native and provider events. The editor, stored source, recurrence and provider write payloads retain their original description. No description conversion is saved. Regression coverage: `apps/mobile/test/features/calendar/widgets/calendar_description_test.dart` checks the actual detail and agenda widgets, formatted Markdown spans, mixed and malformed content, links, image exclusion, light/dark themes and enlarged text. # Chat Source: https://docs.tuturuuu.com/platform/applications/chat Private-schema workspace messaging for direct messages, groups, channels, AI conversations, and Drive-backed attachments. Chat is implemented in two hosts: * `apps/web` owns protected APIs, workspace authorization, storage signing, and private Supabase RPC execution. * `apps/chat` is the standalone satellite UI at `https://chat.tuturuuu.com`, with local Portless origin `https://chat.tuturuuu.localhost` and direct fallback `http://localhost:7821`. Both hosts render the same shared UI from `@tuturuuu/ui/chat/chat-workspace` and call the same `@tuturuuu/internal-api` chat client. Do not add direct browser Supabase reads, client-local raw `fetch('/api/...')`, or host-specific chat business logic. Unmatched `/api/workspaces/*` requests, including workspace invitations and workspace details, use the Web fallback with their paths and queries intact. Local Chat API handlers retain precedence. Regression coverage lives in `apps/chat/src/next-config.test.ts`. ## API Ownership `apps/chat` forwards unmatched `/api/*` paths to `apps/web` through fallback rewrites, after local auth and build-info handlers. The more specific `/api/v1/infrastructure/*` fallback still targets Infrastructure first. The standalone app authenticates through the cross-app session target `chat`; `apps/web` accepts that target only on the chat API surface and still performs normal request-scoped user validation before protected work. Chat consumes `/verify-token` in the proxy before rendering pages. The verifier sets both the Chat-local app-session cookie and the Web-issued app-session cookie pair used by forwarded central APIs. Protected Chat routes require both cookies; if an older local-only cookie is present, Chat sends the user through the local `/login` recovery path so the platform handoff refreshes the full cookie pair. Access-token refresh must stay same-origin through `/api/auth/refresh-app-session` instead of sending the browser back to `apps/web` while a valid refresh cookie exists. Chat routes must follow this order: 1. Authenticate the request user or app-session user. 2. Normalize workspace aliases such as `personal`. 3. Verify workspace membership and the required chat permission. 4. Call private-schema RPCs through a service-role admin client with `.schema('private').rpc(...)`. 5. Return only JSON DTOs that are safe for participants of the conversation. ## Private Schema Contract Durable chat data lives in private tables only: * `private.chat_conversations` * `private.chat_conversation_members` * `private.chat_messages` * `private.chat_message_attachments` * `private.chat_message_reactions` * `private.chat_conversation_ai_settings` * `private.chat_audit_events` The migration revokes private schema, table, and function access from `public`, `anon`, and `authenticated`; grants execution only to `service_role`; and keeps RLS enabled with no permissive direct-access policies. Browser clients must recover durable state by refetching the `apps/web` API, never by reading private or legacy public chat tables directly. RPCs enforce participant access, workspace membership, direct-chat uniqueness, attachment path ownership, message ownership, reaction limits, search scoping, read state, and audit metadata. When adding behavior, extend the private RPC surface first and keep the web route as a thin auth/validation wrapper. ## Attachments Chat attachments use the existing workspace storage provider rather than a separate chat bucket. The upload flow is: 1. Client requests `/api/v1/workspaces/:wsId/chat/conversations/:conversationId/attachments/upload-url`. 2. `apps/web` verifies the participant through `private.chat_prepare_attachment`. 3. `apps/web` creates a Drive-backed signed upload payload under `:wsId/chats/:conversationId/*`. 4. The client uploads to the signed URL and sends the returned attachment draft with the message. 5. `private.chat_send_message` finalizes records and links attachments to the message. Downloads use the attachment signing route. It calls `private.chat_get_attachment` first, then issues a short-lived storage read URL only after the caller is confirmed as a participant. ## Permissions The chat permission set is: * `view_chat`: read conversations where the actor is a participant. * `create_chat`: create direct messages, groups, channels, and AI chats. * `manage_chat`: manage chat membership, state, and AI settings. * `moderate_chat`: moderate messages and reactions. Member defaults include `view_chat` and `create_chat`. The dashboard navigation should hide or disable Chat when `view_chat` is missing. ## AI Conversations AI conversations are normal private chat conversations with `ai_enabled = true` plus private AI settings. Existing AI audit or billing tables can remain for provider usage tracking, but human chat access must not depend on public AI chat tables. Persist generated assistant messages through private chat RPCs so conversation history, read state, attachments, and audit events remain in one protected chat domain. # CMS Source: https://docs.tuturuuu.com/platform/applications/cms Dedicated Tuturuuu CMS app for site editing, preview, publishing, media, and team access. ## Overview `apps/cms` is the dedicated home for Tuturuuu CMS. It should feel like a consumer-grade site editing product for nontechnical editors, even though it continues to use the existing external-project implementation contracts behind the scenes. * It owns the CMS UI, routing, workspace picker, and root-level `/{wsId}/projects` linking console. * It remains a satellite frontend with mixed API ownership: CMS-local handlers own root administration and commerce integration, while the larger external-project content API remains in `apps/web`. * Unmatched CMS `/api/*` traffic falls back to `apps/web`; an exact local route is served by `apps/cms` before that fallback is considered. ## Product Vocabulary Normal CMS product UI should use editor-friendly terms: site, site template, connection, content, section, URL path, custom details, media, publishing, preview, and team access. Avoid exposing implementation terms such as external project, canonical, adapter, binding, slug, schema, metadata, profile data, payload, or JSON in the primary UI. When staff genuinely need exact implementation values, place them behind a collapsed "Developer details" or internal root-console advanced panel. Code, database names, API paths, tests, and operational docs can keep the existing `external-project*` names so route and data contracts remain stable. ## Routing * `/{wsId}`: overview * `/{wsId}/games`: game-focused content library, visible only when CMS Games is enabled * `/{wsId}/landing`: landing-page builder for hero/profile/page-section edits * `/{wsId}/library`: content operations library for non-landing, non-game content * `/{wsId}/library/entries/{entryId}`: compatibility redirect that opens the library fullscreen editor dialog * `/{wsId}/library/collections/{collectionId}`: collection detail * `/{wsId}/members`: workspace member and role management * `/{wsId}/preview`: delivered-content preview * `/{wsId}/settings`: legacy compatibility redirect to `/{wsId}/members` * `/internal/projects`: internal site-template registry and workspace linking console * `/play/{wsId}/webgl/{assetId}`: public WebGL package player. This route does not require a CMS login, but the proxied WebGL asset API still only serves the package when the owning CMS entry is published. WebGL player iframes must stay sandboxed without `allow-same-origin`. When `wsId` resolves to the internal/root workspace, `/{wsId}` and other workspace-local routes should bounce to `/internal/projects` instead of trying to render the bound-workspace CMS surfaces. The previous `/{wsId}/content`, `/{wsId}/collections/...`, and `/{wsId}/admin` CMS routes are removed. New entry points should link directly to the CMS-native route map above. ## Access Model * Only workspaces with CMS access enabled appear in the CMS workspace picker. * A workspace must still satisfy the existing external-project permissions to open CMS workspace routes. * CMS Games is disabled by default for every workspace. Enable it from the CMS settings dialog, which writes `ENABLE_CMS_GAMES=true` to workspace configs and reveals the `/{wsId}/games` sidebar route. * Only platform admins can open `/internal/projects`. * Workspace member and role management lives on `/{wsId}/members`. Read paths resolve through CMS workspace access so editors with CMS access can load people, invites, roles, member defaults, and guest defaults without requiring direct workspace settings-route access. Write paths still respect member and role management permissions. ## API Ownership * `apps/cms` owns host-local auth/session and build-info routes. It also owns the root administration handlers for external-project audits, bindings, and project templates under `/api/v1/admin/*`, plus commerce overview, insights, products, and storefront under `/api/v1/commerce/*`. * The workspace external-project families for content models, collections, entries, blocks, assets, publishing and delivery, sync, and CMS-aware team access remain in `apps/web`. Requests with no CMS-local handler reach them through the fallback `/api/:path*` rewrite. * Keep clients on typed `@tuturuuu/internal-api` helpers. Browser calls should stay same-origin so local routes win and fallback routes are forwarded; request-scoped server calls must preserve forwarded authentication. * CMS-local protected handlers resolve the CMS app-session actor and then apply `getCmsWorkspaceAccess` or the root-admin gate. Forwarded Web handlers still require the coordinated Web-issued session and enforce their own workspace permissions; the proxy guard is not a replacement for route authorization. * The rewrite target must resolve to the central web app, not the CMS app origin. Prefer `INTERNAL_WEB_API_ORIGIN`, `NEXT_PUBLIC_WEB_APP_URL`, or `WEB_APP_URL` for the central origin. If a deployment-level `NEXT_PUBLIC_APP_URL` points at `cms.tuturuuu.com` or the current CMS Vercel preview URL, the CMS config ignores it and falls back to `https://tuturuuu.com` to avoid self-rewriting `/api/*` requests. * Add new behavior to the host that owns its route family. Extend the CMS-local admin or commerce handler for those families; extend the Web-owned external-project handler for content, media, publishing, sync, or team behavior, and expose shared access through `packages/internal-api`. * The root linking console reads the workspace-indexed binding summary from the CMS-local `GET /api/v1/admin/external-project-bindings` handler. * The root linking console may load its initial server-render payload directly with the request-scoped CMS Supabase admin path after `getCmsWorkspaceAccess` proves root admin access. Avoid server-to-server Internal API fetches during that initial render, because production auth/origin forwarding failures turn `/internal/projects` into a hard RSC error page. Keep workspace-secret lookups batched; one `.in('ws_id', allWorkspaceIds)` query can exceed PostgREST/proxy URL limits and return `400 Bad Request` in production. * Backend naming stays on `external-project*` contracts even though the product surface is branded as Tuturuuu CMS. * Add or update the CMS product-copy hygiene test whenever new visible CMS strings are introduced. The test should protect the consumer vocabulary while allowing collapsed developer-detail and internal-only exceptions. ## Content Model * Collections remain the content-type container. Field definitions live in `workspace_external_project_field_definitions`, while entry values continue to be stored in the existing `profile_data` and `metadata` JSON payloads so delivery and sync payloads stay backward-compatible. * Field definitions support the manifest field contract: `string`, `markdown`, `number`, `boolean`, `date`, `datetime`, `json`, and `string-array`. Scope controls whether the value is saved under `profile_data` or `metadata`. * The CMS Library has a `Content model` section with reusable templates for Profile, Blog Posts, Gallery, Shop Products, Writing Worlds, and Social Links. Applying a template creates the collection if needed, stores the collection schema, and creates any missing field definitions without deleting CMS-only fields. * Landing and Library must stay visibly distinct. Landing is a page-builder surface for landing-only sections, preview-first actions, and page readiness. Library is a content operations surface for search, status, bulk publishing, collection health, and non-landing/non-game content. Keep `landing`, `library`, and `games` capability scopes mutually distinct in tests. * The Library command center is the consolidated authoring entry point for content, content models, workflow queues, and settings. Keep new CMS operations reachable from that surface before adding another isolated toolbar or settings panel. * Entry detail forms render schema-aware controls for the active collection field definitions. Authors should edit those typed controls instead of hand-editing raw `profile_data` or `metadata` JSON for modeled fields. * Body and asset affordances should be driven by the collection schema when available. Naming heuristics for legacy Yoola collections remain as compatibility fallback only. * External-project setup and sync import manifest `profileFields` and `metadataFields` into DB field definitions. Sync snapshots are built from DB-managed field definitions, and field removals should only be applied during an explicit destructive sync. ## Yashie Bridge * Yashie is the proof case for the generic content model. Its manifest seeds profile, blog post, gallery, shop product, writing world, and social-link collections and field definitions. * This phase does not change `../yashie` runtime pages. Yashie can be seeded and managed from CMS, but the public Yashie app continues to read its local static data until a later integration pass consumes CMS delivery payloads. * Shop product entries are catalog-only in this phase. No checkout, payment, inventory, or commerce fulfillment behavior is implied by the template. ## Client Architecture * Keep route pages server-side only for auth and access gates, then hand off interactive CMS surfaces to client modules backed by TanStack Query. * Keep `cms-studio-client.tsx` focused on query state, mutations, and routing. Library rendering should stay split across dedicated gallery, workflow, and settings modules rather than growing back into one large TSX file. * Keep CMS team access clients on `@tuturuuu/internal-api` helpers that target external-project-aware `apps/web` routes. Do not call the standard workspace members or roles settings endpoints directly from `apps/cms`. * Entry detail now opens as a fullscreen dialog from the library route so the CMS keeps the library cache warm instead of forcing a separate navigation for each entry. * The Games route reuses the library client with a game-like collection scope and only exposes WebGL ZIP upload controls when `ENABLE_CMS_GAMES` is explicitly enabled. * When a user creates the first Games entry, CMS should automatically create the workspace `Games` collection and then open the new game entry instead of requiring a manual collection setup step. * Published game entries expose a public `/play/{wsId}/webgl/{assetId}` link from the WebGL package card. Keep this route login-free in the CMS proxy, and keep publication checks in the central `apps/web` WebGL asset route so drafts and archived entries do not leak assets. The player iframe and the served WebGL document must both use sandboxing that allows scripts but does not allow same-origin access. * CMS media uploads show per-file progress for cover images, gallery media, and WebGL ZIP packages. Cover and gallery media must use the external-project asset app-server upload route so Tuturuuu measures the actual bytes before writing storage objects, then store the returned Drive path on the CMS asset row. WebGL ZIP package uploads still upload directly to the signed storage URL returned by the self-hosted web API, then call the WebGL package finalize route so the ZIP can be extracted and mapped to a playable artifact. The WebGL asset-serving route must infer browser content types from the requested WebGL filename for known outputs such as `index.html`, `.js`, `.jpg`, `.wasm`, `.data`, and compressed `.gz`/`.br` files, because extracted storage metadata can be too generic or incorrectly recorded as `text/plain`. Served WebGL files must include a CSP `sandbox` header that omits `allow-same-origin`; served HTML is also adjusted for the CMS player so Unity canvases fill the iframe viewport instead of keeping the default fixed-size template layout, hide the stock Unity footer chrome, resize the canvas backing buffer to the iframe viewport, inject a route-local `` and artifact-map URL resolver so `Build/*` and `TemplateData/*` load through the same WebGL package API route even when the Unity template creates scripts dynamically, and show in-frame resource download progress when the runtime fetches package assets. * CMS asset delivery must respect the workspace Drive provider. Supabase assets may use signed image transforms, while R2-backed assets should resolve through the workspace storage provider signed-read path and ignore Supabase-only transform parameters. * CMS asset rows may only store workspace storage paths under `external-projects/`; asset delivery and cleanup must not operate on paths from other workspace modules such as Drive or finance. * CMS does not register the shared offline service worker or emit the shared web app manifest. It is a Vercel-hosted satellite whose unmatched, Web-owned protected API families fall back to `apps/web`, so PWA routes owned by `apps/web` must not be advertised from `cms.tuturuuu.com`. * Library taxonomy edits should stay lightweight: category/tag assignment, creation, and removal can happen directly from the library dialog, while deeper editorial changes still live in the entry sidebar taxonomy card. ## Local Development * Use `bun dev:cms` to run the CMS app with the shared packages and `apps/web`. * Use `bun devx:cms` or `bun devrs:cms` when you also need a reset local Supabase environment. ## CI/CD * Preview deployments run through `.github/workflows/vercel-preview-cms.yaml`. * Production deployments run through `.github/workflows/vercel-production-cms.yaml`. * Both workflows are gated through `ci-check.yml` and the `tuturuuu.ts` workflow allowlist. * The Vercel project must be configured through the `VERCEL_CMS_PROJECT_ID` repository secret. # Contacts Source: https://docs.tuturuuu.com/platform/applications/contacts CRM users, groups, reports, attendance, workforce, and module access. Contacts (`contacts.tuturuuu.com`, `apps/contacts`) owns the workspace-user CRM surface. A CRM workspace user and a signed-in platform account are different entities; links between them are explicit. Central login, the Contacts app session, workspace membership, and feature/role checks govern access. ## Find the right area | Area | Workspace route | Purpose | | - | - | - | | Users | `/{wsId}/users` | CRM overview and user operations | | Database | `/{wsId}/users/database` | User records and details | | Groups | `/{wsId}/users/groups` | Group membership, calendars, schedules, and content | | Attendance | `/{wsId}/users/attendance` | Attendance workflows | | Reports | `/{wsId}/users/reports` | User/group reporting | | Guest leads | `/{wsId}/users/guest-leads` | Lead workflows | | Topic announcements | `/{wsId}/users/topic-announcements` | Contacts, templates, announcements, delivery, and import | | Workforce | `/{wsId}/workforce` | Workforce surface where available | Some areas depend on workspace modules. An unavailable module must distinguish access denial, disabled configuration, and loading/failure states; it should not pretend that all of these mean a missing record. See [Contacts module availability](/platform/applications/contacts-modules). ## Related workflows [User management](/platform/features/user-management) describes user and account boundaries. [Reports](/platform/applications/reports) and [Tutoring](/platform/applications/tutoring) explain the education/CRM flows. Group access does not grant a linked parent unrestricted editing rights. Outreach and topic announcements require their own delivery configuration and recipient rules. ## Ownership and privacy Contacts owns the users routes removed from Web. Shared domain/UI code lives in `packages/users-core` and `packages/users-ui`. Non-owned workspace destinations redirect to their canonical app rather than being implemented as catch-all API proxies. Workspace CRM records, reports, attendance, and outreach are private and receive noindex directives. The public product description belongs on the main site's CRM page. [Source routes](/reference/repository/routes/contacts) list all Contacts pages and handlers. [Permissions](/platform/architecture/workspaces-permissions) and [Satellite apps](/platform/architecture/satellite-apps) explain the shared access contract. # Contacts Module Availability Source: https://docs.tuturuuu.com/platform/applications/contacts-modules How Contacts modules are switched on per workspace, and what each non-404 gate state means. Several Contacts modules used to answer every non-happy path with `notFound()`. That hid the three situations an operator can actually act on, and it hid a plain bug: pages 404'd personal workspaces even though the sidebar links them and the underlying APIs normalize `personal` into a real workspace id. Those pages now resolve one of four states through `resolveWorkspaceFeatureAccess`. ## Gate states | State | Cause | What the page shows | | - | - | - | | Ready | Toggle on, caller may view | The module | | Disabled | Toggle off for this workspace | An explanation, plus an **Enable** button when the caller may flip it | | No access | Caller lacks the module's view permission | Which permission to ask for | | Unavailable | Workspace or `workspace_user_linked_users` profile unresolved | A retry | The order matters: an unresolved workspace is reported before a permission denial, and a permission denial before the toggle, so a member never learns a module's configuration from a page they cannot open. ## Modules and toggles | Module | Toggle | Stored in | Shared default | Personal default | Enable permission | | - | - | - | - | - | - | | Tutoring | `ENABLE_TUTORING` | `workspace_configs` | On | Off | `manage_workspace_settings` | | Feedbacks | `ENABLE_FEEDBACKS` | `workspace_configs` | On | Off | `manage_workspace_settings` | | Topic announcements | `ENABLE_TOPIC_ANNOUNCEMENTS` | `workspace_secrets` | Off | Off | `manage_workspace_secrets` | | Approvals | — | — | On | Unavailable | — | Shared workspaces keep whatever each module defaulted to before the gate existed, so no workspace loses a module. Personal workspaces start opted out and opt in from the page itself, which is what replaces the old hard 404. > [!NOTE] > > Approvals has no module toggle of its own: `ENABLE_POST_APPROVAL` and > `ENABLE_REPORT_APPROVAL` already govern approval behavior, and a third switch > would be ambiguous. Approvals also stays unavailable in personal workspaces by > product decision — it renders an explanation, not a 404. ## Writing a toggle from Contacts Config toggles go through the Contacts-owned route `PUT /api/v1/workspaces/{wsId}/settings/{configId}`, which is satellite-session aware. Reading a toggle needs only the module's view permission; writing needs `manage_workspace_settings`. Topic announcements is a **workspace secret**, not a config, and the platform secrets endpoint authenticates through the Supabase cookie — which resolves anonymous on a satellite domain, so every write from Contacts 401s there. `PUT /api/v1/workspaces/{wsId}/settings/feature-secrets/{secretName}` exists for exactly that case. It is deliberately not a general secrets endpoint: * only names in `CONTACTS_FEATURE_SECRET_NAMES` are addressable; * only the literal values `true` and `false` are accepted; * `manage_workspace_secrets` is required; * it never reads a secret back. > [!WARNING] > > `workspace_secrets` has no unique index on `(ws_id, name)`, and the platform > endpoint inserts without checking, so a workspace can hold duplicate rows for > one name. The feature-secret route updates every matching row before falling > back to an insert, which also repairs those duplicates. Do not switch it to an > upsert with a conflict target until that index exists. ## Creating group score indicators The indicator name is required before creation is enabled. Indicator and metric category dialogs keep their action footer inside the viewport and scroll the form body, including long category lists. Failed creation keeps the draft open and shows an inline error so the user can retry. Repeated taps during a pending save submit once. Creation still requires `create_user_groups_scores`; members with that permission use the same path as administrators. ## Topic announcement list and preview admission Contacts owns the collection GET and preview POST locally. Both resolve the verified Contacts app-session actor and workspace membership before reading topic content, then require `ENABLE_TOPIC_ANNOUNCEMENTS` to equal `true`, a non-personal workspace, and `manage_users`. The module remains off by default; listing or previewing does not enable it or send email. Preview uses only contacts in the requested workspace that are not archived. Web retains its Supabase-session admission. Both apps use the same users-core query, payload validation, recipient verification status, attachment filename normalization, and preview renderer. Contacts forwards collection mutations to Web after its existing session and API edge guards; other topic mutation routes and the delivery worker retain their current ownership. This read/preview repair does not establish satellite mutation or provider-delivery readiness. Regression coverage exercises the local Contacts routes with the actual workspace access helper, denied sessions and membership/capabilities, shared recipient serialization, and exact-method forwarding. Web route and renderer regressions preserve its existing behavior. These adapter-level checks require exact-app CI build and authenticated runtime verification before delivery is confirmed. Before dispatch preparation, the topic sender rechecks the current workspace `ENABLE_TOPIC_ANNOUNCEMENTS` secret. Missing or non-`true` values deny sending. Every linked recipient must still exist, belong to that workspace, and be active; a missing, archived, or moved recipient blocks the entire intended batch. It does not silently send to fewer recipients. Database read errors remain failures. This prerequisite does not change announcement history, statuses, or queue leases. Provider acceptance, durable receipt publication, and safe recovery from ambiguous processing remain separate delivery requirements. ### Inert topic delivery ledger The private delivery-attempt foundation reserves a parent revision and an immutable attempt snapshot. It has no service write API, no sender integration, and no historical backfill. Readiness explicitly reports `activationEnabled: false`. Existing announcement, recipient, attachment, queue, and feature-toggle behavior stays unchanged; the topic feature remains off by default. This foundation alone does not repair uncertain delivery or prevent replay by the existing queue. The `topic-delivery-foundation-contract.yaml` workflow applies the complete schema, runs strict pgTAP and real two-connection ownership/snapshot contention, and generates actual schema types for the exact commit. Local source checks are not SQL or provider-delivery proof. Browser roles cannot access the new private ledger, and its service role receives read access only. Activation requires a separate reviewed atomic caller conversion, current feature and actor-permission admission, and an accepted/rejected/unknown provider-outcome contract. No uncertain attempt may be treated as a safe automatic retry or discarded history. ### Attendance edits during saving Contacts and shared group attendance rosters keep edits made while a save is in flight. Success acknowledges only the submitted draft entries in their original workspace, group, date, and session. Later edits remain visible and available for an explicit subsequent save, including an edit back to the original text. Drafts stay pending until saved or explicitly reset; changing attendance scope starts a new draft. The submitted transport still includes the complete status and note. A rejected save reports the error, keeps the draft visible, and leaves retry to the user; it does not clear the draft or refresh it from stale server data. The deferred-save component regressions in `apps/contacts/src/__tests__/attendance-note-save.test.tsx` cover later edits, reverting text during a save, rejected saves and explicit retries, status-only changes, explicit empty notes and reloads, and older saves completing after workspace, group, date, or session navigation. This rule does not change explicit attendance clearing or post-check reset semantics, and does not recover historical notes. ## Class-post dialog updates Contacts class-post dialogs update only fields changed since that dialog opened. Saving a title or content edit leaves untouched class-post notes on the server, including notes saved by another editor. Explicit empty or null notes still clear the field. Creation sends the complete title, content and notes payload. Create fields are locked while submission is pending so later edits cannot create a duplicate post. Failed saves retain the draft. A completed save closes only its submitted draft; newer edits or a different workspace, group or post stay open. This protects local edits and untouched fields, but concurrent edits to the same field still use the server's last write. It does not apply to attendance or recipient check notes and does not recover previously lost content. Regression coverage: Contacts `use-posts.test.tsx` exercises the real dialog hooks and source API transport for stale snapshots, explicit clears, failed saves, newer edits, target changes and full creation payloads. ## Recipient remarks with completion changes On Contacts class-post recipient cards, Complete and Incomplete save the current remark together with the completion state when that card has local remark edits. An untouched remark is omitted so a stale card cannot overwrite a newer server remark. Explicit empty text clears the remark. The separate Save action remains available; typing alone does not save or create a navigation-safe draft. A successful request acknowledges only its submitted remark revision. Later edits, including a revert while saving, remain pending for the next action. Rejected saves retain the draft for an explicit retry. Each card writes only its recipient; existing approval and delivery behavior and explicit Reset remain unchanged. This rule does not recover previously lost remarks. Regression coverage: `recipient-note-completion.test.tsx` mounts real cards with source API serialization and persistent synthetic HTTP storage, then remounts from stored rows. It covers multiple recipients, completion and explicit Save, pristine concurrent server updates, later edits/reverts, rejected saves/retries and explicit clearing. The synthetic store does not certify deployed database triggers. # Drive Source: https://docs.tuturuuu.com/platform/applications/drive Standalone Drive app with centralized workspace storage APIs. ## Overview `apps/drive` is the canonical Tuturuuu Drive application. Production Drive traffic should use `https://drive.tuturuuu.com/{wsId}` instead of rendering the Drive explorer inside `apps/web`. * `apps/drive` owns the workspace shell, Drive explorer UI, local `/verify-token` handoff, and local app-session logout. * `apps/web /{wsId}/drive` remains a compatibility route. It checks `manage_drive`, preserves the query string, and redirects to the Drive app. * Drive uses local port `7817` and Portless host `drive.tuturuuu.localhost`. ## Native mobile directory behavior The mobile Drive screen uses the shared floating dock for search, view, sort, and permission-gated actions. Search temporarily occupies the shared search surface rather than adding a second search field to the directory body. Closing search clears its query and reloads the current directory. Directories retain their visible entries during refresh. Additional pages load when the viewport is within 400 logical pixels of the end, including directories that initially do not fill the viewport; the explicit load-more action remains available. Appended entries are deduplicated by name within the current directory. Workspace or account changes clear search, selection, and the previous directory. Late responses and signed-file actions cannot restore or open content from the previous account, workspace, or request generation. Definitive authorization failures clear displayed files; verification challenges and temporary failures retain the current view. This includes `MFA_REQUIRED` responses identified by the API error code even when the typed verification flag is absent; the challenge message remains visible, and a subsequent definitive denial still clears entries. Regression coverage: `apps/mobile/test/features/drive/drive_page_test.dart`. ## API Ownership Protected storage APIs remain centralized in `apps/web`: * `apps/drive` forwards `/api/*` traffic to `apps/web`. * Client Drive data flows must use `@tuturuuu/internal-api` helpers with TanStack Query. * Do not create direct Supabase browser reads or storage mutations in `apps/drive`. * `apps/web` storage routes authenticate normal web sessions and Drive app-session cookies through the shared storage route auth helper, then enforce `manage_drive` or the route-specific permission fallback. When adding new Drive behavior, add the protected route in `apps/web`, expose it from `packages/internal-api`, and consume it from `apps/drive`. ## CI/CD Preview and production deployments use dedicated Vercel workflows: * `.github/workflows/vercel-preview-drive.yaml` * `.github/workflows/vercel-production-drive.yaml` Both workflows are registered in `tuturuuu.ts` and use the shared `ci-check.yml` switchboard with affected-path gating. They require environment-scoped Vercel credentials: * preview environment: `vercel-preview-drive` * production environment: `vercel-production-drive` * project secret: `VERCEL_DRIVE_PROJECT_ID` * shared secrets: `VERCEL_TOKEN` and `VERCEL_ORG_ID` The app-specific project secret should live in those GitHub Environments, not in workflow-level `env`. ## Validation Use these focused checks when changing Drive deployment wiring: ```bash theme={null} node --test scripts/ci/check-workflow-config.test.js scripts/ci/release-workflows.test.js ``` Run focused checks locally without app builds. Require the applicable lint, type-check, test, and real app-build workflows to pass in CI for the exact commit; do not run `bun validate` or app builds on the shared machine. # Finance Source: https://docs.tuturuuu.com/platform/applications/finance Shared Finance product surface across apps/web and apps/finance. ## Overview `apps/finance` and the Finance experience inside `apps/web` are paired Finance hosts. They must stay 1:1 for product features, data behavior, mutations, permissions, route behavior, and user-facing workflow updates. Canonical workspace routes include: * `/{wsId}` * `/{wsId}/transactions` * `/{wsId}/wallets` * `/{wsId}/invoices` * `/{wsId}/categories` * `/{wsId}/tags` * `/{wsId}/recurring` * `/{wsId}/budgets` * `/{wsId}/analytics` * `/{wsId}/debts` `apps/web /{wsId}/finance/*` routes render the same shared Finance product surface inside the normal platform dashboard shell. `apps/finance` keeps the shorter standalone route shape without the `/finance` segment. Use route prefixes instead of forks: * `apps/web`: `financePrefix="/finance"` and `FinanceRouteProvider prefix="/finance"`. * `apps/finance`: `financePrefix=""` and `FinanceRouteProvider prefix=""`. Legacy nested category paths, such as `/{wsId}/finance/transactions/categories`, should redirect inside `apps/web` to `/{wsId}/finance/categories` while preserving query strings. ## API Ownership Native Finance checkpoint creation, editing and batch creation serialize the selected instant in UTC, including its timezone, so server parsing cannot shift the user's local time. Batch checkpoint responses retain their authoritative rows; `/wallets/checkpoints` is a collection operation, not a wallet detail mutation in the Inventory dependency scheduler. Ordinary wallet writes keep their existing durable behavior. Mobile error handling accepts both issue arrays and flattened validation objects from the shared Finance handlers. Validation and permission failures retain their HTTP status and readable message rather than becoming Dart type errors. These rules apply to the native client without changing server permissions or web behavior. Regression evidence is in `finance_http_contract_test.dart`, `api_client_error_contract_test.dart` and `offline_inventory_mutation_test.dart`. * `apps/finance` owns the standalone workspace shell, Finance UI route wrappers, local `/verify-token` handoff, host-local auth/session routes, and build-info. * `apps/web` owns platform-shell Finance route wrappers under `/{wsId}/finance/*`. * `apps/finance` owns the hard-cutover product handlers for transactions and categories, wallets and checkpoints, budgets, debts, recurring transactions, invoices, charts and overview reporting, and Inventory reconciliation. It also has local supporting handlers for promotions, inventory products, settings, linked products/promotions, and workspace/user lookup needs. * The local recurring, invoice, and wallet examples include `/api/v1/workspaces/:wsId/finance/recurring-transactions`, `/api/v1/workspaces/:wsId/finance/invoices`, and `/api/workspaces/:wsId/wallets`. Exact local handlers win before the `/api/:path*` fallback rewrite is considered. * Deliberately central exceptions remain in `apps/web`: the legacy `/api/v1/workspaces/:wsId/wallets` list/create route, wallet-role whitelist routes, shared workspace storage routes used by transaction attachments, and the Finance exchange-rate cron. Unmatched requests reach Web through the fallback rewrite. * Keep shared callers on `@tuturuuu/internal-api`. Finance-owned helpers use the Finance API base URL for server calls, while helpers for the deliberate Web exceptions remain on the central API origin; browser calls stay same-origin. * Finance-local protected handlers accept the Finance app-session actor and enforce route-level workspace and product permissions. Forwarded Web exceptions require the coordinated Web-issued session and retain their own authorization checks. * Finance transaction attachment reads must authorize through the same authenticated transaction visibility path as normal transaction reads. Do not grant storage list, metadata, or signed-read URL access from coarse `view_transactions` or `update_transactions` permissions alone; reuse `get_wallet_transactions_with_permissions` with `p_transaction_ids` so wallet whitelists, viewing windows, and granular income/expense permissions stay aligned. * Finance transaction attachment uploads have server-side limits: 10 files per transaction and 50 MB per file. The signed-upload route must reject over-limit declared sizes before issuing a URL, and finalize must inspect the actual stored object size/count and delete over-limit uploads before any follow-up processing. * Finance transaction type filters must not classify confidential amount signs for callers without `view_confidential_amount`. RPCs that accept `p_transaction_type` should apply income/expense predicates only when the row is non-confidential or the caller can view confidential amounts; otherwise typed filters should omit those redacted rows instead of using the raw amount sign. * Finance invoice customer IDs must be validated against `workspace_users` with the route workspace before insert, and admin-backed invoice reads should resolve customer display fields with an explicit `ws_id` filter instead of a nested service-role join on `customer_id`. When adding new Finance behavior, update the shared Finance UI/helper first, then wire both host wrappers in the same change. Add or extend the route in `apps/finance` when it belongs to a hard-cutover family; preserve the explicit Web exceptions until their dependent platform callers migrate. Expose shared access in `packages/internal-api` and consume it through TanStack Query or shared server components. ## Wallet checkpoint reconciliation submission The shared Finance checkpoint adjustment dialog submits the category and annotation visible when the user presses Reconcile. The configured reconciliation category is selected after its options load; choosing no category still submits no category. Edits made while an already-started request is being scheduled must not change that request's payload or workspace, wallet and checkpoint identity. Completion invalidates the submitted target; a dialog that has moved to another target is not closed by the old request. The server continues to recompute the adjustment amount from the checkpoint rather than trusting a client preview. This applies to shared Web and satellite Finance dialogs. Regression: `wallet-checkpoints.test.tsx` covers configured defaults, explicit clearing, a subsequent edit before mutation execution, and retargeting before completion. ## Inventory sales reconciliation Finance owns the Inventory reconciliation inbox and its protected API under `/api/workspaces/:wsId/finance/inventory-reconciliation`. Access to pending entries, provider mappings, provider history synchronization, manual adjustments, and bulk link/unlink actions requires `manage_finance`. Every provider-confirmed Polar, Square POS, or Square Terminal event is first stored as an immutable `private.inventory_finance_entries` source row. The source row affects balances only after an atomic database RPC links it to a currency-compatible wallet transaction. Missing wallets stay pending and are never included in income, wallet, or net-total calculations. Provider-and-currency mappings take precedence over the Inventory revenue wallet fallback and the Finance default wallet. A wallet must use the entry currency. Category resolution uses the unanimous product category first, then the provider mapping, the Inventory default, and finally uncategorized. Deleting or explicitly unlinking a provider transaction removes only the ledger row and returns the immutable source entry to pending. Provider, reference, signed amount, and occurrence date remain provider-controlled; wallet, category, tags, description, and confidentiality remain editable. For rollout and recovery: 1. Deploy the database migration before Inventory, Finance, or shared-package consumers. 2. Verify historical completed provider sales appear in the pending inbox. The migration never auto-posts unmatched historical sales. 3. Configure provider and currency mappings, inspect pending counts by currency, and only then use bulk linking. 4. Run the bounded provider-history sync explicitly to discover historical refunds and Square disputes. 5. If a ledger row was deleted accidentally, relink the still-present source entry. Do not recreate provider events manually. 6. Use audited manual adjustments only when the provider has no supported event, such as a Polar chargeback. ## Invoice history and recovery The invoice **Audit trail** tab requires both `view_invoices` and `manage_workspace_audit_logs`. It reads `audit.record_version` through a workspace-scoped, service-only RPC. The old `audit_logs` view filters out some DELETE events because it checks workspace membership using the new record. Do not use that view as evidence that a deleted invoice has no history. The Finance handlers require `20260916130000_invoice_recovery_and_history.sql`. After authorized production sync, the **Supabase Production Migration** workflow applies pending migrations once its same-commit staging and production deployment prerequisites pass. Verify that workflow actually applied the migration and then check the Finance audit route; a successful skipped job is not schema evidence. Until the RPC exists, deletion fails closed with 503 and never falls back to permanent deletion. Update/history/restore also depend on this migration. Deletions through the Finance invoice endpoint atomically preserve the invoice, its products, promotions, group links, payment transactions, and transaction tags in `private.finance_invoice_recovery`. Existing inventory and wallet triggers still run. The legacy automatic payment-creation trigger is skipped only inside the privileged restore transaction, so recovery cannot mint a second payment. Restore reuses original IDs and timestamps, restores the payment link, and runs in one transaction. Repeated requests cannot duplicate the payment. Restore requires `view_invoices`, `create_invoices`, and `delete_invoices`. Transactions linked to unrelated records block deletion and require review. An invalid or conflicting reference blocks the entire restore. Historical deletions do not automatically have a recovery snapshot. To investigate an older incident, use a read-only query against `audit.record_version`, filtering `table_name = 'finance_invoices'`, `op = 'DELETE'`, the workspace in `old_record->>'ws_id'`, and a bounded UTC time window. Inspect deleted line items and payment audit entries separately. Promotions and group links may not have been audited historically. Compare backups and related records before proposing a restore; a header alone is not a complete invoice. Do not recreate payments without proving the original payment is absent, and do not fabricate missing line items or discounts. Run focused database coverage with: ```sh theme={null} ttr resources run -- node apps/database/scripts/run-supabase-isolated.js \ --test supabase/tests/invoice-recovery.sql \ --typegen packages/types/src/supabase.ts ``` The isolated runner copies Git-tracked files, so register a new migration/test with `git add --intent-to-add` under the normal commit window before running it. The audit trail opens with currently deleted invoices highlighted for administrator review, including customer, amount, currency, deletion time, and recovery readiness. Older deletions without a verified snapshot are labeled as needing recovery review; opening the audit trail never restores records automatically. The full audit feed includes invoice details, line items, saved discounts, group links, and related payment records. Filter by record type, action, date range, or customer/invoice/actor search, and sort newest or oldest first. Before/after values are available for meaningful changed fields; Finance confidential mode masks amounts in the audit UI too. Promotion tracking begins with this migration; missing historical events and actor identities cannot be reconstructed by the UI. For a disputed tuition month, compare the completed invoice's customer, linked user group, `subscription_months`, issue date, and payment record. A receipt for the same student in another class does not settle a debt in the disputed class. Only treat it as a cross-class credit when an explicit adjustment or transfer record identifies the source invoice, destination class, covered months, and actor. Preserve those IDs in the case record. A missing audit event, especially while the audit feed is unavailable, cannot prove that no transfer happened. ### Audit history performance Invoice audit history loads bounded pages of 10, 25, or 50 events. The API fetches one additional event to determine whether a next page exists, without counting the entire audit log. Search, record type, action, date range, and time ordering are applied on the server. Dates and timestamps use the browser timezone shown above the results. Changing page size or filters starts at the first page; sorting and date changes preserve the deleted-invoice review mode. The history RPC reads matching audit events directly instead of materializing every invoice's complete history. Partial indexes support workspace/time reads, deletions, child events, and legacy payment links. Both audit-log and invoice-view permissions remain required. Deploy the additive performance migration through the normal automatic database workflow; existing RPC callers remain compatible. Each supporting index has its own single-statement concurrent migration so audit writes remain available during index construction. Keep those index files separate from the RPC replacement and do not add transaction wrappers. ## Notification refresh diagnostics The shared notification hook refreshes active notification API queries every 120 seconds while the browser tab is visible and immediately when the tab becomes visible again. Consumers for the same user share one timer. Closed inbox queries remain lazy, and existing mutations invalidate the cache immediately. Offline tabs pause periodic invalidation and refresh immediately on reconnect. This is the default across Next.js satellites and the central web notification surfaces; satellites without the shared subscription use the same two-minute query polling interval. Foreground notifications may therefore take up to two minutes to appear without a mutation or resume event. Colab explicitly selects a 30-second interval through the shared popover, and Mail inbox/snooze timers are unchanged. Regression coverage in `use-notifications-subscription.test.tsx` verifies 30 refreshes per visible hour, shared consumers, hidden/offline pauses, reconnect, actor teardown and lazy closed inboxes. `satellite-notification-polling.test.tsx` verifies the two-minute default and explicit Colab interval override. Do not subscribe directly to `public.notifications` with browser `postgres_changes` filters. Production notifications are server-owned; the `authenticated` role has no column SELECT privileges or client RLS policies. Realtime reports `P0001: invalid column for filter user_id` in that state even though the column exists. Check column privileges and policies before changing the schema; the authenticated notification APIs remain the access boundary. ## Category charts and promotions Category breakdown charts keep the plotting area separate from the legend. By default they show the seven largest categories and combine the remaining amounts under Other categories. Show all categories restores the complete list; legend buttons toggle individual series. Category IDs, rather than names, identify series so repeated names cannot overwrite each other. Finance owns the `/[wsId]/promotions` management page. The sidebar and page allow members with `view_inventory` or `create_invoices`; mutations require the matching inventory create, update, or delete permission. Finance forwards promotion mutations to Inventory using the authenticated session, retaining one owner for validation and commerce synchronization. Configure `INVENTORY_APP_URL` for a registered Inventory origin. Unregistered destinations and non-loopback HTTP origins are rejected before credentials are forwarded; requests also have a 10-second deadline and inherit caller cancellation. The list is paginated and shared invoice promotion queries are invalidated after mutations. ## Audit actor attribution Finance resolves the authenticated app, CLI, or Supabase session before creating an isolated admin client with a trusted audit actor header. The database accepts that header only for service-role requests. Direct user requests keep their own JWT actor, and the explicit actor in atomic update/delete/restore RPCs takes precedence. This also attributes linked payment, line-item and discount writes made through the Finance route context. Create, update and delete events remain in the audit feed; reads are not logged. An event with an actor ID but no display name shows the recorded user ID. Events written before actor propagation, or by actorless maintenance processes, may have no actor. Do not infer an update/delete actor from the invoice creator or rewrite historical audit records to fill that gap. ## Subscription coverage and tuition reporting ### Subscription session counting Across workspaces, the Finance subscription invoice form uses the workspace's `INVOICE_USE_ATTENDANCE_BASED_CALCULATION` setting, including invoices opened from a customer or pending-invoice link. Its default is on: completed months and the current month bill present or late attendance, while future prepaid months use planned sessions. When the setting is off, every planned session in the coverage months is billable, regardless of the student's attendance. Completed paid months remain visible in the preview but cannot be billed again. The planned session count includes scheduled records and the group's recurring occurrences in the selected coverage period, even when those future occurrences have not been materialized in `workspace_user_group_sessions`. Canceled occurrences are excluded. The invoice preview reads these dates without reconciling or writing session records. The same session dates feed the total, calendar, notes, and linked tuition product quantity in Finance; Contacts group schedule is the operator view for checking the underlying recurrence. A customer and group supplied in an invoice URL remain selected when the page first loads. When a linked product is absent or has no matching inventory unit, the operator must configure or select a product before creating an invoice; the preview must never invent a tuition price. In the subscription invoice calendar, each group’s day color and tooltip show its worst attendance status: Absent takes priority over Late, then Present, regardless of the order of records. This display rule is shared by Finance and the platform Finance surface; it does not change billable attendance, quantities, or dates. For a reported `Days Attended > 0` with `Total Sessions = 0`, inspect the authenticated subscription context response's `scheduledSessionsByGroupId`, the selected group's recurring series and canceled exceptions, and the effective workspace billing setting. If the Finance settings panel cannot read that setting, it reports a load error instead of showing a guessed default. Verify a real customer and group in Finance and the same group schedule in Contacts without creating an invoice or changing customer attendance. Use a controlled workspace for any save or toggle test. New subscription invoices persist their paid tuition months in `finance_invoices.subscription_months`. This nullable array is the canonical coverage record: only its listed months are covered. A payment for March does not settle an unpaid February. The database validates one to twelve distinct month-start dates and derives `valid_until` from the latest covered month for compatibility with older readers. Invoices whose month array is null retain the legacy `valid_until` cutoff. Historical start dates cannot be recovered reliably from the cutoff alone, so there is no automatic backfill. Any future historical repair must use verified invoice records. Invoice recovery snapshots preserve the explicit month array. Apply migration `20260923040000_subscription_invoice_coverage_months.sql` before releasing the updated Finance API. Local verification uses `supabase/tests/subscription-coverage.sql`; the gated staging and production migration workflows apply schema changes after their exact-commit prerequisites pass. Generate database types from the migrated local schema. Do not deploy API code that writes the new column before the migration. The invoice analytics Tuition coverage tab groups completed positive payments by their recorded tuition months, independent of when payment was received. Payment value is allocated equally across those months. User, group and user–group pair totals are distinct across the full selected period, not sums of monthly counts. The yearly view covers five years ending in the selected year. Each wallet currency has its own report; no currency conversion occurs. User and wallet filters apply, while coverage year controls replace the invoice list's payment-date filters. Old invoices with a coverage cutoff in the selected period but no exact months are counted as unallocated and excluded from totals. This is allocated payment reporting, not a ledger revenue-recognition report. Analytics requires `view_invoices` and reads invoices and wallet currencies in the authorized workspace. It rejects truncated, duplicated or changing-count pages rather than presenting partial totals. Reports are limited to 100,000 invoices. The existing Rust subscription-context port mirrors the exact-month response, workspace scope and pagination rules; it remains a future migration target, not the production runtime. Subscription context also reads every coverage and attendance page, with a 50,000-row limit. A failed context read must be retried before calculating new charges. Unpaid-invoice spreadsheet exports verify page lengths, stable totals and unique student/class identities before producing a file. A failed completeness check shows an error and produces no partial download. This catches incomplete reads; it cannot reconstruct a historical omission without the original export or its date and filters. Pending eligibility still depends on configured group exclusions, class schedules and attendance calculation settings. Pending tuition begins no earlier than the student's recorded class membership date or the class start date, whichever is later. A class's earlier scheduled sessions and attendance are never assigned to a student who joined later, including earlier days in the joining month. Membership dates are read in the workspace's Ho Chi Minh time zone. Contacts group member cards show the current membership's join date. Adding, removing, and re-adding a member creates separate membership events in the existing group audit feed; the active membership timestamp is stable when a member's role is changed. Analytics can use that event history for joins and departures without treating a newly added membership as if it existed when the class started. Legacy null timestamps and activity before audit tracking began are unknown, not inferred from a receipt or the person's name. For a null join timestamp, automated scheduled-session billing starts no earlier than today; staff must reconcile earlier months from source records. Existing completed invoices cover only their recorded tuition months (or the legacy coverage cutoff); a September receipt does not by itself settle July or August if the student was already enrolled in those months. Correct historical membership dates and payments at their source rather than hiding disputed rows by name. The pending tab badge, table pagination and CSV/Excel export all count the same all-month, student-class rows, including older unpaid months. This behavior applies to the shared Finance UI in web and Finance; grouped-by-student mode instead counts one row per student in each surface. The join-date eligibility rule ships in `20260929090000_pending_tuition_respect_student_join_date.sql`. The production database migration workflow must finish successfully for the corrected debt rows to appear; a deployed UI and a green application build do not prove the database function changed. Check the migration marker and a read-only customer row after sync. Never manually push the migration from an agent checkout. ### Exchange-rate session boundary Exchange rates are authenticated global reference data. Web Supabase sessions and verified internal app sessions, including Finance, use the same API. A Finance app session does not require a separate Supabase login. Invalid or expired app sessions and anonymous callers are rejected before any database read; existing session suspension and abuse controls remain active. Both verified Supabase JWT users and app-session actors pass the same Rust active-suspension check before currency reads. Lifted and expired suspensions do not block reads; the policy lookup retains the shared live policy’s fail-open behavior on policy-store outages. Supabase JWT currency reads retain the caller token; only verified app sessions use the server read credential. Currency query failures return 500 and never masquerade as missing rates or trigger seeding; initial seeding runs only after a successful empty lookup. Successful rates are private and not stored in a shared HTTP cache. The client-side exchange-rate hook uses the internal API client. The existing wallet-details server component continues to read rates directly through its server-only admin client. Regression coverage: `apps/web/src/app/api/v1/exchange-rates/route.test.ts` exercises the real session middleware with injected authentication dependencies; `packages/internal-api/src/finance-exchange-rates.test.ts` covers transport and error propagation. Rust source parity is covered by `apps/backend/src/tests/exchange_rates_session.rs`; Rust does not serve production. ## Profile Timeline creation boundary Native Profile Timeline requests pin `until` when loading the first activity page. The Finance activity RPC applies the optional `p_created_at_until` constraint to transaction creation time **before** limit, offset, or total-count calculation. `created_at` ordering uses transaction ID as the unique tie-breaker. Newer transactions therefore cannot shift the next page of the pinned traversal. This is an upper creation boundary, not a historical snapshot: edits, deletions, and explicitly backdated creation timestamps can still change visible records. This rule applies to the Web-owned mobile activity API and shared Finance RPC. Existing Finance list, export, attachment, and Rust migration callers omit the new parameter and retain their unbounded default; `p_start_date` and `p_end_date` continue filtering the transaction's business date (`taken_at`). Actor checks, wallet viewing windows, granular permissions, and confidential field redaction remain unchanged. Calendar permission verification runs alongside other activity sources, but Calendar metadata is read only after permission succeeds; denied access is omitted, and permission failures remain partial errors. Regression evidence lives in the mobile activity route tests and `apps/database/supabase/tests/mobile-activity-transaction-boundary.sql`. The latter covers unique ordering, insertion between pages, the optional default, and actor visibility. Schema application, pgTAP execution, and generated Supabase types require the exact-commit CI migration/typegen gate; source inspection and route unit tests do not prove that a deployed RPC accepts the new parameter. ### Subscription invoice schedule and inventory admission Subscription invoice previews in the shared web and Finance UI use the subscription context's schedule as authority only for the selected civil month and prepaid range. A returned empty group schedule means no scheduled charges in that range; removed or cancelled dates from the older group-session list do not become extra charges. Dates outside the fetched range remain unchanged. Missing, loading, failed, or malformed context is not an authoritative empty schedule and blocks creation until billing data is available. Completed invoice coverage, attendance rules, recurrence cancellation and stored history retain their existing behavior. A selected class link with a missing product, missing billing unit or unit that is absent from the current product inventory blocks the entire invoice with a review instruction. The UI does not silently drop that charge or select another unit. Existing valid warehouse fallback and finite-stock quantity rules remain. The create action and its handler both enforce these admissions. Regression coverage lives in `subscription-billing-groups.test.ts`, `subscription-admission.test.ts`, `use-subscription-auto-selection.test.tsx` and the actual `subscription-invoice.test.tsx` form. These source checks do not prove a customer's create/open/export incident or production storage behavior. Invoice browser preferences are optional: a blocked storage getter or read uses the existing default values and completes initialization, so opening an invoice and reaching print/image export does not depend on persistent storage. Valid saved preferences and in-memory updates remain supported. Regression coverage uses the real shared hook and InvoiceCard with synthetic storage denial; this reproducible restriction failure is not proof of the original customer crash, browser export completion, or deployed behavior. Invoice schedule previews use the workspace billing timezone for both projected recurring classes and materialized sessions. A class keeps the same invoice civil day and month when materialized, including midnight and daylight-saving boundaries; multiple classes on one billing day remain one date. Recurrence identity and cancellation use the original series timezone, and previewing never writes schedules. `planned-session-dates.test.ts` covers projected/materialized parity and cancellation controls. This source regression does not establish the cause of a customer screenshot or deployed invoice behavior. ### Subscription group choices survive clearing and refetching The Finance subscription invoice form and its shared Web surface default an untouched customer selection to groups with schedules. Explicit URL group selections remain selected. Once an operator changes the group selection, including clearing the last group or using **Deselect all**, that choice remains authoritative for the current workspace and customer. Context or membership refetches must not select all groups again. Changing workspace or customer resets this preference so the new untouched selection can receive its own defaults. This lets an operator pay class A, clear it, and select class B for a separate invoice in the same month. Completed coverage still applies per group, and selecting both billable classes together remains supported. Group status badges do not disable selection. Selecting a class alone with no linked products produces no automatic charges on a fresh form; operators must configure or manually select the appropriate billing items. Inventory and invoice-creation admission rules still apply. `subscription-group-selection.test.tsx` exercises the actual form, selector, membership/product/context query transformations and create transport with synthetic HTTP responses, including shared and distinct products, missing links, separate payments and combined selection. `use-subscription-group-selection.test.tsx` covers refetches and workspace/customer resets. These regressions establish the selection behavior; they do not establish the cause of a specific customer's reported incident or verify production financial writes. ### Invoice create completion belongs to the admitted draft Subscription invoice creation captures the current account lifetime, workspace, customer, draft revision, payload, and create/print/download options. Leaving and returning to an account, workspace, or customer permanently expires an earlier completion. Editing the same customer’s draft also prevents the previous response from resetting that newer draft, navigating, announcing a result, or invalidating its queries. An expired response does not undo an already admitted server write. A new scope can create while an old request is pending; the old request cannot clear the new pending indicator. Current-draft success and errors retain their existing behavior, and multiple-create mode resets only its own unchanged draft. The mounted `subscription-create-scope.test.tsx` regressions exercise real account lifetimes, held responses, newer drafts, resets, and duplicate submission. This source regression does not establish the cause of the original customer complaint or verify authenticated invoice creation in production. ### Complete schedule reads for subscription preview Subscription previews retain the workspace/group and requested instant-period filters and never reconcile or write schedules. Materialized dates and recurring occurrence suppression use complete reads rather than treating a capped first page as authority: cancelled tail occurrences must not reappear as projected classes. These reads use UUID keyset order, 500-row pages, exact counts and a maximum of 10,000 rows/20 pages per query. Missing or changing counts, early short pages, invalid/repeated/non-advancing IDs, database errors or an exceeded budget fail the preview with a fixed error. The existing invoice-context failure and checkout blocking paths handle that failure; they never receive a partial successful date map. A deployed row cap below 500 also fails closed. Larger datasets need a separately reviewed bounded query strategy rather than unlimited pagination. This is statement-level validation, not a transaction snapshot. Concurrent writes can make a read fail; count checks do not prove every same-count mutation was observed. The composed regressions in `planned-session-paging.test.ts` model PostgREST filters, ordering, inclusive ranges and caps, including cancelled tail instances, tied starts, tenant/date scope, late errors and budget failures. They are source evidence, not the original customer's deployed incident or a billing write. Invoice quantities, stock, historical coverage and schedule policy are unchanged. ### Subscription context cache follows the verified account lifetime The shared subscription invoice context query uses its workspace, customer, selected groups and period together with the verified account and permanent account lifetime. Changing accounts or leaving and returning to the same account requires a new authorized context read. A pending response from an expired account lifetime cannot publish successful data for the new account lifetime. Without the verified account provider, the query does not admit requests. Fresh context is still reusable within the same account lifetime, and workspace invoice invalidation still refreshes it. Existing five-minute freshness and ten-minute garbage collection bounds remain. This rule covers this context query; other Finance caches are outside this change. The real hook, actor provider, API adapter/client and synthetic transport regressions in `subscription-context-actor.test.tsx` cover account switches, held success/error responses, account return, cache reuse, missing actor admission and invalidation. These tests do not prove the cause of the original customer incident or deployed customer invoice behavior. ### Invoice customer group reads follow the verified account lifetime The shared `useUserGroups` query follows the same permanent account lifetime as subscription invoice context, using a shared lifetime-key helper. Group data for one account cannot become a fresh cache hit or an admitted pending result for a replacement account, including departure and return to the original account. Missing-account automatic and manual reads do not dispatch requests. Current account errors remain visible to the query consumer and permit explicit retry. Existing group mapping, workspace/customer key positions, five-minute freshness, ten-minute garbage collection, request timeout and retry policy remain unchanged. Workspace-prefixed group invalidation still works; invoice mutation invalidation continues to exclude groups. Other Finance caches are outside this change. `user-groups-actor.test.tsx` exercises real actor lifetimes, the actual hook and API adapter/client, held synthetic responses, current error recovery and both queries sharing a lifetime token. These source regressions do not verify the original customer incident or authenticated deployed invoice behavior. ### Invoice customer search retains placeholders only within its scope Customer-list and selected-customer reads in the shared invoice form follow the verified account and permanent account lifetime. Replacement accounts, including departure and return to the same account, require new reads; expired list, detail or page callbacks cannot dispatch or publish for a new account lifetime. Without the verified account provider, automatic, manual and paged reads fail closed. Previous list rows remain useful while changing search text within the same account lifetime and workspace. They are not placeholders in another workspace or account, and cannot suppress the new scope's selected-customer lookup. Current errors and explicit recovery retain their existing behavior. Normalized search, 25-row inclusive paging, count-based continuation, selected-detail fallback, 30-second freshness and five-minute garbage collection remain unchanged. The real provider, query, API adapter/client and synthetic transport cases in `customer-search-scope.test.tsx` cover replacements, account return, held success and errors, workspace placeholders, old page callbacks, missing actor admission and recovery. Existing customer-search tests retain their behavior assertions. This is source regression evidence, not verification of the original customer incident or a production invoice mutation. ### Invoice history follows the verified account lifetime The active paginated invoice-history query follows the verified account and permanent account lifetime as well as workspace and customer. Replacement accounts, including departure and return to the same account, require a new authorized read. Expired responses and retained page callbacks cannot publish history or dispatch requests after their account lifetime ends. Missing-account automatic, manual and paged reads fail closed. The default ten-row page size, count-based continuation, inherited query-provider freshness, garbage collection and retry policy remain unchanged. Workspace invoice mutation invalidation still refreshes active history. Current transport errors remain available on the query and explicit retry remains usable; this change does not add an error presentation to the history accordion or alter other queries. `invoice-history-actor.test.tsx` uses the real mounted accordion, actor provider, hook, API adapter/client and synthetic transport to cover replacement, account return, held success/error responses, missing account, old page callbacks, cache reuse, pagination, invalidation and current-error recovery. This is source regression evidence, not proof of the original customer incident or deployed invoice behavior. ### Invoice history failures require explicit recovery The shared invoice-history accordion distinguishes failed reads from successful empty history. English and Vietnamese surfaces show a fixed accessible failure notice and Retry action without exposing transport diagnostics. Initial failure recovery rereads history; later-page recovery retries the failed page while retaining loaded rows. Pending recovery disables duplicate actions. Automatic scroll loading and queued disconnected observer callbacks do not retry failures. The query's account-lifetime admission, provider retry policy, pagination and workspace invalidation remain unchanged. This behavior covers the mounted history accordion, not other Finance queries or server authorization. Real mounted regressions in `invoice-history-error.test.tsx` cover initial 403/503 failures, genuine empty success, pending recovery, retained rows, page continuation and queued observer callbacks in both languages. These source tests do not establish the original customer incident or authenticated production behavior. ### Invoice history keeps rows with an unrenderable timestamp The shared invoice-history accordion parses each nonempty creation timestamp once and checks for a finite JavaScript date before formatting it. A timestamp that cannot be displayed uses the existing localized No date label instead of causing a render exception. Valid dates retain their existing locale formatting; missing dates, customer links, query admission, filters and invoice accounting are unchanged. This display fallback does not repair or rewrite stored dates. The real mounted EN/VI cases in `invoice-history-date.test.tsx` reproduce render exceptions for synthetic malformed and infinite timestamps and cover valid, null, missing and empty controls. These are rendering-boundary regressions, not proof of a malformed production row or the cause of the original customer complaint. ### Invoice PNG export lifetime PNG export belongs to the admitted signed-in actor lifetime, verified invoice workspace, and current printable card. Replacing the actor, workspace, invoice, or any rendered invoice input invalidates a pending capture permanently, including leaving and returning to the same actor. Render inputs include confidential amount visibility, language, currency, invoice content, products, promotions, configuration, and compact/dark preview choices. Unchanged semantic rerenders remain exportable. Stale renderer/import/blob completions cannot download, notify, clear a newer export's pending state, or consume a newer automatic-image URL intent. Missing actor or workspace admission fails closed. The existing print path is unchanged. `invoice-png-lifetime.test.tsx` exercises actual card/templates/provider lifetime with synthetic held renderer boundaries; this is bounded source evidence, not proof of the original customer incident or a live customer export. A renderer rejection or a null PNG blob reports the existing export error without a download, then releases the current attempt so staff can retry the same invoice. While that retry is pending, repeated clicks cannot start another capture. A successful retry downloads once and releases its temporary object URL. The same-card retry cases in `invoice-png-lifetime.test.tsx` cover both failures with synthetic renderer boundaries. They do not establish browser canvas behavior or customer runtime recovery; those require a disposable authenticated workspace. ### Invoice template dates Full and compact invoice cards omit a date that cannot be rendered as a finite JavaScript date, following the existing missing-date omission. Valid dates retain the same English/Vietnamese locale formatting and preview, print, and PNG surfaces. This is a rendering boundary only: invoice timestamps, accounting, recurrence, and API date authority are unchanged. The original customer's crash cause and presence of malformed customer timestamps remain unproven. `invoice-card-date.test.tsx` covers actual card/template transitions in both locales and preview modes, malformed date boundaries, missing dates, and valid formatting. Source checks do not establish a live customer export or deployment. # Forms Source: https://docs.tuturuuu.com/platform/applications/forms Create forms, publish share links, embed them, and review responses and analytics. Forms (`forms.tuturuuu.com`, `apps/forms`) owns the complete form product: builder, studio, respondent experience, responses, analytics, and its form APIs. Web redirects legacy form destinations to this app. ## Create, review, and share 1. Open `/{wsId}/forms` in an authorized workspace. 2. Create a form at `/{wsId}/forms/new`, then edit its structure and content in `/{wsId}/forms/{formId}`. 3. Configure questions, validation, layout, access, and sharing. Preview the respondent flow before sending the link. 4. Share `/f/{shareCode}` or use the embed tools. A protected form can still require login; possession of a URL is not a universal access grant. 5. Review responses and analytics in the private studio. The current question catalog includes text and typed inputs, choices, rating and scales, NPS, ranking, and presentation blocks. The precise question types, validation behavior, response formatting, and analytics rules are in [Forms: question types, embedding, SEO, and collaboration](/platform/features/forms-embedding-and-seo). Use [Studio layouts](/platform/features/forms-studio-layouts) for layout and editing behavior. ## Embedding and search The SDK is delivered at `/embed.js`; the embedded route is `/embed/{shareCode}`. Embed wrappers are noindex and distinct from the canonical respondent page. The author's SEO controls can override title, description, social image, canonical, keywords, and noindex on a shared form. Public shared forms retain this existing opt-out behavior; protected or unavailable forms keep their access-aware metadata. Private studio and response data stay noindex. Forms are not enumerated into a public sitemap from workspace records. ## Collaboration and data Studio presence/broadcast uses private form channels. Forms tables live in the private database schema and are accessed through authorized server logic. Respondent state, submissions, protected content, and studio access must stay separate. Reopening a shared form can restore the signed-in respondent's own state; this does not expose another respondent's answers. [Forms route reference](/reference/repository/routes/forms), [Search indexing](/platform/features/search-indexing), and [Forms feature details](/platform/features/forms-embedding-and-seo) provide the implementation and behavior contracts. # Git Source: https://docs.tuturuuu.com/platform/applications/git Fast, read-only GitHub repository browsing through the Tuturuuu Git satellite. Git is the public repository browser at `https://git.tuturuuu.com`. It renders repository metadata, source trees, files, commits, issues, pull requests, Actions, releases, refs, and contributors with a server-first Next.js App Router satellite. The initial registry always includes `tutur3u/platform`. ## URL model Public repositories use short, GitHub-compatible paths: * `/{owner}/{repository}` for the overview * `/{owner}/{repository}/tree/{ref}/{path}` and `/blob/{ref}/{path}` * `/{owner}/{repository}/commits`, `/commit/{sha}`, `/issues`, `/pulls`, `/actions`, `/releases`, `/contributors`, `/branches`, and `/tags` The reserved `/-/internal` area uses the shared Tuturuuu satellite shell and app-session authentication. There is no dashboard catch-all route, so `/api/*` fallback rewrites remain safe. ## Repository registry Only explicitly registered public repositories are displayed. Adding, disabling, or refreshing a repository requires the root-workspace `manage_git_repositories` permission. The server verifies that a repository is public and belongs to the configured GitHub App installation before saving it. Private repositories are rejected by both application checks and the database constraint. Registry and credential rows live in the Supabase `private` schema and are accessible only through the service-role client. ## GitHub App Use a dedicated organization-owned GitHub App named `Tuturuuu Git`. Do not extend the existing deployment app. Configure: * Homepage URL: `https://git.tuturuuu.com` * Webhooks, user authorization, and device flow: disabled * Repository permissions: read-only Actions, Checks, Commit statuses, Contents, Issues, Metadata, and Pull requests * Organization permissions: none * Installation: the `tutur3u` organization, all repositories Generate a private key only when an administrator can immediately store it through `/-/internal/github-app`. The private key is envelope-encrypted with `ENCRYPTION_MASTER_KEY`; plaintext is never returned after submission. Runtime installation tokens are restricted to one approved repository ID. ## Deployment The Vercel workflows expect `VERCEL_GIT_PROJECT_ID`, `VERCEL_ORG_ID`, and `VERCEL_TOKEN`. Project creation and Git linkage are a one-time Vercel console step. Configure the production domain as `git.tuturuuu.com`, set `ENCRYPTION_MASTER_KEY` in protected environments, then use the admin page to save the GitHub App ID, installation ID, and private key. The public GitHub API remains a bootstrap fallback for registered public repositories until the app credentials are configured. Mutable repository data uses short cache lifetimes; immutable commit-addressed content uses long-lived cache entries. # Hive Source: https://docs.tuturuuu.com/platform/applications/hive Voxel research playground for CRDT worlds, farming simulation, NPC economies, and manual or autonomous society experiments. Hive is the Tuturuuu research satellite app at `https://hive.tuturuuu.com`. It uses the centralized Tuturuuu login handoff and keeps protected product APIs inside `apps/web` under `/api/v1/hive/*`. Hive consumes cross-app login tokens through `/verify-token`. That verifier posts the handoff token to `/api/auth/verify-app-token`, trusts the returned HttpOnly app-session cookies, and then redirects to the requested Hive path. Protected routes require both the Hive-local app-session cookie and the Web-issued app-session cookie used for forwarded central APIs. If only the Hive-local cookie remains, Hive sends the browser through local `/login` to recover the full cookie pair. Expired access tokens should rotate through same-origin `/api/auth/refresh-app-session` while refresh cookies remain valid. Hive must not create or refresh a Hive-domain Supabase Auth session. Hive local logout is intentionally app-local: `/api/auth/logout` clears `tuturuuu_app_session`, expires stale Supabase Auth cookies on the Hive host, and redirects browser form submissions back to `/login`. Keep that route outside the generic API proxy guard path so logout does not wait on product API rate-limit checks. Unmatched `/api/workspaces/*` requests, including workspace invitations and workspace details, use the Web fallback with their paths and queries intact. Local Hive API handlers retain precedence. Regression coverage lives in `apps/hive/src/next-config.test.ts`. The `/realtime/*` rewrite remains separate and continues to target the Hive realtime service. ## Dual-Host Parity Hive is available through both the standalone satellite host and the main web dashboard. The standalone route shape stays `/` and `/not-whitelisted`. Inside `apps/web`, the route shape is `/{wsId}/hive` and `/{wsId}/hive/not-whitelisted`; the `wsId` segment is only the surrounding web dashboard context and must not filter Hive servers, snapshots, realtime membership, or world data. Both hosts must render the same shared Studio UI, engine, realtime client, data hooks, and access-request card from `@tuturuuu/hive-ui`. Keep `apps/hive` and the `apps/web` Hive routes as thin host wrappers for auth, access resolution, build metadata, and forwarded API context only. Future Hive feature work belongs in `packages/hive-ui`, `@tuturuuu/realtime/hive`, or the centralized Hive APIs so the standalone app and web-hosted app stay 1:1. ## Access Model * Production access is resolved from Supabase `public.hive_members` with `enabled = true` plus platform-admin roles. The dedicated Hive Postgres `hive_members` table is still synchronized for product data workflows, but app access gates must not require `HIVE_DATABASE_URL` just to decide whether a signed-in user can open Hive. * Researchers who authenticate successfully but are not enabled land on `/not-whitelisted`, where they can create or refresh a `hive_access_requests` row. That page polls `/api/v1/hive/access-requests/me` every 5 seconds and opens Hive automatically after the request reaches the approved/access-enabled state. * Platform admins are users whose `platform_user_roles.allow_role_management` value is `true`; they can create and manage Hive servers and Hive members. * Root workspace admins can enable or disable Hive access from `/{rootWorkspaceId}/platform/roles` without opening the Hive satellite app. * Pending Hive requests appear in the same platform roles panel. Approving a request writes both the dedicated Hive Postgres `hive_members` row and the Supabase `public.hive_members` row that the Hive satellite uses for its local server gate and that `apps/web` uses for embedded Hive routes. Do not update only one store, or users can authenticate through Tuturuuu and then loop back to the restricted page or fail an embedded Hive preload. * V1 server policy is intentionally broad: every enabled Hive member can join every enabled Hive server. * Hive servers are global research worlds. Workspace selection inside the Hive editor is only an AI context and billing control; it must not filter server lists, snapshots, realtime membership, or world data. * `apps/web` remains the login authority and verifies platform roles through internal APIs. Hive itself uses the app-session JWT as the local identity cookie. Hive product data is split across two databases (see [Data Model](#data-model)): the authoritative world-event, CRDT, and research tables live in the main Supabase `public` schema, while a parallel Docker-managed Hive Postgres baseline accessed through `HIVE_DATABASE_URL` carries the dedicated-store mirror used by backfill and product-data workflows. ## Data Model Hive product state spans **two physical databases**, and it matters which one is authoritative for any given table when you operate or debug the app. ### Authoritative store: main Supabase `public` schema The live world-event, CRDT, economy, NPC, and research tables that the running `/api/v1/hive/*` routes read and write are in the **main Supabase project** (`public.hive_*`). All apps share one Supabase project, so these tables are managed by the standard Supabase migration flow in `apps/database/supabase/migrations/`, not by the Hive Postgres migrator. This is where the audited world-event path actually runs: * `hive_servers` * `hive_world_states` — authoritative full-world snapshots * `hive_world_events` — event metadata and compact payloads * `hive_npcs`, `hive_npc_runs`, `hive_npc_memories` * `hive_workflows`, `hive_workflow_runs` * `hive_research_sessions`, `hive_research_session_events` * `hive_members`, `hive_access_requests` The `apply_hive_world_event()` Postgres function is defined as `public.apply_hive_world_event(...)` in the Supabase migrations (`20260510143500_add_hive_research_engine.sql`, then hardened by `20260511160200_fix_hive_world_event_ambiguity.sql`, `20260512151000_make_hive_revision_conflicts_non_exceptional.sql`, and `20260512204028_secure_hive_world_event_actor.sql`). It inserts/updates `public.hive_world_states` and appends to `public.hive_world_events` in one transaction. It is **not** a Hive-Postgres migration. If a world save returns `hive_event_failed`, debug it against Supabase — see [Hive world event troubleshooting](/platform/applications/hive-world-event-troubleshooting). ### Dedicated Hive Postgres mirror (`HIVE_DATABASE_URL`) A separate Docker-managed Hive Postgres database holds a parallel dedicated-store baseline (`apps/hive/db/001_schema.sql`) that the one-shot backfill path populates from legacy Supabase Hive rows. Its `001_schema.sql` baseline declares its own copies of `hive_members`, `hive_access_requests`, `hive_servers`, `hive_world_states`, `hive_world_events`, `hive_research_sessions`, `hive_research_session_events`, `hive_crdt_updates`, `hive_npcs`, `hive_npc_needs`, `hive_npc_wallets`, `hive_npc_memories`, `hive_npc_runs`, `hive_ledger_entries`, `hive_inventory_items`, `hive_warehouses`, `hive_trade_offers`, `hive_crop_instances`, and `hive_simulation_ticks`. The `apply_hive_world_event` function and the world-event/actor-security logic are **not** present in this baseline; that path lives only in Supabase. Because the dedicated baseline mirrors many of the same table names, do not assume a fix applied to one database is visible to the other. App access gates read Supabase `public.hive_members` (and platform-admin roles), and approving a request writes **both** stores (see [Access Model](#access-model)). ## Database Migrations Hive Postgres is forward-migrated by the `hive-db-migrate` Docker Compose job before web, Hive, Hive realtime, or Hive cron processes are allowed to start. The deployment watcher also runs that job explicitly with `docker compose run --rm --no-build hive-db-migrate` on every blue/green deployment so an already-completed migration container cannot silently satisfy a new deploy. After the explicit run and after Hive services start, the watcher removes the one-shot migrator by Docker Compose project and service labels, including stopped containers named like `tuturuuu-hive-db-migrate-*`, so the migration job does not stay around consuming host resources or making the cluster look unhealthy. The migration runner records successful work in `hive_schema_migrations` with a timestamp version, filename, checksum, `applied_at`, and `applied_by`. The current `apps/hive/db/001_schema.sql` file is the immutable baseline; future changes belong in `apps/hive/db/migrations/YYYYMMDDHHMMSS_description.sql`. Deployment fails when a pending migration checksum disagrees with history, when its timestamp is not newer than the last recorded migration version, or when its timestamp is not newer than the last recorded `applied_at` time at deployment start. The runner rejects reset-style SQL such as `DROP DATABASE`, `DROP SCHEMA`, `DROP TABLE`, `TRUNCATE`, `ALTER TABLE ... DROP COLUMN`, and mutation of `hive_schema_migrations`. A destructive Hive DB operation requires an explicit DevOps-admin override by setting `HIVE_DB_OPERATOR_ROLE=devops-admin`, `HIVE_DB_ALLOW_DESTRUCTIVE_RESET=1`, and `HIVE_DB_DEVOPS_ADMIN_APPROVED=1`; do not set those values in normal deploy environments. When the migration runner finds an older Hive DB that already has runtime tables but no `hive_schema_migrations` history, it performs a forward-only compatibility pass before recording the baseline. That pass creates the research-session table when needed and adds missing nullable `research_session_id` columns to legacy event, NPC run, and simulation tick tables so the immutable baseline can replay without failing on partial indexes. Shared editor state is a Yjs CRDT document per Hive server. Terrain blocks, objects, public NPC projections, farm tiles, and visual warehouse/crop projections live in keyed CRDT maps. Money, item ownership, trade settlement, warehouse transfers, LLM spend, and bankrupt elimination stay relational and transactional in Postgres so currency and inventory cannot be duplicated by CRDT merge behavior. `revision` is now a compatibility display value backed by the monotonic `op_seq` audit counter. It is not a write precondition for normal CRDT world edits. Authoritative economy writes must use SQL transactions, idempotency keys where available, and ledger rows. The one-shot Hive backfill path copies legacy Hive rows into the dedicated Hive Postgres baseline so the dedicated store mirrors prior product data. Note that the authoritative live world-event, CRDT, economy, NPC, and research writes performed by `/api/v1/hive/*` run against the main Supabase `public` schema (see [Data Model](#data-model)); the dedicated Hive Postgres is the mirrored dedicated store, not the runtime authority for the world-event path. In all cases, `apps/web` internal APIs use the forwarded app-session cookie to resolve the caller and platform-admin status. In Docker production, Hive satellite API rewrites must target the web service through `INTERNAL_WEB_API_ORIGIN=http://web-proxy:7803`. If that value is empty, the Hive Next.js rewrite can fall back to the public web origin and turn every editor save into a browser-to-Hive-to-public-Web round trip. Hive Docker production builds run the Next.js build through `scripts/run-hive-docker-next-build.js` under the real `node:24` builder stage. The builder still copies Bun from the dependency stage for workspace package builds, but the final Hive `next build --turbopack` step must be launched with Node and `/tmp/web.env` instead of `bun --env-file` so production E2E image bakes do not depend on Bun's Next.js process shim. Hive graph workflows are server-scoped product data. Platform admins author shared workflow definitions in `hive_workflows`; enabled Hive members can run enabled, unarchived workflows manually, and every run writes a row in `hive_workflow_runs` with the input, output, step trace, status, and error message. Workflow definitions are JSON graphs with typed nodes and edges. V1 manual execution disallows cycles, caps graphs at 80 nodes / 120 edges, and uses restricted `{{steps.nodeId.output.path}}` or `{{input.path}}` references only. Do not add arbitrary JavaScript evaluation to workflow config. Workflow `world_event` nodes can also include a `worldPatch` object with `blocks`, `objects`, `removeBlockIds`, `removeObjectIds`, or `clear: true`; the engine applies that patch to the latest server snapshot and persists the result through the same audited world-event path as manual editor saves. Workflow `agent_interaction` nodes run configured NPC pairs through the same LLM-backed interaction path as Agent Studio pair queues, with deterministic fallback behavior when provider access is unavailable. Mind imports use `/api/v1/hive/servers/:serverId/mind-simulations` to create NPC agents from a Mind board, create source graph interaction pairs, and save a Hive workflow that stamps the Mind source context before running those pairs. That import route is an admin operation because it creates shared Hive server state. Research sessions are the shared audit spine for multi-agent experiments. A running `hive_research_sessions` row can be attached to NPC runs, workflow runs, world events, and simulation ticks through nullable `research_session_id` columns. When a run payload omits `researchSessionId`, the backend attaches the active running session for that server when one exists. Session events in `hive_research_session_events` record operational actions such as session creation/update and pair queue start/complete markers. Session exports are available from `/api/v1/hive/servers/:serverId/research-sessions/:sessionId/export` as JSON or JSONL and should preserve enough identifiers to replay research timelines outside the app. Shared realtime payloads and Hive CRDT helpers live in `@tuturuuu/realtime/hive`. Keep protocol schemas there when both `apps/hive`, `apps/hive-realtime`, or `apps/web` need the same message or document contract. ## AI Credit Context Hive uses the same AI credit and model contracts as the main dashboard. The editor top bar owns the workspace picker, personal/workspace credit source toggle, credit meter, and model picker. The selected workspace is the credit context only; it does not scope Hive servers. Manual NPC runs and manual NPC-to-NPC interactions send `creditSource`, `creditWsId`, and `model` through the Hive internal API. The web route verifies that the signed-in Hive user can access the selected workspace, resolves the requested model against the workspace plan, preflights AI credits, runs the LLM, and deducts credits only after successful model usage. A failed post-generation credit deduction is a request failure: the provider output is not persisted or returned to the caller. If model access is not configured, the route can still persist a deterministic NPC decision for inspectable simulation history. Autonomous NPC interactions use server settings instead of the current browser selection. `defaultCreditSource`, `defaultCreditWsId`, and `defaultModel` define the billing/model context for scheduled simulation work. If the billing workspace is missing or unauthorized, scheduled LLM autonomy is skipped and the normal simulation tick continues. `hive_npc_runs` stores grouped interaction metadata for manual pair queues, one-shot manual runs, autonomous runs, and workflow-triggered decisions: `interaction_id`, source/target NPCs, trigger, status, model, provider, token counts, credit source/workspace, deducted credits, errors, and optional `research_session_id`. Timeline surfaces should group or filter from this persisted run history plus world events, workflow runs, simulation ticks, and session events rather than recomputing transcripts from transient client state. ## Editor Surface `apps/hive` is a hidden-locale Next.js satellite app. The editor uses a full-bleed React Three Fiber viewport, compact top status chips, a bottom tool dock with build/settings controls, an Agent Studio rail, a research timeline drawer, and selected-detail overlays. The 3D world remains mounted while users open agent setup, workflow authoring, timeline observability, AI context, or operations controls. The editor is built on the shared `@tuturuuu/satellite` workspace shell. Hive uses that shell for collapsible left/right rails, top research overlays, and the bottom tool dock so satellite apps can share layout mechanics while keeping Hive-specific tool density and viewport behavior. Collapsed editor slots must remove hit targets as well as opacity. Hidden Hive toolbars use the satellite shell's collapsed `visibility` and pointer-event gating so invisible dock buttons cannot still receive hover, focus, or tooltip events. Hive keeps one editable CRDT world per server. Admins manage that world through server controls: creating a server creates its world, deleting a server deletes the world through database cascade, and clear/reseed actions persist typed audit events plus CRDT updates against the current server document. Manual editor changes persist through the web gateway world-event API, which calls the Supabase `public.apply_hive_world_event()` function. That function stores the authoritative `world_data` and the matching event metadata in the same Supabase transaction, then the Hive client only broadcasts the already applied event through `hive-realtime`. Do not add a second client-side `sync.update` persistence write after the gateway event succeeds; duplicate writes can churn `op_seq`, slow visible save completion, and let older world snapshots overwrite newer local edits. Realtime and snapshot consumers must also ignore equal or older revisions so delayed broadcasts cannot revert an optimistic edit that already advanced locally. Keep full-world snapshots in `hive_world_states` only. `hive_world_events` should store event metadata and the compact event payload, not another copy of `world_data`, because normal editor saves can otherwise rewrite and insert the entire voxel world twice on every operation. The 3D editor treats the voxel grid as the source of truth. Perspective comes from the camera and controls, not from rotating the editable world group. World edits should commit only after click/drag threshold handling so orbit, pan, zoom, placement, erasing, moving, and rotating do not conflict with each other. The bottom dock uses explicit persistent panel toggles instead of hover-only expansion. Build catalog, editor settings, and live operations each have a visible icon control. Minimal tile gaps are the default terrain presentation; gapless rendering is an explicit settings toggle. The Settings dock tab owns the continuous 24-hour time slider, auto-time speed, season, weather, camera presets, and simulation/server toggles. Do not restore the older five fixed visible time buttons as the primary time control. Live operations in the dock must use existing Hive snapshot state rather than a new route: world counts, crops, warehouses, server currency, events, online users, realtime status, revision, and the last sync notice. Agent Studio owns multi-agent setup and ordered pair queues: multi-select NPCs, batch role/memory /autonomy edits, round-robin pairs, all-to-all pairs, custom target pairs, run prompt, turn count, and current AI context. NPC Lab remains the selected-agent detail editor only. When no NPC is selected, it should show a selection prompt instead of silently mutating the first NPC in the server. The editor uses a single Research Studio panel state instead of separate full-screen World / Workflow graph / Timeline destinations. Workflow graph is a focused overlay on top of the persistent world viewport. Timeline is a drawer that reads `/api/v1/hive/servers/:serverId/timeline`, filters by research session and run metadata, and expands rows into input/output context, status, model/provider, credits, and export identifiers. Workflow mode is still a 2D React Flow graph builder for manual Hive automations, but it must reuse the same AI context, run trace, and research timeline contracts as NPC pair queues. Embedded `apps/web` Hive routes should load `@xyflow/react/dist/style.css` from the Hive route segment layout rather than the root web layout, so React Flow styles are available for workflow mode without adding that CSS to unrelated dashboard routes. Admins can drag nodes from the palette, use starter templates, edit JSON config in the inspector, save shared workflows, and run them against the selected server. Members see the same graph read-only and can manually run saved workflows. Workflow runs apply live effects through the same gateway-backed Hive actions used elsewhere: world events, simulation ticks, NPC decision records, farming, warehouses, and trades. Effects are audited through the workflow run trace, research session timeline, and existing Hive event/economy tables; v1 has no schedule, webhook trigger, retry queue, credential vault, or rollback approval layer. Starter workflow templates should demonstrate a real server-side use case, not just create trace rows. The farm cycle template plants a relational crop, then uses a `world_event.worldPatch` step to stamp a visible crop plot into the Hive world. The cleanup template removes that starter plot by id and records the maintenance event. Keep manual and autonomous interaction rows grouped by `interaction_id` whenever a deeper transcript view is added. Pair queue runs must execute pairs in request order and return partial failures without dropping successful earlier pairs. NPC Lab is a draft editor for the selected NPC only. Identity, brain/model, behavior/autonomy, memory/prompt flags, system prompt, and interaction controls belong in the lab tabs. Save/Reset should protect large text and settings edits from accidental persistence, while manual run buttons can launch one-shot decisions or targeted NPC-to-NPC interactions using the current AI credit context. The chat composer is opt-in from the editor chrome button, and the mini-map is a collapsible viewport overlay. If all Hive servers are deleted, the editor must clear local world, NPC, revision, selection, presence, and awareness state so it does not keep rendering the last server snapshot. Time of day still maps to authored scene backdrops and lerped lighting, fog, background, and cloud tint. Weather and season controls layer visual atmosphere over that time base without changing the durable CRDT world snapshot. Realtime multiplayer awareness is ephemeral. Avatar badges, terrain cursors, selection rings, active tool state, camera focus, and in-world user markers are sent as TTL-based awareness updates and must not be persisted into durable world snapshots. Offline world edits are queued as CRDT updates and replayed on reconnect. The client uses token refresh, exponential backoff, state-vector resync, throttled cursor/position updates, and local actor echo suppression to keep the research surface responsive during reconnects and slow-client conditions. Client data access must go through `@tuturuuu/internal-api` helpers and TanStack Query. Do not add raw client `fetch()` calls in the satellite app. ## Testing Hive has app-local Playwright coverage in `apps/hive/e2e`. The suite assumes the local web app on `https://tuturuuu.localhost` and Hive app on `https://hive.tuturuuu.localhost` are already running through Portless; it does not auto-start dev servers. Root `bun test:e2e` intentionally runs the self-contained Dockerized web E2E suite instead; after starting the Portless services for Hive, run Hive coverage with: ```bash theme={null} bun --filter @tuturuuu/hive test:e2e ``` The authenticated setup uses the web app's development session endpoint for the seeded `local@tuturuuu.com` account before opening Hive. Override `WEB_BASE_URL` or `HIVE_BASE_URL` when bypassing Portless or using direct fallback ports. ## Economy And Farming Each Hive server has a total currency pool, NPC wallets, inventories, warehouses, trade offers, crops, and ledger-backed transfers. NPCs have hunger, energy, morale, upkeep, and optional LLM spend budgets. Crop rules cover soil/water/fertilizer state, growth stages, harvest yields, and day-cycle simulation. Manual tools can plant, water, harvest, deposit, withdraw, and settle trades. Autonomous ticks can advance crops, choose NPC jobs, apply upkeep, record LLM run costs, credit earnings, and eliminate NPCs whose wallets cannot cover required costs. Cron-backed Hive simulation is intentionally disabled by default. Enable global Hive cron and per-server autonomous simulation through Hive settings only after budget limits, tick interval, and max LLM spend have been reviewed. ## LLM Providers Ollama is optional and disabled by default. Docker can start the `hive-ollama` profile, and Hive settings can enable the local model id exactly as `gemma4`. The app loads the model through Ollama's generate API, generates through `/api/generate`, and unloads by sending `keep_alive: 0`. Every Mira-powered LLM path must be gated by an exact `@tuturuuu.com` email check. Subdomains such as `@xwf.tuturuuu.com` are not Tuturuuu-internal for Mira access. # Hive world event troubleshooting Source: https://docs.tuturuuu.com/platform/applications/hive-world-event-troubleshooting Fix ambiguous server_id errors when applying Hive world events. ## Symptoms When creating a Hive world event, the API can return: ``` column reference "server_id" is ambiguous ``` This surfaces as `hive_event_failed` in the client with a 400 error. ## Cause `apply_hive_world_event` returns a `table` signature that includes `server_id`. In PL/pgSQL, output columns are variables. Unqualified references to `server_id` inside the function can become ambiguous and fail at runtime. ## Fix Use a constraint-based conflict target in the insert that bootstraps `hive_world_states` so the SQL does not rely on a bare `server_id` identifier: ``` insert into public.hive_world_states (server_id, revision, world_data, updated_by) values (p_server_id, 0, '{}'::jsonb, p_actor_user_id) on conflict on constraint hive_world_states_pkey do nothing; ``` Apply the migration and re-run Hive event creation after the updated function is live. ## Actor Authorization The actor-accepting `apply_hive_world_event(uuid, uuid, bigint, text, jsonb, jsonb)` overload should not be exposed to browser roles. Keep direct execution revoked from `public`, `anon`, and `authenticated`; server-side API and realtime paths call it with `service_role` after validating the user session or signed Hive realtime token. If a non-service role ever reaches the function, it must derive the actor from `auth.uid()` and reject mismatched `p_actor_user_id` values with `hive_actor_mismatch`. # Infrastructure Source: https://docs.tuturuuu.com/platform/applications/infrastructure Privileged operations, diagnostics, configuration, and hosted scheduler ownership. Infrastructure (`infrastructure.tuturuuu.com`, `apps/infrastructure`) is the privileged operational console. It exposes workspace/account controls, monitoring, configuration, and selected provider gateways. The existence of a console route never bypasses its operator eligibility and permission checks. ## Operational areas * Workspace/user administration, internal accounts, external-app registration, account benefits, and app coordination. * AI policy, agents, credits, rate limits, abuse intelligence/events, blocked IPs, recovery/appeals, and entity-creation limits. * Email queues/templates/audit, push notifications, and Calendar sync. * Mobile/desktop deployment records, versions, translations, holidays, timezones, Devboxes, and migration diagnostics. * Monitoring for requests, logs, analytics, projects, deployments, rollouts, resources, and retained cron/control surfaces. The sidebar groups these areas into labelled sections, matching the Tuturuuu web dashboard: **Fleet** (machines, jobs and resources), **Operate** (monitoring, delivery and integrations) and **Govern** (security, AI operations, communications and platform administration). Add a new route to the section that owns its operator task in `navigation.tsx`. The [route reference](/reference/repository/catalog) lists every current Infrastructure entry point in its numbered source pages. Feature-specific operating rules remain in [DevOps](/build/devops/overview) and [Commercial controls](/platform/features/commercial-controls). ## Fleet machine states Infrastructure > Fleet (`/[wsId]/fleet`) reads the devbox runner snapshot and shows one state per machine. The first matching state wins: | State | Rule | | - | - | | Revoked | The runner was revoked. | | No credential | No active runner token, whatever the heartbeat says. | | Setup incomplete | Registered but no heartbeat has ever arrived. | | Heartbeat off | An administrator turned heartbeats off. | | Disconnected | The last heartbeat is older than 15 minutes. | | Heartbeat late | The last heartbeat is older than 60 seconds, the SDK's placement freshness window, or the status is not `online`. | | Draining | A drain was requested. | | Online | A fresh heartbeat, an active token and `online` status. | Resource readings (load per core, memory, disk) are shown only while the heartbeat is fresh and the runner's `reportedAt` is within five minutes. Otherwise they read **Unknown** or **Not reported**, never as zero or as the last value. A queued, claimed or running run on a late, disconnected, untrusted or revoked machine shows **Outcome unknown**. It is neither counted as running nor assumed failed, and this view never reschedules it. Judge sandbox limits (`resource_limits`) do not constrain trusted commands. They are not lane ceilings, so Fleet reports the lane ceiling as not reported until the balancer publishes host lanes. Run counts cover only the latest snapshot window, and the tiles say so. Regression coverage: `src/lib/fleet/fleet-model.test.ts` (state precedence, freshness, unknown run outcomes, telemetry parsing) and `fleet/_components/machine-card.test.tsx` (fresh versus disconnected rendering). ## Current schedulers Hosted Calendar provider sync and smart scheduling run through Infrastructure's Vercel schedule and authenticated Calendar gateway. The [Cloudflare Cron Control Worker](/build/devops/cloudflare-cron-control) owns immediate notification recovery. The Docker cron runner is retired. Retained Docker controls and stale local heartbeat records do not establish the health of either hosted scheduler. Use the [active runtime map](/build/devops/active-runtime) to trace a job from scheduler to gateway to processor. Verify recent domain results as well as a successful scheduler invocation. ## Privacy and change control Console pages and APIs are noindex, including errors, auth redirects, and non-HTML responses covered by the app policy. Search controls supplement actor, workspace, permission, token, and storage checks. Runtime logs use native `console.*` with the original severity; operational log-drain services are separate boundaries. A configuration edit, deploy action, external registration, or production write requires its own authorized workflow. Reading a runbook or recalling a private record is not authority to execute it. ## Account passwords and access Infrastructure internal-account API requests require fresh persisted root-workspace `MEMBER` membership for the authoritative current actor before any account-service RPC, in addition to the existing exact corporate email, permission, confirmed and unbanned Auth identity, and MFA checks. The global workspace creator permission override does not replace this membership requirement. Each request rechecks membership without caching: removal returns 403 even for a creator; a membership query error or transport exception returns 503 without exposing diagnostics. Regression coverage: `authorization.test.ts`. The separately guarded CLI recovery exception retains its documented authentication boundary below. Administrators with root-workspace `manage_internal_accounts` permission use **Reset any password** to select an account by email, or **Reset password** in an internal account's menu. Both dialogs accept a chosen password or generate a 20-character temporary password locally using Web Crypto. Passwords must contain 12–72 characters. The global reset dialog freezes its target and password and prevents dismissal while the request is pending; a failed request keeps the form editable, and a successful request exposes the credential handoff. Passwords are not written to application logs. The internal-account menu shows **Disable access** for active accounts and **Enable access** for disabled accounts. Both require matching target-email confirmation. Disable and enable accept the root `@tuturuuu.com` domain and strictly validated managed subdomains such as `@xwf.tuturuuu.com`, preserving the account UUID. External addresses and suffix lookalikes are rejected. This exception does not widen profile, password, or MFA action eligibility or the exact-root administrator identity requirement. Enable removes the provider ban; it does not change the password or perform managed-employee restoration. These existing password/access actions have no optional activation gate. Current administrator identity, permission, target eligibility and self-target protections still apply. Administrators cannot use these actions on their own account; managed-employee lifecycle recovery continues through its separate inspection and restoration flow. Regression coverage: `account-password-reset-dialog.test.tsx` exercises password bounds, pending-request protection, generation and refusal; `internal-account-row.test.tsx` exercises the existing active/disabled menus and self-target controls; `service.test.ts` verifies exact confirmation and provider ban changes, managed-subdomain disable/enable UUID preservation, unmanaged-target rejection, and unchanged root-only profile/password/MFA eligibility. Route authorization and password-boundary suites cover the existing Infrastructure API contracts. These synthetic tests do not establish provider or production acceptance. ## Administrator profile username input The Infrastructure internal-account profile dialog accepts administrator usernames without product minimum or maximum length limits. Input is trimmed and lowercased; empty input clears the username. Changed nonempty usernames start with an ASCII letter or digit and contain only lowercase ASCII letters, digits, and underscores. An unchanged legacy username can be retained while editing the display name. Usernames must be unique; reserved names and availability are checked by the server when saving. This administrator input policy does not change ordinary self-service username rules or workspace handles. Transport and storage safety limits remain separate from product input policy. UI and service regression coverage lives in `internal-account-edit-dialog.test.tsx`, `profile-service.test.ts`, and `managed-profile-service.test.ts`; these tests do not establish database or production acceptance. ## Diagnose an internal profile save failure The internal profile dialog sends a same-origin UUID `PATCH` through `updateInternalAccount` in `packages/internal-api`. Infrastructure owns this route and its profile service. Web's satellite rewrite inventory does not forward this legacy UUID route. The employee subtree below has a separate owner. The generic update toast does not identify the failing boundary. Inspect the existing failed request's HTTP status and response message first, then the owning Infrastructure request logs. Do not replay a profile mutation to gather evidence. Keep credentials, request bodies, provider error details, and account identifiers out of shared diagnostics. `profile-service.ts` emits `Internal account profile stage failed` on a returned database failure, with a fixed `profile_read`, `username_reserve`, or `profile_update` stage and an allowlisted code. Unrecognized or absent codes become `unknown`. A successful profile lookup that returns no row also logs `profile_read` with code `unknown` and returns HTTP 404; this event does not necessarily indicate a database error. These events do not prove a specific SQL trigger caused the rejection. They do not cover earlier authorization, provider lookup, or thrown transport failures. Missing events alone do not prove that execution stopped earlier. Returned username-cleanup failures emit `Internal account profile cleanup failed` with a fixed `username_rollback` or `previous_username_release` stage and the same code allowlist. Cleanup diagnostics omit account IDs and raw error fields. A thrown rollback rejection emits `username_rollback` with code `unknown` and preserves the original profile-update failure. Returned previous-username cleanup errors preserve the successful profile response. For an update-stage `42501`, a separately authorized read-only SQL inspection can compare the target's canonical `users.display_name` with the registry's `infrastructure_employees.managed_name` and confirm the installed managed-name trigger. Registered employee names remain managed: changing the public name away from that managed value is rejected even for a service-role write. Do not bypass that fence or widen administrator authorization to make the toast disappear. `23505` indicates a uniqueness conflict; `PT429` indicates a profile change limit. Confirm the exact database error before attributing either to this incident. `profile-service.test.ts` covers each returned failure stage, unknown-code privacy, unchanged status/rollback behavior, cleanup returned errors and rollback rejection, explicit read/reserve/update/cleanup ordering, and success without failure logs. `apps/database/supabase/tests/employee-signup-guards.sql` covers the managed-name fence through the public profile RPC. Service mocks do not establish deployed schema, provider, transport, or customer acceptance. ## Employee API routing Web owns `/api/v1/infrastructure/internal-accounts/employees` and its descendants, including CREATE readiness, employee inspection, restore, and reconcile. Infrastructure forwards that exact subtree in `beforeFiles`, including the base path with zero wildcard segments. A fallback-only rewrite lets the local `internal-accounts/[userId]` PATCH route capture `employees` and answer GET with an empty 405 before Web can handle it. The local internal-account list and legacy UUID PATCH remain in Infrastructure; address-migration endpoints retain their existing Web fallback. The installed Next matchers in `apps/infrastructure/next.config.test.ts` cover these boundaries. Routing checks do not establish downstream readiness: require the exact-commit Infrastructure CI build and an authorized production recheck after deployment. ## Employee SQL transport qualification ### HTTP RPC runtime candidate The Web employee CREATE route can compose the durable operation journal with fixed service-only Supabase RPCs. CREATE is available by default to all authorized root administrators with `manage_internal_accounts`; no administrator activation exception or `EMPLOYEE_CREATION_RUNTIME_ENABLED` opt-in applies. Server configuration and SQL/provider readiness still determine availability. Infrastructure consumes the same availability endpoint; its create control remains disabled while the runtime is unavailable. Isolated SQL, generated-type, HTTP/Auth, target-project migrations and exact-build checks remain release evidence. The adapter uses the configured server Supabase project for both Auth and SQL. The request still requires an eligible root administrator, current membership and permission, and the account-action origin/header checks. SQL repeats the actor assertion and denies expanded function ACLs. An original actor/operation key owns one target UUID. Durable attempted phases and single-use invocation capabilities precede provider effects; unknown responses retain that identity for inspection. Every RPC write acknowledgement is followed by a separate persisted-state observation. A function response from a transaction configured to roll back cannot authorize provider creation or publish account success. Lost responses, malformed state and readback disagreement fail closed without an automatic retry. Passwords remain transient Auth inputs and never enter the operation tables or RPC body. This adapter does not activate the fixed child-worker prototype below. That prototype retains its separate operator, connection and asset qualification requirements. RESTORE and legacy-domain migration remain separate runtime flows; successful CREATE qualification does not establish either behavior. In the Infrastructure CREATE form and Web boundary, the shared password schema requires 12–72 characters with lowercase and uppercase ASCII letters, a digit and ASCII punctuation before journal admission. The password remains transient. Normal success confirms that the account is ready to sign in without an extra observation request. After an uncertain response, the browser retains the original operation reference scoped to actor and workspace, without retaining the password, and admits up to six observation checks within 30 seconds of the first check. These reads never replay CREATE. Completion requires independent active onboarding identity and fresh SQL account/profile/mailbox/grant proof; incomplete outcomes retain the original operation and stay blocked against another CREATE. This behavior does not promise a creation latency. Regression coverage and remaining runtime evidence are recorded in the [CREATE qualification contract](../../build/development-tools/employee-schema-qualification#original-create-response-recovery). CLI recovery of an existing CREATE operation also supports read-only `GET .../operations/{operationId}/cli-recovery?view=outcome` with the same platform CLI access credential. Fresh CLI MFA, current canonical email, root membership and permission checks apply before reads and before disclosure. This view binds the original actor/operation and requires provider plus fresh SQL proof; it never resumes or mutates. Default rejection GET and version-3 POST resume keep their existing contracts. Infrastructure audience authentication remains separate. See the [CLI recovery runbook](../../build/development-tools/employee-cli-recovery) and its CLI outcome route/client regressions for strict HTTP and identity checks. ### Managed employee inspection Web serves `GET /api/v1/infrastructure/internal-accounts/employees/:userId` for the native Infrastructure management client. It returns the retained restoration inspection contract, provider observation time and next action. It requires a current confirmed, active canonical-domain root `MEMBER` with `manage_internal_accounts`; it rechecks the same request actor before SQL and before disclosing private recovery details. Responses are private and uncached. The adapter reads the exact provider UUID and calls only `private.inspect_employee_management` in the same configured Supabase project. Missing schema, conflicting tuples, unavailable reads and changed authority fail closed. An unresolved restore operation remains `inspect`; it never relaunches provider work. Unmanaged legacy addresses remain an adoption/migration concern. The portable restoration boundary lives under `packages/utils/src/internal-accounts`, with Infrastructure compatibility exports. This GET path does not enable CREATE, RESTORE writes or legacy-address migration. No runtime flag is changed. Route and transport regressions live beside the Web implementation, while the existing Infrastructure restoration suites cover compatibility. Exact-source CI builds, deployed request authentication and target-project SQL qualification remain separate release gates. ### RESTORE and reconciliation POST candidate Web owns `POST /api/v1/infrastructure/internal-accounts/employees/:userId/restore` and the sibling `/reconcile` route. Both are available by default to all authorized root administrators with `manage_internal_accounts`; no administrator activation exception or `EMPLOYEE_RESTORATION_RUNTIME_ENABLED` opt-in applies. Configuration, request authorization and lifecycle/SQL/provider guards remain mandatory. The Infrastructure console consumes this contract through the managed-access dialog below; legacy-domain address migration remains a separate flow. The routes reuse the portable restoration HTTP/orchestration helpers, with Infrastructure compatibility exports. The server supplies the actor and provider; strict request input supplies only confirmation email, expected revision and, for reconciliation, the original operation UUID. Current request authentication, root membership/permission and active canonical-domain actor checks repeat before every RPC and provider call and before a successful or pending response is disclosed. The fixed five-function transport uses the same configured Supabase project for Auth and SQL. Separate `inspect_employee_management` requests must observe the matching reserved and attempted operation before the sole provider unban. SQL confirmation/reconciliation receipts must match independently observed completed state, revision and managed name. Rollback responses, missing or malformed readbacks and lost responses retain an unknown outcome without automatic retry. Reconciliation uses the original actor/target/revision/operation tuple and never begins an operation or dispatches another provider mutation. `employee-restoration-rpc.test.ts` and `employee-restoration-runtime.test.ts` in Web exercise actual loopback HTTP against a disposable synthetic SQL endpoint, including unpersisted replies, revocation and provider acknowledgement loss. The shipped route test proves RESTORE and reconciliation work with unset or false activation flags independently of CREATE, while nonadmins and unavailable server configuration remain denied. `employee-creation-runtime.test.ts` covers the same production-composition policy for CREATE and retains SQL-readiness failures. The retained Infrastructure suites cover helper compatibility. These fixtures qualify source and HTTP serialization only: before release, independently verify the five deployed function definitions and service-only ACLs, commit and rollback/readback behavior through real PostgREST/PostgreSQL, request-session and actor revocation behavior with real Auth, and the exact-source Web and Infrastructure CI builds. Production migration completion and authorized delivery remain release-owner gates; neither GET inspection nor CREATE qualification establishes RESTORE delivery. ### Simple account forms For root administrators in Infrastructure, Create uses staff email, full name and an in-memory temporary password. Readiness and bounded original-operation confirmation run automatically; the form reports readiness only after existing creation proof succeeds. Password generation uses the existing cryptographic sampler; explicit password copying requires the secure clipboard and reports failure without logging the credential. Save the CREATE credential before submitting: its field clears after submission and on close, and never enters recovery storage. Password reset accepts a new credential through its ordinary form, supports Enter, and prevents simultaneous duplicate submissions. Its explicit credential handoff remains available until close; administrators must share it securely. The Create dialog accepts the root workspace UUID and the `internal` route alias, including its case variants. Both use the canonical root UUID for component, query and saved-operation scope, so switching between these routes preserves an unknown original CREATE without another POST. Personal and non-root workspaces, and sessions without an actor, do not expose Create. Server permissions and actor lifetime checks remain authoritative. Mounted regressions in `employee-creation-alias.test.tsx` cover these routes and retired-actor results. These Infrastructure forms distinguish a failed availability read from confirmed unavailability; **Check availability again** performs only a GET and cannot admit CREATE. Input, authorization and local recovery-storage failures have separate safe guidance. A bound non-admission receipt proves only that invocation stopped before claim: the original UUID, actor, email and name stay retained for inspection, including after generic errors. Unknown outcomes never clear intent or replay. Secure password generation failure leaves the existing value and visibility intact and offers manual entry in Create, row reset and reset-any-account forms; passwords never enter recovery storage. The directory defaults to active, verified accounts; **Include disabled accounts** changes only the existing active filter. A disabled row grants no restoration eligibility. See the [mounted regression tests](https://github.com/tutur3u/platform/tree/main/apps/infrastructure/src/app/%5Blocale%5D/%28dashboard%29/%5BwsId%5D/internal-accounts): `employee-creation-dialog.test.tsx`, `temporary-password-field.test.tsx` and `internal-accounts-client.test.tsx`. Ordinary messages explain the next action without requiring UUID, digest, revision or provider-state inspection. Advanced recovery retains technical observations and explicit audited CREATE adjudication for exceptional failures. Unknown CREATE never silently replays or receives a replacement operation. Legacy migration and retained mailbox adoption remain separate, and neither is authorized by Restore. These defaults cover the active Infrastructure forms; backend readiness, conflict, self-action and actor/workspace fences remain authoritative. Coverage includes `employee-creation-dialog.test.tsx`, `account-password-reset-dialog.test.tsx` and the restoration regressions below. Hosted login and production account delivery require separate acceptance by the release owner. ### Managed-access console The Infrastructure account directory exposes **Restore access** for other accounts. Opening the form automatically checks current state; only an active, managed, mailbox-ready canonical account with a confirmed provider ban and a RESTORE next action offers restoration. Creation recovery, adoption, conflicting or unconfirmed provider state and legacy migration have explanatory states without a restore button. This dialog never renames an account or implements stable-UUID legacy-domain migration. Confirmation requires the exact inspected account email. Every submit performs another uncached inspection and compares revision and operation before dispatch. The portable consumer retains the original expected revision and server operation UUID across pending results and dialog close/reopen. A lost POST response blocks another RESTORE in that dialog lifetime, even if a subsequent read has no operation. Pending or uncertain replies expose read-only inspection of the retained request; the form does not invoke reconciliation or offer another mutation for it. A latched revision/operation conflict remains visible and blocks subsequent mutations even after another inspection. The portable consumer's explicit reconciliation API is unchanged and remains separate from this ordinary form. It never automatically repeats RESTORE or reconciles on dialog open. No client-generated replacement UUID or blind POST retry is used. State is private and ephemeral; a new page lifetime recovers operations from the authorized persisted inspection rather than browser storage. RESTORE is enabled by default for authorized root administrators at the Web endpoint. Inspection does not advertise write availability. A capability-unavailable response therefore locks writes for the current dialog lifetime while preserving read-only inspection and any retained uncertain operation; it does not establish account absence. Session and permission denial retires actions until the page is reauthorized. Client actor lifetime checks surround each awaited stage, while the endpoint remains authoritative for current actor, root membership and permission. A successful POST alone is not displayed as restored. The console requires a separate GET showing the matching completed operation, original revision plus one, managed active registry, ready mailbox and confirmed active provider. Missing, malformed, mismatched or failed readbacks preserve uncertainty. Directory status and private management state remain separate observations. `employee-restoration-consumer.test.ts` covers revision/UUID fences, explicit reconciliation, unavailable capability, duplicate admission and revoked actors. `employee-restoration-dialog.test.tsx` covers rendered English/Vietnamese controls, automatic readiness, exact confirmation, inspection-only pending recovery and revision conflicts, replacement-operation denial, pending close/reopen, independent readback and actor replacement. These are synthetic source regressions. Exact-commit Infrastructure/internal-API CI and authenticated deployed session/provider/SQL acceptance remain separate; no runtime flags, account activation or migration are performed by the UI change. ### Fixed child-worker prototype The fixed child-worker transport remains unavailable until its protected SQL supplier and project readiness are independently qualified. The fixed transport prototype accepts only preflight, finalize and activation-confirm operations. Each request owns one terminable child and TLS connection; no shared pool, caller SQL, account password or inherited database configuration enters that boundary. The executor is shared through the server-only `@tuturuuu/inventory-core/infrastructure/employee-sql/process` leaf; only this leaf's dependency closure is framework-free. Original Infrastructure entry points remain compatibility entries, while the canonical raw worker and protocol are colocated under `packages/inventory-core/src/lib/infrastructure/employee-sql/`. Before binding the Web supplier, verify that the compiled route's `.nft.json` trace and resolved `fork()` target load the canonical worker, protocol, and runtime dependencies. Relocation requires qualification of the exact source and build with refreshed signed attestations, even when raw worker/protocol hashes are unchanged. The parent requires external Ed25519-signed project and execution attestations, including the exact worker and protocol hashes. Missing bindings deny before spawning. Ordered, same-connection catalog checkpoints validate the role, cluster, ledger, function bodies and effective privileges before effects and COMMIT. The parent records an uncertain commit before authorizing COMMIT; lost commit acknowledgement never authorizes a blind retry or replacement account ID. The process requests cancellation at 13 seconds and kills only its owned child at 14.5 seconds, reserving cleanup time within the qualification profile's 15-second budget. It waits for actual child closure. Client process/TCP drain controls do not establish server transaction rollback or row-lock release. Before wiring the supplier, qualify delayed connection/query/lock/COMMIT cases against disposable PostgreSQL, verify backend and lock drain, and verify the static worker/protocol assets in the exact hosted Next build and file trace. Source tests, schema assertions and signed synthetic fixtures cannot replace those gates or activate account creation. ### Legacy employee address migration The internal-accounts page has a separate legacy address migration dialog. Migration changes the original UUID's `@xwf.tuturuuu.com` address to the same localpart at `@tuturuuu.com`, preserving its identity and linked data; RESTORE instead re-enables a previously suspended managed employee at its existing address. Neither flow creates a replacement account. Migration does not repair verification or claim/provision somebody else's mailbox. It requires existing approved active source and destination mailboxes owned by the original UUID, email-provider readiness, revision zero and no CREATE/RESTORE registry ambiguity. A separate bounded exception supports a confirmed legacy account whose sole Google identity already verifies the exact canonical destination with matching provider ID/subject. The explicit Web `address-migrations/prepare` endpoint may first adopt an empty, unowned, disabled canonical personal mailbox, then requires committed ownership readback before a fresh migration binding. Quarantined, archived, populated, shared or owned mailboxes remain unavailable. This path needs no source mailbox and permits only GoTrue's one verified email identity addition while preserving the original Google identity/data exactly. Completion stores distinct actual before/after fingerprints. See the [supplier contract and qualification](../../build/development-tools/employee-address-migration). The Google provider and Web state-flow regressions plus the separate 30-assertion SQL packet cover this exception with the stated fixture boundaries. Web migration availability follows current root administrator permission, configuration and fresh SQL/provider readiness. Neither composition nor reauthorization consults an optional activation environment flag; unset or false legacy migration flag values do not block an otherwise authorized operation. The operator can supply the existing operation UUID before the first action; leaving it blank creates a new operation only for a new intent. The first inspect or explicit preparation freezes and retains the exact operation UUID, target UUID, source, destination and revision, including after denial, dialog reopening and same-session remount. The locked fields cannot mint a replacement operation. Mailbox preparation is an explicit, separate administrator action. It requires retyping the exact target UUID and both addresses and calls only the existing `address-migrations/prepare` endpoint. Neither inspect nor migrate silently prepares a mailbox. Preparation acknowledgement is shown separately and requires inspection before migration. Migration requires both exact address confirmations again and a fresh authorization/readiness inspection before its single request. Recovery distinguishes unattempted, prepared, uncertain inspection/preparation and dispatched migration receipts. Unknown preparation stays inspect-only until inspection positively observes exact readiness, which may unlock migration only. Denied, forbidden or invalid inspections never clear the preparation fence or allow another preparation. A dispatched migration, including an old bare recovery tuple, never regains dispatch permission, even after a ready or denied inspection. Unknown reads cannot remove either write fence. Independently observed completion is required. Recovery storage is scoped to actor/workspace and this browser session; changing actor/workspace retires the old workflow. No password or token is requested. This decision applies only to the Infrastructure operator surface and Web migration endpoints; CREATE/RESTORE keep their existing contracts. The `address-migration-session.test.ts`, `address-migration-dialog.test.tsx`, Web migration runtime tests and typed consumer tests cover these boundaries with fixtures. Hosted mail ownership/delivery, full-schema qualification, exact-commit CI and the named real account's preservation remain separate gates. See the [migration runbook](/build/development-tools/employee-address-migration). ### Employee POST origin boundary Web owns CREATE, RESTORE/reconcile and address-migration POST handlers behind Infrastructure's external rewrite. Next preserves the browser `Origin` while changing the destination Host, so the request URL alone cannot identify the browser's origin. A configured production Infrastructure origin is accepted only with a cryptographically verified app-session bearer targeted to `infra`. Forwarded host/protocol headers never grant this exception. Actor, root membership, permission and operation checks remain required independently. Foreign origins and cross-site fetch metadata remain denied. Direct Web requests retain their existing same-origin and non-browser bearer behavior. Migration continues to reject missing-origin cookie requests. No runtime flag is enabled by this boundary. `employee-request-origin.test.ts` covers signed tokens, wrong app and forged credentials, spoofed forwarding headers and all three active adapters; it does not certify production Auth, SQL or provider actions. ### Feedback schema admission The feedback schema candidate reuses the canonical employee registry. Staff eligibility requires an active registry tuple matching the confirmed current corporate email, no current ban and a Boolean employee-onboarding marker; the service-only wrapper delegates to the same private assertion used by inbox reads. A domain match alone grants no access. Reports remain private; ordinary actors receive only their own content-free receipt, and staff reads grant no management capability. This schema scope does not change employee CREATE or RESTORE rules. The active Web routes `/api/v1/product-feedback`, `/{id}` and `/eligibility` now bind the existing read factories to the schema-backed service. The staff inbox at `/{workspace}/feedback` and its navigation entry require fresh eligibility; workspace permissions alone do not grant access. English and Vietnamese views support title search, bounded cursor pages, inbox/resolved/archive filters and revision/updated/archive state. Detail text is rendered as plain text. The current contract is intentionally read only; no status mutations, media URLs or reporter identities are disclosed by the metadata/detail RPCs. A detail 404 or transient failure stays inside the selected report while the list remains usable; 401/403 hides the list and cached private detail. Other list/eligibility failures show a load error. Component regressions cover these distinctions. Navigation starts staff eligibility only after workspace permission succeeds, overlapping preference reads. Navigation and page share React request-scoped memoization, with no result retained across requests; scheduling/denial tests preserve the admission guard. `PRODUCT_FEEDBACK_STAFF_INBOX_ENABLED` remains default off. Auth and RPC reads share a ten-second invocation allowance, with the existing SQL three-second statement and 500 ms lock limits; there are no retries. `PT403` maps to a sanitized 403; schema/provider faults map to 503. Synthetic service composition regressions exercise current identity and SQL denials through the real PostgREST serializer; they do not establish hosted database or browser acceptance. Feedback CLI `--json` errors use one sanitized `{ error: { code, status, message } }` object on stderr, empty stdout and exit code 1, including invalid arguments and missing credentials. Argument validation precedes configuration and network work. Provider details and credentials never enter this projection. Regression coverage: `feedback-entry.test.ts` drives the actual source entrypoint; `feedback.test.ts` also covers client-construction and transport failures. Feedback availability remains off pending separate activation. The default-off hosted feedback profile retains the original105 rollback assertions plus correlation31, for106 after the canonical employee foundation. Its eligibility fixture constructs synthetic identities without personal membership by temporarily suppressing only the named personal-workspace bootstrap trigger, then requiring its exact normal state restored before assertions. This does not prove canonical employee signup lacks membership; that behavior remains a separate parent audit item. The retained older277 result does not qualify this new278 profile or causal phase. The profile flag selects test packets only; every disposable profile applies the full tracked migration snapshot. It does not activate feedback or prevent schema application in other profiles, whose results do not qualify feedback coverage. See the [schema qualification runbook](/build/development-tools/employee-schema-qualification) for the exact hosted profile, full-history requirement and remaining evidence. The optional default-OFF feedback causal profile tests eight single-removal counterfactuals only in the owned hosted database, requiring exact targeted RED, transaction rollback/catalog equality and restoration GREEN. Synthetic tests and source hashes are not SQL proof. The domain-regexp check has a structural redundancy disposition, not observed mutation coverage; ACL/registry availability remain ordinary denial coverage. No production staff predicate or feature flag is changed. ### Rejected first employee creation The default for an unknown employee CREATE is to retain the original operation and prohibit replay. In the root Infrastructure account dialog, the original administrator may explicitly adjudicate a terminal rejection of the first Auth attempt at unknown/version 2. This exception requires retained evidence, an explicit no-request-in-flight attestation and independent SQL absence checks; nearby logs or absence alone do not prove rejection. A failed adjudication remains bound to its original event, evidence digest and identity tuple. After a fresh matching eligible readback, the administrator may explicitly retry that same adjudication and attest again. A committed readback enables the original CREATE without another adjudication; fenced or changed identities remain blocked. Old references without the retained tuple remain inspectable but cannot be retried. The recovery helper and rendered dialog regressions cover this distinction. A committed one-time repair preserves the UUID, intent and history and returns reserved/version 3. Matching audit readback unlocks a fresh password field for one explicit normal CREATE submission with the original UUID, email and name. Neither closing the form nor losing the repair response clears that reference. Uncertain repairs stay fenced for explicit readback. Later phases, revoked operations and other actors/workspaces are excluded. Route, recovery helper and dialog regressions enforce this rule; the optional disposable Web session fixture exercises authenticated adjudication and CREATE end to end. Older interrupted employee creation requests without a saved browser reference can be loaded under **Advanced recovery** using their original operation ID. The server supplies and validates the account identity. Loading only observes the request; a fenced or unavailable request cannot create a replacement account. Audited recovery still requires explicit administrator action and a fresh temporary password. Regression coverage: `employee-original-operation-resume.test.ts`. ### CLI recovery of an existing employee CREATE Web exposes the explicitly scoped `employees/operations/{operationId}/cli-recovery` GET/POST endpoint for the original administrator when browser recovery is unavailable. This exception accepts only a verified platform CLI access bearer with CLI origin and current required-MFA proof. It freshly checks the corporate domain, persisted root MEMBER membership, `manage_internal_accounts`, and confirmed, unbanned current Auth identity. It grants no CLI access to ordinary employee creation, availability, management, RESTORE or address migration routes and issues no new credentials. Every request binds the path to `Idempotency-Key`. GET inspects only an owned original operation; missing, foreign and fenced operations cannot be resumed. POST accepts only `adjudicate` with the existing full explicit attestation and evidence digest, or `resume` with the complete freshly read `retry_ready` version-3 tuple and a fresh validated temporary password. Resume preserves the original actor, operation, target UUID, email, name and audit identity; it rereads that tuple before the durable claim. Unknown/pending state never admits replay. Adjudication never automatically submits CREATE. A lost acknowledgement requires inspection and retention of the same event/evidence reference. Use the portable `inspectEmployeeCliRecovery` and `submitEmployeeCliRecovery` helpers from `@tuturuuu/internal-api/infrastructure`. Operator setup and the single-dispatch CLI authentication example are in the [employee qualification runbook](/build/development-tools/employee-cli-recovery). Regression coverage: `employee-cli-recovery-authorization.test.ts`, `employee-cli-recovery-boundary.test.ts`, `employee-cli-recovery.test.ts`, and the existing Infrastructure authorization/runtime and rejection boundary regressions. Hosted authentication, exact Web build CI and account delivery remain separate release-owner checks. ## Managed employee profile edits The existing **Edit profile → Save profile** action supports active, consistently managed employee names and usernames. The service authenticates the current request; SQL independently requires a fresh root employee administrator. The atomic transaction updates the managed registry, public display name, private full name and canonical personal mailbox display/sender names, advancing the registry revision and appending an immutable rename receipt. It never changes UUID, email, Auth credentials, grants, membership or account access. Administrator Infrastructure profile edits allow any nonempty username length; public self-service remains 5–32 characters. The guarded managed and unmanaged SQL entrypoints provide this exception. Changed usernames retain lowercase letters, digits and underscores, must start with a letter or digit, and reject reserved names. NULL clears the username. PostgreSQL B-tree key size and storage limits still apply; this is not a guarantee that arbitrarily large values fit. The managed SQL writer uses an ungranted backend/transaction/actor/target/handle capability with fresh root authority. Only `users.handle` and `handles.value` length enforcement admits that exception; bare service writes cannot mint it. Exact reservation ownership, uniqueness and cooldowns remain enforced. Previously owned handles stay reserved, unlike the legacy unmanaged writer's release of old handles. NULL or foreign reservations are never adopted. Failed writes roll back profile, mailbox, handle, quota, revision, capability and receipt changes. Legacy unmanaged Infrastructure edits use a separate private atomic SQL entrypoint with fresh root authority, exact target/email admission and nullable name/username preimage comparison. Exact `@tuturuuu.com` eligibility includes disabled and unconfirmed targets. Managed registry, intent, onboarding, CREATE, RESTORE or address-migration evidence excludes this path. Its protected transaction context admits the same username length exception without bypassing syntax, reservations or quotas. The transaction releases only the target's previous owned handle and appends an immutable operation receipt; failures roll everything back. Independent operation inspection verifies committed current state after success or a lost acknowledgement, without another write. Legacy edits do not change managed names, mailbox state or employee provenance. Regression coverage includes `employee-unmanaged-profile-usernames.sql` and the versioned legacy HTTP packet. Pending/inconsistent employees and unresolved CREATE, RESTORE or address operations cannot be renamed. Original CREATE names, intent and journal remain historical evidence. Terminal active CREATE observations expose the real current `displayName` and, after complete SQL provenance/readiness proof, a separate `creationDisplayName` binding the original request. Pending and unknown operations retain strict original-name proof. A rename makes old RESTORE revision receipts stale; a new RESTORE uses the new revision and current name. Lost acknowledgements are inspected by their original internal operation reference, without a second write or a new confirmation step. Regression coverage: `employee-managed-profile.sql`, `employee-admin-profile-usernames.sql`, managed-profile transport checks, and read-only CREATE observation/client negative controls. Hosted qualification and production acceptance are separate delivery gates. # Inventory Source: https://docs.tuturuuu.com/platform/applications/inventory How inventory.tuturuuu.com is wired as the inventory satellite app, operator console, public storefront, checkout reservation, and audit operations surface. Inventory lives in `apps/inventory` and runs locally through Portless at `https://inventory.tuturuuu.localhost`. Production is intended for `https://inventory.tuturuuu.com`. ## Web sale item picker Record sale shows one selectable row per product, unit and warehouse identity. Overlapping loaded pages and repeated stock entries do not create duplicate rows or add stock quantities. The later provided complete product snapshot supplies amounts, prices and archived status; page position does not guarantee chronological freshness, so server sale validation remains authoritative. Distinct products with the same name and distinct unit/warehouse variants remain separate. Equal name or price sort results use stock identity as a stable tie-breaker. Season eligibility and scheduled pricing continue to apply after catalog normalization, and server permissions and checkout validation remain authoritative. The item list occupies the space remaining beneath the search/filter controls and above the pinned sale footer. It scrolls within that space on mobile and desktop, rather than stopping at a fixed list height. This behavior is covered by `sale-create-items.test.ts`, `sale-product-picker.test.ts` and the mounted `sale-product-picker-layout.test.tsx` regression; DOM checks do not establish browser layout or customer-flow success. Web Record sale uses two tabs: Items and Checkout. Checkout combines editable cart, revenue details and review in compact accordions; collapsed headers retain item counts, selected revenue targets and confirmation readiness. Missing revenue or sale-name details open the Revenue section on entry. Going back to Items keeps those edits and quantities. Confirmation remains an explicit action and retains current season-price validation, required revenue fields, in-flight submission protection, and the same request ID when retrying an uncertain response. The Items list loads another page when its end is within 200 pixels of the actual list viewport, including when the initial list is shorter than that viewport. Raw page progress rearms loading even when filters/season eligibility hide every new item. Only one page request starts at a time. A thrown or resolved query error stops automatic loading and leaves a localized manual Load more retry. Filters and tab/dialog closure disconnect the old observer; manual loading also works when IntersectionObserver is unavailable. Regression evidence lives in `sale-picker-pagination.test.tsx` and `season-sale-integration.test.tsx`; these mounted tests do not establish live browser/provider success. ## Native Inventory presentation The Flutter mini-app keeps Overview, Products, Sales, Manage and Storefront destinations in the established floating navigation. Overview retains Sell and Create product as visible workflows; it does not repeat the dock destinations. Manage keeps every setup collection and its permitted add action visible without a second counter dashboard. Season selection, creation, editing and archiving remain visible on Sales. Product summaries show metadata once and keep each quantity and price beside its warehouse and unit. Quantities across different units are not summed. A null quantity means unlimited stock and must never display as zero or a low-stock warning. An absent stock row is shown as unconfigured. The Products low-stock count covers loaded search results, not the entire catalog. Native presentation does not change server permissions, mutation authorization, or canonical workspace membership. Existing pending-sync indicators remain attached to their owning rows. Native Overview analytics describe the loaded sample, not workspace-wide totals. Receipt activity groups unique dated receipts by device-local day for the selected 7- or 30-day view and reports records without dates separately. Loaded revenue keeps currencies separate, excludes pending receipts and duplicate IDs, and reports receipts without an explicit currency. Stock summaries keep incompatible units separate and preserve unlimited versus unconfigured stock. These rules are covered by `inventory_analytics_redesign_test.dart`. Manage opens dedicated catalog, sales-period and audit destinations. The native product and checkout forms retain their primary actions while options refresh; queued deletion rows retain their existing retry or manual-conflict controls. Verified permission hints remain isolated by account and workspace and are revalidated online; an online denial revokes them. Server authorization remains authoritative. `inventory_access_scope_test.dart`, `workspace_permissions_offline_test.dart` and the Inventory editor tests cover scope changes, revocation and pending writes. Products, Sales and searchable forms submit through native search actions. An empty or whitespace-only submission closes search and clears the filter. A nonempty submission keeps results visible and dismisses the keyboard. Old shell search callbacks cannot replace the current query or update an unmounted owner. `inventory_search_submit_test.dart` covers mounted shell and standalone form submissions; the shared Apps search policy uses the same empty-query behavior. The product editor preserves unlimited stock when an unrelated field is edited. Leave quantity empty to represent unlimited stock; finite zero remains zero. Manage clears previous rows and add controls when the authenticated account or selected workspace changes. An open setup sheet cannot submit into a different account/workspace scope. These UI safeguards supplement server authorization. Native Inventory writes accept pending setup selections. The dependency queue creates referenced owners, manufacturers, categories, units, warehouses and Finance categories before product writes, then applies their authoritative IDs. The earlier sync-first guard is replaced by automatic prerequisite handling. Repository regressions in `inventory_setup_dependencies_test.dart` cover both product writes, all six pending references, nullable optional fields and resource-scoped mappings. Legacy already-completed setup creates whose old API returned no ID cannot retroactively recover local-ID provenance; that historical limitation remains tracked in [issue #5737](https://github.com/tutur3u/platform/issues/5737). This compact presentation does not establish parity for web commerce checkout, payment providers, stock ledgers, scoped analytics, costing or effective season pricing. Those require their existing authorized API contracts and separate verification; today's catalog price must not replace historical sold prices. ## Automatic offline dependency sync implementation Native period-sale creation omits optional notes when none were entered; it does not send JSON null to the non-nullable optional server field. Empty entered notes remain an empty string. A confirmed invoice remains a successful sale if local cache invalidation fails; the client attempts scoped resource-cache eviction without repeating the financial write. Server validation and authorization failures still propagate. The native HTTP regressions in `inventory_api_mutation_contract_test.dart` cover omitted, empty and populated notes, durable receipts and post-acknowledgment cache failure. Read contracts are covered by `inventory_api_read_contract_test.dart`. These client safeguards do not change server permissions, season pricing or stock accounting. Native create and supported Inventory mutations persist their operation identity before any HTTP request, including successful online creates. Online callers receive the authoritative acknowledged resource; offline or temporarily blocked callers keep their optimistic representation. This source behavior becomes available after the matching mobile/API/database release has passed its gates. A queued product write must wait for referenced Inventory owners, manufacturers, categories, units, warehouses and Finance categories to be created, regardless of enqueue order. Dependencies and mappings belong to the authenticated account, workspace and resource type. Related mutations retain their per-entity order; independent ready writes can progress. Missing prerequisites and dependency cycles remain visible without deleting queued work. Account/workspace purges serialize with durable pending writes. Malformed encrypted pending records remain visible as conflicts while independent valid records can continue; corrupt reference metadata cannot abort the entire replay pass. Online sale-period clearing preserves the nullable server response. These boundaries are covered by `offline_inventory_review_regression_test.dart` and the foreground verification regressions in `offline_inventory_verification_test.dart`. Product create permits at most 500 stock rows. Stock quantity and minimum quantity must be integers, matching their database columns; unit prices preserve fractional major currency amounts. `offline-create-schema.test.ts` and `inventory-offline-create.sql` cover these limits for the offline create contract. The dedicated setup/product/period create contract returns authoritative IDs and deduplicates the original operation identity before the client retries an uncertain create. The client never falls back to a legacy create route when this contract is missing. After acknowledgment, the queue persists the mapping and rewrites dependent paths/payload references. An acknowledged create must not be sent again because mapping storage or cache refresh failed. Automatic sync must preserve user data across account switches, restart, retry and temporary network loss. A missing endpoint or RPC retains the mutation and retries with bounded backoff, connectivity, authentication and app-resume wakeups. Permission/domain failures, canceled/deleted prerequisites, malformed payloads, ambiguous creators and cycles remain stored with localized diagnostics; they cannot block unrelated ready work. Confirmed create and write acknowledgments survive restart before mapping/dequeue. Successful deletions persist resource-scoped tombstones, preventing stale mappings from restoring deleted resources. Automatic replay never invents a replacement for a canceled/deleted prerequisite. Typed references never rewrite free text, workspace path segments or query parameters. The dedicated online scheduled-sale journal keeps its existing receipt recovery contract. Legacy invoices without an inventory period do not gain retry safety; an uncertain legacy invoice remains retained for review, rather than duplicating its financial effects. Wallets retain their existing stable client-ID contract. Regression evidence is in `offline_inventory_replay_test.dart`, `offline_dependency_graph_test.dart`, `offline_inventory_mutation_test.dart`, `finance_repository_inventory_dependency_test.dart` and `offline_changes_sheet_test.dart`; these synthetic tests do not establish native airplane-mode or authenticated production acceptance. The app is a registered Tuturuuu satellite app. It uses Tuturuuu app-session auth for `targetApp: 'inventory'`, exposes local `/verify-token` and `/api/auth/verify-app-token` handoff routes, and forwards fallback `/api/*` traffic to centralized `apps/web` APIs. Keep protected inventory, payment, Stripe Connect, checkout, Square Terminal, and audit mutations behind `apps/web` so provider secrets, bot protection, request logging, and Observability stay centralized. Workspace-scoped Inventory APIs in `apps/web` must authorize through `authorizeInventoryWorkspace`, which accepts the Inventory app-session cookie and then performs workspace membership and permission checks. Authenticated dashboard and workspace API access is permission-driven; do not hide these routes behind the `ENABLE_INVENTORY` workspace config. Keep public storefront delivery separate, since published storefront behavior may still apply storefront-specific rollout gates. Do not use `resolveAuthenticatedSessionUser`, `supabase.auth.getUser()`, or request-scoped Supabase clients as the primary auth gate for these routes, because the satellite clears local Supabase cookies and forwards app-session cookies instead. The operator console uses the same collapsible Tuturuuu satellite workspace structure as the Tasks, Finance, Calendar, and CMS apps: dashboard layouts should keep server work to auth/workspace gating, then render client-side views backed by TanStack Query and `@tuturuuu/internal-api`. Do not reintroduce a separate Inventory-only app shell or direct client Supabase reads for protected workspace data. The local token verifier must call the central Web verifier with `verificationBaseUrl: WEB_APP_URL`; Inventory protected routes require both the host-only Inventory app-session cookie and the Web-issued app-session cookie used by rewritten `apps/web` API requests. Local-only token validation will create a redirect loop back to platform login. Current-user bootstrap APIs such as `/api/v1/users/me/default-workspace` and `/api/v1/users/me/profile` must keep `inventory` in their app-session audience allowlist, or `/dashboard` will accept the local handoff cookies and then bounce back to Web auth after the bootstrap request returns `401`. Public storefront routes live at `/store/[storeSlug]` inside `apps/inventory` and are intentionally exempt from the operator auth proxy. They should only read published storefront data through `apps/web` public APIs and should create checkout reservations through the central `apps/web` RPC wrapper. Do not add storefront CRUD, reservation writes, invoice finalization, or settlement writes directly to `apps/inventory`. ## Local Development Use: ```bash theme={null} bun dev:inventory ``` The package `dev` script runs Portless. For direct port debugging, run `apps/inventory` with `bun dev:app`, which falls back to port `7815`. ## Product Boundary Inventory starts with workspace-scoped surfaces for: * product catalog categorization by type, owner, manufacturer, talent, supplier, channel, and fulfillment policy * stock movement and reservation ledgers * bundle and promotion availability controls * checkout fee visibility for processing fees, Tuturuuu platform fees, conversion fees, settlement estimates, and net payout * payment and inventory audit streams * Stripe Connect readiness for B2B2C sellers who link their own Stripe account The commerce storefront extension adds: * operator routes for overview, catalog, stock, bundles, storefronts, checkouts, sales, setup readiness, and audits * public routes for `/store/[storeSlug]`, `/store/[storeSlug]/products/[listingId]`, cart, checkout, and order status * private-schema tables for storefronts, listings, bundles, checkout sessions, checkout lines, reservations, Square connection state, terminal checkout identifiers, and settlement ledger entries * commerce money (listing/bundle prices, checkout amounts, settlement, and costing) stored in integer minor units of the row currency (cents for USD, whole units for JPY/VND); convert with `@tuturuuu/utils/money` and enter with the shared `MoneyInput`. See the Polar storefront and Square Terminal integration runbooks. * Square Terminal settings for workspace app credentials, OAuth/manual tokens, location selection, device pairing, webhook verification, and commerce actions that send, cancel, and reconcile terminal payments after local stock is reserved. The same settings surface provides guarded Square catalog and stock import, additive publish, and conflict-aware two-way sync. Provider deletion is deliberately unsupported. * service-role-only RPCs for creating reservations, releasing or expiring reservations, materializing checkout TTL expiry, and linking a completed checkout to a `finance_invoice` * private sales periods that group both invoice-backed and completed checkout sales into seasons, conventions, campaigns, or other operating windows. A sale has at most one period assignment, while archived periods keep their historical assignments and remain available for reporting. * durable Finance source entries for every completed real-provider checkout, refund, Square chargeback hold/release, and audited provider-unavailable adjustment. Simulated checkouts are excluded. Manual Inventory sales continue using their existing Finance invoice path. The Inventory Sales list shows whether a provider checkout is linked, pending, refunded, or disputed and links to the corresponding Finance transaction or reconciliation entry. Unlinked entries are operationally visible but do not affect Finance ledger totals. New commerce tables belong in the `private` schema, not `public`. Public and satellite clients must go through Inventory-owned `apps/inventory` APIs plus `@tuturuuu/internal-api`; direct Supabase client access to these tables is not part of the contract. Protected workspace routes must authenticate and normalize the workspace with the request-scoped client before any private-table read or write, then use server-only database access or service-role RPCs behind `apps/inventory`. Convention selling uses an explicit sales period. The sale dialog defaults to an in-range configured period, otherwise the sole current scheduled period. An intentionally configured current legacy default is honored; legacy-only implicit selection requires a choice. Overlapping or absent current periods require a choice. Operators can explicitly choose the legacy unassigned workflow; it is never an automatic fallback. New periods default to effective season pricing with explicit dates and an IANA timezone. Prices are major currency units, scoped to product, unit, warehouse and period. Price intervals start at local midnight; end dates are inclusive. A new later interval closes an earlier interval without replacing its amount. Price history does not alter stock quantity, legacy catalog prices or completed invoice snapshots. Existing periods remain in legacy pricing mode until deliberately changed; the migration performs no price backfill. Priced period dates, timezone and pricing mode are immutable. Use another period to change those boundaries. Scheduled selling filters eligible active products and requires a current price in the workspace currency. Gaps and missing prices prevent checkout; another season's prices are never borrowed. Price controls require catalog-management permissions. Managers can preview upcoming selected-season prices in the price history, labeled with effective dates and the season timezone. Viewing a future price does not make it eligible for checkout at the current sale time. Offline/stale carts require refresh and review, with no silently changed total. Period-linked invoice creation validates the quote and eligibility and captures line amounts, stock changes and period assignment in one private transaction after the existing Finance authorization checks. Historical invoices, reports and completed commerce orders continue using their saved amounts. Price receipts survive invoice deletion as durable idempotency tombstones: deleted requests cannot recreate a canceled sale, and restored invoices retain the same receipt and captured prices. Legacy manual periods keep six-decimal major-unit precision, existing currency fallback and existing finite overselling behavior. Provider listings/promotions and their minor-unit prices are intentionally unchanged. Scheduled manual sales keep the existing custom-price workflow's no-promotion semantics and require a matching wallet currency. The additive migration must be installed before scheduled controls can be used. Missing tables/RPCs fail closed; never apply production migrations manually. Sales-period clients use the Inventory-owned routes below. Keep these paths in the Flutter API mapping check whenever the mobile catalog changes: * `GET/POST /api/v1/workspaces/:wsId/inventory/sales-periods` * `PATCH/DELETE /api/v1/workspaces/:wsId/inventory/sales-periods/:periodId` * `GET/POST /api/v1/workspaces/:wsId/inventory/sales-periods/:periodId/prices` * `PUT /api/v1/workspaces/:wsId/inventory/sales/:saleId/period` * `GET /api/v1/workspaces/:wsId/inventory/sales?period_id=:periodId` Core stock and setup data lives in private inventory tables: `private.inventory_products`, `private.inventory_units`, `private.inventory_warehouses`, `private.inventory_suppliers`, `private.inventory_batches`, `private.inventory_batch_products`, `private.inventory_owners`, `private.inventory_audit_logs`, and `private.inventory_manufacturers`. Dashboard pages and APIs should access them through server-owned `apps/web` routes. Prefer private-schema RPCs for product catalog, low-stock, and other repeated join-heavy reads; call them with `createAdminClient().schema('private').rpc(...)` from server code. Manufacturers are a normalized workspace setup entity matching the supplier-style management model. Products store only `workspace_products.manufacturer_id`; API responses may still include `manufacturer` as a display name for older clients. Legacy imports that send package/product manufacturer text should upsert the trimmed name into `private.inventory_manufacturers`, assign the resulting `manufacturer_id`, and avoid writing manufacturer text back to `workspace_products`. Bundle components are a workspace-scoped stock contract. When creating or updating a bundle, every component's product, unit, warehouse, and stock row must belong to the same workspace as the bundle. The database trigger on `private.inventory_bundle_components` enforces that invariant for direct writes, and the checkout reservation RPC re-checks the same workspace before locking stock. Do not trust stored bundle component UUIDs as already authorized input. Do not hardcode Stripe fee schedules as durable truth. The checkout estimator is for quoting and operator review; production reconciliation should persist the estimate shown to the seller and then reconcile it against actual Stripe balance transaction fee rows after settlement. ## Deployment Inventory has dedicated Vercel workflows: * `.github/workflows/vercel-preview-inventory.yaml` * `.github/workflows/vercel-production-inventory.yaml` These workflows use `VERCEL_INVENTORY_PROJECT_ID`. Add that secret before enabling hosted deployments for `inventory.tuturuuu.com`. Price history references durable product/unit/warehouse identities instead of the replaceable stock tuple. Combined product edits and dedicated stock edits for priced products commit metadata, tuple changes and movement history together; a failed edit leaves no partial metadata or phantom stock movement. Scheduled period scope/rule replacement takes the same period lock as checkout in a single transaction. Search filters never invalidate cart quotes; selecting the current period is a no-op. Price authoring forwards the scoped catalog pagination so products after the first page can be selected without preloading another dialog. Atomic pricing-aware edit routing also applies before a product has its first authored price and while a legacy period is being converted. The database transaction resolves current state under its locks; routing never relies on an earlier mode or price-existence read. Checkout, stock editing and price authoring acquire stock tuples before the product row to avoid mixed legacy/scheduled lock inversion. If price support is installed but its edit transaction is unavailable, edits fail closed instead of falling back to separate writes. On native mobile, an active user Save may open the existing verification dialog for that record only. Background replay never opens verification dialogs or persists verification tokens. Canceling that dialog leaves the already-requested Save queued: the editor closes and the item keeps its existing **Waiting to sync** indicator, rather than claiming server completion or creating another operation on a repeated Save. The original operation identity is reused on later replay. Explicitly discarding the queued change cancels unsent work; canceling verification does not discard it. Account changes and real membership or permission denials retain their original error behavior. Regression coverage lives in `offline_inventory_verification_test.dart` and the mounted product editor tests. ### Transactional offline create validation Automatic dependency sync uses a separate deduplicated create contract. Its private receipt and all resource, stock, history and audit effects commit together. Reusing an operation identity with different input is rejected. The service authorizes the captured account, workspace and resource permission before invoking this contract; customers cannot read receipts or forge actors. `.github/workflows/inventory-offline-contract.yaml` validates the exact PR head by applying the complete schema in a disposable hosted database, running strict `inventory-offline-create.sql` pgTAP assertions, and generating `packages/types/src/supabase.ts` as an artifact. A queued workflow is not schema or type parity evidence. The native scheduler persists operation identities before sending, orders prerequisites, and rewrites acknowledged references automatically. An unavailable server contract retains queued work and retries automatically; it never falls back to an unsafe legacy create. Release readiness still requires the exact-source database, generated-type, native, and owning-app CI gates. The new `/api/v1/workspaces/:wsId/inventory/offline-mutations` POST route accepts an operation identity, an explicit create kind and a strictly validated payload. Current workspace membership and the owning kind permission are checked on every retry, even when a prior receipt exists; a revoked grant denies the request. Inventory stock initialization additionally requires stock permission. Finance categories use `create_transactions` and accept Inventory or Finance app sessions. Receipt identities have no TTL or automatic pruning. Recognized responses carry `X-Tuturuuu-Offline-Contract`. Missing RPC/schema returns `OFFLINE_CONTRACT_UNAVAILABLE` with 503; an unknown route on an older deployment has no contract header. These rollout gaps must retain the operation and retry automatically, while a marked domain 404 or permission 403 is permanent. The native implementation must never fall back to an undeduplicated create POST. Offline catalog create receipts intentionally have no time-based expiry. Their private storage lasts for the owning actor/workspace lifetime and is removed by those owners' deletion cascades. The mobile outbox has no maximum retry age, so pruning a receipt could replay an old successful create as a new resource. Changing this default requires a coordinated client/server operation expiry and server rejection of expired operation IDs before receipt deletion is enabled. This rule covers inventory catalog/setup create receipts, including stored request/response data; it does not introduce a financial transaction retention policy. The private table is inaccessible to ordinary client roles. Receipt replay and payload-identity checks in `inventory-offline-create.sql` guard the current behavior; lifecycle pruning remains intentionally disabled. An offline create RPC that completes with a malformed receipt or a different resource returns sanitized HTTP 500 `OFFLINE_CONTRACT_RESPONSE_MISMATCH`. No row IDs are exposed, and the same operation remains retained for operator review. A missing RPC function/schema remains HTTP 503 `OFFLINE_CONTRACT_UNAVAILABLE`. These distinguish a server receipt defect from contract availability; the client must not blindly resend a new create identity. `offline-create-route.test.ts` covers malformed receipts and resource mismatches. ## Merge products and warehouses The Inventory web operator exposes **Merge products** above the product table and **Merge warehouses** in Setup. Select a source and destination, review the current stock/reference preview, choose which metadata and overlapping price, minimum-stock and revenue-share configuration to keep, then acknowledge the destination before confirming. Both update/manage access, inventory deletion permission, and stock adjustment permission are required. This is ordinary authenticated inventory work; it is not an offline bulk download and must not require download-protection setup. Product selectors search active products independently of catalog filters and the currently loaded table page. Each selector supports loading more results. Warehouse stock reviews resolve product names by identity; confirmation waits for those names and offers a retry when they cannot load. On narrow screens the dialog fills the viewport, keeps its actions pinned, and scrolls the review body; long record names wrap rather than push conflict details outside the screen. Failed previews and failed merges retain the dialog and require a fresh acknowledgment before retrying. Regression coverage: `inventory-merge-dialog.test.tsx` and `inventory-merge-product-options.test.tsx`. Different unit structures are supported: separate units remain separate stock rows and quantities are never converted between units. Matching finite stock quantities are added exactly once. Two unlimited rows remain unlimited. Mixed unlimited and finite rows are blocked until the operator explicitly adjusts that stock outside the merge. Active reservations and active/upcoming scheduled source prices block the operation. Duplicate provider mappings, storefront variants, bundle identities and other live unique identities are shown as conflicts and must be resolved in their owning editor before merging; no provider objects or conflicting records are silently deleted. The global price policy also chooses the associated minimum stock and revenue-share settings together. The merge is one database transaction with a current preview version and a durable receipt. Concurrent stock/reference changes invalidate the preview; retries of the same source, destination, version and policies do not add stock again. Live references move to the destination while invoices, movement history, scheduled price quotes and checkout snapshots keep their original IDs and values. Source products are archived; source warehouses are removed from new selectors. Their durable rows remain available for historical detail. Future writes using a merged source identity, including stale web/mobile/offline/provider writes, reject atomically with a refresh-and-select-the- destination message. Historical updates that do not change their identity remain allowed. Authorized invoice recovery is the narrow exception for historical inserts: it restores only exact saved invoice lines with their original product and warehouse IDs, after invoice recovery permissions and workspace checks. A private transaction capability restricts this exception to the restoration RPC; new sales and stale writes cannot use it, including by setting a restoration flag. Restoring history does not consume the combined stock again. New merge preview and apply require the final schema readiness RPC and the active warehouse view, restoration guard and writer guards. During deployment before gated migrations, ordinary warehouse reads may use the legacy table only after the existing product-form-options RPC successfully returns a valid warehouse array without an `inventoryMergeSchema` marker. Alias-table creation atomically replaces that RPC to return `aliases-v1`; marker presence and a missing active view fail closed. Cached PostgREST metadata cannot substitute an older server function body, and a missing-table API error alone cannot establish legacy schema. Merge actions remain unavailable until readiness succeeds. Merge transactions reserve the buckets containing the source and destination identities. Identity coordination uses 16 stable buckets per resource kind and workspace, so large imports and stock/reference updates acquire at most 32 identity keys within one workspace instead of one advisory lock per record. Product/warehouse parents supply the authoritative workspace for all writers; a child row cannot choose a different namespace. Different workspaces have separate bucket namespaces. Two unrelated identities in the same workspace can share a bucket: when a merge holds it exclusively, that unrelated write safely returns retryable `55P03` rather than waiting or bypassing guards. Retry after the merge finishes. Actual workspace removal exempts its deletion cascades because that workspace can no longer merge; ordinary deletes in a live workspace retain all identity and merged-source guards. Reference inserts, updates, deletes and checkout state changes coordinate with those identities; unrelated workspace CRUD and other buckets remain available. Contention fails fast and requires refresh/retry. Row-lock waits are limited separately; this does not establish a deadline for the entire RPC. New reference tables must install both the merged-reference guard and the identity writer coordination trigger before merging can use them. Offline creation receipts retain their original identity rather than creating a replacement resource; operators must refresh and select the destination for new work. The feature does not execute automatic background merges, convert units, merge external provider objects, or delete historical identities. New tables that reference inventory identities must install the merged-reference guard as part of their migration; the preview enumerates current foreign keys and fails closed for unsupported composite relationships. Regression evidence lives in `inventory-merge.sql`, `inventory-merge-restoration.sql`, `inventory-merge-concurrency.mjs`, `inventory-merge-readiness.sql`, the merge API route tests, internal API transport tests, and Inventory merge-dialog tests. Deployment needs the additive merge and repair migrations before execution becomes available; missing merge RPCs return a temporary-unavailable response while existing warehouse lists continue working on an older schema. The existing `inventory-offline-contract.yaml` CI lane applies the full isolated schema and runs offline create plus merge, alias pagination, restoration and readiness pgTAP fixtures. Its testing phase also runs the three-client `inventory-merge-concurrency.mjs` executor; SQL or concurrent-writer failures fail the gate and still pass through owned-stack cleanup. ## Merge sales seasons and periods The Inventory web operator can merge two sales periods using an explicit, paged review. Both preview and apply require workspace membership, `update_invoices` and `delete_invoices`, plus `manage_inventory_catalog` or legacy `update_inventory`. The Rust migration source mirrors this contract; Web remains the live API. The sales page derives the merge action from this complete role contract on the server; missing or failed permission lookup hides the action. Catalog management alone does not expose it. Regression coverage includes `sales/page.test.tsx` and `sales-periods-panel.test.tsx`. Flutter has no season-merge action in this change. The destination keeps its name, dates, time zone and pricing mode. Description and the complete product eligibility rule set each require a source/destination choice. With live or upcoming source prices, calendar or pricing-mode differences block merging. Without those prices, calendar differences are reviewable and the destination calendar remains unchanged. Chosen eligibility rules must allow every source price product; the review displays excluded-price counts before approval. Overlapping schedules require either blocking the merge or explicitly keeping the destination overlap. The latter imports only uncovered source intervals with fresh price IDs, clipped to merge time. Every original price, captured invoice quote and invoice line stays intact; stock and movement history are unchanged. Reporting assignments move to the destination, with their original classification stored relationally. Replaced destination product rules retain every original rule identity, label and timestamp in the receipt, including rules beyond the first preview page. The source is archived as a durable alias, excluded from new selectors, and cannot be edited, restored or newly referenced. Trusted invoice recovery and offline request replay continue to use the original durable quote. Prices, overlap conflicts and product rules are paged at 50 rows per section. Confirmation requires explicit policies, resolved human labels and review of all pages. A server token binds actor, workspace, both periods and a frozen cutoff, and expires after five minutes. Its fingerprint hashes affected mutable planning rows and retained-history ownership counts without aggregating historical payloads. Refresh after expiry, concurrent changes, unresolved conflicts or a retryable readiness failure; acknowledgment is invalidated before retry. Merge apply and child writers coordinate on only the selected period rows. Assignment/price writers recheck aliases after waiting; unrelated periods and workspaces remain available. Missing schema/guards return 503 and perform no merge. Historical provenance foreign keys are deferred until transaction end, allowing whole-workspace cascade ordering while rejecting standalone removal of referenced periods and original/imported quotes. Regression coverage: `inventory-season-merge.sql` exercises actual migration, history, trusted recovery and transaction-boundary constraints; `inventory-season-merge-concurrency.mjs` uses independent PostgreSQL clients for writer rejection and unrelated CRUD. Both run in the existing Inventory contract CI lifecycle, including official type generation and owned cleanup. Route, internal API transport and dialog tests cover authorization, tokens, errors, policies, expiry and pagination. App builds and Rust tests require exact-commit CI; source and mocked UI checks do not establish browser or production behavior. The season test’s cascade control retains quote tombstones after trusted invoice deletion. Deletion of a workspace that still contains a live invoice has a separate parent-schema defect: the invoice product unit foreign key attempts a null default against a non-null column. An isolated parent-schema control reproduced that error before applying the new season migrations. The expected-defect control is retained as local validation evidence, outside the passing season CI contract. Season merging does not alter that existing schema. Season merge previews and review pages are scoped to the authenticated Inventory actor and workspace. Switching accounts resets the visible review and prevents late responses from completing another account's dialog. Before submitting, Inventory saves one immutable actor/workspace-bound request (original source, destination, policies and preview token) in the current tab's session storage. Storage failure prevents sending. Closing/reopening or reloading that tab restores an unresolved request; it is never replaced by a fresh preview. For an ambiguous response or authentication pause, Check original merge replays the exact saved request. The existing apply RPC checks its committed receipt before preview expiry or merged-source validation, so a lost success response can be reconciled after the token expires or source is archived. A conflict or validation response allows fresh review only for a first known attempt. Once uncertainty exists, even a retry 409 retains the original request: a lock timeout can occur while its earlier transaction still commits. Recovery is manual and per tab; it does not claim a cross-tab journal or new offline navigation support. Mounted regressions in `use-season-merge-recovery.test.tsx` and `use-inventory-season-merge-review.test.tsx` cover scope changes, late responses, remount recovery, storage failures and lost-response/conflict/receipt sequences with synthetic transport. Existing isolated SQL receipt replay coverage remains the database evidence; browser/device and exact-CI evidence remain separate. ## Cleared checkout search The web Inventory sale dialog restores its loaded product catalog immediately when product search is cleared. Category and warehouse choices and scheduled price eligibility derive from those restored products. A previous empty response or in-flight response cannot replace the unfiltered catalog. During a new search, loaded products remain searchable while the server query settles. This changes search selection only; current season price validation and existing cart snapshots remain authoritative. Mounted regressions in `season-sale-integration.test.tsx` cover settled empty search, clearing an in-flight search, restored category/warehouse choices, and the original scheduled prices in the submitted sale. The checkout category and warehouse pickers use the full authorized workspace form options, independent of product search, pagination, or season price coverage. Selecting a category queries its products across pages; search results have their own pagination. Categories with no currently eligible stock remain selectable and show an empty product result rather than disappearing from the picker. The mounted unloaded-category regression uses synthetic data outside the initial catalog page and verifies searchable choices, category-scoped requests, and the second page. This does not imply every product has a current scheduled price. ### Merge concurrency lock boundary The independent-client cascade fixture requires zero unexpected advisory locks. It permits only the bigint key computed by `hashtextextended('employee-address-reservations', 0)` in `ShareLock` mode and `objsubid=1`. This shared employee-admission lock protects a separate boundary: workspace deletion invokes the profile default-workspace FK's `SET DEFAULT` update, whose statement-level admission trigger runs even for an empty update. The full-schema PostgreSQL failure classified that lock separately from the cascade warehouse's inventory identity key. The fixture explicitly accounts for the permitted lock. Every other key, mode, and two-integer namespace remains forbidden, including real inventory identity locks held alongside permitted admission. Its 28-check plan preserves the original 22 cases and adds six disposable PostgreSQL controls: a zero-row profile update that takes shared admission, a real inventory lock beside it, an unexpected shared key, exclusive employee admission, the same key halves in the two-integer namespace, and rollback cleanup of all control locks. Controls roll back without changing profile rows or weakening employee admission. An unexpected lock retains a bounded failure-only TAP diagnostic: the tested unexpected count, disposable backend PID/assigned transaction ID, and at most 32 granted advisory tuples with truncation and barrier/permitted/forbidden labels. A later snapshot never replaces the tested count; diagnostic errors cannot hide the boundary assertion. Passing the boundary adds no diagnostic query or wait. Require the exact candidate's Inventory offline create database contract workflow to pass all 28 checks plus season concurrency, strict SQL packets, generated types and owned cleanup. Local source and mock checks do not establish PostgreSQL acceptance. Compare the retained same-schema failing count with the new candidate before declaring the fixture repair verified. ## Checkout expiry invalidation receipts The Cron Control checkout Worker remains off by default. When separately enabled, it records owed storefront invalidations and sends workspace batches to Inventory's cron-authenticated checkout-expiry POST adapter. That adapter reports each workspace as successful only after its throwing invalidation helper finishes. One workspace failure does not prevent attempts for the other workspaces. Worker obligations clear only on matching success receipts; failed or missing receipts remain owed, and three unsuccessful attempts quarantine the item without discarding it. Quarantine and incomplete work keep the slot unsuccessful and preserve the durable job stop budget. The existing GET expiry path and other best-effort cache helpers retain their behavior. The route and Worker checkout-expiry regressions cover receipts, partial progress, backpressure and bounded retries; hosted cache freshness remains separate acceptance. See the [processor runbook](/build/devops/cloudflare-processor-migration). # Square POS with Tuturuuu Inventory Source: https://docs.tuturuuu.com/platform/applications/inventory-square-pos Start here to connect Square Terminal, synchronize catalog and stock, rehearse safely, and launch in-person payments. Tuturuuu connects a Storefront order to a physical **Square Terminal** through Square's Terminal API. Customers shop in the Tuturuuu Storefront, Inventory reserves the stock, and the Square checkout is dispatched to the selected Terminal. An authorized operator can also send or cancel an eligible reserved checkout from Commerce. Square processes the card-present payment and reports the result back to Tuturuuu. > [!NOTE] > > This integration uses Square Terminal in Connected Mode. It does not launch > the Square Point of Sale mobile app, and connecting an account never creates > a charge by itself. ## Choose your guide > **[Set up the account and counter](/platform/applications/inventory-square-pos/customer-setup)** > > A non-technical walkthrough for the Square owner, Inventory admin, and > counter operator. > **[Rehearse in Sandbox](/platform/applications/inventory-square-pos/sandbox-testing)** > > Test success, cancellation, timeout, offline behavior, stock release, and > duplicate webhooks without moving real money. > **[Synchronize catalog and stock](/platform/applications/inventory-square-pos/catalog-sync)** > > Import from Square, publish from Tuturuuu, compare both sides, and resolve > conflicts without deleting Square objects. > **[Launch Production safely](/platform/applications/inventory-square-pos/production-launch)** > > Pair the physical Terminal, run one owner-approved live sale, and apply the > go/no-go gate. > **[Operate and verify payments](/platform/applications/inventory-square-pos/operations)** > > Read the Payments hub, reconcile transactions, and understand reservation > and webhook behavior. > **[Troubleshoot safely](/platform/applications/inventory-square-pos/troubleshooting)** > > Follow symptom-based recovery steps without double-charging or corrupting > stock. ## How one payment travels ```mermaid theme={null} sequenceDiagram autonumber actor Buyer participant Store as Tuturuuu Storefront participant Inv as Inventory participant Sq as Square participant Term as Square Terminal Buyer->>Store: Submit the cart Store->>Inv: Create checkout and reserve stock Inv->>Sq: Create Square order and Terminal checkout Sq->>Term: Show the itemized payment request Buyer->>Term: Complete or cancel payment Term-->>Sq: Report the result Sq-->>Inv: Deliver signed webhooks Inv->>Inv: Complete sale or release reservation Inv-->>Store: Show final order status and receipt evidence ``` Tuturuuu finishes a sale only after it can reconcile a verified Square payment. If checkout creation fails, the buyer cancels, Square reports failure or expiry, or the local reservation expires, Tuturuuu releases the reserved stock. ## The Payments control center Open: ```text theme={null} https://inventory.tuturuuu.com//payments ``` The page is read-only by default. Use the compact edit control only when you intend to change settings or start a catalog synchronization. | Payments section | What it answers | | - | - | | **Connect & set up** | Is the selected Square environment connected, signed, located, and routed to a device? | | **Catalog sync** | Which products and variations are linked, where they originated, and which conflicts need review? | | **Test & verify** | Did a provider checkout create one transaction with the expected amount, status, and evidence? | ## Sandbox and Production stay separate ```mermaid theme={null} flowchart LR A["Square Sandbox seller"] --> B["Sandbox token, webhook, location, simulator ID"] B --> C["Tuturuuu Sandbox rehearsal"] C -->|"All exit checks pass"| D["Create a separate Production connection"] D --> E["Production token, webhook, location, physical device"] E --> F["One approved low-value live sale"] ``` | Sandbox | Production | | - | - | | Test seller, credentials, objects, and simulator device IDs | Real seller, credentials, catalog, location, and physical Terminal | | No real card or Square hardware | Real card-present processing and possible fees | | Safe place for demo CRUD, retries, cancellations, and timeouts | Change only approved records and run only approved payments | | No physical receipt | Verify the actual Terminal and printed or digital receipt | > [!WARNING] > > Never copy a Sandbox token, object ID, location ID, webhook signature key, or > simulator device ID into Production. Square keeps the environments isolated, > and Tuturuuu checks that the saved connection matches the selected > environment. ## Safety contract Tuturuuu provides these protections: * Square settings and synchronization controls start in read-only mode. * Checkout readiness fails closed when the connection, webhook key, location, or device is missing. * Square catalog synchronization is additive and never deletes or archives Square catalog objects. * Duplicate and out-of-order Square webhooks are reconciled idempotently. * A reserved checkout expires after 15 minutes; cancellation, failure, and expiry release its stock. * A Production charge requires a person to send a real order and a buyer to finish payment on the Terminal. People still own these decisions: * which Square seller, location, catalog records, and device belong to the workspace; * whether a Production sync or payment is authorized; * the amount, card, refund policy, and staff member for the first live test; * business, banking, tax, tip, receipt, and hardware configuration in Square. ## Definition of fully working Call the integration ready only when all of these are true: 1. Sandbox connection shows all five setup checks complete. 2. The Sandbox test matrix passes for success, cancel, timeout, and offline simulation, with stock changing exactly once in every path. 3. Catalog links are visible and have no unexplained conflict or error state. 4. Production uses its own OAuth connection, webhook subscription, location, and paired Terminal. 5. One owner-approved low-value Production sale matches in Tuturuuu, Square, the Terminal receipt, stock, and finance exactly once. 6. Counter staff know the stop-and-reconcile procedure for an uncertain payment. For implementation details and automated coverage, use the [Square Terminal engineering runbook](/build/devops/square-terminal-integration). # Synchronize Square catalog and stock Source: https://docs.tuturuuu.com/platform/applications/inventory-square-pos/catalog-sync Import, publish, and compare products, variations, prices, and physical counts without deleting Square catalog objects. Tuturuuu links an Inventory product/unit/warehouse combination to a Square item variation at the selected Square location. The link stores both sides' last known state so two-way sync can distinguish a safe one-sided change from a conflict. > [!NOTE] > > Synchronization controls are locked by default. Open **Payments → Catalog > sync**, review the selected environment and linked records, then use the > compact edit control to enable an intentional sync action. ## Choose the right direction ```mermaid theme={null} flowchart TD Q{"Where is the trusted change?"} Q -->|"Square only"| A["Import from Square"] Q -->|"Tuturuuu only"| B["Publish to Square"] Q -->|"Unsure or both systems are active"| C["Two-way sync"] C --> D{"Both sides changed the same link?"} D -->|"No"| E["Apply the one-sided change"] D -->|"Yes"| F["Pause as review conflict"] ``` | Action | Use it when | Result | | - | - | - | | **Import from Square** | Square is the current source of truth or this is the first Sandbox discovery | Imports items, variations, prices, and physical counts; creates or updates local links | | **Publish to Square** | The approved change was made in Tuturuuu | Batch-upserts Tuturuuu items and variations, then writes physical counts at the selected location | | **Two-way sync** | Staff use both systems or the source is uncertain | Applies safe one-sided changes and marks simultaneous edits for review | > [!WARNING] > > Confirm **Sandbox** or **Production** before every sync. A Production catalog > sync changes the real seller catalog and inventory counts even though it does > not charge a card. ## Non-destructive Square behavior Tuturuuu deliberately does not call a Square catalog delete endpoint and does not archive Square catalog objects as part of sync. * Square-only variations remain attached when Tuturuuu updates a known item. * A Square-side deletion marks the local link as **Square deletion preserved** for review; it does not delete the local product or stock. * A simultaneous local and remote edit becomes **Review conflict**. * A failed row stays visible as **Sync error** with its last error. * Only records that the operator explicitly synchronizes are created or updated. ```mermaid theme={null} flowchart LR Local["Tuturuuu product + unit + warehouse"] <-->|"link hashes"| Link["Catalog link"] Link <-->|"Square item variation"| Remote["Square catalog"] Remote -. "remote deletion" .-> Review["Preserve link and request review"] Review -. "never cascades" .-> Local ``` ## What is synchronized | Tuturuuu | Square | Notes | | - | - | - | | Product name and description | Catalog item name and description | Trimmed display data; review branding before Production publish | | Unit or sellable variant | Item variation | One product can have several variation links | | SKU | Variation SKU | Use stable, unique SKUs where possible | | Price and currency | Square Money amount and currency | Exact sub-unit prices import directly, including USD 8.10 and three-decimal currencies such as BHD | | Warehouse stock row | Physical inventory count at selected location | The chosen Square location is part of the routing context; Tuturuuu Inventory stores whole-unit counts | | Link origin and last hashes | Link metadata in Tuturuuu | Supports conflict detection and observability | Do not manually multiply or divide prices before sync. Enter and review the human-readable amount in Tuturuuu; the integration converts it to Square's currency-aware integer Money representation. If USD 10.00 appears as USD 0.10 or USD 1,000.00, stop and investigate before another sync. > [!NOTE] > > Tuturuuu Inventory stores major-unit prices with exact decimal precision and > converts them to Square's currency-aware integer Money amount at the provider > boundary. Physical stock remains whole-unit inventory. A fractional stock > count is still held for review instead of rounded. > **Why do older rows say Ready to retry?** > > Those links were imported before cent-level Inventory prices were supported. > Square was not changed and the previous local price was preserved. Open > **Manage sync**, choose **Import from Square**, and run one read-only import. > Tuturuuu applies the exact Square price and clears the legacy hold. ## Safe first synchronization **1. Verify the environment and location** Open **Payments → Connect & set up** and read the Square summary. Confirm the environment, seller connection, and location. Return to **Catalog sync** and confirm the same environment badge. **2. Start with one clearly labeled demo item** In Sandbox, use a unique demo name and SKU. In Production, use an owner- approved item and review its current Square record before any action. **3. Import from Square first** For a seller with an existing Square catalog, choose **Import from Square**. Review the summary and linked record list before publishing anything back. **4. Inspect every linked row** Match the Tuturuuu product, Square item and variation name, SKU, shortened variation ID, origin, status, and last synchronized date. A processed count is not proof; the visible linked row is the evidence. **5. Publish a controlled Tuturuuu change** Change one field on the demo record, then choose **Publish to Square**. Verify the exact field and physical count in the Square Dashboard. **6. Run two-way comparison** After both one-way directions work, choose **Two-way sync**. Review any conflict rather than repeatedly syncing until it disappears. ## Read the sync summary | Metric | Meaning | | - | - | | Products processed | Item-level records inspected or changed in the run | | Products created | New Tuturuuu products created from Square | | Variations changed | Variation links imported or published | | Stock rows changed | Physical inventory counts imported or published | | Needs review | Simultaneous edits or records that require an operator decision | | Square deletions preserved | Remote deletions detected without local deletion | Counts describe operations, not unique products. One imported product can update both its variation and its physical stock row, so five linked products can legitimately produce ten imported changes. Use the linked-record list to count actual relationships. ## Link statuses | Status | Meaning | Safe next action | | - | - | - | | **Linked** | The last known states agree | No action unless a new business change is approved | | **Ready to retry** | A legacy import safely held a cent-level Square price | Run **Import from Square** once; Square remains read-only and the exact price is applied locally | | **Review conflict** | Both sides changed since the last shared state | Compare Square and Tuturuuu, choose the authoritative value, then run one directional sync | | **Sync error** | A Square or validation request failed | Read the row error, fix credentials/data, and retry only that intended direction | | **Square deletion preserved** | The linked Square object is absent or deleted | Ask the owner whether to recreate/publish or intentionally leave it disconnected; do not delete the local product | ## Webhook-driven updates The webhook subscription includes: * `catalog.version.updated`, which asks Tuturuuu to reconcile catalog changes; * `inventory.count.updated`, which asks Tuturuuu to reconcile physical counts. Square might not emit an inventory event when a count is written to the same value it already had. To verify this path in Sandbox, change a demo count to a different value and then restore it intentionally. Webhooks can be duplicated or delivered out of order. A duplicate event should not create a duplicate product, link, stock change, or checkout. ## Conflict-resolution worksheet For each conflict, record: ```text theme={null} Tuturuuu product and unit: Square item and variation ID: Environment and location: Last synchronized at: Tuturuuu name / SKU / price / count: Square name / SKU / price / count: Approved source of truth: Approver: One-way sync selected: Final values verified in both systems: ``` Never solve a price or stock conflict by deleting the Square object. Preserve the audit trail and apply one approved direction. ## Production catalog gate Before enabling Production sync actions: * the Square owner confirms the seller and location; * Sandbox import, publish, two-way, and conflict tests pass; * all demo names and SKUs are unmistakable; * the visible price and currency match exactly on both sides; * the physical count belongs to the selected location; * every linked row is **Linked** or has a documented review decision; * the operator understands that Production sync changes real catalog and stock data but never deletes Square objects. # Set up the Square account and counter Source: https://docs.tuturuuu.com/platform/applications/inventory-square-pos/customer-setup A non-technical, role-based walkthrough for connecting a Square seller to Tuturuuu Inventory before accepting payments. This guide prepares the Square account, Tuturuuu workspace, webhook, location, and in-person hardware route. Start with the safe Sandbox checks even when the store already owns a Square Terminal, Square Reader, or Tap to Pay device. > [!WARNING] > > Do not paste credentials, tokens, application secrets, or webhook signature > keys into chat, tickets, or documents. Enter them only in the Square settings > editor inside the intended Inventory workspace. ## Who should be present | Role | Owns | Does not need | | - | - | - | | **Square account owner** | Seller authorization, business settings, locations, banking, taxes, tips, receipts, and approval for a live test | Tuturuuu engineering access | | **Inventory workspace admin** | Payments setup, environment selection, catalog links, Storefront checkout mode, and transaction verification | The owner's Square password after OAuth is approved | | **Counter operator** | POS app sign-in, Reader or Terminal connectivity, paper, and the controlled first sale | Developer Console access | | **Technical helper** | Square application, OAuth redirect, webhook subscription, and diagnosing rejected events | Permission to run a live charge | One person can hold several roles, but the Square owner should explicitly approve the Production seller, location, item, amount, and payment card. ```mermaid theme={null} flowchart TD Owner["Square owner authorizes the seller"] --> Admin["Inventory admin saves the connection"] Helper["Technical helper configures OAuth and webhooks"] --> Admin Admin --> Choice{"Counter hardware"} Choice --> Reader["Phone / tablet + Reader: Square POS app"] Choice --> Terminal["Standalone Terminal: Terminal API pairing"] Reader --> Operator["Counter operator prepares the device"] Terminal --> Operator Operator --> Gate["Owner approves one controlled live sale"] ``` ## Prepare the account and hardware Have these items ready before opening the setup editor: * a Square seller in a country and currency supported by Square; * owner access to the [Square Developer Console](https://developer.squareup.com/apps); * an Inventory workspace where you can manage Payments and Storefronts; * a Square location dedicated to or clearly associated with this counter; * either a phone or tablet with the latest Square POS app and a connected Square Reader/Tap to Pay, or a standalone Square Terminal with current software; * reliable Wi-Fi or Ethernet without a browser-based captive portal; * a clearly named Sandbox demo product with known price and stock; * a clearly named, low-value Production test item for the later go-live check. Review Square's official [Terminal setup guide](https://squareup.com/help/us/en/article/6535-set-up-square-terminal) and [hardware network requirements](https://squareup.com/help/us/en/article/8348-set-up-network-requirements-for-square-hardware) before the launch day when using standalone Terminal hardware. For a phone or tablet, review Square's [Point of Sale mobile web guide](https://developer.squareup.com/docs/pos-api/build-mobile-web). ## Choose the correct hardware path Square exposes these devices through different APIs. Choosing the correct path prevents the most common setup failure. | What the customer has | Tuturuuu checkout mode | Setup in Inventory | Does it appear under Refresh terminals? | | - | - | - | - | | Phone/tablet running Square POS with Bluetooth Reader or Tap to Pay | **Square POS app + Reader** | Register the displayed POS callback URL, save the Production location, and open the Storefront on that phone | **No.** The phone's name and device ID are informational | | Standalone Square Terminal or Square Handheld receiving remote prompts | **Square Terminal** | Create a Tuturuuu Terminal API pairing code and save the paired device | **Yes** | > [!NOTE] > > A Square POS device ID such as a phone installation ID is not a Terminal API > device ID. Do not paste it into the Terminal dropdown. Tuturuuu opens Square > POS on the phone instead, then verifies the returned Square Order and card > Payment before completing inventory. ## Prepare event staff access Do not share a full workspace administrator account at the counter. In **Settings → Members & roles**, choose **Invite member**, then select **POS operator — start payments only**. The first limited POS invitation performs one confirmed, atomic access migration: 1. every current workspace member receives the explicit **Workspace Admin (preserved)** role; 2. the member-wide default **Admin** permission is disabled so new members do not inherit it; 3. Tuturuuu creates a **POS Operator** role containing only **Start POS checkout**; and 4. the pending invitation records that role so it is assigned as soon as the invited person accepts. The confirmation panel lists the number of current members being protected and explains the resulting access. A POS operator can start an approved Square payment, but cannot edit products, stock, sales, payment settings, members, or roles. For multiple standalone Terminals, staff choose the **Payment station** in the Storefront checkout form. Tuturuuu validates that the selected device is a paired Terminal API device at the configured selling location before it reserves stock. Square POS App + Reader remains a same-device flow: open the Storefront on the compatible phone or tablet that should launch Square POS. > [!WARNING] > > Never use a public shopper account as event staff. The checkout API enforces > the POS permission server-side and rate-limits repeated dispatches; hiding the > button is not the security boundary. ## Open the correct Tuturuuu workspace 1. Sign in to [Inventory](https://inventory.tuturuuu.com). 2. Select the customer's workspace. 3. Open **Payments** in the sidebar. 4. Stay on **Connect & set up**. 5. Choose **Square POS**. 6. Confirm the environment badge before changing anything. The page shows five detected checks: ```mermaid theme={null} flowchart LR A["Application"] --> B["Connection"] --> C["Webhook"] --> D["Location"] --> E["Device"] ``` Use the compact **Edit Square settings** button only when you are ready to complete the next check. Stop editing afterward so accidental changes are less likely. ## Fast handoff when Production is preconfigured If a technical helper already prepared Production, do not paste or rotate the credentials again. Keep the page read-only and verify these visible facts with the Square account owner: * the environment is **Production**; * the masked connection and webhook checks are complete; * the location is the real owner-approved selling location; * **Catalog sync** shows the expected Production links and no unexplained conflicts; * the intended hardware path is clear. A phone/Reader path does not require a Terminal API device or Terminal webhook key; a standalone Terminal does. The customer can then skip credential entry and continue directly to the [Production hardware path](/platform/applications/inventory-square-pos/production-launch#choose-the-production-hardware-path). The owner still needs to confirm business, bank, tax, tip, and receipt settings inside Square. Tuturuuu cannot safely choose those business settings on the customer's behalf. ## Part 1: configure Sandbox **1. Create or select the Square application** Open the [Square Developer Console](https://developer.squareup.com/apps), create an application for the Tuturuuu integration, and keep the environment toggle on **Sandbox**. Use a recognizable name such as `Tuturuuu Sandbox`. In Inventory, choose **Sandbox**, enable editing, and copy the Sandbox Application ID and Application secret into **Square app credentials**. Save them before starting OAuth. **2. Register the OAuth redirect URL** Copy the **OAuth redirect URL** displayed by Inventory. In the Square application's Sandbox OAuth settings, add that exact HTTPS URL as an authorized redirect. Do not type the URL from memory. The scheme, domain, path, and trailing characters must match what Inventory displays. **3. Authorize the Sandbox seller** Choose **Connect OAuth** in Inventory. Sign in to or select the intended Sandbox test seller and approve the requested permissions. Return to Inventory and confirm the read-only connection summary shows a token ending in four characters. OAuth is preferred because the connection can refresh and the seller can revoke it. A manual Sandbox token is available for a controlled rehearsal, but it must still belong to the same application and environment. **4. Create the Sandbox webhook subscription** Copy the **Webhook notification URL** shown in Inventory. In the Square application's **Webhooks** section, create a Sandbox subscription with that exact URL and these seven events: * `device.code.paired` * `terminal.checkout.created` * `terminal.checkout.updated` * `payment.updated` * `oauth.authorization.revoked` * `catalog.version.updated` * `inventory.count.updated` Copy the subscription's signature key into Inventory and save. Send a Square test event and confirm its delivery returns a `2xx` response. Square can deliver the same event more than once, so duplicate delivery is expected and handled idempotently. **5. Select the Sandbox location** Refresh locations in Inventory and choose the test location owned by the Sandbox seller. Confirm its country and currency match the rehearsal. Catalog stock counts are associated with this selected Square location. **6. Select a Sandbox simulator device** Square Sandbox cannot pair real hardware through the Devices API. Paste a supported Terminal simulator device ID into the Sandbox device field and save it as the default. Start with the success simulator from Square's [current Sandbox test values](https://developer.squareup.com/docs/devtools/sandbox/testing#terminal-api-checkouts). > [!TIP] > > The Sandbox guide should now show **5/5 checks complete**. Continue with the > [Sandbox test plan](/platform/applications/inventory-square-pos/sandbox-testing) > before creating any Production connection. ## OAuth permissions Tuturuuu requests only the permissions needed for the Terminal, orders, payments, catalog, and inventory workflows: | Workflow | Square permissions | | - | - | | Seller and Terminal | `MERCHANT_PROFILE_READ`, `DEVICE_CREDENTIAL_MANAGEMENT` | | Orders | `ORDERS_READ`, `ORDERS_WRITE` | | Payments | `PAYMENTS_READ`, `PAYMENTS_WRITE` | | Catalog | `ITEMS_READ`, `ITEMS_WRITE` | | Inventory counts | `INVENTORY_READ`, `INVENTORY_WRITE` | If the customer declines a required permission, the corresponding readiness check or API action fails closed. Re-authorize the correct seller instead of adding a second unrelated token. ## Part 2: create a separate Production connection Do this only after Sandbox exit criteria pass. **1. Switch both systems to Production** In Square Developer Console, switch the application to **Production**. In Inventory, switch the Square setup guide to **Production**. Verify both environment labels before copying anything. **2. Repeat credentials, OAuth, and webhook setup** Save the Production Application ID and secret, register the Production OAuth redirect URL, authorize the real seller, and create a separate Production webhook subscription using the URL shown in Inventory. Save the Production signature key. Never reuse a Sandbox credential or key. **3. Choose the real selling location** Select the Square location that owns the counter, currency, receipts, tax, and reporting. Ask the Square owner to verify the location name before saving. **4. Prepare the in-person hardware** For Square POS app + Reader, install or update Square POS, sign in to the selected location, and connect the Reader or enable Tap to Pay. For a standalone Terminal, power it, install updates, load paper, and connect to the final counter network. Continue with the matching Production path. ## Connection review Before pairing, the read-only Production summary should show: | Field | Expected | | - | - | | Environment | Production | | Connection | Token ending in four characters | | Square application | The Production Application ID | | Location | The owner-approved counter location | | In-person device | POS app/Reader needs no Terminal ID; standalone Terminal is unconfigured until pairing | | Webhook verification | Signature key ending in four characters | If any row is unexpected, stop and correct it before creating a device code. Continue with the [Production launch guide](/platform/applications/inventory-square-pos/production-launch). ## Official Square references * [Square Sandbox overview](https://developer.squareup.com/docs/devtools/sandbox/overview) * [OAuth API overview](https://developer.squareup.com/docs/oauth-api/overview) * [Square webhooks overview](https://developer.squareup.com/docs/webhooks/overview) * [Connect Square Terminal to a POS application](https://developer.squareup.com/docs/terminal-api/integrate-square-terminal) * [Build a Point of Sale mobile web integration](https://developer.squareup.com/docs/pos-api/build-mobile-web) * [Point of Sale mobile web technical reference](https://developer.squareup.com/docs/pos-api/web-technical-reference) * [Square hardware network requirements](https://squareup.com/help/us/en/article/8348-set-up-network-requirements-for-square-hardware) # Operate and verify Square payments Source: https://docs.tuturuuu.com/platform/applications/inventory-square-pos/operations Use the Inventory Payments hub to monitor readiness, catalog links, transactions, reservations, and safe reconciliation. The Payments hub is the customer's control center for Square and Polar. It combines provider readiness, catalog-link observability, and recent transaction evidence without exposing secret values. Open: ```text theme={null} https://inventory.tuturuuu.com//payments ``` ## Read the overview first ```mermaid theme={null} flowchart LR A["Readiness score and next action"] --> B["Square links"] B --> C["Square tests"] C --> D["Verified webhook configurations"] D --> E["Connect & set up"] D --> F["Catalog sync"] D --> G["Test & verify"] ``` | Overview signal | What it means | What it does not mean | | - | - | - | | Square links | Visible Tuturuuu-to-Square variation links | Every linked value is correct; inspect status and values | | Square tests | Recent checkouts have Square status evidence | The physical Production Terminal is certified | | Verified webhooks | A Square connection has a saved signature key | Every Square delivery succeeded; check Square delivery history during incidents | | Readiness score | The detected setup and test prerequisites are progressing | The owner has approved a Production charge | ## Connect & set up The settings summary is intentionally read-only. It displays the environment, masked connection, application, location, default device, and masked webhook signature state. Use **Edit Square settings** only to perform an approved change. Tuturuuu opens a focused dialog with **App & OAuth**, **Connection & webhook**, and **Location & terminal** tabs. Before saving, read the environment label again. Close the dialog and verify the read-only summary after every change. Each incomplete setup accordion also opens the exact tab required for that step. The five setup checks are: 1. Square application credentials, or a ready manual connection. 2. A ready OAuth or manual token connection. 3. A saved webhook signature key. 4. A selected Square location. 5. A Sandbox simulator ID or Production paired device. Readiness fails closed when a required check is missing. ## Catalog sync The catalog panel shows: * selected Square environment; * last run status and time; * products, variations, stock, conflict, and preservation metrics; * every visible linked variation, including its Tuturuuu product, Square item, variation, SKU, shortened variation ID, origin, state, and last sync date; * row-specific errors when a link cannot synchronize. Sync actions remain locked until an operator chooses **Enable sync actions**. See [Catalog and stock synchronization](/platform/applications/inventory-square-pos/catalog-sync) before running a Production action. ## Test & verify Each recent provider row shows the customer or public order reference, provider, environment, provider status, observed time, amount, failure reason when available, and a receipt link when Square supplies one. The transaction view intentionally mixes Square and Polar evidence so a seller can verify all payment providers in one place. Use the provider badge and environment label before interpreting a status. ## Checkout and stock lifecycle ```mermaid theme={null} flowchart TD Cart["Cart submitted"] --> Reserve["Local checkout reserved for 15 minutes"] Reserve --> Dispatch["Square order and Terminal checkout created"] Dispatch --> Pending["Terminal checkout pending"] Pending --> Paid["Verified Square payment"] Pending --> Cancel["Buyer or operator cancels"] Pending --> Fail["Square failure"] Pending --> Expire["Terminal or local expiry"] Paid --> Consume["Reservation consumed, stock reduced once, sale booked once"] Cancel --> Release["Reservation released, no sale"] Fail --> Release Expire --> Release ``` | State | Operator interpretation | Stock behavior | | - | - | - | | Reserved | Tuturuuu is holding sellable quantity while checkout starts | Available stock is temporarily reduced | | Pending | Square has not produced a final result | Keep the reservation; do not create a replacement order | | Cancel requested | Square accepted cancellation but a final webhook may still be arriving | Wait and reconcile the same checkout | | Completed / paid | A verified Square payment completed | Reservation is consumed and stock changes once | | Canceled / failed / expired | No successful sale should be booked | Reservation releases and stock returns once | Checkout reads, new checkout creation, and the scheduled expiry sweep reconcile stale 15-minute reservations. Operators can also cancel an eligible Square checkout from the Inventory Commerce surface. ## Transaction reconciliation Use this procedure whenever the customer or operator is unsure whether a payment finished: **1. Stop new attempts** Do not resend, reload into a new order, accept a second card, or manually restore stock. Preserve the current checkout for investigation. **2. Read Tuturuuu evidence** Note the public order reference, provider, environment, status, observed time, total, failure reason, and receipt link. Record the current stock and reservation state. **3. Read Square evidence** In the matching Sandbox or Production Square Dashboard, search the same time, location, amount, and receipt. Determine whether a payment was completed, canceled, or absent. **4. Check webhook delivery** In Square Developer Console, inspect the matching environment's webhook delivery. A successful delivery receives `2xx`. A duplicate delivery is acceptable; different final business state is not. **5. Choose one final path** If Square shows a completed payment, reconcile that payment and do not retry. If Square proves no payment and the checkout is pending, cancel it or allow it to expire. Verify stock after the final status arrives. ## Duplicate and out-of-order webhooks Square may deliver the same webhook more than once and may deliver related events out of order. Tuturuuu verifies the signature against the exact webhook URL and raw request body, stores provider identifiers, and reconciles the event idempotently. A healthy duplicate-delivery result looks like this: | Evidence | Expected count | | - | - | | Square webhook delivery rows | One or more | | Tuturuuu checkout | One | | Square order / Terminal checkout / payment linked to it | One each | | Completion transition | One | | Stock consumption or release | One | | Finance sale | At most one | ## Opening, daily, and weekly checks ### Before opening the counter * Terminal is online, charged, updated, and has paper. * Payments shows the intended Production seller, location, and default device. * The latest Production webhook test or recent delivery is healthy. * No prior checkout is pending or uncertain. * High-risk catalog links have no conflict, error, or remote-deleted state. * The operator knows who owns refunds and incident escalation. ### During the day * Submit each order once. * Match the Terminal amount before the buyer taps a card. * Stop after any uncertain result; reconcile before another attempt. * Use Square's normal receipt and refund process. * Never change Production environment, location, or device during an active checkout. ### End of day * Compare completed Tuturuuu Square rows with Square Payments for the location. * Investigate pending, canceled, failed, and expired rows. * Compare sold quantities with Inventory stock and reservations. * Confirm finance entries are not duplicated. * Record any refund or chargeback workflow separately. ### Weekly * Review OAuth connection health and Square authorization status. * Check webhook delivery failures and retries. * Review catalog conflict, error, and remote-deleted links. * Confirm the selected Terminal and location still match the counter. * Re-run Sandbox regression tests after material app, catalog, or workflow changes. ## Escalation packet Send support this information without secrets: ```text theme={null} Workspace name and ID: Sandbox or Production: Square seller and location name: Terminal name: Tuturuuu order reference: Date, time, and timezone: Amount and currency: Tuturuuu status and failure reason: Square payment status and receipt URL, if present: Webhook event type, event ID, response code, and retry number: Stock before and after: Actions already taken: Screenshot with tokens and customer PII redacted: ``` For symptom-specific recovery, continue to [Troubleshooting Square POS](/platform/applications/inventory-square-pos/troubleshooting). # Launch Square POS or a physical Terminal Source: https://docs.tuturuuu.com/platform/applications/inventory-square-pos/production-launch Configure the correct Production hardware path, run one owner-approved card-present sale, and decide whether the counter is ready. Production launch is the only part of this guide that can move real money. It requires the Square account owner, an Inventory workspace admin, the intended Square hardware, and the counter operator to work through the same checklist. > [!WARNING] > > A Production payment can incur Square processing fees. Get explicit approval > for the seller, location, item, amount, card, operator, and refund owner before > creating the checkout. Tuturuuu never runs this test automatically. ## Launch gates ```mermaid theme={null} flowchart LR A["Sandbox exit criteria"] --> B["Production 4/5 preconfiguration"] B --> C{"Hardware path ready"} C -->|"Phone + Reader"| C1["POS callback registered"] C -->|"Standalone Terminal"| C2["Terminal paired: 5/5"] C1 --> D["Catalog, price, tax, stock reviewed"] C2 --> D C --> D["Catalog, price, tax, stock reviewed"] D --> E["Owner approves one live sale"] E --> F["Payment, receipt, stock, finance match"] F --> G["Open the counter"] ``` Do not skip a gate because the Sandbox test passed. Sandbox cannot prove the real seller, physical device, counter network, or receipt behavior. ## Preflight checklist ### Square owner * [ ] Legal business and bank details are complete in Square. * [ ] The intended selling location, currency, taxes, tips, and receipt settings are correct. * [ ] The Square application is in Production and authorizes this seller. * [ ] The owner approves one clearly named low-value test item and exact amount. * [ ] The owner decides whether and how the test will be refunded afterward. ### Inventory admin * [ ] The Payments page shows **Production**. * [ ] Application, connection, webhook, and location checks are complete. * [ ] The selected location matches the owner's intended counter. * [ ] The Production webhook has the required seven events and its test delivery returns `2xx`. * [ ] Catalog links, price, currency, tax, and stock are reviewed. * [ ] The intended Storefront uses **Square POS app + Reader** or **Square Terminal**, matching the physical hardware. ### Counter operator * [ ] The phone/Reader or standalone Terminal is powered, charged, updated, and ready for receipts. * [ ] Wi-Fi or Ethernet is stable and does not require a browser sign-in page. * [ ] A backup connection and Square login are available if the network fails. * [ ] The operator knows not to retry an uncertain payment. ## Choose the Production hardware path **Phone or tablet + Reader** Use this path for the customer's Square POS app, Bluetooth/contactless and chip Reader, or Tap to Pay. The phone never appears in **Refresh terminals**. **1. Select Phone or tablet with Reader** Open **Payments → Connect & set up → Square POS → Edit Square settings → Hardware & POS**, choose **Production**, then select **Phone or tablet with Reader**. **2. Save the selling location** Select the same Production location currently signed in on Square POS. A location mismatch is rejected by Square and by Tuturuuu verification. **3. Register the exact callback URL** Copy the read-only callback URL from Inventory. In [Square Developer Console](https://developer.squareup.com/apps), open the Production application, choose **Point of Sale API**, paste it into **Web Callback URL**, and save. Do not add, remove, or infer a trailing slash. **4. Prepare Square POS** Install or update Square POS on the phone, sign in to the saved location, and connect the Reader or enable Tap to Pay. The displayed phone name and Square device ID are only support evidence; they are not entered into Tuturuuu Terminal routing. **5. Enable the Storefront** Set the Storefront checkout mode to **Square POS app + Reader**. Open the Storefront on that same phone. When submitted, Tuturuuu opens Square POS with the exact minor-unit amount and card tender selected. Tuturuuu accepts the callback only when its random request state matches the reserved order. It then retrieves the returned Square Order and Payment and verifies completed status, card tender, location, currency, and exact amount before consuming stock. Cancellation releases the reservation. A missing or unverifiable online transaction ID stays in review and never reduces stock. **Standalone Square Terminal** Use this path only for a Terminal or Handheld that receives a remote Terminal API checkout prompt. ## Pair the physical Terminal **1. Open the Production setup** In the correct workspace, open **Payments → Connect & set up → Square POS** and select **Production**. Choose **Edit Square settings**, then open **Location & terminal**. The dialog separates physical Production pairing from the Sandbox simulator route and presents the four pairing steps in order. **2. Choose the location and name the counter** In step 1, choose the Square location that will receive this counter's in-person payments. In step 2, use a durable name such as `Front counter`, `Convention booth A`, or `Warehouse pickup`. The name should tell support which physical Terminal is receiving an order. **3. Create the pairing code in Tuturuuu** Choose **Create pairing code**. Tuturuuu asks Square's Devices API for a code with product type `TERMINAL_API` at the selected location. > [!WARNING] > > Do not create a generic device code in Square Dashboard. Dashboard codes > are not compatible with Terminal API Connected Mode. **4. Enter the code on the Terminal** Tuturuuu displays the code and its exact expiry. On the physical Terminal sign-in screen, choose **Use a device code**, then enter the code before it expires. If it expires, generate a new code in Tuturuuu; do not keep retrying the old one. **5. Wait for paired status** Square sends `device.code.paired`. In step 4, choose **Refresh terminals**, select the newly paired Terminal, and choose **Save as default terminal**. The Production setup should now show **5/5 checks complete**. Square's official pairing sequence is documented in [Connect a Square Terminal to a POS application](https://developer.squareup.com/docs/terminal-api/integrate-square-terminal). ## Activate the selling path 1. In **Settings → Members & roles**, invite each counter volunteer as **POS operator — start payments only**. Confirm the one-time preservation of existing member Admin access before sending the first limited invitation. 2. Open **Storefronts** in Inventory and select the intended storefront. 3. Confirm it belongs to the same workspace as the Square connection. 4. Select the checkout mode matching the hardware: **Square POS app + Reader** on the same phone, or **Square Terminal** for the paired standalone device. 5. Publish only the approved listings and bundles. 6. Place one non-payment test cart and verify the name, variant, quantity, tax, discount, currency, and total. 7. Keep **Payments → Test & verify**, Square Payments, and the physical Terminal visible during the first sale. For standalone Terminal, the signed-in operator chooses the intended payment station and Tuturuuu verifies its pairing and location before reserving stock and dispatching a Square Order and Terminal checkout. For POS app + Reader, Tuturuuu reserves stock, opens the Square POS app on the same compatible device, and verifies the returned provider records before completion. Never create a replacement order until the existing one is reconciled. ## Run one controlled live sale **1. Read the approval aloud** Confirm the seller, location, item, quantity, amount, currency, card owner, operator, and refund decision. Stop if any detail differs from the owner's approval. **2. Record the starting evidence** Write down the product's available stock, the Tuturuuu time, and the intended total. Open Square Payments before submitting the checkout. **3. Submit exactly once** Submit the Storefront checkout once. Wait for the itemized request on the selected Terminal. Do not double-click, reload into another order, or send a second request while the status is pending. **4. Complete the card-present payment** Use the owner-approved card and follow the Terminal prompts. Capture the printed or digital receipt according to the store's policy. **5. Match both systems** Compare the amount, currency, location, status, Square order ID, Terminal checkout ID, payment ID, and receipt evidence in Tuturuuu and Square. **6. Verify stock and finance exactly once** The checkout should be completed, its reservation consumed, available stock reduced once, and the finance sale recorded at most once. A duplicate webhook delivery must not repeat any of those changes. **7. Apply the approved refund decision** If the owner planned to reverse the test, use the store's normal approved Square refund process and reconcile the refund in both systems. Do not make a second charge to offset an uncertain first charge. ## First-sale evidence | Evidence | Pass condition | | - | - | | Tuturuuu checkout | One completed checkout for the approved cart | | Square order | One order with the matching items, tax, currency, and total | | Hardware evidence | One completed POS app order/payment, or one completed Terminal checkout, for the approved location | | Square payment | One completed payment for the exact amount | | Receipt | Printed or digital receipt matches the payment and location | | Inventory | Reservation consumed and on-hand changed once | | Finance | One sale entry when finance booking is configured | | Webhooks | Signed deliveries accepted; duplicates cause no duplicate state | ## Go/no-go decision ```mermaid theme={null} flowchart TD A{"Do all eight evidence rows match?"} A -->|"Yes"| B["Mark the counter ready"] A -->|"No"| C["Stop new Square orders"] C --> D["Reconcile the existing checkout"] D --> E{"Was money captured?"} E -->|"Yes or uncertain"| F["Use Square payment evidence; do not retry"] E -->|"No"| G["Cancel or allow the checkout to expire"] F --> H["Escalate with IDs and timestamps"] G --> H ``` The counter is **no-go** when any of these are true: * the Production environment or seller is uncertain; * the location, device, price, currency, or tax is wrong; * the webhook test is not accepted; * the Terminal is offline or shows a different account; * the prior checkout is still pending or its payment result is unknown; * stock or finance changed more than once; * staff do not know who owns reconciliation and refunds. Follow the [troubleshooting guide](/platform/applications/inventory-square-pos/troubleshooting) before accepting another order. ## Counter handoff message Copy this into the customer's Discord channel and replace the brackets: ```text theme={null} Square Terminal launch handoff Workspace: [workspace name] Square seller and location: [seller / location] Physical Terminal: [counter name] Launch owner: [name] Counter operator: [name] Completed: - Sandbox 5/5 setup checks - Success, cancel, timeout, offline, expiry, and duplicate-webhook tests - Catalog links and stock reviewed with no unexplained conflicts - Production OAuth, webhook, location, and Terminal pairing Customer action: 1. Confirm business, bank, tax, tip, receipt, and location settings in Square. 2. Approve one low-value item, exact amount, card, operator, and refund plan. 3. Keep Tuturuuu Payments and Square Payments open. 4. Submit the checkout once and complete it on the paired Terminal. 5. Reply with the Tuturuuu checkout ID, Square payment ID, amount, status, receipt result, stock result, and any error. Safety rule: if the status is pending or uncertain, do not retry. Stop and reconcile the existing checkout first. ``` After launch, give counter staff the [operations and verification guide](/platform/applications/inventory-square-pos/operations). # Rehearse Square Terminal in Sandbox Source: https://docs.tuturuuu.com/platform/applications/inventory-square-pos/sandbox-testing A complete, no-money test plan for connection, catalog, checkout, webhook, stock, cancellation, timeout, and offline behavior. Square Sandbox simulates Terminal API checkouts without a physical Terminal or real card. Use it to prove the workflow and failure recovery before any Production credential is saved. > [!NOTE] > > Square hardware cannot be paired to Sandbox. Tuturuuu uses Square's special > Sandbox Terminal device IDs to produce deterministic results. Sandbox > payments do not reach a bank and do not incur processing fees. ## What Sandbox can and cannot prove | Sandbox proves | Sandbox does not prove | | - | - | | Credentials, scopes, environment routing, Orders API, Terminal checkout payloads, webhook signatures, idempotency, catalog links, and stock transitions | The customer's physical Terminal, counter network, receipt printer, real seller configuration, or card-present approval | | Success, buyer cancellation, Square timeout, and an unresponsive Terminal simulation | A live refund, physical receipt, or bank settlement | | Isolation from Production data and money | That Production credentials or object IDs are correct | ## Create isolated demo data Use records that are unmistakably temporary and owned by the test: ```text theme={null} Product: [Tuturuuu Sandbox] Terminal checkout test YYYY-MM-DD SKU: TTR-SBX-YYYYMMDD Price: USD 1.00 Opening stock: 4 ``` Use a fictional customer name and email, or omit customer details. Square warns against storing personal information in Sandbox. Do not reuse a real customer's name, phone number, address, or card data. > [!WARNING] > > Do not delete or archive pre-existing Square records. Import or modify only > the clearly labeled demo item. Tuturuuu catalog sync never deletes Square > objects; any later manual cleanup in Square requires the account owner's > separate approval. ## Simulator device IDs Copy these from Square's current [Terminal API Sandbox test values](https://developer.squareup.com/docs/devtools/sandbox/testing#terminal-api-checkouts) into the **Sandbox device ID** field one scenario at a time: | Scenario | Device ID | Square result | | - | - | - | | Approved card | `9fa747a2-25ff-48ee-b078-04381f7c828f` | Completes a card payment up to USD 25 | | Buyer cancels | `841100b9-ee60-4537-9bcf-e30b2ba5e215` | Reports a canceled checkout | | Square timeout | `0a956d49-619a-4530-8e5e-8eac603ffc5e` | Immediately simulates checkout timeout | | Terminal unavailable | `da40d603-c2ea-4a65-8cfd-f42e36dab0c7` | Leaves the request unclaimed so it can be canceled or expire | Keep the test total at or below USD 25 for the standard success simulator. Square deliberately leaves larger attempts pending rather than treating them as an ordinary approval. ## Test flow ```mermaid theme={null} flowchart TD A["Save one simulator device ID"] --> B["Create one demo checkout"] B --> C["Observe Square Sandbox"] C --> D["Observe Payments > Test & verify"] D --> E["Verify reservation and stock"] E --> F{"Result matches the test matrix?"} F -->|"Yes"| G["Record evidence and continue"] F -->|"No"| H["Stop, reconcile, and troubleshoot"] ``` For every scenario: 1. Open **Payments → Connect & set up → Square POS → Sandbox** and save the intended simulator ID. 2. Confirm all five Sandbox checks are complete. 3. Confirm the demo Storefront uses **Square Terminal** checkout. 4. Open **Payments → Test & verify** in one tab and the Sandbox Square Dashboard in another. 5. Submit one checkout only. Do not double-click or start a second checkout while the first is pending. 6. Match the checkout ID, amount, currency, status, and timestamps across both systems. 7. Record the final stock and reservation result before changing the simulator. ## Required checkout matrix | Test | Expected Square evidence | Expected Tuturuuu evidence | Expected stock | | - | - | - | - | | **Approved card** | One completed Terminal checkout and payment | One completed checkout with Square order, Terminal checkout, payment, and receipt reference when available | Reservation consumed once; on-hand decreases once | | **Buyer cancels** | Terminal checkout becomes canceled | Checkout becomes canceled or released with the Square result recorded | Reservation released; available stock returns once | | **Square timeout** | Terminal checkout reports timed out | Checkout becomes expired/failed and is not recorded as paid | Reservation released; no sale ledger entry | | **Terminal unavailable** | Checkout stays pending until canceled or timed out | The same checkout remains traceable; operator can cancel rather than resend | Stock stays reserved while pending, then releases once | > [!WARNING] > > A pending result is not permission to send the order again. First cancel or > reconcile the existing Terminal checkout. Re-sending an uncertain order can > create a second payment request. ## Reservation expiry test Tuturuuu checkout reservations expire 15 minutes after creation. Expiry is materialized by the scheduled sweep and also reconciled during checkout reads and new checkout creation. 1. Use the unavailable Terminal simulator. 2. Create one checkout and verify the item becomes reserved. 3. Do not create a replacement checkout. 4. Cancel it through the Inventory Commerce action for a fast test, or allow the reservation to expire for the full expiry-path test. 5. Verify the checkout is no longer sellable as pending, the reservation is released, and stock returns exactly once. ## Duplicate webhook test Square can retry webhooks and does not guarantee delivery order. Tuturuuu uses Square event IDs and provider identifiers to reconcile duplicates safely. **1. Complete one successful Sandbox checkout** Record its Tuturuuu checkout ID, Square Terminal checkout ID, payment ID, stock before and after, and finance transaction if the workspace records one. **2. Resend a Square webhook delivery** In the Square Developer Console, open the relevant Sandbox webhook delivery and resend it once. Use the same event; do not create a second payment. **3. Verify idempotency** The webhook may appear twice in delivery history, but Tuturuuu must still show one checkout, one payment link, one completion transition, one stock change, and at most one finance sale. ## Catalog and stock rehearsal Run this after the checkout matrix so the payment flow and catalog flow can be diagnosed separately. 1. Open **Payments → Catalog sync**. 2. Enable sync actions with the compact edit control. 3. Choose **Import from Square** and verify the demo item appears as one linked Square variation. 4. Change only the demo item's name, price, or physical count on one side. 5. Run the matching one-way sync and verify the other side once. 6. Make different changes on both sides, run **Two-way sync**, and confirm the item becomes a review conflict instead of silently overwriting either side. 7. Restore the demo item through an intentional one-way sync after deciding which side is authoritative. An unchanged Square inventory count might not emit an `inventory.count.updated` event. Use an actual demo count change when validating that webhook, then restore the count deliberately. For the full data model and conflict rules, see [Catalog and stock synchronization](/platform/applications/inventory-square-pos/catalog-sync). ## Exit criteria Sandbox is complete only when: * all five connection checks are ready; * the seven webhook events are subscribed and a test delivery returns `2xx`; * approved, canceled, timed-out, and unavailable-device scenarios match the matrix; * duplicate webhook delivery does not duplicate payment, stock, or finance; * a 15-minute or explicitly canceled reservation releases correctly; * the demo catalog item is visible as a linked variation; * a two-sided edit becomes a review conflict; * no Production token, object, device, or payment was touched. ## Test evidence template ```text theme={null} Workspace: Square application and Sandbox seller: Square location: Tuturuuu demo product and SKU: Test date and operator: Approved checkout ID / payment ID / result: Canceled checkout ID / result: Timed-out checkout ID / result: Unavailable checkout ID / cancel-or-expiry result: Duplicate webhook event ID / final record count: Stock before: Stock after successful payment: Stock after cancel, timeout, and expiry: Catalog link count: Conflicts requiring review: Unexpected errors: ``` When every exit criterion passes, continue with [Production launch](/platform/applications/inventory-square-pos/production-launch). # Troubleshoot Square POS safely Source: https://docs.tuturuuu.com/platform/applications/inventory-square-pos/troubleshooting Diagnose connection, webhook, catalog, Terminal, checkout, and stock problems without deleting data or risking duplicate charges. The first rule is simple: if a Production payment is pending or uncertain, do not send it again. Reconcile the existing checkout before changing settings, stock, device, or Storefront configuration. ## Start here ```mermaid theme={null} flowchart TD A{"Was this Production?"} A -->|"No, Sandbox"| B["Record simulator ID and expected scenario"] A -->|"Yes"| C["Stop new payment attempts"] B --> D{"Is Square setup 5/5?"} C --> E{"Does Square show a completed payment?"} D -->|"No"| F["Fix the first incomplete setup check"] D -->|"Yes"| G["Inspect Square and Tuturuuu status"] E -->|"Yes"| H["Reconcile that payment; do not retry"] E -->|"No"| I{"Is the Terminal checkout pending?"} E -->|"Uncertain"| J["Inspect Square payment and webhook evidence"] I -->|"Yes"| K["Cancel or let the same checkout expire"] I -->|"No"| L["Verify reservation release and stock"] J --> H J --> K ``` ## Five-minute operator triage 1. Record the workspace, environment, location, Terminal name, order reference, time, timezone, amount, currency, and visible status. 2. Stop submitting new checkouts for the affected order. 3. Compare **Payments → Test & verify** with the matching Square Dashboard. 4. If Square shows a completed payment, treat it as paid and reconcile it. 5. If Square proves no payment and the Terminal checkout is pending, cancel the same checkout or allow it to expire. 6. Verify the reservation and stock after the final event. 7. Escalate with IDs, timestamps, and redacted screenshots if the systems still disagree. ## Connection and readiness > **Production shows 0/5 or 'No Square token saved'** > > This is expected for an unconfigured environment. Select Production, enable > editing, save the Production application credentials, connect the real > seller through OAuth, add the Production webhook signature key, choose the > location, and pair the Terminal. Do not copy the Sandbox token. > **Connect OAuth is unavailable or fails before Square opens** > > Save the Square Application ID and Application secret for the selected > environment first. Copy the OAuth redirect URL from Inventory into that > environment's Square application settings. Confirm the URL matches exactly. > **Square returns Unauthorized** > > The access token commonly belongs to the other environment, was revoked, or > lacks a required scope. Confirm the environment badge, seller, and > application. Re-authorize the intended seller instead of adding unrelated > manual tokens. > **Locations are empty or the wrong business appears** > > Verify the OAuth seller and `MERCHANT_PROFILE_READ` permission. A location > cannot be borrowed from another seller or from Sandbox. Reconnect the > correct account, refresh locations, and ask the Square owner to confirm the > location name. > **The connection was revoked** > > Square sends `oauth.authorization.revoked`, and Tuturuuu marks the > connection unavailable. Stop checkouts, ask the owner why access was > revoked, then re-authorize only if the owner approves it. ## Webhooks > **Square test delivery is rejected** > > Confirm the subscription environment, notification URL, signature key, and > event type. Copy the workspace webhook URL from Inventory; do not rebuild it > manually. The exact URL used by Square is part of signature verification. > **Signature verification fails after a domain or tunnel change** > > Square signs the configured notification URL plus the raw body. Update the > Square subscription and Inventory's advanced notification URL to the same > exact HTTPS value, then replace the matching environment's signature key. > **Square sent the same event more than once** > > Duplicate delivery is normal when an acknowledgement is delayed or Square > retries. Compare the `event_id`. Tuturuuu should keep one checkout, payment, > stock transition, and finance entry. Escalate only if business state is > duplicated. > **Events arrive in an unexpected order** > > Square does not guarantee delivery order. Reconcile by provider object and > final payment status rather than arrival time. Do not edit checkout state > manually to match the first event you saw. > **Inventory count webhook did not appear** > > Square may not emit `inventory.count.updated` when the written count equals > the existing value. In Sandbox, change the demo count to a distinct value, > verify the event, then restore it intentionally. ## Terminal and pairing > [!WARNING] > > A phone or tablet running Square POS with a connected Reader is not a > Terminal API device. It will not appear after **Refresh terminals**. Select > **Phone or tablet with Reader**, register the POS callback URL, and use the > **Square POS app + Reader** Storefront mode instead. | Symptom | Check | Safe action | | - | - | - | | Pairing code expired | It was not entered within five minutes | Create a new code in Tuturuuu | | Dashboard code does not pair | Generic Dashboard codes are not Terminal API codes | Discard it and create the code in Tuturuuu | | Paired device does not appear | `device.code.paired` delivery, seller, environment, and location | Refresh devices after the webhook succeeds | | Terminal shows no payment prompt | Device online state, selected default device, location, and existing pending checkout | Reconcile the current checkout; do not send a second one | | Wrong Terminal receives the order | Saved default device and counter name | Stop checkouts, select the correct paired device, then test with an approved order | | Terminal is offline | Network indicator, software updates, Wi-Fi/Ethernet, captive portal | Restore connectivity and reconcile the existing checkout | ## Square POS app and Reader | Symptom | Check | Safe action | | - | - | - | | Phone/Reader does not appear in terminal list | Hardware is connected inside Square POS, not Terminal API | Do not paste its device ID; switch to the phone/Reader setup path | | Square POS does not open | Request is on Android/iOS, latest Square POS is installed, and browser permits app links | Return to the same reserved order; install/update Square POS before trying a new checkout | | `UNAUTHORIZED_CLIENT_ID` or callback error | Production Application ID and exact Point of Sale API Web Callback URL | Copy the URL from Inventory and save it in the Production Square application | | `ILLEGAL_LOCATION_ID` / user mismatch | Square POS is signed into the same location saved in Inventory | Sign in to the approved location; do not remove the location safeguard | | Payment returns but order stays pending | Square Order/Payment may still be synchronizing, or amount/currency/location/card verification failed | Keep the order open and inspect its failure reason plus Square payment evidence; do not charge again | | No server transaction ID | Payment was offline or no supported online card order was returned | Tuturuuu leaves stock unchanged for manual review; reconcile Square before any retry | The Point of Sale API callback is not treated as payment proof by itself. Tuturuuu uses the returned transaction ID as a Square Order ID, retrieves its Payment, and verifies the exact reserved amount, currency, location, completed status, and card tender. This is why cash and offline returns are not automatically finalized. Square Terminal cannot use browser-based captive-portal networks. Review [Square's network requirements](https://squareup.com/help/us/en/article/8348-set-up-network-requirements-for-square-hardware) and [Terminal network troubleshooting](https://squareup.com/help/us/en/article/8350-troubleshoot-network-connection-on-square-terminal). ## Checkout, payment, and stock > **The checkout is pending** > > Keep the same order. Check Square Payments and the Terminal checkout. If no > payment completed, cancel that checkout from Inventory Commerce or let it > expire. Tuturuuu reservations expire after 15 minutes and release stock when > final reconciliation runs. > **The buyer says they paid but Tuturuuu is not completed** > > Search Square by location, time, amount, and receipt. If Square shows a > completed payment, do not retry. Record the Square evidence and inspect the > `payment.updated` and `terminal.checkout.updated` webhook deliveries. > **Tuturuuu says completed but Square evidence is missing** > > Confirm you are viewing the same Sandbox or Production seller and location. > Record all evidence and stop new attempts. This mismatch requires support > investigation; do not create a balancing payment or manual stock change. > **Canceled or expired checkout still holds stock** > > Refresh the Commerce and Payments views after the final Square event. Allow > the scheduled expiry reconciliation to run. If the reservation remains, > escalate with the order reference, final Square status, timestamps, and > stock values. Do not compensate by increasing on-hand stock manually. > **Stock or finance changed twice** > > Stop processing the item, preserve the rows, and compare Square event IDs > and provider IDs. Duplicate webhooks must be idempotent. Do not delete a > duplicate-looking record before support confirms which row is authoritative. > **No receipt link appears** > > Confirm the payment is completed and inspect the Square payment directly. > Sandbox has receipt limitations, while Production receipt behavior depends > on Square and the seller's receipt settings. ## Catalog and stock sync > **The summary says products synchronized, but I cannot see them** > > Open the **Linked catalog records** list, clear any UI filter, and verify the > environment. Metrics count item, variation, and stock operations, so the > total can exceed the number of unique products. One visible link row is the > reliable evidence for one Square variation relationship. > **A price is 100 times too small or large** > > Stop all sync and checkout actions for that item. Record the human-readable > amount and currency on both sides. Do not manually multiply or divide and > sync again. Confirm the current Tuturuuu release, then correct the approved > source once and verify a one-way sync with a demo item first. > **Two-way sync reports a conflict** > > This is protective behavior. Compare the Tuturuuu and Square values, get an > owner decision, and run one directional sync from the approved source. Do > not alternate directions or delete the Square item. > **A Square deletion is preserved** > > Tuturuuu intentionally keeps the local product and link for review. Ask the > owner whether to republish the item or leave it disconnected. Synchronization > never deletes Square objects or local product data to resolve this status. > **A link shows Sync error** > > Read the row's error, then check environment, token scopes, location, > currency, SKU, and Square object availability. Retry only the intended > direction after fixing the cause. ## Storefront issues | Symptom | Safe check | | - | - | | Storefront not found | Verify the published slug and use the Inventory Storefront URL generated by the workspace; do not infer a slug on another host | | Square option is missing | Confirm the Storefront mode matches the hardware: **Square POS app + Reader** or **Square Terminal**, and the matching readiness check is complete | | Checkout returns a readiness error | Open Payments and fix the named connection, webhook, location, or device check | | Two checkout tabs or prompts appear | Stop and inspect whether two requests were submitted; reconcile both provider records before any new attempt | | Cart reserves but no provider request appears | Inspect the same checkout in Commerce and Payments; cancel/release it if Square creation failed | ## Never do these during an incident * Do not send the same Production order again while the first is pending or uncertain. * Do not create a second charge to cancel out an uncertain charge. * Do not copy Sandbox tokens, IDs, device simulators, or webhook keys into Production. * Do not delete or archive Square catalog objects to force synchronization. * Do not manually increase stock while an unresolved reservation exists. * Do not paste secrets or customer personal data into an escalation message. * Do not factory-reset a Terminal until the Square owner understands the impact and the current checkout has been reconciled. ## Escalate with evidence Include the packet from the [operations guide](/platform/applications/inventory-square-pos/operations#escalation-packet) and check [Square system status](https://www.issquareup.com/) for provider-wide incidents. Redact tokens, application secrets, signature keys, full card data, and customer personal information. For implementation-level failures, use the [Square Terminal engineering runbook](/build/devops/square-terminal-integration). # Learn learner app Source: https://docs.tuturuuu.com/platform/applications/learn Student and parent-facing education app for Tuturuuu workspaces. Learn lives in `apps/learn` and runs locally on port `7812`. It is the learner-facing companion to the main Tuturuuu web platform: students and parents use Learn for lessons, practice, assignments, reports, marks, XP, streaks, and hearts, while teachers and admins manage education data in Teach. Unmatched `/api/workspaces/*` requests, including workspace invitations and workspace details, use the Web fallback with their paths and queries intact. Local Learn API handlers retain precedence. Regression coverage lives in `apps/learn/src/next-config.test.ts`. ## Ownership model Learn does not render its own login portal. Its `/login` route first checks for an existing Learn app-session JWT. If the app session is already present, it redirects inside Learn to the requested `next` path, usually `/dashboard`. Otherwise it redirects to the platform login at `apps/web` with a `returnUrl` pointing back to `/verify-token`. Learn stores a host-only `tuturuuu_app_session` cookie after token verification, not a Learn-local Supabase Auth session. The `/dashboard` entry route must only send users to `/login` when the Learn app-session is missing. If the app-session exists but the Learn bootstrap API returns no eligible education workspace, render the empty workspace state instead of redirecting back to login. Social auth providers still run on `apps/web` because OAuth provider callbacks are registered for `tuturuuu.com`. After the platform login confirms the current account, `apps/web` generates a cross-app token for the `learn` target app and redirects back to `/verify-token`. Learn's local `POST /api/auth/verify-app-token` route only completes the host-only cookie handoff; token validation is delegated back to the central web app so Learn does not depend on a Learn-local Supabase Auth project. The handoff stores a Learn-local app-session cookie for satellite route guards and shared session material used when a retained platform service must be called. If older session material cannot be refreshed, Learn sends the user back through the platform handoff so the coordinated cookies are renewed without manual deletion. Learn owns learner and parent-facing v1 API contracts, including bootstrap, courses, modules, tests, practice, assignments, reports, marks, parent links, and vocabulary support. These handlers live under `apps/learn/src/app/api/v1`. Next.js fallback rewrites send all unmatched `/api/*` paths to Web; they do not proxy a path that Learn implements locally. ## Programming The Learn Programming workspace is available inside eligible education workspaces. Its default layout fills the available dashboard viewport: a compact challenge and language picker sits above a resizable problem pane, code editor, and test console. Narrow screens use vertically resizable panes. Monaco runs in the browser with syntax highlighting for supported languages, and local JavaScript and TypeScript diagnostics and definition lookup. Local editor checks are guidance; only the platform Judge determines the result. Students can run public cases and one optional custom input/expected-output pair without consuming hidden cases. Submitting runs the public and private cases. Public inputs, expected outputs, actual outputs, diagnostics, and timing are visible to the learner. Private cases disclose only pass/fail and an aggregate count; their input, output, errors, and individual timing stay private. The default Judge feature is off on a newly connected Devbox until an administrator enables it and the machine reports a verified sandbox with cached pinned images. An unavailable language remains editable for learning but cannot run there. Parents may read the challenge and a linked learner's execution history but cannot run or submit code. Each test run and submission records the source, language, timestamp, verdicts, and public case wall times in private platform tables. History is scoped to the learner, workspace, and challenge and can restore earlier source into the editor. The displayed median and range use the same monotonic wall-clock measurement for each public case. They include container startup and, where needed, compilation, so repeated runs may differ; the UI does not claim a hardware-normalized benchmark or rank users by these numbers. Hidden-case timings are omitted from learner responses. `packages/education-core` contains reusable server-only education domain logic; it does not own HTTP traffic. Programming catalog clients are exposed through `@tuturuuu/internal-api/programming`; keep new catalog consumers on that scoped entry point instead of extending the legacy education client module. The Tulearn helpers in `packages/internal-api/src/tulearn.ts` select the Learn origin for learner contracts. Explicit exceptions such as platform profile updates keep the Web origin. Learn-local logout clears the host-only app-session cookies and stale Supabase Auth cookies on `learn.tuturuuu.*`, then redirects browser form submissions to the central `apps/web` `/logout?from=Learn` continuation. JSON callers can still POST `/api/auth/logout` and receive `{ success: true }`. Learn also exposes a learner-focused AI Chat surface at `/[wsId]/ai-chat`. The UI stays inside `apps/learn`, while its unmatched `/api/ai/*` requests use the Web fallback so model routing, credits, logging, and chat persistence remain centralized. ## Workspace access Every Learn workspace API requires both: * the authenticated user has student access or an explicit active parent-student link; and * `workspace_secrets.name = ENABLE_EDUCATION` is set to the canonical value `true` for that workspace. The bootstrap route only returns eligible education workspaces and linked students: ```txt theme={null} GET /api/v1/tulearn/bootstrap ``` Workspace-scoped learner routes use the normalized workspace id so aliases like `personal` do not diverge between selection and final reads. Linked learners in `workspace_user_linked_users` count as eligible student access even when the platform user is not a direct workspace member, so course lists and learner dashboard bootstrap must agree on the same workspace set. ## Parent links Parent access is explicit and read-only in v1. The existing Tulearn schema adds: * `tulearn_parent_student_links` for accepted parent to student links; * `tulearn_parent_invites` for invite-based parent linking; * admin-managed parent-link APIs under `/api/v1/workspaces/[wsId]/tulearn/parent-links`. Parents can switch between linked students in Learn. Parent requests may read home, courses, assignments, reports, marks, and practice context for linked students, but mutation routes reject parent writes. ## Gamification Learn-owned gamification behavior is backed by the existing Tulearn tables, separate from teacher-owned course data: * `tulearn_gamification_events` stores XP events with an idempotency key per workspace and learner. * `tulearn_learner_state` stores hearts, max hearts, total XP, streaks, freezes, selected workspace, and UI preferences. Direct authenticated writes are limited by RLS to the learner's own row in workspaces where that learner is a member; non-null `selected_workspace_id` values must also point to a workspace the learner can access. XP awards and heart loss must go through the database RPCs `award_tulearn_xp` and `lose_tulearn_heart`. Those functions lock the learner state row and keep event insertion, streak updates, XP totals, heart decrements, and refill timer resets atomic under concurrent practice or assignment submissions. Streak dates currently use UTC day boundaries until Learn stores learner or workspace time zones. Courses, modules, quiz sets, flashcards, assignments, monthly reports, and marks continue to reuse existing education and user-group tables. ## Programming route and operations Learn owns the learner-facing Programming workspace at `/[wsId]/programming`; `/[wsId]/coding` redirects there. It starts with curated array, search, and stack exercises. Students in a workspace with `ENABLE_EDUCATION=true` can submit solutions; parents with read-only learner access cannot. The audited imported catalog is shared across eligible education workspaces; workspace managers can additionally author private workspace catalogs. Python, JavaScript, TypeScript, C, C++, Java, Rust, Go, Ruby, and PHP use the same standard-input/standard-output exercise contract. The selected language only becomes runnable when a platform Judge runner reports a cached pinned image for it. The fixed Judge command budget is 48,000 base64url characters for the combined source, catalog cases, and optional custom case. Individual field limits are upper bounds, not independently reserved capacity. Author saves reject catalogs that cannot fit even minimal source; execution validates the complete combined payload and rejects oversized commands before enqueue. Learners may reduce source or custom input to fit the shared budget. This applies to both workspace and imported catalogs and preserves the existing runner contract. The Programming workspace uses a full-bleed shell at this route, with shared Select, Button, Textarea, Tooltip, Tabs, and Accordion controls. Public test cases start collapsed in both problem and console panels. The bottom console can be resized or collapsed from the editor toolbar; collapsed content is inert, and completing a newly queued execution expands the console to show its result. Compact run/submit icons retain localized accessible labels and tooltips. The Judge readiness warning uses foreground text on a muted surface in both color modes and is informational; it does not enable a runner or change security. Code uses the self-hosted regular JetBrains Mono v2.304 font, scoped to this workspace. Its unmodified webfont, full SIL OFL 1.1 license, copyright and source/hash notice are colocated in the Programming component's `fonts` folder. There is no operating-system font installation or additional font package. Submissions are stored in `private.learn_coding_submissions` and queued atomically with a private Devbox lease and typed Judge run. The default is at most 20 submissions per learner per hour. Learn reads only that learner's submission, displays aggregate pass counts and visible case outcomes, and does not award XP or affect hearts yet. Hidden cases remain server-owned. If no eligible Judge machine is ready, the editor remains available and submission is disabled. Workspace members consume platform capacity; they do not control the machines. Root administrators manage runner feature toggles and Judge resource limits in Infrastructure > Devboxes. ## Code organization Learn learner pages keep the public `apps/learn/src/components/learner-pages.tsx` entrypoint as a thin barrel export. Route-level screens live under `apps/learn/src/components/learner-pages/*`, with shared page motion, loading, empty state, and section primitives in `shared.tsx`. The home dashboard should be a real learner workspace, not a landing page. Keep daily plan, quest board, learner toolkit, course path, assignments, marks, reports, practice, and AI Chat entrypoints visible as responsive Neobrutalist panels. Secondary rails should stack below the main grid until there is enough width for readable cards, and color should use dynamic theme tokens rather than a single accent. Keep Learn learner files under 400 LOC and individual components under 200 LOC. When a screen grows, split reusable cards, rows, panels, and route-specific helpers into adjacent modules before final verification instead of letting `learner-pages.tsx` or any route screen become a monolith again. Language switching is handled inside Learn with `next-intl`, but locale prefixes are hidden from URLs. Legacy locale-prefixed paths such as `/vi/dashboard` are canonicalized back to `/dashboard` while preserving the selected locale in `NEXT_LOCALE`. Keep English and Vietnamese strings in `apps/learn/messages/en.json` and `apps/learn/messages/vi.json`, then run `bun i18n:sort`. Learn metadata and auth return URLs must resolve to absolute HTTP(S) app URLs. Prefer `LEARN_APP_URL` or `NEXT_PUBLIC_LEARN_APP_URL` for the app origin. A valid absolute `BASE_URL` can be used as a fallback, but non-URL environment values such as `development` are ignored so local development falls back to `https://learn.tuturuuu.localhost` through Portless. Do not configure Learn return URLs with the retired `tulearn.tuturuuu.com` origin. Production learner redirects should use `https://learn.tuturuuu.com`, and teacher-facing redirects should use `https://teach.tuturuuu.com`. ## Programming problem catalog Programming opens its authorized catalog at `/[wsId]/programming` and each problem at `/[wsId]/programming/problems/[problemId]`. The legacy `/coding` entry redirects only after learner access is checked. Catalog pages return at most 50 summaries and expose a UUID continuation cursor; a selected problem remains accessible even when it is outside the first catalog page. Workspace authors require workspace membership, `manage_users`, and enabled education. Author forms can create and revise workspace problems; imported global problems remain read-only. Up to nine cases can be stored per problem, reserving the existing runner's tenth slot for a learner's custom test. Revision conflicts preserve the author's form so another author's changes are not overwritten. Learners receive published problem data and visible cases; hidden cases remain behind the authorized server boundary. Editor code, language, custom input, and inspected result selection persist per tab in session storage scoped to actor, workspace, learner, and problem. When storage is unavailable, drafts use memory for the current tab. History and polling bind to the opaque problem UUID; only the three audited imported global problems may read never-bound legacy slug history. Deleting a problem preserves existing submission history through its permanent identity binding. These decisions apply to the Learn catalog, problem workspace, author forms, and shared Programming lab. Backend access, case capacity, pagination, history, and subject regressions live in `packages/education-core/src/education/programming-*.test.ts` and `apps/web/src/lib/programming-api.test.ts`. The disposable actual Next/auth/API regression is `apps/web/e2e/programming-catalog.noauth.spec.ts`; it exercises RPC author writes, stale revisions, hidden-case filtering, and workspace isolation. Learn actor/history regressions live in `apps/learn/src/lib/programming/server.test.ts` and `apps/learn/src/lib/coding/programming-store.test.ts`; scoped draft regressions live in `apps/learn/src/lib/programming/drafts.test.ts`. The mounted canonical harness in `apps/learn/tests/programming-workspace/run-canonical.mjs` uses synthetic Next navigation and server-action adapters and does not replace authenticated Next/API/database integration evidence. ## Verification After changing Learn routes, run focused non-build route or component tests locally. Run applicable typecheck, lint, tests, and the owning Learn build in CI for the exact candidate commit. Do not run `bun validate` or a product build locally; their task graphs may compile workspace dependencies. For the owning Learn build, dispatch `.github/workflows/vercel-preview-learn.yaml` on trusted `main` with `preview_ref` set to the immutable candidate SHA. Verify the checked-out source SHA and successful build step separately from preview deployment. Schema changes require disposable full-schema replay and generated types before integration; message changes require `bun i18n:sort`. Cover parent read-only access, student-only writes, XP idempotency, assignments, marks, and reports when those behaviors change. ## CI and deployment Learn has dedicated Vercel workflows: * `.github/workflows/vercel-preview-learn.yaml` * `.github/workflows/vercel-production-learn.yaml` Production uses the shared workflow switchboard. Preview runs only by trusted manual dispatch on `main`, then checks out the supplied `preview_ref`. They require environment-scoped Vercel credentials plus `VERCEL_LEARN_PROJECT_ID`; production Supabase values should live in the Vercel project environment rather than GitHub Actions. Deployment credentials must stay environment-scoped in GitHub Actions. The preview job is bound to the `vercel-preview-learn` GitHub Environment, and the production job is bound to `vercel-production-learn`. Store `VERCEL_TOKEN`, `VERCEL_ORG_ID`, and `VERCEL_LEARN_PROJECT_ID` in those environments instead of repository-wide or organization-wide secrets. Production Supabase values remain in the Vercel project environment pulled by `vercel pull`. The repository-level `TURBO_TOKEN` and `TURBO_TEAM` variable are passed only to the wrapped `vercel build` step; never place them at workflow or job scope, and never expose the token to pull-request or Dependabot code. Preview dispatch is manual-only. Run `vercel-preview-learn.yaml` from `main`, set `preview_ref` to the reviewed branch, tag, or SHA, and keep `TRUSTED_PREVIEW_DEPLOY_ACTORS` limited to maintainers approved to run secret-backed preview builds. Manual production dispatch is only valid from `refs/heads/production`. `apps/learn/vercel.json` disables Vercel Git deployments and GitHub integration so preview and production deploys only happen through the CI workflows. The full-bleed shell measures its mobile navigation header, including safe-area padding and wrapped rows, and reserves bottom safe-area space inside the viewport. Disabled Run and Submit controls expose their tooltips to keyboard focus. Font loading failures retain fallback editor metrics without unhandled rejections. Source regression coverage is in `apps/learn/tests/programming-workspace/review-regressions.node-test.mjs`; real mobile and Next build checks remain separate verification gates. ### Programming database acceptance The enabled `programming-database-contract.yaml` pull request gate checks out the exact source head and replays all repository migrations in an owned disposable Supabase project. `learn-programming-full-schema.sql` requires strict pgTAP success for grants, workspace boundaries, hidden-case redaction, stale revisions, invalid case visibility, and complete transaction rollback. Actual public schema types are uploaded under that source SHA after scoped cleanup succeeds; they are not committed by the workflow. The job has read-only repository permissions and a 45-minute deadline. This gate validates the current catalog contract without activating the separate inert hosted typegen proposals. Run the finite parser and session regressions with `node --test apps/database/scripts/programming-database-tap.test.mjs apps/database/tests/programming-disposable/session.test.mjs`. Use the repository isolated lifecycle for local schema acceptance, never a shared or production database. A failed migration, TAP assertion, type generation, or owned-project cleanup blocks acceptance. ## Hosted projects and meetings Programming also supports [hosted playgrounds](/platform/features/programming-playgrounds) and the shared Meet coding workbench. Project saves belong to personal Drive; normal access requires a paid personal account or an active Infrastructure benefit. See [account benefits](/platform/features/account-benefits) for the centralized grant model and [the realtime runbook](/build/devops/programming-realtime-runbook) for implementation, egress controls and operations. ## Personal To do The **To do** sidebar destination (`/{wsId}/todo`) is the signed-in actor's own work in this education-enabled workspace. It intentionally ignores parent learner selection: the actor's verified workspace-user link is resolved on the server, and `studentId`/other subject query overrides are rejected. A parent without an own learner link has an empty personal list; existing parent learner views remain available elsewhere. Tutoring lists explicitly assigned, pending, unresolved sessions. Assignments, lessons and tests come only from the actor's actual STUDENT course memberships in active, non-guest, published courses. Only approved assignments and published lessons/tests are visible. Completion comes from this actor's assignment checks, module completion records and submitted test attempts. Completed entries are hidden on the current page by default; the count includes assigned completed entries, and the toggle plus pagination avoids presenting an empty page as an empty workspace. Sessions show their recorded local date/time and duration, including explicit longer tutoring exceptions. Reads use Learn-owned `/api/v1/workspaces/{wsId}/tulearn/todo` and the shared internal API transport. They are private/no-store, paginated by category, and cached by app, workspace and verified actor. Failures offer Retry and do not turn unavailable data into an empty-success response. These existing app-owned education routes are outside the platform Web-to-Rust/TanStack migration inventory. Regression evidence: `packages/education-core/src/todo/service.test.ts`, both app-owned `todo/route.test.ts` files, internal API `education-todo.test.ts`, and shared UI `education-todo.test.tsx`. Exact app builds and authenticated runtime verification remain required delivery evidence. # Tuturuuu Mail Source: https://docs.tuturuuu.com/platform/applications/mail Multi-mailbox client with permanent SES and Cloudflare transports. `apps/mail` is the standalone Tuturuuu mailbox app. It runs on `https://mail.tuturuuu.com` in production and port `7820` locally, delegates auth to `apps/web`, and preserves Tuturuuu workspace and mailbox-role checks. Platform operators may configure additional managed domains; a mailbox address must match its linked `private.mail_domains` row. ## Flutter Mail The mobile Apps hub exposes Mail to exact `@tuturuuu.com` accounts, genuine managed subdomain accounts, and tagged reviewer accounts on the routed `@tutur3u.com` domain. Discovery from mobile session metadata is only a hint: the Mail API checks the live administrator reviewer tag, active account, workspace membership, and personal workspace on every request. Subdomain admission additionally requires current confirmed Auth and an existing active owned personal mailbox; discovery alone grants no access. Reviewers cannot access shared or staff mailboxes. The review domain has an active Mail domain row for personal mailbox bootstrap; the exact reviewer address is forwarded to the verified QA inbox for login codes. The Mail UI defaults to the reviewer's own personal workspace. Its API client routes workspace Mail requests directly to `mail.tuturuuu.com` (port 7820 in development), with an optional `MAIL_API_BASE_URL` build override. Bearer API requests skip browser-cookie refresh in the Mail proxy but still pass the API guard and route-level workspace and mailbox authorization. The native client supports mailbox switching, paginated conversations, search, standard folders, labels and custom folders, read/star/archive/trash actions, bounded bulk actions, and folder-wide mark-read. Drafts retain their server ID, recipients, reply headers and attachments. Closing saves pending edits; a failed save keeps the editor open. Composer attachments use bounded authenticated uploads, and forwarding copies attachments through the authorized draft API. Rich-text composition uses Quill and exports email HTML through the same draft and send contracts as the web client. Untouched saved HTML is preserved. AI results require review before replacing the editor content and never send mail automatically. Owners and admins can manage mailbox settings, forwarding, smart-label configuration, custom folders/labels and group membership. Account or workspace changes dispose the entire Mail navigation stack. Attachment downloads reject redirects and oversized responses. Original HTML renders in an isolated, script-disabled web view. Remote images follow the saved Mail image preference, which is on until the user turns it off; notification-opened readers suppress them until revealed (see [Mail inbound notifications](/platform/applications/mail-inbound-notifications)). Downloaded attachments use the device's native share sheet. Run `ttr resources run -- bun check:mobile` after native changes, and the Mail proxy auth tests plus the actual Mail build after auth-routing changes. Unit and widget checks do not prove real-provider sending, receiving, or store delivery; verify those separately with the intended authenticated account. ### Tablet reading pane and instant open Scope: the Flutter Mail inbox on every platform. When the Mail body is at least 720dp wide (portrait and landscape tablets, desktops), the inbox list and the open conversation sit side by side. Without a selection, the pane shows a localized empty state. Narrower bodies keep the pushed reader. The open conversation survives rotation and window resizing, moving between the pane and the pushed reader. Notification deep links open in the pane on wide layouts. On wide layouts, the first Back (dock, rail or system) and Escape close the pane; the next Back leaves Mail. The pane header carries the subject and message actions; the shell navbar and dock keep the inbox title, filters and actions. Opening never waits for the network. The reader renders the inbox row's subject, participants and snippet in the opening frame, then hydrates from the in-memory preview store, the encrypted Mail cache, or one detail request (one retry on transient failures). A conversation shown from memory or from the encrypted snapshot is revalidated with one refresh request when it opens. A failed load stays in the reader with an inline Retry, keeping notification-entry image suppression. Drafts bypass the preview store: each open loads the saved draft through the repository before the composer opens. Switching mailbox closes the open conversation, and a resize never reopens a conversation from another mailbox. Prefetching is bounded. For verified mailboxes it fetches the rows currently built in the list, after scrolling pauses for 250ms: conversations in thread folders and message details in Sent; never drafts. At most two requests run, eight are queued, and each makes one attempt. A failure is not retried in the background. The queue is replaced when the visible rows change, and the neighbours of an opened conversation are queued next. Prefetching fetches message JSON only; images load only when a body is shown, under the saved remote-image preference (or the notification-entry suppression). The preview store lives in memory for one signed-in workspace view, holds 40 details, and is cleared on access denial. Rendered HTML documents of plain bodies are memoized by their exact HTML and rendering options (12 entries) in the same view. The memo is cleared on access denial and discarded with the view, which is keyed by account and workspace; a render finishing after its reader or view closed is not stored. Regression coverage: `mail_master_detail_test.dart`, `mail_preview_latency_test.dart`, `mail_preview_revalidation_test.dart`, `mail_rendered_documents_test.dart` and `mail_workspace_test.dart` in `apps/mobile/test/features/mail`, and `core/layout/master_detail_test.dart`. ## Read state and archive actions Opening a loaded conversation optimistically clears its unread indicators and updates cached Inbox counts. Failed writes restore that conversation's prior state. The reader's compact read/unread control closes the conversation when marking it unread, preventing automatic viewing from immediately clearing it. Archive actions persist both `archived_at` and `read_at` for the current user; users can explicitly mark an archived conversation unread afterward. Inbox and Archive each offer a folder-wide **Mark all as read** action. This covers the selected mailbox's entire folder, including unloaded messages, and ignores the current search and selection. The app-local POST endpoint `/api/v1/workspaces/:wsId/mail/mailboxes/:mailboxId/read-all` scans 250 inbound messages per request. Clients continue with the returned `nextCursor` and `before` until the cursor is null. The timestamp excludes later arrivals; mailbox access and group-message visibility are checked for every batch. Batches persist independently. If a request fails, already completed batches remain read and the client refreshes the mailbox; retrying completes remaining unread messages. Thread and selected-thread actions also paginate message IDs and write bounded batches instead of silently truncating long conversations. ## Similar deliveries and failed recipients The copy addressed to the active mailbox stays separate. Alternate-recipient copies with the same sender and normalized subject within ten minutes share a compact expandable summary. All original copies remain inside that group with their own selection, content, read state, and actions; personalized previews do not split otherwise matching deliveries. Recognized delivery failures offer a blacklist shortcut in the list and reader. The reason defaults to **Inactive/Abandoned** and supports additional Infrastructure quick reasons. The action writes to the existing global `email_blacklist`, blocking platform outbound email to the chosen recipient. It requires Mail mailbox access, a root-workspace linked user, and `view_infrastructure`. The server derives allowed recipients from the authorized failure message, validates the submitted address, and records the current actor. Existing blacklist entries retain their reason and actor. Ordinary messages and delay notifications do not produce automatic blacklist suggestions. ## Architecture * `apps/mail` owns the mailbox UI and protected app-local APIs under `/api/v1/workspaces/:wsId/mail/*`. * The mailbox mirror is stored in service-only `private.mail_*` tables. Browser code never reads those tables directly; routes verify workspace membership and mailbox roles before using an admin client. * SES and Cloudflare Email Service are permanent outbound transports. The domain default comes from `mail_domains.outbound_provider`; an optional mailbox override wins. Shared abuse, rate-limit, and audit controls in `@tuturuuu/email-service` still run for both providers. * Inbound transport is domain-wide. SES receipt/S3/SNS ingestion remains supported, while Cloudflare Email Routing invokes the Worker at `apps/mail/src/email-worker/index.ts`. * Supabase is authoritative for domains, authorization, audit, threads, search, AI state, and MCP credentials. The private R2 bucket contains raw MIME, body objects, and attachment bytes; callers receive authorized short-lived access, never raw keys or R2 credentials. * Thread resolution checks `Message-ID`, `In-Reply-To`, and `References` first. Normalized subject is only a recent-reply fallback and is not unique. Mail consumes `/verify-token` in the proxy before centralized auth handling so local Portless handoffs set cookies on `mail.tuturuuu.localhost`. The app keeps token refresh same-origin through `/api/auth/refresh-app-session`; a valid refresh cookie should rotate the Mail-local and Web-issued app-session cookies without sending the browser back through `apps/web` login. Authenticated root and personal workspace entry requests redirect directly to `/personal/inbox` in the proxy, preserving query state and locale. Mailbox discovery uses bootstrap `?view=mailboxes`; unread badges load separately through `?view=counts` and stay unknown until available. Both paths retain session and membership checks. The default bootstrap response still includes counts for other clients. Thread scans fetch previews rather than full bodies; missing legacy snippets are loaded only for the visible page. State scans exclude read-only rows unless the requested search needs read state. ## Reading and attachment previews Settings → Reading stores the archive navigation and email appearance preferences in the current browser. Archiving an open inbox conversation selects the next visible conversation by default, falling back to the previous one at the end of the loaded list. Users can choose to return to the list instead. Bulk archive skips all selected conversations when choosing the next message. Loaded unread conversations are marked read even when opened through restored URLs or archive navigation. Read updates wait for pending archive/trash operations to settle. Archive controls wait for read-state writes to settle before another mutation. Its header remains available from the inbox summary while the message body loads. Failed operations restore only their own conversations and counters; mailbox reconciliation waits for overlapping operations to finish. Catch-all headers fall back to the observed delivery recipient, then the envelope recipient when parsed To recipients are absent. Sender and recipient summaries clamp long addresses and expose full text in tooltips. Email frames remain hidden until the saved appearance is restored and contrast adjustments finish. Dark mode matches neutral paper surfaces to the reader's background, including black and gray panels and neutral gradients, and softens bright neutral borders while preserving colored panels and images. Compact App theme/Dark/Original icon controls live on the floating action toolbar with tooltips. New browsers follow the selected app theme; saved explicit choices remain unchanged. Original mode retains sender backgrounds and images, while unreadable text is corrected to at least 4.5:1 contrast on resolved solid backgrounds, including calendar invitations. Dark mode keeps the same contrast floor. Regression coverage lives in `mail-preview-contrast-dom.test.ts` and `mail-preview-appearance.test.ts`. Neither mode enables scripts inside email HTML. Message headers use a single truncated sender-to-recipient row. The participant button opens full address details; the separate chevron collapses the message. The reader collapses recognized Gmail, Outlook, cite-style, and plain-text reply history into a native disclosure. Quote-only and unrecognized messages remain visible. Quote detection runs on the sanitized isolated document before it is revealed; it never modifies stored message content or outgoing reply headers. The protected attachment endpoint accepts `?preview=1` for a passive-format allowlist: raster images, supported video/audio types, and plain text (including `.txt` files stored as `application/octet-stream`). Preview access uses the same mailbox and message authorization as downloads and preserves byte-range support. HTML, SVG, and other unsupported types remain downloads. Responses are private, uncached, MIME-sniffing-disabled, and sandboxed. The reader exposes previews from both the conversation and Attachments tab, with a separate download action. Text previews use the internal API client, render escaped text in the reader theme, and fall back to download on authorization failures or files larger than 1 MiB. ## Composing and draft recovery Close saves the latest draft before dismissing the composer; offline or failed saves keep the editor open. Untouched empty composers close without creating a draft. Drafts exposes Continue editing and deletion, and reopening keeps the original draft identity, recipients, reply headers and attachments. Switching composers waits for the previous draft to save before starting a new editor session. The reader header omits its back button; narrow layouts retain a message-list action on the floating toolbar. The composer keeps recognized trailing Gmail/Outlook history outside the rich-text editor, collapsed by default, preserving its HTML when saving or sending. Bounded reply blocks are recognized; ambiguous Outlook tails and authored quotations stay editable. Inline quoted images retain their attachment metadata. Selecting text exposes Enhance selection. AI previews replace only that passage after review; a document change invalidates the captured selection. Plain-text reading caps runs of blank lines without changing stored text or meaningful indentation. ## SES Receiving Setup Do not change DNS from code or migrations. The current public MX for `tuturuuu.com` is Google-routed, so real `@tuturuuu.com` receiving requires an explicit staged MX cutover or a pilot subdomain first. 1. Verify the domain or pilot subdomain in the SES receiving region. 2. Create an S3 bucket for raw MIME objects. 3. Create an SNS topic for receipt notifications and subscribe the web webhook: `POST /api/v1/webhooks/mail/ses`. 4. Create an SES receipt rule that stores raw MIME in S3 and publishes the SNS notification. 5. Configure `MAIL_SES_INBOUND_TOPIC_ARN`, `MAIL_SES_INBOUND_BUCKET`, `MAIL_SES_INBOUND_KEY_PREFIX`, and `MAIL_SES_REGION`. 6. Only after validation, stage the MX/DNS change outside the app repository. For local SNS fixture tests, set `MAIL_SES_SNS_SIGNATURE_VERIFICATION=disabled`. Do not use that setting in production. ## Cloudflare onboarding Cloudflare must already manage DNS for an onboarded domain. Arbitrary-recipient sending also requires Email Sending to be enabled for the account. Configure a staging domain before changing a production domain. 1. Create a private R2 bucket (the checked-in Worker configuration uses `tuturuuu-mail`) and bind it as `MAIL_R2_BUCKET` in `apps/mail/wrangler.email-routing.jsonc`. 2. Configure the Mail app server with `MAIL_R2_ACCOUNT_ID`, `MAIL_R2_ACCESS_KEY_ID`, `MAIL_R2_SECRET_ACCESS_KEY`, and `MAIL_R2_BUCKET_NAME`. The bucket name must match the Worker binding. `MAIL_R2_ENDPOINT` is only needed for an R2-compatible development or test endpoint. Object keys are private implementation details and must not be returned to clients. See `apps/mail/env.example` for the complete contract. 3. Set the Worker secret with `bunx wrangler secret put MAIL_INGEST_SECRET --config apps/mail/wrangler.email-routing.jsonc`. 4. Configure the same value as `MAIL_CLOUDFLARE_INGEST_SECRET` in the Mail Vercel environment. Signed events include the request body and a timestamp; the API rejects invalid or older-than-five-minute signatures. 5. Set `MAIL_INGEST_URL` to the deployed Mail endpoint `/api/v1/webhooks/mail/cloudflare`, then deploy with `bunx wrangler deploy --config apps/mail/wrangler.email-routing.jsonc`. 6. In Cloudflare Email Routing, onboard the domain and route its intended address patterns to `tuturuuu-mail-email-routing`. 7. Configure the domain row through `GET/PUT /api/v1/mail/domains`. Only root workspace operators may use this endpoint. Move the domain from `verifying` to `active` only after DNS and routing checks pass. 8. For outbound Cloudflare sends, set `MAIL_CLOUDFLARE_API_TOKEN` with Email Sending permission and either store the managed account ID on the domain or set `MAIL_CLOUDFLARE_ACCOUNT_ID` as the fallback. The Worker checks domain/provider status before reading and parsing the MIME stream, uses `postal-mime`, stores deterministic R2 objects, and submits a signed idempotent delivery event. Malformed or spam/virus-signaled deliveries are recorded as quarantined. Transient API failures are thrown so Email Routing can retry without creating duplicate messages. Cloudflare controls the outbound `Message-ID` header and rejects clients that set it. Mail therefore sends only `In-Reply-To` and `References` through the Cloudflare API. SES raw MIME sends retain a deterministic `Message-ID`. Store Cloudflare's returned provider identifier separately; do not substitute it for an RFC message identifier unless the provider explicitly returns one in that format. ## Mailbox API foundation Mailbox routes require workspace membership and a mailbox role on every request. The API provides chronological thread retrieval and thread-level state changes, label and custom-folder CRUD, bulk message mutations, and private attachment upload/download/delete routes. Attachment downloads stream through an authorized route with byte-range support; clients never receive an R2 object key. Message listing accepts the structured search operators `from:`, `to:`, `cc:`, `bcc:`, `subject:`, `is:`, `has:attachment`, `before:`, `after:`, and `label:`. Quote values containing spaces. Structured filters are combined with remaining free text and mailbox/folder state filters. Client applications should call these routes through `packages/internal-api/src/mail.ts`. Cloudflare currently permits 50 combined `to`/`cc`/`bcc` recipients and a normal outbound size of 5 MiB including attachments. Email Routing accepts up to 25 MiB inbound. The provider enforces outbound limits before making the API request; the Worker rejects inbound events above the routing limit. Reconfirm current quotas in the [Cloudflare Email Service limits](https://developers.cloudflare.com/email-service/platform/limits/) before changing these constants. The managed staging baseline uses `tutur3u.com` for Email Routing and Email Sending and the private `tuturuuu-mail` R2 bucket. Do not attach a routing rule to the inbound Worker until the Mail deployment has the matching ingestion secret and Supabase has an enabled `ingest.tutur3u.com` domain row linked to the canonical `tuturuuu.com` row. Email Sending and R2 can be verified independently before that inbound cutover. ## Google Workspace shadow-ingestion migration Do not onboard `tuturuuu.com` into Cloudflare Email Routing while Google Workspace still owns its apex MX records. Email Routing is enabled at the zone level before Cloudflare allows routing subdomains, so onboarding the production zone would replace and lock the Google MX records too early. Use the already onboarded staging zone as the shadow bridge instead: * Cloudflare Email Routing is enabled for `ingest.tutur3u.com`; its routing DNS records are managed and locked by Cloudflare. * A temporary exact-address routing rule may forward a pilot shadow address to a verified test inbox. Replace this action with the deployed ingestion Worker before starting a parity run. * Google Workspace has a recipient-address-map setting named `Cloudflare shadow ingestion pilot`. Keep it disabled between tests. It must map each selected `@tuturuuu.com` address to the same local part at `@ingest.tutur3u.com`, retain the original Gmail destination, and add `X-Gm-Original-To`. * The public `tuturuuu.com` MX records remain Google-only throughout the shadow phase. Never publish Google and Cloudflare MX records together as a substitute for dual delivery. ### Activation gates Complete all of these before changing the temporary Cloudflare forwarding rule to the ingestion Worker or enabling the Google pilot: 1. Canonicalize a trusted shadow recipient such as `user@ingest.tutur3u.com` to `user@tuturuuu.com`. Preserve both addresses in the ingestion event and accept `X-Gm-Original-To` only on the configured shadow domain. 2. Configure the same HMAC secret as `MAIL_INGEST_SECRET` on the Worker and `MAIL_CLOUDFLARE_INGEST_SECRET` on the Mail deployment. 3. Deploy the Worker with the private `tuturuuu-mail` R2 binding and confirm a signed domain check and ingestion event reach the Mail webhook. 4. Ensure Supabase has enabled domain metadata for the shadow and canonical domains, including their explicit relationship. Do not infer an arbitrary production domain from an inbound subdomain. 5. Prove direct shadow delivery, raw MIME storage, body and attachment storage, quarantine behavior, and duplicate retry before enabling Google delivery. The additive `add_mail_domain_canonical_relationship` migration installs this exact staging relationship. Apply it through the normal database release path; do not push it ad hoc from a workstation. The Worker derives the canonical recipient only after a signed domain check, and the webhook independently validates the ingress domain, canonical domain, observed recipient, and local part. Duplicate transport deliveries with the same mailbox and RFC `Message-ID` reuse the existing message instead of incrementing thread counts. ### Rollout plan 1. **Single-address pilot:** point one exact Cloudflare shadow rule at the Worker, enable only the matching Google address-map entry, and send external and internal test messages. The original Gmail delivery must remain enabled. 2. **Shadow parity:** expand the explicit map to the active user, group, and alias inventory. Run for at least three days and preferably seven. Compare Google Email Log Search with Supabase ingestion records by authoritative `Message-ID`, recipient, timestamp, raw MIME hash, attachment count, and quarantine result. 3. **Cutover readiness:** require no unexplained missing messages, idempotent duplicate handling, correct canonical recipients, attachment parity, and an alertable ingestion-latency baseline. Snapshot the Google MX records and lower or verify their DNS TTL at least 24 hours before the change. 4. **Apex cutover:** during a low-traffic window, onboard `tuturuuu.com` in Cloudflare and route its intended addresses to the same Worker. Keep Google Workspace and the shadow address map available for at least seven days so senders using cached Google MX records still feed the Cloudflare ingestion path. 5. **Stabilization:** remove the temporary test forwarding destination only after the Worker route is verified. Retire the Google shadow map after the cached-MX window and parity checks are complete; migrate outbound transport separately. ### Rollback Restore the saved Google MX records first and wait for DNS confirmation. Keep the Google shadow map and Cloudflare staging subdomain available during rollback so messages delivered through either cached MX path still reach the same idempotent ingestion boundary. Change the Supabase inbound-provider flag only after DNS is serving the intended provider. A rollback must not delete R2 objects, mail metadata, Google accounts, or the disabled pilot configuration. The initial transport smoke test used distinct subjects for Google outbound and Google-to-Cloudflare shadow delivery. Google delivered the original inbound message to the Workspace inbox, and Cloudflare recorded the mapped shadow copy as forwarded. After the test, the Google pilot setting was returned to its disabled state. ## Catch-all delivery Catch-all routing is platform-operated because it affects an entire inbound domain. The destination is relational metadata on `private.mail_domains`, not a workspace secret: `catch_all_mailbox_id` must reference an active mailbox on the canonical domain, and `catch_all_enabled` defaults to `false`. Automatic drafts for catch-all deliveries have a separate opt-in and remain disabled unless a platform operator explicitly enables them. Activate the bridge in this order: 1. Apply the additive `mail_catch_all_delivery` migration through the normal database release process and deploy the matching Mail app and Email Routing Worker. 2. Open Mail settings as a root workspace operator, select `ingest.tutur3u.com`, choose the destination mailbox, and enable the logical catch-all route. The initial pilot destination is `phucvo@tuturuuu.com` when that mailbox exists. 3. In Cloudflare Email Routing, select the already-onboarded `ingest.tutur3u.com` subdomain and set its catch-all action to the `tuturuuu-mail-email-routing` Worker. Keep explicit rules enabled; they take precedence over catch-all. 4. Send a unique random local part directly to the ingress subdomain. Confirm the original recipient is visible in Mail, raw MIME and attachments are in R2, and a retry does not create another message. 5. In Google Admin, add a rule named `Tuturuuu Mail catch-all bridge` for inbound **Unrecognized/Catch-all** recipients only. Replace only the recipient domain with `ingest.tutur3u.com`, add `X-Gm-Original-To`, and leave Users and Groups unchecked. This keeps recognized Google Workspace delivery unchanged while preserving the unknown local part for Mail. Do not enable Cloudflare Email Routing on the `tuturuuu.com` apex while Google owns its MX records. To roll back, disable the Google unrecognized-recipient rule first, disable the Cloudflare subdomain catch-all second, and disable the logical Mail route last. Do not delete ingested metadata or R2 objects. ## Provider rollout and rollback Provider selection is independent in each direction. Change only one direction at a time on the staging domain, complete inbound delivery, outbound delivery, attachment, threading, duplicate retry, and bounce/throttle smoke tests, then enable the production domain. A mailbox override may be used for a narrow outbound canary. To roll back outbound delivery, clear the mailbox override and set the domain outbound provider to `ses`. To roll back inbound delivery, restore the domain's SES MX/receipt-rule configuration first, then set `inbound_provider` to `ses`. Do not change the database flag before DNS is serving the intended provider. Existing SES jobs, raw S3 metadata, and credentials remain supported throughout the rollback. ## Operations ### Mail settings and account settings Mailbox settings use the `mailSettings=open` query parameter. The shared satellite account settings use `settingsDialog=open` and `settingsTab`; keep these separate so the guidance dialog cannot cover the mailbox delivery, membership, and sender controls. Closing either dialog must preserve the other dialog's query state. Mail sanitizes message HTML and signatures with `sanitize-html` in both the server ingestion/draft path and browser previews. Its allowlist retains email tables, typography, and `cid:` image references while excluding active content and CSS resource URLs. Avoid reintroducing an externalized jsdom-based sanitizer: an incompatible CommonJS/ESM dependency can fail module initialization and make even the mailbox bootstrap route return HTTP 500. Validate sanitizer security fixtures and a real Mail build when changing this dependency boundary. ### Full Google mail migration Inventory active and suspended accounts, aliases, group membership, delegated mailbox access, and existing routing before importing data. Preserve suspended account access restrictions. Google groups can also authorize access to Google Cloud resources; migrating their email does not authorize deleting those groups or changing their IAM membership. For the Tuturuuu migration, suspended accounts stay suspended while incoming mail for their addresses follows the domain catch-all to `phucvo@tuturuuu.com`. An existing inactive mailbox must not be recreated by automatic provisioning. This delivery policy does not grant the suspended user mailbox access. Google Admin's available organization export may include all services rather than Gmail alone. Review the actual scope before starting it, obtain approval for non-mail data, and use only the mail portion for this migration. A scheduled or in-progress export is not an imported archive. Keep the source service until the completed export has been downloaded, reconciled, and imported with original dates, folders/labels, read state, attachments, and mailbox ownership intact. The live Cloudflare webhook imports new inbound deliveries; it is not a historical Gmail importer and must not be used to silently flatten sent mail, drafts, or labels into the inbox. Use the resumable Google Takeout importer after extracting only each account's `Takeout/Mail` directory into one directory per email address. Run it without `--apply` first and reconcile its report with an independent MBOX inventory: ```bash theme={null} bun --env-file=/path/to/mail-production.env \ apps/mail/scripts/import-google-takeout.ts \ --root=/path/to/mail-data \ --report=/path/to/import-dry-run-report.json ``` The production operator can then repeat the command with `--apply`. The importer writes raw MIME and attachments to the configured Mail R2 bucket, uses deterministic IDs, and skips existing provider or Internet Message-ID records so an interrupted run can resume safely. It processes Deleted MBOX files first so duplicates retain their trash state. It preserves Gmail thread IDs, original timestamps, sent/draft/spam/trash/read/star/archive state, system labels, and custom labels. State rows may be recorded for a suspended user's existing profile, but the importer does not activate a mailbox or create a mailbox membership. After the apply run, compare its report with counts from `private.mail_messages`, `private.mail_raw_messages`, `private.mail_attachments`, and `private.mail_stored_objects`. Re-run the importer with the same arguments to verify that every message is reported as already present. Keep the source export until database counts, R2 objects, and an authenticated Mail reader sample all agree. Onboard Cloudflare **Email Sending** separately from **Email Routing**. Sending uses its bounce subdomain and DKIM records and can be prepared while the apex MX remains on Google. Verify the existing DMARC policy and reporting addresses after onboarding. Check the account's actual daily quota and the outbound message-size limit before switching the application provider; domain activation alone does not prove application sends or recipient delivery. For `tuturuuu.com`, the requested catch-all destination is `phucvo@tuturuuu.com`. Configure the logical Mail destination first, route the Cloudflare catch-all to the ingestion Worker, and retain explicit recipient routes. Prove delivery to a new random local part, the preserved original recipient, attachment storage, and duplicate handling before enabling the Google catch-all bridge or changing the apex MX. Never use SMTP forwarding back to the same domain as a substitute for internal mailbox ingestion. ### Smart labels and AI-assisted drafting Apply the `mail_smart_labels` migration before deploying the matching settings UI. It adds a description, mailbox-scoped AI instructions, an enable flag, and an auto-apply flag to each private custom label. The migration is additive and defaults every AI option to disabled. Label CRUD remains limited to mailbox owners and admins; senders may apply configured labels but cannot redefine the taxonomy. Mail exposes AI drafting and smart-label classification only through mailbox-authorized app routes and `packages/internal-api`. Drafting supports new messages, rewrites, and follow-ups with bounded thread context. Message content is treated as untrusted reference material so instructions embedded in an email cannot override the system prompt. Generated text is returned to the composer as an editable draft; the AI route has no send, schedule, or transport tool. Smart-label suggestions help owners/admins create a taxonomy from recent mailbox patterns. Classification accepts explicit thread IDs, validates every thread and label against the active mailbox, and applies labels only after an authorized user invokes the workflow. `ai_auto_apply` records whether a label may be applied by an authorized automatic workflow; it does not grant AI any additional mailbox role or send capability. The `repair_mail_thread_subjects` migration backfills blank legacy thread subjects from the newest meaningful message. Runtime thread hydration also falls back to the newest message so sent mail remains accurate when application deployment precedes the migration. * Run `bun sb:up` locally after mail schema changes, then `bun sb:typegen`. * Keep new mail route access checks in `apps/mail`; do not add direct client Supabase reads. * Use `packages/internal-api/src/mail.ts` for client helpers and TanStack Query in the app UI. * Unknown inbound recipients are retained as `quarantined` jobs for administrator review instead of being delivered to a user inbox. * Keep generated public assets such as `/manifest.webmanifest`, `/sw.js`, and offline worker files out of the auth proxy matcher. Redirecting those files to central Web login breaks standalone Mail startup and PWA registration. * Keep `apps/mail/src/proxy.ts` `config.matcher` entries as inline string literals. Next.js statically parses proxy matcher config during Vercel builds and rejects imported constants even when they resolve to strings. ## CI and deployment Mail preview and production use `.github/workflows/vercel-preview-mail.yaml` and `vercel-production-mail.yaml`, registered in `tuturuuu.ci.ts` through `ci-check.yml`. Preview builds prebuilt Vercel CLI artifacts. Production uses concurrency to prevent stale deployment; manual dispatch requires `refs/heads/production`. Credentials belong to the corresponding `vercel-preview-mail` or `vercel-production-mail` GitHub Environment: `VERCEL_TOKEN`, `VERCEL_ORG_ID`, and `VERCEL_MAIL_PROJECT_ID`. Keep production Supabase/SES values in the Vercel project. Do not put those values, `TURBO_TOKEN` or `TURBO_TEAM` into workflow env; use `vercel pull`. `apps/mail/vercel.json` disables Vercel Git integration. Fresh disposable hosted runners explicitly provision resource launchers with `bun packages/sdk/src/cli/resources-entry.ts setup --root "$GITHUB_WORKSPACE" --shell none` before the first queued setup workload. Both subsequent commands reuse that same installation and canonical queue. `run` never provisions missing launchers; a cold caller must complete explicit setup first. This hosted bootstrap does not authorize updating an installed developer or Studio scheduler. Workflow ordering is covered by `scripts/ci/mail-profile-runtime.test.mjs`; the cold reject → explicit setup → admitted run boundary is covered by `packages/sdk/src/cli/resources-provisioning.test.ts`. The exact-head `mail-profile-runtime-contract.yaml` follows resource CLI changes and uses frozen normal setup through the shared queue for Lettin profile upload/save/reload and independent Chromium session transport tests. Its exclusive disposable VM owns complete-schema Supabase Auth/REST/Storage on safe local API port 8001, local D1 fixtures and Next apps. The profile browser and session cookies use registered `http://localhost:7833`; Web/API, storage and readiness retain their independent IPv4 bindings. This fixture origin matches the existing signed-upload CORS registry without widening capability or authentication policy. Storage uses an owned HTTPS proxy and one-day CA with normal verification. Chromium sandboxing stays enabled: hosted-only setup authenticates Google's signed Release/Packages SHA256 chain, extracts only a fresh packaged helper without maintainer scripts, and records package/helper hashes. Root installs it exclusively at `/usr/local/libexec/tuturuuu-mail/chrome-sandbox` with protected parents and `4755` mode; `CHROME_DEVEL_SANDBOX` selects it using Chromium's [helper option](https://chromium.googlesource.com/chromium/src/+/main/docs/security/apparmor-userns-restrictions.md). No existing `/opt` bytes, shared Linux permissions or security policy change; require actual runtime success. Initial profile navigation failures retain at most 20 navigation-response source/target route classes, fixed locale presence, same-path booleans and HTTP status codes, without URLs, query values, workspace IDs, headers or bodies. Navigation failure records also retain document-body completion and observed DOMContentLoaded/load booleans. HTTP 200 alone does not prove a completed HTML stream or a loaded page; these observations never extend navigation deadlines or replace profile assertions. Terminal receipts retain actual statuses for the two named tests even on failure; stopped app records remain available to startup diagnostics. The disposable hosted fixture also enables default-off profile proxy provenance: fixed response-producer and request/Next pathname locale categories with a same-path boolean, without URL, tenant, query, cookie or token values. An absent marker is unclassified, not proof of a post-proxy cause; a marker identifies the proxy producer, not the redirect root cause. Lettin uses Next.js `skipProxyUrlNormalize` so locale canonicalization sees the original client URL instead of a synthesized locale prefix; explicit `/en` and `/vi` redirects, locale cookies, queries, shared-session and MFA checks remain enforced. Config changes require the real Lettin build and hosted profile runtime. Source checks and these observations do not turn a failed runtime gate into a pass. Missing/skipped/retried tests and failed cleanup fail the gate; fixtures delete only their synthetic IDs/media and stop recorded project/app/proxy processes. No provider credentials, raw traces or private CA keys are published. Broad E2E stays disabled; terminal evidence proves local profile/session behavior, not Worker/provider/production/customer delivery; pgTAP/schema types remain separate. ## Mail client navigation and recovery Mail owns one settings entry in its sidebar. Its shell disables the shared settings utility with `showSettingsButton={false}`; other satellite apps keep the default. Mail settings continue using the `mailSettings` URL state. Unread and attachment quick filters compose with the search query. The selection checkbox selects loaded conversations, and selection resets when the mailbox, folder, label, or search changes. Message loading failures show an explicit retry state instead of appearing as an empty mailbox. Sending, draft autosave, protected attachments, and delivery settings remain behind the existing Mail APIs. The conversation pane constrains message width and keeps message details and attachments available without expanding them by default. Small screens show one pane at a time, with a back action returning to the message list. ## Distribution groups A shared address can be provisioned as a distribution group by setting `private.mail_mailboxes.metadata.mail_group` to: ```json theme={null} { "posting": "organization", "attachments": "members", "sendAs": "managers", "historyEnabled": false } ``` Provision this metadata when creating a new address. Settings cannot convert an existing archive into a group, or a group into an archive. Owners and admins can change the three permission scopes in **Settings → Members**, add active internal members by email, change their roles, and remove non-owner members. Routine member management cannot create, demote, or remove an owner. Posting and attachment scopes support managers, members, the organization, or anyone. Send-as supports managers or all members. Owners and admins are managers; viewer and sender roles are ordinary members. A sender role does not override a managers-only send-as policy. Personal mailbox status must remain active for group access, sending, membership additions, and delivery. Membership does not reactivate suspended users. Cloudflare and SES ingress distribute accepted messages into active members' personal mailboxes in the group's domain. No shared inbound message or thread is created. Drafts and sent copies made using the group address are visible only to their author. Removing a member stops future delivery and access to the group address; copies already delivered to that member remain personal. Delivery uses the existing Message-ID/provider deduplication when groups overlap or delivery is retried. An empty group accepts a permitted message with zero personal copies. Group ingress verifies DKIM against the stored raw bytes and requires the signing domain to exactly match the From domain. It does not trust an incoming Authentication-Results header. This intentionally requires DKIM even for an anyone posting policy; SPF-only senders are not accepted. Failed authentication or posting/attachment restrictions quarantine the delivery job. Temporary DNS errors fail processing so the existing transport retry can recover. R2 attachment objects may be shared by personal copies; download authorization follows the accessible message and its attachment record. This supports direct internal membership and per-message delivery. It does not replicate Google Groups join requests, external or nested membership, digest subscriptions, shared archives, custom roles, Google footers, or moderator notification/approval workflows. Quarantine records remain available to operators through the existing delivery controls. Google IAM groups and their access grants are independent of Mail group configuration and must remain in place when still used for Google Cloud authorization. ### Internal forwarding and smart labels Mailbox owners and administrators can use Settings → Automation to forward new incoming messages to another accessible, active mailbox in the same domain, or to that domain's current enabled catch-all mailbox. Delivery retains the source copy and preserves original content and attachments. Forwarding is one internal hop; forwarded copies never trigger another forwarding rule. Self, inactive, cross-domain and distribution-group targets are rejected. Distribution groups continue to use member delivery. Disabling catch-all suspends a catch-all-based forward until an eligible target is configured again. Smart inbox uses `gemini-3.5-flash-lite`, Google's latest stable Flash-Lite model verified on September 7, 2026. Enable it separately per mailbox. New incoming mail is classified against custom labels; only labels with both AI and automatic application enabled are applied. Gemini may suggest up to three new categories; owners and administrators can review recent suggestions under Settings → Labels. Suggested labels are never created automatically. Subjects, sender addresses and up to 6,000 text characters are processed by the configured Google AI service. Attachments are not sent to the classifier. The existing AI memory/usage wrapper continues to apply its configured policies. Classification is bounded to twelve seconds without provider retries. Failures are logged and never reject accepted mail. The existing manual classification and suggestion controls remain available for recovery and older messages. Completed classification events prevent repeat work on normal delivery retries. Concurrent duplicate deliveries can still produce duplicate AI requests; label assignment itself is idempotent. Forwarding errors remain retryable through the inbound delivery job. Configuration is stored in mailbox metadata; this feature requires no schema migration. The reader defaults to dark appearance, with original newsletter colors available from the floating toolbar or Reading settings. Stylesheets are retained only inside a sandboxed iframe with scripts, forms, remote stylesheets/fonts and network APIs blocked by CSP. The iframe grants same-origin access to the parent solely for height measurement and protected inline images; it never grants script execution. External links open separately with no referrer. Raster CID images resolve through authorized attachment endpoints. Signature sanitization still removes stylesheets. Wide messages scroll within the reader rather than expanding the app. Rendering aims for common Gmail-style newsletters; it is not a claim of pixel-identical Gmail compatibility for every email template. Thread lists always display both the message date and delivery time. The mobile reader uses constrained native scrolling to prevent wide tables, subjects or attachment names from widening the application viewport. The reader preserves hidden newsletter preheaders and isolated inline CSS. Dark appearance adapts neutral surfaces and borders while preserving branded colors. Message content uses the full pane width; reply actions float over the bottom edge with reserved scroll space so the last line remains reachable. The collapsed sidebar contains folder actions only. Expanded navigation groups shared mailboxes by repeated address prefixes (for example GCP), while personal mailboxes remain directly accessible. ### Keyboard navigation Use the keyboard button beside the mailbox filters, or `?` while single-key shortcuts are enabled, to open the shortcut reference. Reading settings and the reference both let users disable single-key shortcuts; Tab, Shift+Tab and arrow navigation remain available. Arrow keys move focus between loaded conversations, Home/End reach the list boundaries, and Enter opens the focused row. `j`/`k` also switch an already-open reader. `x` selects a conversation, Shift+X toggles all loaded conversations, and `e`, `#`, and Shift+I apply archive, trash, and mark-read to the checked selection. `u` or Escape clears a checked selection; when no selection remains, it returns to the list. `/` focuses search, `c` composes, and `r`/`a`/`f` reply, reply all, or forward the loaded message. `g` followed by a folder key navigates while preserving the active mailbox. Composer shortcuts use Ctrl on Windows/Linux or Command on macOS: Enter sends through the normal review flow, S saves, and J opens AI assistance. Escape saves and closes. Focus moves to recipients for a new draft or the body for a reply, and returns to the opener after closing. Mailbox shortcuts pause during typing, IME composition, composing, and dialogs. Same-origin email-frame key listeners retain the script-disabled sandbox. ## Address decoding and similar deliveries Mail recovers damaged display names from the matching original RFC 2047 address header when available, including Latin-1 encoded words incorrectly labeled UTF-8. Already-lost replacement characters cannot be reconstructed; the reader displays the address instead. New inbound records use the same decoder. This requires no production backfill and does not alter stored raw headers. The loaded list groups single-message catch-all deliveries with distinct original recipients when sender, subject, preview, attachment presence, mailbox and a 10-minute time window match. These are labeled **similar deliveries**, since previews do not prove identical bodies. Groups are presentation-only: records, message counts, search, permissions and per-delivery actions remain independent. Expanding a group exposes recipient rows; keyboard navigation opens a collapsed group as focus reaches those rows. Filtering and loading additional pages may change group membership. No grouping occurs across mailbox access boundaries. ### Mobile inbox restoration Mail is a core mobile app for accounts whose email domain is `tuturuuu.com` or one of its managed subdomains, and for marked review accounts on `tutur3u.com` (see [Flutter Mail](#flutter-mail)); other accounts do not see its launcher or direct-route content. Discovery is only a hint: API authorization still controls mailbox access. The mobile inbox restores its last mailbox, folder, search, labels, and message list from encrypted, account- and workspace-scoped storage. Snapshots expire after seven days. Opening Mail rechecks access and refreshes messages; cached send permissions are never trusted. A denied access response clears the cached view and prevents late requests from restoring it. Draft editing and attachment downloads continue to use authenticated network requests. Opening a mobile message shows the reader immediately from the inbox row and keeps its detail request active while the inbox revalidates. Cached thread detail renders at once; transient detail failures get one bounded retry. If loading still fails, the reader shows the error with an inline Retry. A failed draft open still shows a Retry action above the floating dock. The reader leaves enough bottom scroll space to reveal the end of long messages above that dock. ## Mobile incoming-mail notifications See [Incoming Mail notifications](/platform/applications/mail-inbound-notifications) for event admission, configured domain authority, recipient preferences, physical-event deduplication, push-entry image privacy, recovery and held runtime verification gates. ## Snooze and mute Snooze and mute are personal thread preferences. They do not change another member's shared mailbox. Snooze hides a thread from your Inbox until its stored UTC deadline, including newly arriving replies. Inbox and Snoozed views refresh while open and on returning to the app; expired threads reappear without a cron write. Snoozing from Archive restores that user's message state so the thread can return to Inbox. Muted threads remain in the Muted view until unmuted. Both states suppress incoming Mail notification creation and delivery for that recipient. Other mailbox members are unaffected. Unmuting does not replay old muted notifications. Apply `20260923110000_mail_thread_snooze_mute.sql` after `20260923100000_mail_received_push.sql` before enabling these actions in production. The native swipe settings include Snooze and Mute. Swipe and web actions offer Undo; reader and web menus support rescheduling, unmuting, and returning snoozed mail to Inbox. ## Calendar invitations and message details Mail reads scheduling requests from authorized calendar attachments, including Google `multipart/alternative` calendar parts and legacy SES raw MIME. Ordinary ICS exports (`PUBLISH`), cancellation notices and calendar replies are files, not RSVP requests. The responding address must exactly match an invited mailbox; viewers and group delivery identities cannot send replies. Unsupported delegated identities and multiple competing event attachments do not expose controls. Google's duplicate alternative-body and ICS attachment copies are treated as one request only when their decoded contents match after newline normalization. Every copy must independently pass mailbox authorization; differing sequence, attendee, UID or other content remains ambiguous and hides RSVP controls. Reads are bounded to eight copies, 256 KiB per copy and 512 KiB combined. This applies to modern stored attachments and legacy SES raw MIME; regression coverage is in `calendar.test.ts` and `calendar-sources.test.ts`. The invitation card preserves the organizer, UID, sequence and occurrence when sending an iTIP `REPLY`. It displays the original location and time-zone label; Teams and Google Meet links have a separate join action. It creates no calendar event copy. A self-organized personal hold is not the organizer's invitation. Replies use a persisted invitation claim and an atomic draft-to-sending claim. Retries keep the same request identity. A pending or uncertain provider result is checked rather than automatically sent again. Interrupted preparation can resume with its original request identity, exposed only to its original actor. For historical threads without indexed iCalendar identity, only the latest inbound message in the thread can be answered; newer mail conservatively hides older RSVP controls, including after updates or cancellation notices. Mobile message details expand to show each authorized From, To and Cc name and address with native text selection/copy. Bcc appears only when it exists in the already authorized message data. A resolved empty inbox remains visible during background refresh; exiting the reader waits for pending archive settlement before reconciliation. ### Focused synthetic verification Run the calendar parser, attachment worker, reply claim, permission and invitation card tests in `apps/mail` with one Vitest worker. Run the Mail empty-inbox, invitation-card and message-details Flutter tests with `--no-pub` after `flutter gen-l10n`. Include existing optimistic/cache/filter/reader tests. Never send RSVP, archive user messages or create/delete live events for verification. A timezone-specific recurrence reply includes the original referenced `VTIMEZONE` component. Mail does not infer UTC from custom or Windows timezone names. Missing, competing, malformed or oversized definitions suppress RSVP; supported definitions use bounded STANDARD/DAYLIGHT observances and common yearly timezone rules. Scheduling enum parameters are case-insensitive; only individual attendee identities are eligible, including when `CUTYPE` is explicitly supplied. A completed historical request acknowledges its receipt without replacing a newer reply claim or the current response displayed by either client. Fresh changed intentions use fresh request identities. Preparation recovery uses the original stored reply identity, including when reopened in another authorized workspace; mailbox permissions and the original actor are still required. List refresh remains available during reader mutations and overlays only the owning mailbox's pending reader actions, so unrelated incoming messages remain visible. Web inbox list responses also replay state changes that were pending when the request began or started while it was in flight. This applies to pagination and background refresh in the owning workspace/mailbox. An archived final row stays hidden while the action is pending; a failed action restores it without removing new arrivals. The archive folder retains archived rows. The mounted React test uses the actual inbox, reader, Archive control and action hooks with synthetic API responses; it covers empty state, failure/retry and refresh after reader exit. Pending archive refreshes compare the captured conversation revision before hiding stale results. A newer inbound message in the same conversation remains visible because it falls outside the earlier archive action. Failure restores optimistic flags or missing old rows without replacing newer conversation data. ### Explicit invitation links to Calendar On web and mobile, an actionable invitation can be associated with an existing Calendar event by pasting its Calendar event link, viewing both records, and confirming. The preview separates the original invitation's organizer, invited identity, time, physical location and conference action from the selected event's account, organizer, attendees and location. A self-organized private hold remains a separate event even when the title and time match. No event is copied, merged, deleted or reparented, and linking never sends an RSVP. Replies continue to use the original invitation's validated scheduling protocol and identity. The association belongs to the actor and original Mail message. The server rechecks current invitation access, Calendar workspace/account/source access, provider UID and occurrence identity, and preview authority at confirmation. Unknown identity, superseded invitations, updates/cancellations and revoked permissions fail closed. A changed preview requires a new preview; an uncertain network retry reuses its receipt. Metadata compare-and-swap preserves reply claims and other actors' associations. Remove link deletes only the actor's association; it never deletes the Calendar event. Opening a linked event requires a fresh Calendar-authorized target. Ordinary ICS attachments do not expose these controls. On mobile, replacing the Mail repository clears the link preview and saved target even when workspace, mailbox and message stay the same. Delayed results from the previous repository are discarded; `mail_calendar_link_test.dart` covers this boundary. Mail-owned association endpoints use the existing message path followed by `/calendar-link`: GET reads the actor's association and authorized target; POST `/preview` previews `{ calendarWorkspaceId, eventId }`; PUT confirms that selection with `receipt`; DELETE removes the saved association with `receipt`. All responses are private and uncached. Calendar owns the read-only event authority endpoint; Mail accesses it using the configured Calendar origin and existing forwarded cookie/Bearer authentication, with no Calendar table access. ## Native inbox refresh and settings Opening a Mail notification prepares the inbox alongside the reader. An existing snapshot for the same inbox remains visible, and the inbox revalidates while its reader is open. Background refresh pauses during outstanding optimistic Mail mutations. Network, timeout, and server list failures retry once. Rate limits are not automatically retried and preserve the authorized snapshot; revoked authentication/access is not retried and clears cached content. A failed refresh preserves a previously resolved empty inbox and shows a retry action rather than replacing it with a full-screen error. Cold failures remain visible. These rules apply only within the same account/workspace/mailbox and retain the existing cache permission checks. `mail_background_refresh_test.dart` and existing inbox mutation tests cover this behavior; authenticated provider/device proof remains a release gate. A completed Mail mutation can invalidate a concurrent inbox or detail fetch. Within an unchanged actor/workspace cache scope, the native repository restarts that interrupted read once and coalesces concurrent consumers onto the new request. Repeated invalidations remain bounded and surface a failure for retry; authentication, access denial, logout and scope clears never trigger this restart. The reader awaits the API client's transport timeout rather than starting a shorter timeout that rejoins the same unfinished request. Real API failures still use the existing transient-error policy. `mail_invalidation_race_test.dart` covers delayed mark-read success/failure, coalescing, bounded restarts, scoped mutations and denial/logout ABA fences with the actual encrypted cache and repository. `mail_error_scope_test.dart` covers awaited fallback and cache-unavailable publication boundaries, including late errors after a new same-ID session. Mail quick settings and central App settings use the same mailbox settings editor. Central settings resolves real mailbox membership before opening the editor; members keep personal device options and only owners/admins edit mailbox configuration. Mail settings uses the existing shell title and bottom Back/Save actions, without a second app bar. Unsaved mailbox changes require confirmation to discard; saves block exit until settled. Account or workspace transitions cancel the editor, including a switch away and back. `mail_settings_navigation_test.dart` covers the title/actions and edit guards. Retained sender image and gradient backgrounds in Original view keep their foreground colors, because a background-color alone does not establish the painted contrast. An opaque solid child resumes contrast correction. The immediate request reader checks monotonic elapsed time before and after each stream read, including end-of-stream. Immediately resolved chunks cannot bypass the ten-second deadline while timer callbacks await service; wall-clock changes do not extend it. The existing byte/chunk/selection limits and authenticated request ownership remain unchanged. Deadline regressions count actual stream reads at the exact boundary; this bounds request intake, not automatic draining or spend. ## Personal Gmail and Outlook accounts Mail also offers **Connected accounts** in a personal workspace. Any authenticated Tuturuuu user with access to that personal workspace may connect Gmail or Outlook; managed Tuturuuu mailboxes retain their existing staff/reviewer and mailbox-role checks. Connections belong to the authorizing user, not to workspace members or shared mailbox delegates. Account discovery and every provider operation bind both user and workspace before decrypting credentials. The connected view reads provider mail directly. Inbox, Sent, Drafts, Archive, Trash and Spam, provider search, pagination, read state, stars, archive, trash and restore therefore operate on Gmail/Outlook rather than a separate local mirror. Mailbox operations use immutable Outlook IDs. Refresh retrieves current provider state; this view does not implement push notifications, offline mail storage, custom-folder/label management, or Google Tasks/Microsoft To Do synchronization. Calendar account consent remains separate from Mail consent. Compose, Reply, Reply All and Forward send through the connected provider. Reply-To can contain multiple addresses; Reply All retains To/Cc roles, removes the user's address and deduplicates case-insensitively. Replies to sent messages target the original recipients. Bcc is never copied into a reply. Forwarding copies selected original attachments from authorized source bytes and starts without recipients. MIME carries Unicode subjects, threading headers and calendar scheduling types. Gmail replies and reply drafts additionally retain the authorized provider thread ID when the subject is unchanged apart from reply prefixes; forwards and changed subjects start a new conversation. Attachments are limited to 10 MiB in the browser and outbound MIME to 20 MiB. Message preview and JSON request reads have bounded server-side limits. Aggregate attachment bytes are checked before MIME encoding, including forwarded copies. Drafts are saved in the provider mailbox and can be opened, edited, and sent from Drafts. Gmail edits update the existing draft. Graph does not support updating a draft with raw MIME, so an edit first creates a confirmed replacement and deletes the unchanged original with an ETag fence. A deletion conflict retains both drafts and reports that partial outcome. Untouched draft HTML, inline image content IDs, threading headers and attachment bytes are preserved. Original HTML is recovered from the authorized provider source for saving; previews still use sanitized content. Save edited drafts before using the native Drafts send action. HTML previews use a script-disabled sandbox and a restrictive CSP; remote images are blocked. Original attachments download as files with `nosniff`. Personal calendar invitations use the same bounded iTIP parser as managed Mail. Accept, Decline and Tentative send a single-attendee `METHOD:REPLY` to the stored organizer, retaining UID, sequence and recurrence identity. No calendar event is copied into Tuturuuu, and ambiguous/delegated/cancelled requests do not expose RSVP controls. ### OAuth setup and delivery verification Configure these server-only variables for the Mail deployment: * `MAIL_CONNECTED_ACCOUNTS_KEY`: a dedicated 32-byte encryption key encoded as 64 hexadecimal characters. Credentials and PKCE verifiers use AES-256-GCM with the authenticated user ID as associated data. Keep the key stable; changing it requires reconnecting accounts. * `MAIL_GOOGLE_CLIENT_ID`, `MAIL_GOOGLE_CLIENT_SECRET`, `MAIL_GOOGLE_REDIRECT_URI`. * `MAIL_MICROSOFT_CLIENT_ID`, `MAIL_MICROSOFT_CLIENT_SECRET`, `MAIL_MICROSOFT_REDIRECT_URI`. Both registered callback URLs point to the Mail origin's `/api/v1/mail/connected/callback`. Enable the Gmail API and grant `https://www.googleapis.com/auth/gmail.modify`. This is a restricted Google scope; complete the provider's required consent verification before public rollout. Register the Microsoft app for organizational and personal Microsoft accounts when both are intended. Scopes: `User.Read`, `Mail.ReadWrite`, `Mail.Send`, and `offline_access`; Mail requests no Calendar scopes. OAuth uses PKCE, random hashed state, an HttpOnly SameSite browser cookie, a 10-minute expiry, atomic state consumption, and renewed personal-workspace access checks during the callback. Private connection, OAuth and send-claim tables have RLS and no `anon`/`authenticated` grants. Expired tokens refresh on the server; refresh writes compare revisions; only a newer scoped, valid winner can resolve a conflict. An unauthorized read can refresh and retry once; mutations are not automatically replayed. Disconnect removes local access and encrypted credentials without changing provider messages. Provider-side application consent can be revoked in Google/Microsoft account settings. Sends reserve an account/request claim; acceptance records a receipt. Proven pre-send failures or explicit provider rejections release only their matching sending claim for user retry. Completed requests acknowledge without resending; in-flight, unknown or post-acceptance failures require provider Sent checks. Provider acceptance is not a delivery receipt. Test only with disposable mail and meeting fixtures unless real-account actions have been explicitly authorized. Regression coverage: `apps/mail/src/lib/mail/connected/*.test.ts`, connected composer/reply tests, managed `mail-reply-actions.test.ts`, and the private-table checks in `apps/database/supabase/tests/connected-mail-accounts.sql`. The DB gate compares the three generated private Mail table contracts against committed types, ignoring only presentation; it does not certify unrelated schema drift. Require the Mail and affected workspace CI type-check, lint, tests and real app builds for the exact authored commit. Synthetic tests do not prove provider consent, delivery or RSVP; verify those with configured test accounts after deployment. ### Complete-schema database gate The `Connected Mail database contract` workflow runs on normal pull-request updates that change migrations, its fixture or verifier. It checks out the exact PR head, applies every tracked Supabase migration in an isolated hosted database, and requires all 10 assertions in `connected-mail-accounts.sql` to pass without skips. Its enabled-gate check fails if the workflow is disabled. After TAP succeeds, it generates actual `public`, `private` and `storage` schema types and uploads `connected-mail-accounts-types-` for three days. Inspect the exact run's reset, fixture-labelled TAP, type-generation and owned-project stop results, then compare the downloaded types with the authored private Mail tables before merging. A generated artifact or staging wrapper success alone does not prove the entire contract. This disposable gate does not apply production migrations or establish provider consent, mailbox delivery or RSVP outcomes. ### Native Mail type boundary (candidate) Scope: Mail's native frontend defaults to strict noncomposite noemit app checking, then genuine Mail-only declarations, then the actual noDOM Worker check. Both app programs retain all current roots and imported-source checking; shared package export/build/check owners remain authoritative. `bun run type-check` sequences app, boundary and Worker. The boundary emits into `.typecheck/app` with rootDir `.`, noEmitOnError and incremental false. The Worker resolves only emitted `#mail-handler` declarations; Vite resolves that exact alias to the real source. Inherited Turbo prerequisites and `.typecheck/**` outputs are preserved. Direct Mail production/test imports use package exports: the narrow Supabase realtime-log-actions entry follows its existing dist-types/source-Bun/dist-JS convention and build roots; Satellite workspace/invitation entries already exist. The app-local resolver exempts server suppliers when porting client calls, avoiding recursive transport aliases. No supplier or shared producer is changed. Static edge regressions remain authored UNRUN; real compiler external-source classification still requires exact-source CI. Limits: generated binding-only declarations must come from the qualified emitted deployment config. Pinned compiler workspace-external classification/rootDir behavior, declaration closure and clean/restored-cache acceptance remain unproven. Missing bridge/ambient isolation regressions are authored UNRUN in `apps/mail/src/runtime/type-programs.test.ts`; source assertions do not establish compiler or workerd acceptance. Unexpected foreign emission or incompatible contracts stop qualification without source exclusions. Logger timer/buffer lifetime and all provider/runtime delivery gates remain parent-owned; this decision adds no scheduler or resource. # Incoming Mail notifications Source: https://docs.tuturuuu.com/platform/applications/mail-inbound-notifications Event admission, recipient privacy, deduplication, and verification boundaries for mobile Mail. ## Admission and defaults New SES and signed Cloudflare deliveries use the existing Inbox-label transaction to create personal `mail_received` notifications and dedicated immediate push batches. They do not wait for a periodic scan. There is no notification email. This describes source behavior; it does not establish a delivery latency bound. Recipients must be active persisted mailbox members with a current confirmed, non-banned Auth account on exact `tuturuuu.com` or a DNS-label-valid descendant. Both account and canonical mailbox domains require active configured `private.mail_domains` rows with `verified_at`. This stored status is configured authority, **not fresh DNS or provider ownership proof**: the management API can stamp it. The message's raw provider identity, observed ingress recipient, and canonical domain mapping must bind to the persisted mailbox. Cloudflare ingress must pass the existing signature check; SES uses the existing SNS verification. Production provider configuration remains a separate deployment prerequisite. Mobile launcher discovery accepts the same domain syntax as a hint. The Mail API admits a subdomain account only after rechecking current Auth and its existing active personal mailbox ownership and membership. It retains the personal-workspace restriction. This does not broaden the global staff predicate or reviewer rules. Google Takeout imports, historical imports, outbound mail, quarantined or failed spam/virus messages, and initial deliveries older than five minutes do not alert. Mail and general push preferences, quiet hours, thread mute and snooze still apply. These suppressions are recipient-specific. Current membership, configured domains, message availability, preferences, unread notification and recipient Mail state are checked again before sending. Existing notification read/dismiss handling remains in use. ## Physical-event identity and recovery `20261012140000_mail_inbound_notification_admission.sql` adds a nullable receipt `event_key`, unique per user for non-null keys. New decisions use `raw_message_id` so original and internally forwarded copies sharing the same raw message notify a common owner once. Different owners each retain their own decision. Suppressed decisions also claim the event; enabling preferences or unmuting later does not replay it. Provider retries and Inbox relabeling cannot duplicate that claim. The migration reconciles existing accepted and suppressed receipts before new admission. It retains duplicate historical rows with null event keys and never backfills notifications. Only the reconciled canonical receipt can authorize a legacy pending send; duplicate history cannot. Historical messages without raw identity retain a message-based legacy key. It does not rewrite provider outcomes or forwarding. Delivery continues through the existing immediate queue and Firebase device registry. The recovery processor preserves its bounded retry and expiry limits. A persisted `delivery_in_flight` marker fences a lost provider response as `delivery_outcome_unknown`; it requires operator reconciliation, not automatic replay. See the [explicit selection budget](/build/devops/cloudflare-cron-control#explicit-immediate-selection-budget). No new scheduler or dispatch service is introduced. ## Push previews and opening Mail push copy is bounded plain text. HTML, control characters and URL tokens are removed from sender/subject previews before constructing visible and data payloads. The payload retains UUID mailbox/thread/message/user identities; no remote image is supplied. This sanitization does not classify every possible secret in prose. A push tap requires the same signed-in recipient and fresh authorized mailbox bootstrap. Notification-opened readers suppress external images for that entry, even when the saved image preference is enabled. Explicit per-reader reveal is allowed and does not change the saved preference. A failed detail request retains this privacy intent for its visible Retry action. Ordinary inbox entry continues to use the saved preference. Reader CSP blocks remote images while suppressed. ## Regression evidence and held gates Run the bounded SQL fixture through the normal resource queue: ```sh theme={null} ttr resources run -- bun apps/database/scripts/mail-inbound-notification-fixture.mjs ``` The fixture applies the actual legacy Mail migrations and new admission migration in PGlite with pgTAP. The schema, notification preference lookup and `pg_net` transport are synthetic scaffolds. Assertions cover receipt reconciliation, recipient/canonical binding, alias and forwarding deduplication, suppression, notification/Mail read, archive and trash before send, and revocation. This is **not** the full Supabase migration chain, RLS/Auth integration, actual `pg_net`, provider delivery, or concurrent hosted execution. Full migration application and generated-type verification remain required in an authorized database environment before promotion. Focused route tests cover managed mailbox authority and existing signed ingress. Preview tests exercise real push payload construction. Flutter `mail_notification_privacy_test.dart` covers access-before-open, local reveal, preference preservation and failed-open retry; existing push UUID and dismissal regressions remain required. Exact-commit CI must pass applicable lint, type, tests, web/Mail builds and mobile gates. Actual foreground/background notification arrival, permission behavior, system dismissal and tap timing require authorized fixtures and a device. A Firebase response alone does not prove device arrival. Source checks cannot establish production DNS/provider configuration or delivery. # Meet Source: https://docs.tuturuuu.com/platform/applications/meet Meeting plans, collaboration rooms, calls, transcription, assistants, and follow-up review. Meet (`meet.tuturuuu.com`, `apps/meet`) combines meeting planning and live collaboration. Public product explanations live on the main site; operational rooms, plans, and workspace meeting records are excluded from search indexing. ## Choose the meeting surface | Surface | Purpose | Details | | - | - | - | | Workspace meetings | Find and manage workspace meeting records | `/{wsId}/meetings` | | Plans | Plan availability and coordination | `/{wsId}/plans`, [Meet Together](/platform/features/meet-together) | | Calls | Audio/video and session collaboration | [Calls](/platform/features/meet-calls) | | Solo mode | Individual session workflow | [Solo mode](/platform/features/meet-solo-mode) | | Live assistants | Session-specific assistant behavior | [Live assistants](/platform/features/meet-live-assistants) | | Follow-ups | Review proposed tasks and calendar events | [Follow-ups](/platform/features/meet-followups) | | Native collaboration | App/native collaboration boundary | [Meet route reference](/reference/repository/routes/meet) | ## Before, during, and after a session Before joining, verify the correct workspace/plan, participant access, and the configured meeting provider. During the call, recording, transcription, and assistant behavior follow the documented session controls and provider state. Afterward, review notes and proposed follow-ups before writing to Tasks or Calendar. A proposal is not an executed action, and a room URL is not broad workspace authority. ## Public authentication callback Meet's native app renders the tokenless `/verify-token` and `/vi/verify-token` callback shell for exact GET and HEAD requests, including locale context, without consuming a verification token or requiring an account session. The explicit English locale prefix retains normal locale canonicalization. This lets a direct callback visit render the bilingual loading/logo UI and its hydration assets. An explicit `token` query parameter, including an empty value, and other methods continue through the shared verifier; token validation, safe next destinations, session cookies, login routing and protected routes retain their existing rules. The exception applies only to these exact callback routes, not API or workspace routes. Real-proxy controls live in `apps/meet/src/proxy.public-callback.test.ts`; SSR, hydration assets and both locales still require the emitted Worker CI gate. ## Browser language selection When a Meet page has no supported locale in its URL or locale cookie, browser language negotiation uses valid locale tags from `Accept-Language` in their quality order. Wildcard ranges and invalid locale tags are ignored before locale matching. If no valid preference remains, Meet uses its existing English default. Valid regional English and Vietnamese preferences continue to select their supported language. Zero-quality ranges remain excluded by negotiation. A supported URL locale takes precedence over the locale cookie, which takes precedence over the browser header. Public callbacks retain their existing locale handling; authentication, SSO destinations and safe next-path rules are unchanged. Real-proxy and Request-bridge regression controls live in `apps/meet/src/proxy.public-callback.test.ts`. Hosted original and restored Worker acceptance remains a separate gate. ## Public login locale routing For the exact locale-prefixed public login paths `/vi/login` and `/en/login`, Meet uses the configured English default for `as-needed` prefix handling. Explicit `/vi/login` continues to the login renderer with the Vietnamese locale header, even when the locale cookie or browser language prefers English. Explicit `/en/login` intentionally retains its redirect to unprefixed `/login`. Unprefixed `/login` retains the existing cookie and browser language selection; all other paths retain their existing locale handling. This path-scoped rule leaves the default authentication policy, public callback handling, token verification, session checks and branch ordering unchanged. Central SSO continues to return through Meet's `/verify-token` callback, and the shared safe next-path guard continues to reject external destinations. The real-proxy/bridge regressions in `apps/meet/src/proxy.public-callback.test.ts` cover both login paths with absent, English and Vietnamese headers and conflicting locale cookies, preserving the encoded query, forwarded locale, exact callback continuation and zero fetches. Their fixed Start SSO response establishes only proxy/bridge continuation; shared login-page rendering and emitted original/restored Worker acceptance require separate runtime evidence. These controls do not establish the cause of a past hosted redirect. ## Plan guest passwords and sessions Scope: guests who join a Meet plan by name, with or without a password, on both the Meet satellite and the web-hosted plan page. Signed-in platform users are unaffected. * **Storage.** Guest passwords are stored with the shared server-only KDF in `@tuturuuu/utils/crypto` (scrypt, encoded as `scrypt$N$r$p$salt$key` with N=2^15, r=8, p=1, a 16-byte random salt and a 32-byte key). The salt lives inside the encoding, so `password_salt` is written as an empty string for new rows. Verification uses a constant-time comparison. * **Credential flow.** The guest submits the plaintext password over HTTPS to the guest login server action. The server verifies it and returns a signed guest session (`@tuturuuu/utils/meet-guest-session`) bound to that guest and plan, valid for 12 hours. Availability updates and guest poll actions present that session (`guestSession`); the server re-verifies the signature, plan, guest and expiry, and checks that the guest still belongs to the plan. Stored password hashes are never returned to the browser and are not accepted as a credential. * **Default.** Passwordless guests keep working: the empty password is hashed like any other value. The saved-name auto login on reload still applies only to passwordless guests; the password and the session are not persisted. * **Expiry.** When a session expires the guest action is rejected and the guest signs in again from the plan page. * **Attempt limits.** Guest password attempts are limited per plan and guest name and per client IP (see [shared-secret password budgets](/build/devops/adaptive-abuse-rate-limits#shared-secret-password-budgets)). While a budget is spent the form shows a localized retry message, even for the correct password. Verified logins refund one target attempt; source counters retain the charge. The source budget is 300 attempts per 15 minutes to tolerate shared office addresses. Creation reserves 10 attempts per plan and source network per 15 minutes, independent of the chosen name. Different networks do not share a plan-wide creation cap. IPv6 addresses share their /64; unknown IPs share a bucket. Missing plans do no hashing. Creation denials use distinct English/Vietnamese copy about attempts to join. The participant view and guest table are available only to server/admin clients; client roles cannot query either directly. Regression coverage lives in `packages/apis/src/meet/actions/auth.test.ts`, `packages/utils/src/abuse-protection/__tests__/password-attempt-limits.test.ts`, and `apps/database/supabase/tests/security-meet-guest-grants.sql`. * **Table access.** `meet_together_guests` keeps row level security with no client-role policies, and client-role table grants are revoked; only server code using the service role reads it. * **Signing secret.** Sessions are signed with the shared server token secret (`TUTURUUU_APP_COORDINATION_SECRET`, falling back to `SUPABASE_SECRET_KEY`) through a purpose-derived key, so they cannot be replayed as any other token type. Rotating that secret ends all active guest sessions. ### Password hash migration 1. **Reset markers.** `verifyPassword` accepts only the `scrypt$` encoding. Any other non-empty stored hash, including the legacy unprefixed salted SHA-256 hex digest, returns `resetRequired: true` and never verifies or upgrades from a submitted password. Guest sign-in returns `PASSWORD_RESET_REQUIRED`, and the plan creator recovers the guest with **Reset a guest password**. The full policy is in [shared-secret password reset](/platform/features/shared-secret-password-reset). 2. **No backfill.** Legacy rows cannot be converted without the plaintext, so the existing hash format is the durable reset marker; there is no schema change, migration step or bulk update. 3. **Parameter rehash.** When a scrypt hash with older parameters verifies, the login request replaces it with a fresh scrypt hash using an update filtered on the previous `password_hash` value, so a concurrent upgrade is never overwritten. A failed upgrade is logged and the login still succeeds. 4. **In-flight clients.** Browsers holding a page from before this change send the retired hash field, which the server now rejects. Those guests see a failed save or vote and sign in again after reloading. Regression coverage: `packages/utils/src/__tests__/crypto.test.ts`, `packages/utils/src/__tests__/meet-guest-session.test.ts`, `packages/apis/src/meet/actions/auth.test.ts`, `packages/apis/src/meet/actions/polls.test.ts`, `apps/web/src/app/api/v1/meet/plans/[planId]/availability/route.test.ts`, `apps/meet/src/runtime/legacy-action-ports.test.ts` and `apps/database/supabase/tests/security-meet-guest-grants.sql`. ## Runtime boundaries Meet shares behavior through `packages/meet-core` and `packages/meet-ui`. Realtime, signaling, provider connectivity, and hosted SFU/TURN are separate boundaries. A local Worker fixture does not establish hosted media-network success. The [Meet runbook](/build/devops/overview) and linked call feature guide identify the owning deployment and verification path. [Mobile workspace tools](/platform/features/mobile-workspace-tools) documents native availability and opt-in defaults. Rooms and plan share links stay noindex even when participants can join without browsing an entire workspace. ## Native Worker verification The native renderer uses TanStack Start SSR, Vite+ and the official Void SDK. Shared meeting behavior and the separate realtime Worker retain their existing ownership. Framework source or a successful build does not establish production cutover or hosted media acceptance. Preserve supplier-generated `src/routeTree.gen.ts` bytes, including generated casts. Meet and Calendar need owning-config `formatter.includes` set to `["**", "!src/routeTree.gen.ts"]`: Biome 2.5.13 rebases inherited root `files.includes` globs under nested configs, so a root app-qualified exclusion can miss this file. Follow the development-tooling formatting procedure; isolated formatter fixtures do not establish full CI or Worker runtime acceptance. Use `bun run build:cloudflare` in CI. Discover the emitted Worker configuration through exactly one of `.wrangler/deploy/config.json` or Void's saved `.void/preview-deploy-config.json`; reject missing or simultaneous pointers. Void preserves the pointer bytes when moving it, so resolve `configPath` from the original `.wrangler/deploy` directory in either case. Do not assume an output directory or recreate a missing pointer. Preserve the existing Worker identity, targeted placement, bindings, secret names and Durable Object migration history. Qualify, seal and restore the complete output before publishing those exact bytes with the app-local Wrangler adapter. Void CLI deployment is not interchangeable: the released CLI rebuilds, prepares additional output and cannot preserve this targeted-placement path. Live qualification validates the materialized input and emitted config against Meet's fixed resource policy and pinned supplier/parser profiles. It measures materializer and loader-selection facts twice, rejects typed-source, input or profile drift, and admits only explicit default representations. Empty queue producer/consumer lists cannot authorize a queue; existing bindings, migration history and placement remain exact. Inspect the bounded field-rejection reason when qualification fails; diagnostic absence does not approve a value. The schema-2 artifact seal retains the original input path/hash, platform and qualification profile alongside exact output hashes. Restored discovery requires the seal, external expected SHA and complete file hashes before policy checks. It compares historical metadata without opening or rebasing the original input path and never falls back after a malformed seal. Raw emitted config bytes stay unchanged. This relationship does not prove historical retained-state provenance. Regression coverage is in `scripts/ci/verify-meet-start-output.test.js`. Both the original prepack dry-run and production restored dry-run use `scripts/ci/meet-dry-run-scratch.mjs` from `apps/meet`, passing `"$SOURCE_SHA"`. The wrapper derives the emitted config through the existing artifact verifier, requires its manifest and canonical output, and captures the strict directory seal and absence of the config parent's `.wrangler` and `.wrangler/tmp` before running the same app-owned `bun x --no-install wrangler deploy --dry-run -c` command with the discovered config and inherited environment. Wrangler can leave empty `.wrangler/tmp` ancestors after removing its deploy child. After successful child close, the wrapper accepts no residue or exactly that empty two-directory layout. It verifies file hashes and the complete prior layout before using nonrecursive `rmdir` on the leaf and then parent, and rechecks the manifest and strict directory seal afterward. Preexisting, partial, nonempty, linked, special or unexpected entries fail closed; command failure preserves residue without cleanup or retry. The file manifest alone cannot reject extra empty directories. Keep the hidden-entry allowlist, full tar contents and launcher's original-artifact seal unchanged. The credential-free restored gate does not need another dry-run or rebuild. On rejection, preserve the failed artifact/evidence for bounded inspection; do not recursively delete scratch or normalize the archive. Syntax and source review do not qualify this repair: require exact-commit dry-run, pack/restore, and original/restored launcher acceptance in CI before claiming producer repair. After qualification, collect `native-emitted-config-meet.json` even on failure. Keep the actual source HEAD separate from the event SHA. Retain pointer and config hashes and a redacted key-shape inventory, never raw configs, resource identifiers, or secret values. Unavailable or overflow diagnostics remain failures. The receipt provides no acceptance, allowlist approval, or rollback proof. Inspect the actual receipt before qualifying unexpected `queues` or `configPath` fields. Preserve the strict resource, saved-pointer, native-relative-base, restore, and deployment gates. Diagnostic receipts use schema 2 with `wireEncoding: "scoped-layouts-v1"` when `inventory` or `defaultProbe` is present. Only those fields use shared ordered `layouts`: `[0, layoutIndex, ...values]` represents an object and `[1, ...items]` represents an array. Scalars and full hashes remain unchanged; optional absence, null, false, property order and row order are preserved. Top-level status and provenance remain readable. Use `decodeReceipt` from `scripts/ci/native-receipt-layout.mjs` to restore the original logical schema 1; it also accepts legacy schema-1 receipts. It rejects unsupported encodings, malformed layouts/tags, duplicate or prototype-related layout keys, excessive depth and expanded size. Decoding never qualifies acceptance or supplies missing status/evidence. `inventoryHash` still commits to the original inventory JSON. The complete wire receipt, including its final LF, must fit 16,384 UTF-8 bytes. Overflow retains the existing schema-1 unavailable summary and failing exit code, without partial diagnostics. Collection and the live default probe stay logical objects. Regression coverage lives in `native-receipt-layout.test.mjs` and `native-emitted-config-receipt.test.mjs`; actual emitted-payload fit requires CI on the new commit, separately from historical and synthetic fixture coverage. Request adapters preserve satellite sessions, locale rewrites, response cookies and central API ownership. Native plan mutations use POST server functions with CSRF checks and the canonical authorization suppliers. Intentional credentialed guest actions remain scoped to the existing plan policy. Confirmed mutations invalidate the native loader; denied or uncertain results do not report success. The owning workflow must verify emitted server/client boundaries, bilingual SSR, SSO redirects, logout cookies, API forwarding, static assets and Live admission. The artifact-dependent suite is `scripts/ci/meet-cloudflare-render.runtime.mjs`; it runs after building and again against the restored artifact, outside generic source-only test discovery. The credential-free `restored-artifact` job depends on `validate` and downloads its exact-SHA `meet-worker` archive into a fresh immutable-source checkout with frozen dependencies. Unlike the original post-build gate, it restores the uploaded bytes without rebuilding, verifies the seal and discovers the restored config, then runs `scripts/ci/meet-native-launcher.mjs` and the finite SDK checks under the existing three-minute deadline. It retains finite graph evidence even on failure and rechecks the manifest after acceptance. This job has only `contents: read`, no production environment or account credentials, and performs no deployment. The production job retains its own restored-runtime defense. Workflow wiring is not an executed CI result: client-boundary source review does not establish hydration or token completion. Provider, staging, canonical-route and recoverable rollback acceptance remain separate requirements. Signed-in workspace, room and plan flows, all native mutation transports and browser hydration need independent acceptance. Preserve an observed hosted configuration and recoverable prior Worker version before traffic changes. Local workerd probes do not qualify hosted SFU/TURN, devices, recording or assistant stop behavior. # Mind Source: https://docs.tuturuuu.com/platform/applications/mind Mindboard satellite app for long-horizon planning, knowledge graphs, and AI-aided graph patches. Mind lives in `apps/mind`, runs locally on port `7816`, and is served in production from `https://mind.tuturuuu.com`. Local development should use Portless at `https://mind.tuturuuu.localhost`; the legacy direct fallback is `http://localhost:7816`. Mind is available to signed-in Tuturuuu users, not only internal `@tuturuuu.com` accounts. The satellite app accepts the Tuturuuu cross-app login handoff through `/verify-token`, stores a host-local `tuturuuu_app_session` cookie for the `mind` app target, and keeps workspace data behind membership checks. Mind must not create a local Supabase Auth session. Mind consumes `/verify-token` in the proxy and requires the coordinated cookie pair on protected routes: the Mind-local app-session cookie for route guards and the Web-issued app-session cookie for forwarded central APIs. If only the Mind-local cookie remains, route users through local `/login` to refresh the pair. Expired access tokens should rotate through `/api/auth/refresh-app-session` on the Mind origin while refresh cookies are valid. Mind AI also follows the shared AI credit contract instead of an employee-only allowlist. The `/api/ai/mind` route resolves the selected personal or workspace credit source, checks the caller's membership for workspace credits, preflights model availability and remaining credits, and deducts usage from that same billing workspace after a successful stream. Mind AI uses the stable `google/gemini-3.1-flash-lite` model entry for its Flash Lite default/fallback surface. Stored preferences and old clients that still send `google/gemini-3.1-flash-lite-preview` are normalized to the stable ID before credit model resolution and provider streaming. The model selector reads from the paginated infrastructure model catalog with server-side search and "load more" pages. Do not reintroduce first-page-only catalog fetches or local-only filtering; matching models must remain reachable even when they are outside the initial response. ## Dual-Host Parity Mind is available through both the standalone satellite host and the main web dashboard. The standalone route shape stays `/{wsId}` and `/{wsId}/boards/{boardId}`. Inside `apps/web`, the route shape is `/{wsId}/mind` and `/{wsId}/mind/boards/{boardId}`. Both hosts must render the same shared UI and use the same client logic from `@tuturuuu/mind-ui`. Keep `apps/mind` and the `apps/web` Mind routes as thin host wrappers for auth, workspace resolution, and route prefixing only. Future Mind feature work belongs in `packages/mind-ui` or the centralized Mind APIs so the standalone app and web-hosted app stay 1:1. Board route-segment layouts that render Mind board routes must load `@xyflow/react/dist/style.css`, and the shared Mind shell must keep a concrete dashboard embed height. Keep that stylesheet out of root app layouts and the Mind index so it is only loaded when users enter a canvas route. Without both pieces, React Flow can mount but render as a blank or collapsed canvas inside embedded dashboard routes. ## Board library vs studio The workspace index route is a **board library**, not the canvas studio: * **Web**: `/{wsId}/mind` lists boards (search, create, pick). Selecting or creating a board navigates to `/{wsId}/mind/boards/{boardId}` for the studio. * **Satellite**: `/{wsId}` is the same board library; `/{wsId}/boards/{boardId}` is the studio. `MindBoardIndex` from `@tuturuuu/mind-ui` owns the index experience. Do not auto-select the first board on the index route. `MindDashboard` only mounts on board routes and receives `initialBoardId`; it must not fall back to `boards[0]`. If a board route loads without a selected board, prompt the user to return to the index instead of showing an infinite loading state. ## API Ownership `apps/mind` owns its protected Mind product handlers: * `/api/v1/workspaces/:wsId/mind/boards` * `/api/v1/workspaces/:wsId/mind/boards/:boardId` * `/api/v1/workspaces/:wsId/mind/boards/:boardId/graph` * `/api/v1/workspaces/:wsId/mind/boards/:boardId/patches` * `/api/v1/workspaces/:wsId/mind/search` * `/api/v1/workspaces/:wsId/mind/ai/patches/:patchId/apply` * `/api/ai/mind` Exact local handlers win before the `/api/*` fallback rewrite. All remaining API requests go to `apps/web` with their paths intact, including the shared workspace selector's `/api/workspaces/invitations` and `/api/workspaces/:wsId` reads. These unversioned routes still belong to Web; forwarding only `/api/v1/*` and `/api/ai/*` leaves the selector's requests as Mind-local 404s. `apps/mind/src/next-config.test.ts` covers both workspace requests, versioned APIs, shared AI attachments, and fallback placement. The shared AI attachment endpoints also have no Mind-local handler and are therefore forwarded to `apps/web`: * `/api/ai/chat/upload-url`, `/api/ai/chat/delete-file`, and `/api/ai/chat/file-urls`, which provide shared Mind chat attachments The separate `/api/v1/hive/servers/:serverId/mind-simulations` integration is Hive-owned in `apps/hive`, not a Mind product handler. It imports a Mind board as Hive agents plus a saved interaction workflow. Consume local Mind, Web fallback, and Hive integration families through their typed `@tuturuuu/internal-api` helpers. Browser requests for the first two stay same-origin so the Mind rewrite boundary remains transparent. Mind-local protected handlers resolve the Mind app-session actor and enforce workspace membership; forwarded Web exceptions require the coordinated Web-issued session and keep their own product permissions. Do not add direct client Supabase reads or client-local raw `fetch('/api/...')` calls for protected Mind data. Workspace routes must normalize aliases such as `personal`, verify workspace membership with the request-scoped auth context, and then perform private-schema reads or writes through the centralized server repository. Mind repositories must not use ad-hoc raw SQL from application code. Keep data operations in private-schema Postgres RPCs and call them through a service-role Supabase admin client with `.schema('private').rpc(...)`. `apps/database/supabase/config.toml` exposes the `private` schema to PostgREST so these RPCs are callable, but table/function grants stay service-role-only. Changing that config requires a local Supabase restart or `bun sb:up` before the Mind APIs stop returning `Invalid schema: private`. The canvas should load from the graph-only snapshot path, while generated draft patch artifacts load from the patch-list path. Do not couple canvas rendering to recent AI patch serialization: a failed patch-artifact refresh should stay inside the assistant panel and must not replace the board canvas with a board load error. The legacy full snapshot can still return graph data plus patches for backward compatibility. Mind graph handles use loose React Flow connections with one visible connection point per side. Cluster and children frames are synthetic canvas nodes used only for interaction: manual links to a frame persist as normal node edges with frame endpoint metadata, so saved graph payloads still satisfy the node-only edge schema while rendering the relationship to the group boundary. Nodes, relationships, clusters, and child-group frames should all be selectable from the canvas. Node and relationship selections open editable properties, while synthetic group or cluster frame selections open a compact read-only properties island that identifies the anchor node and child count. ## Hive Integration A Mind board can be sent to Hive from the compact top-right canvas controls. The Hive-owned import API reads the saved Mind graph, verifies workspace membership through the request-scoped client, requires Hive admin access, and creates Hive NPC agents from the highest-signal Mind nodes. Mind edges become Hive agent interaction pairs, and the generated Hive workflow first stamps the Mind source context into the world before running the agent-interaction node. Keep the mutation in `apps/hive`; the shared Mind canvas should not duplicate Hive server logic. Client code should call `createHiveMindSimulation()` from `@tuturuuu/internal-api/hive`; do not add client-local raw fetch calls or duplicate graph-to-agent conversion logic. ## Data Model Mind product tables live in the `private` schema. User access goes through the Mind-local product APIs, while only the explicit fallback families above go to the central Web API. Direct table access is service-role only. * `private.mind_boards` * `private.mind_nodes` * `private.mind_edges` * `private.mind_tags` * `private.mind_node_tags` * `private.mind_groups` * `private.mind_group_nodes` * `private.mind_node_links` * `private.mind_ai_threads` * `private.mind_ai_messages` * `private.mind_ai_patches` `mind_node_links` is the first integration seam for Tasks, Calendar, documents, projects, and external URLs. Live pickers can attach to this link contract later without changing the core graph schema. Nodes carry a first-class workflow status: `backlog`, `planned`, `in_progress`, `in_review`, `blocked`, `completed`, `deferred`, and `cancelled`. The canvas and AI tools should treat status as a planning signal, not just decoration: blocked nodes need dependencies, in-review nodes need validation criteria, and completed nodes should remain available for historical context and dependency tracing. ## AI Patch Safety Mind AI chats default to review mode. In review mode, tools can inspect mindboards, load graph chunks, search nodes, and store proposed patches, but the user applies the patch explicitly from the Mind UI. Direct-write mode is scoped to the current chat. In direct-write mode, the `apply_mind_patch` tool can write the structured patch transactionally and the repository records the patch status, `applied_at`, and applying user for audit. Structured patches should stay small enough to review. Prefer multiple focused patches over a single broad rewrite when consolidating large graphs. For normal structure-generation requests, a patch should still be complete enough to be useful: include the major clusters, concrete child nodes, and the relationship edges that connect them to the root goal or to each other. Avoid AI drafts that expand only one branch while leaving related top-level systems as isolated nodes. The existing board is authoritative. AI drafts should reuse and extend relevant existing node IDs first, then create missing child nodes and relationships around those anchors. Do not draft a detached replacement root when the current mindboard already contains a matching goal, system, cluster, or milestone. The patch tool normalizes generated aliases and stores operations in apply-safe order: newly-created parent and child nodes are inserted before relationship edges or updates that reference them. Existing draft patches are normalized again just before application so older edge-first drafts do not fail foreign-key checks. For large boards, the assistant should inspect structure first, then search or load neighborhoods/chunks instead of requesting a full graph by default. Keep responses action-oriented: suggest follow-up passes, propose draft patches when they are useful, and only implement graph writes when the chat is explicitly in Implement mode. After a draft patch is applied from the Mind UI, the client closes the assistant panel, reloads the board, runs the smart canvas organizer, saves the resulting positions, and refreshes board queries. The organizer should keep true same-level sequence nodes in a compact horizontal lane, place explicit children under their parent, and anchor supporting or dependency nodes near the higher-level node they affect. Applying a draft and refreshing layout are separate phases: once the patch application RPC returns, patch artifacts should show `Applied` immediately. If the follow-up auto-layout save fails, keep the patch applied and show a retryable layout-refresh warning instead of treating the graph patch as failed. Mind boards auto-save canvas edits. The board title, canvas tools, tag filter, and save status live in one compact top-left island. The title is editable from that island, the tag filter uses an icon-only ghost dropdown, and the save icon shows saved, saving, unsaved, or retryable error state and can be clicked to force a save. In the web-hosted board route, the compact top-right island owns the Hive simulation launcher and the assistant toggle. Autosave signatures, tag indexing, group-frame layout, and relationship routing obstacle scans are intentionally debounced so dragging stays responsive on dense boards; keep direct node movement immediate and move only derived calculations onto short debounce windows. React Flow canvas routes should pan with two-finger trackpad movement while preserving pinch-to-zoom. Do not switch trackpad scrolling back to zoom-only behavior; use explicit canvas controls or pinch gestures for zoom. Generated plans and patch drafts should be treated as artifacts. The newest artifact can open in the proposal island, while every message keeps a compact artifact row for reopening it. When a generated visual plan and a draft patch belong to the same assistant response, render them as one centralized draft proposal pending approval: the structured patch preview is the review context, and the single Apply action belongs to the proposal shell. Do not show the visual plan and draft patch as duplicated stacked content. Tool-call and artifact sections default to collapsed compact rows; while the assistant is working, the row should show a spinner and the latest tool or artifact name without expanding the full debug list. When a draft is applied, the applied patch should render as `Applied` in those artifact views instead of staying visually draft-only. The canvas toolbar can copy the current board as Markdown or JSON. This export uses the local in-canvas graph state, including unsaved position edits, so it is useful for sharing a planning snapshot or debugging AI patch output. ## Deployment Mind has dedicated Vercel workflows: * `.github/workflows/vercel-preview-mind.yaml` * `.github/workflows/vercel-production-mind.yaml` Store `VERCEL_TOKEN`, `VERCEL_ORG_ID`, and `VERCEL_MIND_PROJECT_ID` in the workflow environments `vercel-preview-mind` and `vercel-production-mind`. Deployment should rely on Vercel project environment variables pulled by `vercel pull`; do not add provider AI keys or production Supabase service keys to GitHub Actions. The repository-level `TURBO_TOKEN` and `TURBO_TEAM` variable are passed only to the wrapped `vercel build` step, never at workflow/job scope and never to pull-request or Dependabot code. ## Verification After changing Mind schema, API, or UI code, run the most relevant focused checks first, then the repo-required checks: ```bash theme={null} bunx vitest run packages/internal-api/src/mind.test.ts packages/ai/src/mind/patch.test.ts bun i18n:sort bun type-check:mind bun validate ``` After applying the local Supabase migration, run `bun sb:typegen` and consume database shapes through `@tuturuuu/types/db`. # Mobile Source: https://docs.tuturuuu.com/platform/applications/mobile Native workspace products, defaults, account controls, and offline behavior. The Flutter app (`apps/mobile`) brings eligible Tuturuuu workspace tools into a native shell. Its launcher, module availability, background behavior, and device permissions are separate from the web app's browser runtime. ## Learn by surface | Topic | Guide | | - | - | | Launcher defaults and optional modules | [Workspace tools](/platform/features/mobile-workspace-tools) | | Timer, background behavior, and recovery | [Mobile timer](/platform/features/mobile-timer) | | Private messaging | [Mobile chat](/platform/features/mobile-chat) | | Account/settings navigation | [Settings shell](/platform/features/mobile-settings-shell) | | Inventory stock health | [Stock health](/platform/features/inventory-stock-health) | | Season pricing | [Season pricing](/platform/features/inventory-season-pricing-mobile) | | Voice note review | [Notes voice analysis](/platform/features/notes-voice-analysis) | | Distribution and release evidence | [Mobile deployment](/build/devops/mobile-store-deployment) | Tasks, Calendar, and Finance are default launcher modules. Meet, Mail, Chat, and Notes are opt-in experiments documented in the workspace-tools guide. Turning a module on exposes its eligible launch surfaces; it does not grant workspace or account privileges. Mail keeps its exact-domain eligibility rule. ## Shell and offline expectations Screens inherit the app shell's background and single top title/actions bar. On phones and portrait tablets the floating bottom navbar owns in-app Back navigation and scroll clearance. On landscape tablets, laptops, and desktops (width >= 840dp, shortest side >= 600dp) the same destinations, including Back, move to a leading rail and the dock keeps only composers and page actions. Full-screen/system forms have their own shell rules. These conventions keep controls reachable and avoid duplicate headers. Every screen uses the same page gutters, section spacing, and wide-screen max widths. Only calendar, board, conversation, call, and media/map canvases run full-bleed. See the [mobile design system](/build/development-tools/mobile-design-system). Offline availability is product-specific. Cached data is not proof that an edit reached the server. Review queued/sync states and recover through the owning product's documented flow. Optional products should not warm private endpoints until access is known to be enabled. ## Versions and privacy The [toolchain reference](/reference/repository/versions) reads the Flutter and Dart constraints and mobile package version from `pubspec.yaml`. Distribution artifacts and build metadata establish what a device is running. The browser bootstrap for Flutter is noindex; it is not a duplicate public marketing site. Developers changing translations regenerate localization before analysis/tests. Native app work does not require the paused Rust/TanStack Start runtime or the retired Docker cron runner. Database-dependent test fixtures still need an appropriate isolated environment; see [Without Docker](/build/development-tools/without-docker). ## Private product feedback Settings → Send feedback opens an account-scoped form inside the existing shell; the shell keeps its single title and dock navigation. The active platform Web `/api/v1/product-feedback` route owns submission, not the workspace CRM feedback store. Native calls use the current Supabase Bearer identity and never send an authoritative actor id. English and Vietnamese copy ship together. Ingress retains the shared 512 KiB request limit for every other route/method; only exact `POST /api/v1/product-feedback` gets the 2,850,000-byte envelope needed for base64 image plus bounded text. Both declared and actual streamed bytes are checked at the proxy and again in the owning route. The regression includes an old-limit negative control and adjacent-path/method denials. The default is off: `PRODUCT_FEEDBACK_SUBMISSION_ENABLED=true` enables text intake and requires a real Turnstile configuration even in development. Each explicit dispatch obtains a fresh token. The existing SQL intake owns atomic actor/network/global quota charges and the content-free idempotent receipt; unverified forwarded headers do not select a quota bucket. No automatic offline, Auth-response or challenge-response replay is allowed. HTTP 429 retains `Retry-After`; 409 retains the original reference. One optional PNG/JPEG/WebP screenshot is bounded at 2 MiB of source bytes. The server validates the actual format, rejects animation and more than ten million pixels, strips metadata, fits within 1920×1920, and stores at most 512 KiB of WebP. `PRODUCT_FEEDBACK_MEDIA_ENABLED=true` additionally requires the additive private media migration. The wrapper reuses the existing intake transaction and advisory lock: screenshot and receipt commit together, identical retries do not charge again, and adding, changing or removing media conflicts. Every Web submission, including a screenshot-free replay, uses this wrapper. Omitting a previous screenshot still conflicts when media intake is disabled; missing media schema fails closed. Small normalized screenshots live in the RLS-protected private media table, one per report; originals, filenames, public URLs and general-purpose attachments are not stored. This bounded design does not create a public Storage bucket. The app freezes an attempted draft and retains its original UUID. Only that reference is saved in account-scoped preferences; text, images and Turnstile tokens stay in memory. After restart, recovery is receipt observation only. The owner-only `/receipts/{key}` route remains available with submission disabled, so stopping intake does not prevent recovery. A missing receipt remains unknown and never starts another POST. An explicit in-session retry uses the same immutable draft/key with a fresh token. Initial definitive pre-acceptance 400/401/403/413/429 responses allow editing only if no earlier attempt has an unknown outcome. After a 503/transport uncertainty, a later retry rejection cannot erase the original key or unlock editing. Only a confirmed receipt resolves that uncertainty. There is no automatic polling or write replay. Staff can explicitly open a private screenshot from the Web inbox when both staff and media gates are enabled. The media route rechecks the current Auth identity and the existing SQL activated exact-domain staff assertion on each read. It returns a bounded uncached image projection, with no reporter identity, storage path or bearer URL. Staff status/archive/revision metadata stays read only. Regression coverage is in `product-feedback-{handlers,service}.test.ts`, `product-feedback-private-media.sql`, the internal-api feedback tests and `product_feedback_{page,repository}_test.dart`. The page tests exercise both 503 and transport uncertainty followed by each supported retry rejection. The privacy fixture first verifies synthetic camera/GPS EXIF on the input, then requires the stored WebP to omit metadata. Web replay tests exercise the real dispatcher against modeled RPC contracts; they do not replace SQL qualification. The disposable database runner applies the full current migration history before the 17-assertion media packet and type generation. Run it with `bun run --cwd apps/database sb:validate:isolated --test supabase/tests/product-feedback-private-media.sql --typegen packages/types/src/supabase.ts` through `ttr resources run`; it owns and cleans a separate temporary Supabase project. Before activation, require exact-head Web/mobile CI, hosted Auth and registry checks, real Turnstile acceptance, and device tests for image picking, account changes, pending recovery, keyboard/dock clearance and enlarged text. ## Desktop beta downloads The same Flutter app ships through the [desktop beta channel](/build/devops/desktop-beta-distribution) for Windows x64, macOS, and Linux. The 2026-10-22 policy permits unsigned Windows direct-download installers when both signing secrets are absent. The download page and release notes disclose SmartScreen warnings and checksum verification. Configured signing failures block the Windows package. macOS still requires Developer ID signing and notarization; the Microsoft Store channel is separate. Windows in-app updates retain their publisher-signature checks, so unsigned betas use manual verified-installer updates. Packaging and receipt regressions are covered by `scripts/desktop-deployment/windows-signing.test.mjs` and `verify-publication.test.mjs`; native Windows acceptance remains a release gate. # Native Worker release identity Source: https://docs.tuturuuu.com/platform/applications/native-release-identity Public, read-only build identity for the admitted Calendar, Mail and Apps native Workers. ## Scope and default The admitted native Calendar, Mail and Apps Workers expose `/api/build-info` before session middleware. The endpoint reports public bundled release metadata: app name, full source SHA and environment. It is no-store, accepts GET/HEAD/OPTIONS, returns 405 for other methods, and matches only that exact path. It exposes no session or secret values. Other API routes retain their existing authentication and authorization. Apps evaluates its canonical-host fence before build identity as well. The staging profile returns 503 at `apps.tuturuuu.com`; its held production profile explicitly admits that host. Legacy Vercel deployments retain their existing behavior until explicit cutover. This decision does not enable production publication or routing. ## Evidence and operating procedure `scripts/ci/wave1-native-publishers.test.js` covers endpoint path/method/cache behavior. Original/restored CI workerd acceptance checks the actual bundled SHA, app and environment, along with assets and the Apps fence. A hosted build-info receipt is release identity, not signed-in/provider acceptance. See the [native publisher runbook](/build/devops/wave1-native-publishers) for staging setup, publication holds, rollback evidence and remaining cutover requirements. # Nova - Prompt Engineering Platform Source: https://docs.tuturuuu.com/platform/applications/nova Architecture and implementation of the Nova prompt engineering platform Nova is Tuturuuu's prompt engineering platform designed to help users learn, practice, and compete in AI prompt engineering challenges. ## Overview Nova provides an interactive environment where users can: * Learn prompt engineering through structured problems * Practice against problem test cases (some public, some hidden) * Compete in timed, attempt-limited challenges * Submit prompts for automated, criteria-based evaluation * Track progress through sessions and leaderboards (individual and team) > [!NOTE] > > Nova is a **standalone satellite app** that lives at `apps/nova`, not inside > `apps/web`. It runs on port `7805` locally (`nova.tuturuuu` via Portless) and > delegates authentication to `apps/web` through the shared cross-app login > handoff, the same satellite pattern used by > [mail](/platform/applications/mail), [learn](/platform/applications/learn), > [teach](/platform/applications/teach), [mind](/platform/applications/mind), > [hive](/platform/applications/hive), and [tasks](/platform/applications/tasks). ## Session integrity Creating a Nova participant submission requires the caller's own `IN_PROGRESS` session and an associated problem in that session's challenge. The server rejects submissions at or after `min(start_time + duration, close_at)`, including before the expiry cleanup runs. Only an enabled manager of the problem's own challenge (resolved server-side from the problem) may submit without a session; managing a different challenge, or a disabled role, grants no bypass. A supplied session must satisfy the same ownership, challenge and expiry checks. After creation, a submission's `problem_id` and `session_id` are immutable for every caller. Participants cannot edit, delete or grade their own submissions. Only an enabled manager of the submission's challenge may write or clear its grading (`/api/v1/submissions/{id}/criteria` and `/test-cases`), and only on a submission they own may that manager edit the prompt or delete it. A graded criterion must belong to the submission's challenge, and a graded test case must belong to its problem. The grading tables live in `private` with no `authenticated` grants, so the service-role routes are the only write path. The admin submission detail page applies the same scope: an enabled manager of the submission's challenge, or the owner when the submission is bound to their own session in that challenge. Challenge password verifier fields are never sent to the client. Active-session reads select the newest start. Session inserts serialize on the challenge row and reject an overlapping active session with HTTP 409. Expired rows remain as attempt history and do not prevent a new attempt. Daily attempt limits use UTC in both the API and database. Criteria retain catalog/password eligibility before `open_at`; starting a session still requires the opening window. Regression coverage: `submissions/route.test.ts`, `submissions/[submissionId]/route.test.ts`, `submissions/[submissionId]/grading-access.test.ts`, the admin `submissions/[submissionId]/page.test.tsx`, `packages/utils/src/nova/submissions/check-permission.test.ts`, `challenge-catalog-access.test.ts`, `sessions/route.test.ts`, and `supabase/tests/private-schema-nova-session-limits.sql`. The grant boundary is covered by `private-schema-nova-runtime.sql` and `private-schema-nova-challenge-catalog.sql`. ## Architecture / Satellite Auth Nova is a Next.js App Router app under `apps/nova` that owns the prompt engineering UI and its own `/api/v1/*` route handlers. Authentication is delegated to `apps/web`, and Nova-specific data lives in the shared Supabase project under the `private` schema, accessed with the service-role admin client. ### Cross-app login handoff * `apps/nova/src/proxy.ts` runs a centralized auth proxy created with `createCentralizedAuthProxy({ targetApp: 'nova', sessionMode: 'supabase-first', mfa: { enabled: false } })`. MFA is disabled in the satellite because `apps/web` already enforces `aal2` before issuing a cross-app token. * For browser navigation, the proxy first calls `consumeVerifyTokenRequest`, which handles the `/verify-token` handoff so a local Portless login can set cookies on `nova.tuturuuu.localhost`. It then runs the auth proxy and locale handling. * `POST /api/auth/verify-app-token` is generated by `createPOST('nova', { verificationBaseUrl: TTR_URL })` from `@tuturuuu/auth/cross-app/server`. It exchanges a one-time cross-app token from `apps/web` for Nova's local app-session. * Token refresh stays same-origin through `POST /api/auth/refresh-app-session`; the proxy refreshes the app session for `/api/*` requests via `refreshAppSessionForRequest` and clears Supabase auth cookies on failure. ### App-session helpers `apps/nova/src/lib/app-session.ts` is the single source of truth for resolving the current Nova user and their platform role: * `getNovaAppSessionUserFromRequest(request)` resolves the app-session user from a `Request` inside a route handler (`targetApp: 'nova'`). * `getNovaAppSessionUserFromHeaders()` / `requireNovaAppSessionUser()` resolve the user in Server Components and redirect to `/login` when absent. * `getNovaPlatformRole(userId, sbAdmin?)` reads the caller's row from the shared `platform_user_roles` table (`enabled`, `allow_challenge_management`, `allow_manage_all_challenges`, `allow_role_management`). * `requireNovaEnabledRole(user)` redirects to `/not-whitelisted` when the role is not enabled. > [!WARNING] > > There is **no Nova tRPC router** and no Nova server-action data layer in > `apps/web`. Nova route handlers authenticate the caller, then read and write the > `private.nova_*` tables directly with the service-role admin client. Use > `packages/internal-api` helpers and the Nova `/api/v1/*` routes for client data > access; do not add direct client-side Supabase reads of Nova tables. ## Database Schema All Nova tables live in the `private` schema of the shared Supabase project and are reachable only through the service-role admin client (`createAdminClient({ noCookie: true })`). The shapes below are derived from the generated types in `packages/types/src/supabase.ts` — treat that file as the source of truth and never hand-edit generated DB types. ### Challenges and problems A **challenge** is the top-level unit. **Problems** belong to a challenge (`nova_problems.challenge_id`), and **test cases** belong to a problem (`nova_problem_test_cases.problem_id`). Note the relationship direction: problems reference their parent challenge, not the other way around. #### `nova_challenges` ```sql theme={null} CREATE TABLE private.nova_challenges ( id uuid PRIMARY KEY DEFAULT gen_random_uuid(), title text NOT NULL, description text NOT NULL, duration integer NOT NULL, -- session duration in seconds enabled boolean NOT NULL DEFAULT false, max_attempts integer NOT NULL, max_daily_attempts integer NOT NULL, open_at timestamptz, close_at timestamptz, previewable_at timestamptz, whitelisted_only boolean NOT NULL DEFAULT false, password_hash text, password_salt text, created_at timestamptz NOT NULL DEFAULT now() ); ``` Challenge passwords use the shared scrypt KDF from `@tuturuuu/utils/crypto`; new hashes embed their salt, so `password_salt` is `null` for them. Any other non-empty stored hash, including legacy salted SHA-256, is a reset marker: it never verifies, `verify-password` returns HTTP 409 `PASSWORD_RESET_REQUIRED` without a grant, and a challenge manager must set a new password. Scrypt hashes with older parameters still verify and are rehashed with an update guarded by the previous hash. See [shared-secret password reset](/platform/features/shared-secret-password-reset). After the password verifies, `/api/auth/challenges/verify-password` sets an httpOnly `nova_challenge_access_` cookie holding a signed grant bound to that challenge and the signed-in user, valid for the challenge duration (at most seven days). Challenge pages accept only that grant; the stored hash is never sent to the browser, and the retired `token` cookie is cleared and no longer grants access. Users with an open challenge from before this change re-enter the password once. Each password attempt reserves capacity atomically before verification. Verified success refunds exactly that target reservation. Budgets allow 10 outstanding or failed attempts per challenge and user, plus 60 admitted checks per user across challenges in 15 minutes. The aggregate budget uses the authenticated user id, so an office does not share one IP budget. A spent budget answers 429 with `Retry-After` (see [shared-secret password budgets](/build/devops/adaptive-abuse-rate-limits#shared-secret-password-budgets)). Starting a session (`POST /api/v1/sessions`) applies the same participant catalog rules as the problem APIs and, for a password-protected challenge, requires that grant for the caller; challenge managers are exempt. Because the problem APIs only serve participants with an in-progress session, this is what keeps protected problems behind the password. Sessions and submissions by id are scoped to their owner, and a session can only be ended, not moved to another challenge, restarted or reopened. Coverage: `apps/nova/src/app/api/auth/challenges/verify-password/route.test.ts`, `apps/nova/src/app/api/v1/sessions/route.test.ts`, `apps/nova/src/app/api/v1/sessions/[sessionId]/route.test.ts` and `apps/nova/src/app/api/v1/submissions/[submissionId]/route.test.ts`. #### `nova_problems` ```sql theme={null} CREATE TABLE private.nova_problems ( id uuid PRIMARY KEY DEFAULT gen_random_uuid(), challenge_id uuid NOT NULL REFERENCES private.nova_challenges(id), title text NOT NULL, description text NOT NULL, example_input text NOT NULL, example_output text NOT NULL, max_prompt_length integer NOT NULL, -- caps how long a submitted prompt may be created_at timestamptz NOT NULL DEFAULT now() ); ``` #### `nova_problem_test_cases` ```sql theme={null} CREATE TABLE private.nova_problem_test_cases ( id uuid PRIMARY KEY DEFAULT gen_random_uuid(), problem_id uuid NOT NULL REFERENCES private.nova_problems(id), input text NOT NULL, output text NOT NULL, hidden boolean NOT NULL DEFAULT false, -- hidden test cases are not exposed to participants created_at timestamptz NOT NULL DEFAULT now() ); ``` #### `nova_challenge_criteria` Free-form scoring criteria attached to a challenge. Submissions are graded against these criteria. ```sql theme={null} CREATE TABLE private.nova_challenge_criteria ( id uuid PRIMARY KEY DEFAULT gen_random_uuid(), challenge_id uuid NOT NULL REFERENCES private.nova_challenges(id), name text NOT NULL, description text NOT NULL, created_at timestamptz NOT NULL DEFAULT now() ); ``` ### Sessions and submissions #### `nova_sessions` A timed attempt at a challenge. ```sql theme={null} CREATE TABLE private.nova_sessions ( id uuid PRIMARY KEY DEFAULT gen_random_uuid(), challenge_id uuid NOT NULL REFERENCES private.nova_challenges(id), user_id uuid NOT NULL, status text NOT NULL, start_time timestamptz NOT NULL, end_time timestamptz, created_at timestamptz NOT NULL DEFAULT now() ); ``` #### `nova_submissions` A submitted prompt for a problem. The aggregate score is **not** stored on this row; per-criterion and per-test-case results live in child tables (see below) and are aggregated by the `nova_submissions_with_scores` view. ```sql theme={null} CREATE TABLE private.nova_submissions ( id uuid PRIMARY KEY DEFAULT gen_random_uuid(), problem_id uuid NOT NULL REFERENCES private.nova_problems(id), session_id uuid REFERENCES private.nova_sessions(id), user_id uuid NOT NULL, prompt text NOT NULL, overall_assessment text, created_at timestamptz NOT NULL DEFAULT now() ); ``` #### `nova_submission_criteria` Per-criterion grading results for a submission. ```sql theme={null} CREATE TABLE private.nova_submission_criteria ( submission_id uuid NOT NULL REFERENCES private.nova_submissions(id), criteria_id uuid NOT NULL REFERENCES private.nova_challenge_criteria(id), score numeric NOT NULL, feedback text NOT NULL, strengths text[], improvements text[], created_at timestamptz NOT NULL DEFAULT now() ); ``` #### `nova_submission_test_cases` Per-test-case results for a submission, including whether the model output matched and the grader's confidence/reasoning. ```sql theme={null} CREATE TABLE private.nova_submission_test_cases ( submission_id uuid NOT NULL REFERENCES private.nova_submissions(id), test_case_id uuid NOT NULL REFERENCES private.nova_problem_test_cases(id), output text NOT NULL, matched boolean NOT NULL DEFAULT false, confidence numeric, reasoning text, created_at timestamptz NOT NULL DEFAULT now() ); ``` ### Teams Nova supports team-based participation through three tables (not a single "team management" table): ```sql theme={null} CREATE TABLE private.nova_teams ( id uuid PRIMARY KEY DEFAULT gen_random_uuid(), name text NOT NULL, description text, goals text, created_at timestamptz NOT NULL DEFAULT now() ); CREATE TABLE private.nova_team_members ( team_id uuid NOT NULL REFERENCES private.nova_teams(id), user_id uuid NOT NULL, created_at timestamptz NOT NULL DEFAULT now() ); -- Invite-by-email roster for a team CREATE TABLE private.nova_team_emails ( team_id uuid NOT NULL REFERENCES private.nova_teams(id), email text NOT NULL, created_at timestamptz NOT NULL DEFAULT now() ); ``` ### Access control tables Per-challenge whitelisting and manager assignment are keyed by email: ```sql theme={null} -- Emails allowed to participate when a challenge is whitelisted_only CREATE TABLE private.nova_challenge_whitelisted_emails ( challenge_id uuid NOT NULL REFERENCES private.nova_challenges(id), email text NOT NULL, created_at timestamptz NOT NULL DEFAULT now() ); -- Emails granted management rights over a specific challenge CREATE TABLE private.nova_challenge_manager_emails ( challenge_id uuid NOT NULL REFERENCES private.nova_challenges(id), email text NOT NULL, created_at timestamptz NOT NULL DEFAULT now() ); ``` Platform-wide Nova permissions are **not** stored in a dedicated `nova_*` roles table. They come from the shared `public.platform_user_roles` table (`enabled`, `allow_challenge_management`, `allow_manage_all_challenges`, `allow_role_management`), exposed to Nova through `getNovaPlatformRole()`. The `is_nova_role_manager()` RPC reflects the `allow_role_management` flag. ## Data Access Patterns Nova route handlers follow a consistent shape: resolve the app-session user, authorize against the caller's platform role and (for management writes) the challenge they are touching, then read or write the `private` schema with the admin client. ### Listing problems for a challenge ```typescript theme={null} // apps/nova/src/app/api/v1/problems/route.ts (simplified) import { createAdminClient } from '@tuturuuu/supabase/next/server'; import { NextResponse } from 'next/server'; import { getNovaAppSessionUserFromRequest } from '@/lib/app-session'; export async function GET(request: Request) { const { searchParams } = new URL(request.url); const challengeId = searchParams.get('challengeId'); // App-session resolution is synchronous; do NOT await it. const user = getNovaAppSessionUserFromRequest(request); if (!user?.id) { return NextResponse.json({ message: 'Unauthorized' }, { status: 401 }); } // createAdminClient is synchronous, but { noCookie: true } returns a promise // in this entrypoint, so await it here. const sbAdmin = await createAdminClient({ noCookie: true }); let query = sbAdmin .schema('private') .from('nova_problems') .select('*') .order('created_at', { ascending: false }); if (challengeId) { query = query.eq('challenge_id', challengeId); } const { data: problems, error } = await query; if (error) { return NextResponse.json( { message: 'Error fetching problems' }, { status: 500 } ); } return NextResponse.json(problems, { status: 200 }); } ``` ### Creating a problem (authorized write) A problem belongs to a challenge, so the caller must be allowed to manage that specific challenge before the service-role insert runs. ```typescript theme={null} // apps/nova/src/app/api/v1/problems/route.ts (simplified) import { createAdminClient } from '@tuturuuu/supabase/next/server'; import { NextResponse } from 'next/server'; import { getNovaAppSessionUserFromRequest } from '@/lib/app-session'; import { canManageNovaChallenge } from '@/lib/challenge-management-auth'; import { createProblemSchema } from '../schemas'; export async function POST(request: Request) { const user = getNovaAppSessionUserFromRequest(request); if (!user?.id) { return NextResponse.json({ message: 'Unauthorized' }, { status: 401 }); } const validatedData = createProblemSchema.parse(await request.json()); const sbAdmin = await createAdminClient({ noCookie: true }); // Authorize against the target challenge before the privileged write. if (!(await canManageNovaChallenge(user, validatedData.challengeId, sbAdmin))) { return NextResponse.json({ message: 'Forbidden' }, { status: 403 }); } const { data: problem, error } = await sbAdmin .schema('private') .from('nova_problems') .insert({ title: validatedData.title, description: validatedData.description, max_prompt_length: validatedData.maxPromptLength, example_input: validatedData.exampleInput, example_output: validatedData.exampleOutput, challenge_id: validatedData.challengeId, }) .select() .single(); if (error) { return NextResponse.json( { message: 'Error creating problem' }, { status: 500 } ); } return NextResponse.json(problem, { status: 201 }); } ``` > [!NOTE] > > Supabase client constructors from `@tuturuuu/supabase/next/server` differ: > `createClient()` and `createDynamicClient()` are async (`await` them), while > `createAdminClient()` is the sync admin client. Nova's `{ noCookie: true }` > admin entrypoint is awaited as shown above. ## Authorization Helpers `apps/nova/src/lib/challenge-management-auth.ts` centralizes management checks so service-role writes are never gated by app-session presence alone: * `canManageNovaChallenge(user, challengeId, sbAdmin?)` — true when the caller can manage all challenges, or has `allow_challenge_management` and is listed in `nova_challenge_manager_emails` for that challenge. * `canManageNovaChallengesGlobally(user, sbAdmin?)` — true when the caller can manage all challenges (`allow_manage_all_challenges` or `allow_role_management`). * `canManageNovaRolesGlobally(user, sbAdmin?)` — true when the caller has `allow_role_management`. * Synchronous predicates `canManageNovaChallenges`, `canManageAllNovaChallenges`, and `canManageNovaRoles` evaluate an already-fetched `NovaPlatformRole`. * Resolver helpers `getNovaProblemChallengeId`, `getNovaTestCaseChallengeId`, and `getNovaCriterionChallengeId` walk child rows back to their owning challenge so a single `canManageNovaChallenge` check can guard nested mutations. ## Best Practices ### ✅ DO 1. **Authorize service-role writes explicitly.** `getNovaAppSessionUserFromRequest()` only proves a valid Nova app-session. Any route that mutates Nova management data through `createAdminClient({ noCookie: true })` must also check the relevant `platform_user_roles` permission before the write, using the shared helpers in `apps/nova/src/lib/challenge-management-auth.ts` (`canManageNovaChallenge()`, `canManageNovaChallengesGlobally()`, `canManageNovaRolesGlobally()`). For nested resources (problems, test cases, criteria), resolve the owning `challenge_id` first via the resolver helpers and then authorize against that challenge. 2. **Keep hidden test cases hidden.** Never return `nova_problem_test_cases` rows where `hidden = true` to participants. Filter on the server with `.eq('hidden', false)` for participant-facing reads. 3. **Validate challenge timing and attempt limits.** Respect `open_at`, `close_at`, `previewable_at`, `max_attempts`, and `max_daily_attempts` before accepting a submission or starting a session. 4. **Honor whitelisting.** When `whitelisted_only` is set, only admit emails present in `nova_challenge_whitelisted_emails`. 5. **Read scores from the aggregate view.** Use `nova_submissions_with_scores` instead of recomputing from `nova_submission_criteria` / `nova_submission_test_cases` in application code. ### ❌ DON'T 1. **Don't add a Nova tRPC router or `@/lib/nova` server-action layer.** Nova has neither; product data flows through the Nova `/api/v1/*` routes and `packages/internal-api` helpers. 2. **Don't read Nova tables directly from the client.** All `private.nova_*` access goes through service-role route handlers after authorization. 3. **Don't invent score columns on `nova_submissions`.** Scores are derived from the per-criterion and per-test-case child tables. ## Related Documentation * [TanStack + Rust migration](/platform/architecture/tanstack-rust-migration) - the broader move away from `apps/web` * [Mail satellite app](/platform/applications/mail) - the canonical satellite auth pattern * [Authentication](/platform/architecture/authentication) - cross-app login and sessions * [Database overview](/reference/database/schema-overview) - shared schema conventions ## Future Enhancements * **Richer team challenges** - deeper collaborative prompt engineering flows * **Live leaderboards** - real-time ranking surfaced from the leaderboard views * **Prompt history** - version control for participant submissions * **Advanced metrics** - token usage and latency analysis per submission * **Custom evaluation** - configurable, criterion-weighted scoring functions # Product directory Source: https://docs.tuturuuu.com/platform/applications/overview Every Tuturuuu product family, its purpose, access boundary, and guide. Use the [Apps gateway](https://apps.tuturuuu.com) to find routable products. Workspace apps keep their own permissions and session requirements when you follow a link. The directory below groups products by purpose; it does not imply that every module is enabled in every workspace. ## Productivity and collaboration | Product | What you can learn | Guide | | - | - | - | | Platform and Command Center | Workspace home, priorities, settings, and shared account tools | [Dashboard](/platform/features/command-center-dashboard), [Getting started](/platform/guides/getting-started) | | Tasks | Boards, task organization, cycles, progress, and goals | [Tasks](/platform/applications/tasks), [Goals](/platform/features/progress-goals-leaderboards) | | Calendar | Events, provider connections, native recurrence, and scheduling | [Calendar](/platform/applications/calendar), [Smart scheduling](/platform/features/smart-scheduling/overview) | | Track | Running timer, session history, requests, and management | [Track](/platform/applications/track) | | Meet | Plans, rooms, calls, transcription, and reviewed follow-ups | [Meet](/platform/applications/meet) | | Chat | Private direct messages, groups, channels, and attachments | [Chat](/platform/applications/chat) | | Mail | Eligible team mailboxes and message organization | [Mail](/platform/applications/mail) | | Drive | Workspace files, folders, previews, and storage | [Drive](/platform/applications/drive) | | Mind | Mindboards, nested ideas, and knowledge planning | [Mind](/platform/applications/mind) | | Notes and documents | Workspace writing and explicit voice-analysis review | [Daily workflows](/platform/guides/workflows), [Notes voice analysis](/platform/features/notes-voice-analysis) | | Mobile | Native workspace tools with optional modules and offline behavior | [Mobile](/platform/applications/mobile) | ## Business operations and publishing | Product | What you can learn | Guide | | - | - | - | | Contacts | Workspace user CRM, groups, reports, attendance, and outreach | [Contacts](/platform/applications/contacts) | | Finance | Wallets, transactions, budgets, invoices, debts, and recurring records | [Finance](/platform/applications/finance) | | Inventory | Stock, catalog, bundles, sales, checkout, and provider audit trails | [Inventory](/platform/applications/inventory), [Square POS](/platform/applications/inventory-square-pos) | | Storefront | Published shops, product pages, carts, checkout, and orders | [Storefront](/platform/applications/storefront) | | Pay | Workspace billing, subscription management, and return flows | [Pay](/platform/applications/pay) | | Forms | Form studio, shared forms, embeddings, responses, and analytics | [Forms](/platform/applications/forms) | | CMS | Editorial collections, media, pages, and external-project publishing | [CMS](/platform/applications/cms), [External project studio](/platform/features/external-project-studio) | | Shiraoki | Separately owned Shopify storefront integrated with CMS/auth | [Shiraoki](/platform/applications/shiraoki) | | Reports and tutoring | Contacts-backed reporting, education groups, and tutoring operations | [Reports](/platform/applications/reports), [Tutoring](/platform/applications/tutoring) | ## Learning, creation, research, and AI | Product | What you can learn | Guide | | - | - | - | | Learn | Learner and parent courses, practice, marks, and reports | [Learn](/platform/applications/learn) | | Teach | Teacher-facing education planning and workspace tools | [Teach](/platform/applications/teach) | | Nova | Prompt-engineering learning resources and controlled challenges | [Nova](/platform/applications/nova) | | AI Studio | Provider/model policy, prompts, datasets, runs, and usage | [AI Studio](/platform/ai/ai-studio) | | Mira | Workspace assistant surfaces and governed memory/tools | [Assistant Live](/platform/features/assistant-live), [Memory service](/platform/ai/memory-service) | | Rewise | Private AI conversations and tool surfaces with access gates | [Rewise](/platform/applications/rewise) | | Tulletin | Private creative notebooks and explicitly published worlds | [Tulletin](/platform/features/lettin) | | Colab | Collaborative programming environments | [Colab](/platform/features/colab) | | Hive | Voxel research, social simulation, and AI NPC experiments | [Hive](/platform/applications/hive) | | Parley | Controlled multiplayer scenario training and reflection | [Parley](/platform/applications/parley) | ## Developer tools and administration | Product | Purpose | Guide | | - | - | - | | Apps | Canonical app launcher and redirects | [Apps](/platform/applications/apps) | | Tools | QR generation and random utilities | [Tools](/platform/applications/tools), [QR](/platform/applications/qr) | | Git | Public repository browser and private integration management | [Git](/platform/applications/git) | | Shortener | Redirect execution; workspace link management lives in Web | [Shortener](/platform/applications/shortener) | | Infrastructure | Privileged operations, configuration, and diagnostics | [Infrastructure](/platform/applications/infrastructure) | | Docs | Product learning, engineering guides, and operational references | [Start here](/overview/start-here) | | SDK and CLI | Programmatic APIs, workspace tasks, and developer workflows | [SDK](/reference/packages/sdk), [Build tools](/build/development-tools/overview) | Service-only workspaces—realtime Workers, cron control, Devbox control, storage processing, Redis, database, and memory—are documented in the [complete repository catalog](/reference/repository/catalog) and their runbooks. Internal playground and external SDK examples are development references. Rust and TanStack Start are inactive migration targets, not active products. ## Discoverability and privacy Search indexes explicit public product and learning pages. Workspace content, authentication, invitations, private shared resources, and buyer transactions are excluded by the [indexing policy](/platform/features/search-indexing). Public form indexing uses the author's existing form controls. Publishing a world or storefront is distinct from making a workspace publicly accessible. # Parley Source: https://docs.tuturuuu.com/platform/applications/parley Controlled scenario training, sessions, and research access. Parley (`parley.tuturuuu.com`, `apps/parley`) is a controlled multiplayer scenario-training and reflective-research surface. It is not a generally public catalog of workspace or session data. ## Studio destinations | Destination | Route | | - | - | | Studio | `/` | | Sessions | `/sessions` | | New session | `/sessions/new` | | Session details | `/sessions/{meetingId}` | | Scenario | `/scenarios/{scenarioId}` | | Scenario management | `/manage/scenarios` | | Room entry | `/r/{code}` | Central login, app-session handling, and Parley's access gate govern entry. Access-denied and login views are separate from a missing scenario/session. A room code is a session entry point, not permission to administer scenarios or read unrelated participant records. ## Research and operational boundaries Availability is controlled by the actual deployment and access policy. Do not promise unrestricted simulation, validated training outcomes, or production readiness from retained source routes. Realtime/session behavior depends on its owning services and shared meeting boundaries. All Parley application routes, rooms, and session records are noindex. Explain research purpose in public documentation without exposing scenario/session content or participant data. Use the [Parley source reference](/reference/repository/routes/parley) for current entry points and the [active runtime map](/build/devops/active-runtime) for the distinction between deployed services and retained tooling. # Pay Source: https://docs.tuturuuu.com/platform/applications/pay Workspace subscription billing, invoice views, seats, and billing return flows. Pay (`pay.tuturuuu.com`, `apps/pay`) is the private workspace billing surface. It is distinct from Finance's financial records and Inventory/Storefront's customer purchases. ## Open billing The app entry redirects to `/dashboard`, which shows pending invitations first. Without pending invitations, it lists only the signed-in user's workspaces with the `manage_subscription` permission used by the billing page. One eligible workspace opens billing directly; several show a workspace picker. With none, Pay explains how to request billing access and links to Tuturuuu to create or join a workspace. Workspace lookup failures use the page error boundary rather than appearing as an empty membership list. The workspace destination is `/{wsId}/billing`; the provider return flow uses `/{wsId}/billing/success`. Central sign-in and the Pay app session establish the actor before billing access is checked. This applies to Pay's root/dashboard entry for both personal and team workspaces. Direct billing URLs still enforce workspace membership and billing permission; the picker grants no access. Regression coverage lives in `apps/pay/src/app/[locale]/dashboard/page.test.tsx` (one/many/none, excluded workspaces, invitation precedence, authentication, and lookup failures). Billing surfaces can include subscriptions, seats, invoices, and provider payment methods according to the configured provider and workspace permissions. Use [Commercial controls](/platform/features/commercial-controls) and [Account benefits](/platform/features/account-benefits) for entitlement and commercial rules. An app directory link does not grant billing administration. ## Read payment evidence correctly A browser return or success URL is part of navigation. Provider state, subscription records, authorized webhook processing, and the application's billing reconciliation determine the actual result. Avoid repeating a checkout simply because a return view is still loading; inspect the current provider and workspace state first. Billing pages, provider returns, invoices, and payment methods are noindex and excluded from public sitemaps. Public pricing/product information belongs on Web. See [Search indexing](/platform/features/search-indexing). [Pay routes](/reference/repository/routes/pay), [Finance](/platform/applications/finance), and [Storefront](/platform/applications/storefront) explain the separate ownership boundaries. # QR Source: https://docs.tuturuuu.com/platform/applications/qr Public QR generator app hosted at qr.tuturuuu.com. ## Overview `apps/qr` serves the public Tuturuuu QR generator at `https://qr.tuturuuu.com`. It owns the QR generator UI and reuses the shared `@tuturuuu/ui/custom/qr/qr` component. The app is public and does not own workspace auth, app-session cookies, or protected APIs. Existing `apps/web` QR generator routes are compatibility redirects to the QR app root. The root layout uses `@tuturuuu/satellite/providers` so the public QR surface still supports `system`, `light`, and `dark` theme switching through the shared `next-themes` shell. ## Routing Contract * `/`: canonical QR generator. * `/en` and `/vi`: canonicalize back to `/` while storing `NEXT_LOCALE`. * `apps/web /qr-generator`: redirects to `qr.tuturuuu.com/`. * `apps/web /{wsId}/qr-generator`: redirects to `qr.tuturuuu.com/` without forwarding the workspace ID. Query strings are preserved during compatibility redirects. ## Local Development * `bun dev:qr` starts the app through Portless. * Local app origin: `https://qr.tuturuuu.localhost`. * Direct fallback port: `7819`. * App URL overrides: `QR_APP_URL` or `NEXT_PUBLIC_QR_APP_URL`. ## CI/CD Preview and production deployments use dedicated Vercel workflows: * `.github/workflows/vercel-preview-qr.yaml` * `.github/workflows/vercel-production-qr.yaml` Both workflows are registered in `tuturuuu.ts` and use the shared `ci-check.yml` switchboard with affected-path gating. They require environment-scoped Vercel credentials: * preview environment: `vercel-preview-qr` * production environment: `vercel-production-qr` * project secret: `VERCEL_QR_PROJECT_ID` * shared secrets: `VERCEL_TOKEN` and `VERCEL_ORG_ID` The app-specific project secret should live in those GitHub Environments, not in workflow-level `env`. ## Validation Use these focused checks when changing QR app routing or deployment wiring: ```bash theme={null} bun type-check:qr bun --cwd apps/web vitest run src/lib/qr-app-url.test.ts 'src/app/[locale]/(dashboard)/[wsId]/qr-generator/page.test.ts' 'src/app/[locale]/(marketing)/qr-generator/page.test.ts' bun --cwd packages/utils test src/__tests__/app-url.test.ts node --test scripts/portless-config.test.js node --test scripts/ci/check-workflow-config.test.js scripts/ci/release-workflows.test.js ``` Because QR touches TypeScript, workflow config, docs navigation, and translations, finish QR changes with `bun validate` when the shared worktree state allows it. # Daily and Periodic Reports Source: https://docs.tuturuuu.com/platform/applications/reports Configure, approve, deliver, and troubleshoot daily, weekly, monthly, quarterly, and yearly workspace reports. The Contacts Reports hub at `/{wsId}/reports` is the canonical workspace surface for operational reporting. It keeps two established data models separate while giving managers one worklist with a shared cadence selector: * **Daily reports** are existing user-group posts. Their permissions and email behavior remain unchanged. * **Periodic reports** extend the existing monthly-report records to weekly, monthly, quarterly, and yearly cadences. Monthly is the default. * **Automations** configure workspace schedules, optional group overrides, generation runs, sender readiness, and delivery history. Legacy `/posts` and `/users/reports` links redirect into the corresponding hub cadence and preserve their filters. The canonical hub opens **Daily** by default when the actor can view daily reports; explicit Periodic and Automations links still open their requested cadence or Automations view. ## Central dashboard The Reports worklist offers Daily, Weekly, Monthly, Quarterly, Yearly and All periodic. Automations stays a separate view. All periodic spans the four periodic cadences; Daily uses recipient rows and is intentionally excluded from this total. Daily defaults and existing `view=daily`, `view=periodic`, `view=automations` and `report*` filter URLs remain compatible. Daily and periodic date/status filters retain separate URL state so switching cadence does not reinterpret an old filter. Every displayed count is a server total over the same active result predicate, including stage, statuses, search, dates, category and access scope. Daily counts recipient rows; periodic counts report records, including category counts. Changing a filter resets actionable selection and hides previous-scope totals while the new request is pending. Loading and failed reads show unknown counts rather than zero. Selection totals describe the current loaded selection and retain the 100-report limit; they are not filter totals. Recipient suppression and infrastructure blockers are distinct categories. Suppression includes recorded blocking/suppression evidence and does not imply a confirmed unsubscribe. Missing profile email, changed approval, unknown provider outcome and other recorded failures have separate categories. Selecting a category filters the complete server result before pagination. Existing approval, recipient, authorization and delivery confirmation checks still apply; this dashboard adds no bulk unsuppression or automatic sending/retry action. The current periodic reader walks ordered server chunks to classify recorded errors consistently without changing database schema. It refuses scopes over 20,000 reports with an instruction to narrow dates or search, and rejects missing or incomplete count receipts. Reads scale with the scoped dataset. Daily stage counts use the existing rows RPC across complete scoped chunks. Neither reader presents a partial page as a dashboard total. Regression coverage includes `report-list-query.test.ts`, `search-pagination.test.ts`, `report-filters.test.ts`, `reports-list.test.ts`, Daily `lib/posts/data.test.ts`, `periodic-reports-panel-counts.test.tsx` and `reports-hub.test.tsx` for scope changes, pagination, category intersections, route compatibility and retained action guards. Component fixture screenshots exercise synthetic data; they do not qualify database or customer delivery. ```mermaid theme={null} flowchart LR history["Scoped workspace history"] --> draft["Editable report draft"] manual["Manager-authored content"] --> draft ai["AI-authored narrative"] --> draft draft --> review["Explicit manager review"] review -->|Approved| gates["Email safety gates"] review -->|Rejected| draft gates --> queue["Idempotent email queue"] queue --> audit["Delivery attempt and sent-email audit"] ``` ## Calendar periods In a class report workspace, changing the workspace, class, student, or selected report loads that selection before showing an editable report or choosing a fallback. A previous student's saved report or empty report list must not be used for the next student. Student search and background refresh for the same selection retain the editor while loading. Failed requests show an error and leave the selection intact; they do not establish that a report was deleted. This preserves unsaved fields when a refresh returns unchanged saved content. If the server returns changed title, content, or feedback, the existing editor reset still applies; resolving concurrent edits is outside this selection rule. Periods are calculated in the workspace timezone: | Cadence | Boundary | Scheduled draft behavior | | - | - | - | | Weekly | Monday through Sunday | AI draft after Sunday closes | | Monthly | Calendar month | Default cadence | | Quarterly | Q1 through Q4 | Draft after the quarter closes | | Yearly | Calendar year | Draft after December 31 closes | Manual schedules create an editable draft at the start of the period. AI schedules generate after the period closes. The default delivery target is 09:00 on the first day after close. Automation remains disabled until a valid IANA timezone and an enabled schedule are saved. ## Generation and approval Managers can create a periodic report at any time. An AI generation request is scoped to the report subject and group, including configured metrics, relevant history, profile notes, a previous report, and an editable manager instruction. Unrelated workspace users and groups must never enter the prompt. Deterministic scores and structured metrics are stored independently from the generated narrative. Every AI-generated report starts in a reviewable state and must be explicitly approved before delivery can be queued. Regeneration never bypasses that approval boundary. In the Contacts monthly report editor, approval is available only while reviewing saved current content. Unsaved title, narrative, or feedback changes, a pending save, and a selected historical revision block approval with compact save or return-to-current guidance. Failed saves retain human edits, including multiline feedback and intentionally cleared fields. A matching authoritative refresh is required before approving the edited report; an unrelated or stale refresh does not acknowledge the draft. This is a frontend review safeguard, not an atomic cross-client revision lock, and it does not queue or send email. Regression coverage: `monthly-report-review-safety.test.tsx` exercises the actual editor, form, save/approval hooks, and synthetic HTTP responses. Ordinary manual report creation and edits through the shared report API remain pending even when the legacy approval setting is disabled or the author can approve reports. Contacts Save and score recalculation do not submit approval markers; an explicit permitted approval action remains separate. Narrative, feedback, title, score, cadence, period, manager instruction and generation changes invalidate the API review state. Subject and group cannot be changed through this update API. Approval timestamps and actor attribution are server-owned. This API/client safeguard alone does not establish dispatch authorization: legacy database approval triggers and configuration transitions can still produce approved statuses without per-entry review. Existing status, approver and time fields do not distinguish those paths from explicit human approval. Keep email gates off until canonical revision-bound approval receipts, database mutation closure and delivery consumers enforce explicit permitted review for each entry. Do not infer consent for a backlog from its approved count. Coverage: `explicit-approval.test.ts`, `report-review-transition.test.ts` and `report-save-explicit-approval.test.tsx`; these source tests do not prove the remaining database or provider boundaries. The principal permissions are: * `view_user_groups_reports` — view daily and periodic reporting. * `manage_user_report_automation` — configure schedules and initiate generation. * `send_user_group_report_emails` — preview and control periodic email delivery. Existing group-post permissions continue to govern Daily reports. The periodic hub's Approve action uses the same dedicated approval operation as report details and Daily review. `approve_reports` permits review without `update_user_groups_reports`; approving never grants content-edit authority. Approval-only supervisor and workspace/actor isolation regressions cover this boundary in `periodic-reports-approval.test.tsx` and the shared approval handler `put.test.ts`. ## Email safety Periodic report email requires all of the following: 1. The report is approved. 2. The report subject has a workspace-profile email. 3. Workspace secret `ENABLE_EMAIL_SENDING=true`. 4. Workspace secret `ENABLE_REPORT_EMAIL_SENDING=true`. 5. A valid workspace sender is configured. 6. The actor has `send_user_group_report_emails`. The dedicated report gate defaults to disabled and does not change Daily report delivery. It is discoverable by platform admins in **Settings → Secrets**, where the readiness card shows both gates and sender state and offers a prefilled action for the periodic gate. Contacts Automations also offers an explicit, confirmed periodic-report gate control to actors with **both** `manage_workspace_secrets` and `send_user_group_report_emails` in that workspace. Its satellite-aware endpoint accepts only the allowlisted report flag and literal boolean strings; it never reads credentials, changes the global email gate, or grants access to platform Secrets. The default remains disabled. Enabling allows explicitly queued reports to pass this one safeguard, rather than queueing all approved or skipped reports. Route admission and confirmation/cancellation regressions cover the control. Actual parent-address mapping and provider/inbox delivery require runtime proof. Contacts shows each missing global gate, periodic gate, and sender separately, with an administrator action. Platform Secrets remains root-permission gated; Contacts does not grant access to it or invent a sender setup route. Approved counts are report stages, not delivery queue claims or evidence of parent receipt. The legacy skipped stage remains excluded from automatic approval-triggered sending; enabling gates does not resend historical reports. Delivery goes exclusively to the subject workspace-profile email. The system does not infer an alternate address. Preview never queues an email. Test send, send, retry, and cancel are explicit actions, and each transition remains auditable. ## Inert explicit-review provenance foundation Report, daily-post and per-subject daily-check rows have server-controlled review versions. Review content, creator attribution, generation inputs and approval provenance changes advance the version; delivery bookkeeping does not. Caller-supplied versions are ignored, and integer overflow rejects the mutation. Daily approval must eventually bind both the parent post and its individual recipient check. Private immutable receipt snapshots use canonical lowercase SHA-256 payload and recipient digests. They store identifiers and digests, not raw report content or recipient addresses. Snapshot identifiers intentionally have no live parent foreign keys: authorized parent or workspace teardown preserves audit history without being blocked by receipt immutability. Customers have no receipt access; trusted service audit reads do not restore access or establish current permission. Product-managed retention, export and deletion policy remains unfinished. This foundation has no receipt-minting API, legacy approval backfill or delivery caller activation. Its delivery-readiness function always returns false. The narrow future admission predicate follows current application creator, MEMBER-role/default and GUEST-default permissions, and requires an exact live workspace actor link. Deleted or revoked actors cannot gain admission from retained history. Existing legacy approval/configuration/dispatch paths still need complete closure before email gates can be enabled. CI verifies the full historical schema, strict SQL/TAP controls, two-connection version/lock behavior and actual generated types through `report-review-receipts-contract.yaml`; source review or static tests alone do not prove those database controls or customer delivery. ## Automation processor Vercel calls `/api/cron/process-report-automation` every 15 minutes. Private Postgres RPCs claim due work idempotently. The processor uses: * bounded concurrency; * unique period/schedule claims; * retry backoff and next-attempt timestamps; * stale-lock recovery; * permanent-failure diagnostics; * separate generation-run and email-attempt histories. The Next.js API remains the production source of truth. New reporting paths are registered in the TanStack migration manifest until the Rust backend is ready for an explicit cutover. ## Operating checklist Before enabling a workspace: 1. Set a valid workspace timezone. 2. Confirm the intended managers have automation and delivery permissions. 3. Configure and verify the workspace email sender. 4. Enable the general email gate. 5. Create a manual schedule first and inspect its draft. 6. Enable the periodic-report gate. 7. Preview and test-send one approved report. 8. Confirm the recipient, sent-email record, and delivery-attempt history. 9. Enable AI generation only after the manual path is understood. > [!WARNING] > > Never enable either gate merely to make a readiness badge green. Confirm the > workspace recipient data and sender first. AI-generated content must still be > reviewed for accuracy and appropriateness. ## Troubleshooting ### A report cannot send Open the Automations tab and inspect delivery readiness. Common blockers are a pending approval, missing subject email, disabled gate, missing sender, or insufficient permission. The report retains the last delivery error. ### A scheduled report did not appear Verify the schedule is enabled, the timezone is valid, and the expected period has closed for AI mode. Check recent generation runs for a failed or recovered claim. Manual schedules create drafts at period start rather than after close. ### Delivery is queued for too long Inspect the email queue attempt history and processor logs. A stale processing claim is recoverable; repeated permanent failures preserve their error instead of silently retrying forever. Confirm global email infrastructure, blacklist, unsubscribe, rate-limit, and sender diagnostics. ### Recipient is unexpected Cancel the queued delivery immediately. Periodic delivery must use only the subject's workspace-profile email. Correct that profile, then preview again before retrying. ### Daily and periodic totals differ Daily reports count group-post completion and delivery. Periodic reports count subject reports by cadence and approval/delivery state. They intentionally use different underlying models and should not be summed as the same metric. Periodic summary cards use a private aggregate RPC rather than materializing report rows in the application. This keeps totals exact beyond PostgREST's default row limit. The report list remains independently paginated and can load every matching record without using the summary result as a page. ## Verification Schema changes must be prepared as additive migrations and validated locally; do not push production migrations from an agent session. Minimum release validation includes: * pgTAP coverage for the compatibility defaults, private tables, RLS, claims, and permissions; * timezone boundary tests for every cadence; * route/service tests for permission and email-gate combinations; * component tests for hub tabs, mobile dialogs, filters, and error states; * E2E coverage for manual and AI approval flows, blocked delivery, retry, audit history, and legacy redirects; * Contacts and Web builds plus `bun validate`. ## Automatic delivery after approval In **Reports → Automations**, enable **Send automatically after approval**. Changing this setting requires both `manage_user_report_automation` and `send_user_group_report_emails`. The setting applies to future approval transitions, including approvals from the report editor and bulk approval flows. It does not backfill previously approved reports or automatically resend delivered reports. The `20260911100000_periodic_report_approval_delivery.sql` migration atomically queues the report with its approval. Production migration CI applies it automatically after integration into production. Enable the setting after that workflow succeeds. `AUTO_SEND_APPROVED_REPORTS` is a workspace config, defaulting to off. The worker still checks both email gates, the workspace sender, approval, the current workspace user email, and the unsubscribe/block list before sending. Revoking approval cancels waiting or retrying deliveries. An email already being processed or accepted by the provider cannot be recalled. Open a periodic report's details to see its recipient, delivery status, attempt count, next retry, and latest 20 attempts. The list refreshes every 15 seconds; open delivery details refresh every 10 seconds. **Sent** means provider acceptance, not confirmed inbox delivery or a read receipt. Test sends are labelled separately. Missing email addresses and permanent failures require correction before retrying. Worker logs use `periodic_report.delivery_sent`, `periodic_report.delivery_failed`, `periodic_report.attempt_write_failed`, and `periodic_report.generation_failed`. Correlate by `queueId`, `reportId`, `workspaceId`, and provider message ID; recipient addresses and report content are omitted from these structured events. If the provider accepted an email but tracking failed, the worker blocks automatic retry. Check provider logs before requesting another delivery to avoid duplicates. SES dispatch uses one SDK attempt, while quota validation retains its existing retries. A delivery is accepted only with HTTP 200 and a valid provider message ID. Missing receipts, transport failures, and ambiguous server responses are blocked as unknown outcomes and require provider verification before a manual retry. Definitive rejection responses retain the existing retry policy. Both the historical worker-timeout and provider-unknown warnings survive reapproval and Send/Test requests; only an explicit Retry after provider verification can clear them, and a disabled gate preserves the warning. A service-only readiness probe stops claims during the app-before-migration window. Other providers without this optional classification retain their existing behavior. These source safeguards do not prove inbox receipt or exactly-once delivery; actual SES-adapter/worker regression tests cover the boundary. Local verification: run the Contacts schedule tests, the web `src/lib/user-report-automation` suite, the users-core report route tests, and the isolated Supabase periodic-report tests. These checks do not send real email. The isolated Supabase runner stages tracked files only. For an untracked migration or pgTAP test, explicitly include both files in the disposable project's `trackedFiles` list using `stageDisposableProject`; verify the staged migration is present before accepting a reset result. No production schema push is needed for this local validation. Manual delivery requests lock the report before the queue and update both states in the same database transaction. Approval transitions use the same lock order; worker claims and stale claim recovery follow the same order. Workers check the original lease before sending; a service-only completion function checks its owner and timestamp and commits the queue and report states together. AI generation retries conditionally claim the previously observed generation state, so a report that became ready is not downgraded. Stale queue requests are rejected after approval is revoked. Provider-accepted deliveries retain their acceptance timestamp even if later tracking fails, preventing re-approval from automatically resending them. A processing lease older than 15 minutes is moved to blocked on the next worker pass, with an attempt diagnostic explaining that its outcome is unknown. Check provider logs before explicitly retrying; re-approval does not automatically resend an unknown outcome. During the app-before-migration deployment window, delivery requests return a temporary 503 with `Retry-After`, and enabling automatic sending waits until the new database function is available. Disabling automatic sending remains available throughout rollout. ## Monthly email previews and delivery status The Reports tab uses the same approval and email badge vocabulary as daily reports. Click a status total to filter; use the delivery filters for queued, processing, failed, blocked, and cancelled messages. Approval and sending remain separate states: an approved report can still be **Not sent**. The compact email settings banner shows whether the sender, delivery gates, and automatic sending after approval are ready. Opening a monthly report from this tab loads the actual email HTML. Both the preview and the delivery worker use `loadReportEmailPreview` and `renderReportEmail` in `packages/users-core/src/reports`. They read the workspace's report template settings: logo, contact details, introduction, section labels, conclusion, and closing. Student, group, and teacher variables are escaped and resolved from the workspace-scoped report view. The score is the saved representative score; save editor changes before previewing or sending. Emails use a continuous responsive document rather than A4 page breaks. No PDF is attached. The full report editor remains available from the preview. `GET /api/v1/workspaces/:wsId/users/reports/:reportId/delivery?preview=true` requires report view permission and returns private, uncached HTML without queueing mail. Sending still requires send permission, approval, and enabled workspace gates. Template-loading failures fail delivery rather than silently sending a simplified report. Delivery diagnostics show the actual recipient, acceptance timestamp, retries, and attempt history; successful test sends remain explicitly labelled tests and do not mark the report as sent to its real audience. Before rendering or sending a periodic report, the worker verifies that the current report subject matches the retained queue subject. A subject change while a delivery was waiting, including during a workspace-user merge, blocks that delivery instead of sending the current report to the previous subject's address. Request a new delivery after confirming the current subject profile; gates, approval, and workspace permissions still apply. The worker re-reads the matching subject's workspace profile email. This safeguard is covered by the actual-worker recipient boundary regressions. An active delivery locks the report content and approval until the worker finishes. Edits, deletion, or approval changes during that window return a conflict; retry once delivery has finished. This prevents an approved report from changing between the final approval check and sending. ### Review filters and test delivery Periodic reports open with Pending approval selected, excluding drafts, approved, rejected, and terminal delivery states. Periodic filters and sorting use separate URL parameters from daily reports. Date bounds select overlapping saved report periods; reports without a saved period are included under All periods. Status totals reflect the selected period before search and status filters narrow the list. Report delivery and Test send are separate statuses. A successful test does not mark the report as delivered or prevent its regular send. Diagnostics show the latest send retry count separately from up to 20 recent delivery-history entries. Timestamps explicitly use the viewer device timezone. Provider references are available under each history entry. ## Periodic report stages Weekly, monthly, quarterly, and yearly reports use ten exclusive stages: Drafts, Pending approval, Approved awaiting delivery, Undeliverable, Queued, Processing, Sent, Failed, Skipped, and Rejected. The default view shows Pending approval. Select a status to filter or Show all reports to include terminal states. Counts respect the cadence and period range. Skipped reports are preserved and do not send automatically after approval. The September 12, 2026 cleanup marks Easy Center reports created strictly before `2026-09-11T17:00:00Z` as Skipped when their delivery status is still Not sent. It covers all periodic cadences and generation states, preserves content/approval/history, and excludes active queues, accepted real deliveries, and unknown delivery outcomes. Any stale retryable queue entry on a skipped report is cancelled. The migration logs the affected row count and is safe to rerun. ### Monthly report editor draft refresh Contacts retains independently edited title, lesson observations, and next-step feedback when the same report refreshes in the background. Untouched fields use the latest saved values. An exact saved draft acknowledgment clears dirty state; switching workspace, report, student, or group resets the prior draft. This is in-memory draft protection, not cross-device conflict resolution or automatic generation of teacher observations. It does not change approval or email gates. Regression coverage: `use-report-draft-sync.test.tsx` exercises the real form controller, conflicting refreshes, intentionally cleared fields, save acknowledgments, and all four scope boundaries. ### Periodic delivery database contract The `periodic-report-delivery-contract.yaml` CI workflow replays the complete historical schema in an isolated disposable database, runs the approval, stage and provider-outcome pgTAP fixtures with strict assertion accounting, generates actual schema types, and cleans up its owned database. The source-only runner and mocked adapter tests are not database or provider delivery proof. Require this workflow for the exact repair head before merging the migration. Production applies it through the gated migration workflow after authorized promotion; do not enable flags or send reports merely because source tests pass. Explicit Retry for either uncertainty marker shows a localized possible-duplicate warning in Contacts, requiring provider-log and intended-recipient verification before confirmation. Ordinary definitive rejection retains its normal retry copy. Confirmation is invalidated across actor/workspace or send-capability changes and suppresses duplicate submissions while pending; this does not verify provider acceptance or inbox delivery. The periodic delivery database contract also checks real two-connection claim exclusion, approval revocation versus a waiting delivery request, and stale completion versus a successor lease. Generated types are strictly compiled from the complete historical schema after those checks. These checks cover database lease behavior; they do not make legacy approvals canonical review receipts, authorize provider dispatch, or prove recipient delivery. ### Unwired report presentation envelope The shared server presentation helper constructs a normalized recipient, transport subject, HTML and SHA-256 digest from one copied input snapshot. It uses the existing email renderer, saved representative score, student/group/teacher names and complete allowlisted branding/report configuration. Recipient normalization matches the current periodic worker (`trim().toLowerCase()`). The transport title and HTML heading share the renderer's configured or localized fallback. Configured title parts are trimmed before joining; whitespace-only parts use the localized fallback. Before rendering or hashing, the helper applies the shared transport address and subject schemas, including the 254-character address and 200-character subject limits. Invalid input fails without truncating reviewed human text. The pure validation subpath imports no provider or service initialization. Explicit null values and intentionally cleared feedback remain distinct from missing input; missing fields, malformed revisions and incomplete configuration fail closed. This unit is unwired: it does not read a database, store presentation content, issue an approval receipt, change current preview or delivery callers, or authorize an email. Its presentation digest is not a complete review certificate: full reviewed fields, current permissions, canonical approval actions, revision locks and dispatch validation remain separate requirements. Existing status-only delivery and legacy approval paths must not be treated as covered by this helper. Regression coverage: `reviewed-email-envelope.test.ts` uses the actual renderer for names, score, branding, escaping, multiline and cleared text, immutable copies, canonical key ordering, recipient normalization and missing-input rejection. These synthetic source tests do not prove a consistent database snapshot, provider acceptance or recipient delivery. ### Web periodic approval tenant boundary Web's initial periodic-report approval and rejection checks require both the report subject and group to belong to the requested workspace. Batch selection uses the same two filters. Foreign-group reports cannot enter these mutations through a subject that belongs to the workspace. Existing permission denials, Web daily-post approval and email-enqueue behavior remain unchanged. The live Web handler is first-class and split into focused GET, PUT and shared validation modules. Its GET still enters request-time rendering and HEAD retains status and headers without a body. Rust continues to implement GET only; PUT falls through to Web. This source migration does not indicate a traffic cutover. These initial checks are not an atomic permission or review certificate: linked records can change after lookup. Canonical revision locks, explicit approval receipts and delivery validation remain required before enabling status-only report delivery. This change does not authorize approval, gate changes or email. Regression coverage: Web's `tenant-boundary.test.ts` exercises foreign subject, foreign group, single approval/rejection, batch selection and permission denials; `route.test.ts` retains the original daily-post permission controls and `facade.test.ts` checks request-time GET, bodyless HEAD and the original PUT binding. These synthetic handlers do not prove database concurrency or delivery. ### Approval read consistency Periodic approval lists and their exact pagination counts require both subject and group workspace membership in Contacts and Web. Pending-summary counts and latest approved-report history use the same boundary. Contacts' standalone report page rejects foreign or missing groups and excludes those reports from sibling history. Daily-post behavior, permission checks and saved history remain unchanged. Existing Rust GET implementations carry the same query filters; this is source parity, not a backend traffic cutover. Coverage: `get-tenant-boundary.test.ts`, `review-reads-tenant-boundary.test.ts` and the actual Contacts `page-tenant-boundary.test.tsx` exercise foreign subjects, foreign/missing groups, own reports, pagination, counts, history and permission denials. These checks remain initial reads, not atomic review or permission certificates. Canonical approval and delivery closure are still required; no gate or email is enabled by this consistency rule. ### Contacts periodic approval tenant admission Contacts requires both the report subject and its group to belong to the current workspace before single-entry approval or rejection. The existing batch selection uses the same two workspace filters, excluding an entry whose subject belongs to the workspace but whose group does not. Approval permission and the current actor link remain required. The dedicated `put-tenant-boundary.test.ts` covers single actions, mixed-tenant batches and permitted/denied controls. This is an initial query admission check, not an atomic review certificate. A later content or scope change can race the separate update. Observed revisions, explicit selected-batch intent, canonical receipts and locked permission/tenant validation remain required before enabling report emails. The independent Web legacy mutation path is not changed by this Contacts packet; its faithful parity move is a separate prerequisite. Daily-report behavior is unchanged here. ### Unwired explicit periodic approval protocol The pure shared protocol accepts a nonempty selection of at most 50 unique periodic report IDs with observed revisions as canonical positive decimal text. It rejects filter-based blanket selectors, caller-supplied actor fields, daily entries and numeric revisions. Decimal text preserves signed-bigint revisions above JavaScript's safe integer limit. Returned request and result snapshots are independent and frozen. A complete result must match the explicit action, workspace, supplied actor comparison context and every selected entry, with unique receipt identities and advancing revisions. Original and replay results use the same validation; replay still needs current permission and revision admission by the future backend. Full review-input digest, presentation digest and renderer version remain separate fields. Format validation does not prove either digest's canonical encoding, rendered payload consistency or a receipt's authenticity. This unit is unwired. Its comparison context is unauthenticated pure input; future trusted backend admission, authoritative subject and group tenancy, workspace provenance for both role and grant, atomic batch locks and canonical receipt creation remain mandatory. It performs no SQL, RPC, queue mutation, provider call or readiness activation. Legacy approvals remain insufficient for canonical dispatch. `approval-protocol.test.ts` covers selection bounds, exact large revisions, foreign identities, incomplete and replay results, distinct digests, immutable snapshots and fail-closed malformed input. ## Cloudflare dispatch outcomes Cloudflare sends expose a dispatch outcome separately from the existing success boolean. Positive message-ID, delivered-recipient, or queued-recipient evidence means `accepted`: the provider accepted at least part of the dispatch. It does not prove delivery to every recipient. A partial permanent bounce still retains `success: false` and its existing error while reporting `accepted`. Local recipient, attachment, and message-size limits or preparation failures before the provider request report `rejected`. Once the request is handed off, transport loss, malformed or incomplete responses, and all-bounce responses without acceptance evidence report `unknown`. Neither `accepted` nor `unknown` is proof that automatically retrying the whole dispatch is safe. This adapter change adds no automatic retry, caller activation, or delivery reconciliation. Coverage: the actual adapter's synthetic-response tests in `cloudflare-delivery-outcome.test.ts` retain legacy success/error behavior and assert zero provider requests for rejected local preparation. Existing `cloudflare.test.ts` request and attachment controls remain unchanged. Synthetic checks are not evidence of customer email delivery or live provider behavior. ## Human feedback generation consumer Automatic and manual generation capture the original workspace, subject, group, report, cadence, civil period and stored manager instruction. Automatic retries use the existing report instruction. Claims, successful saves and failed-attempt writes require a returned row matching the original tuple, instruction and acknowledged updated-at revision. A conflict or unacknowledged write is not a successful save or a safe-retry guarantee. These predicates have synthetic client construction tests; real database race and authenticated save/reload evidence remain required. The context loader obtains human feedback once. The same complete evidence envelope enters the narrative prompt and the successful report source context. Manager instructions have a separate prompt section. Feedback commands, URLs and role markers remain literal observation strings. Source timestamps do not establish session or topic identity. Prompt partition tests do not prove model obedience or generated factuality. Legacy metrics retain their separate UTC/date semantics. Stored civil dates are interpreted in the current workspace timezone. Automatic schedules are checked against the run workspace, cadence and group; a null group is the workspace default expanded by schedule reconciliation. Manual regeneration may follow only the exact automation run in source context after validating its original workspace/group/cadence/period, then its exact schedule. A genuinely manual, foreign, malformed or unavailable origin stays explicitly unavailable with null schedule timezone and mismatch. Verified origins survive regeneration. Ready empty feedback and ready incomplete feedback, including zero retained records, are distinct usable draft contexts. Under the assigned consumer policy, unavailable feedback stops generation before a model call. Its exact loader status/reason, validated caller identity and observed schedule provenance are saved only after a conditional failed-attempt acknowledgement. The frozen loader does not expose intermediate timezone/window observations on failure, so these fields remain null even if an internal workspace lookup succeeded. The consumer does not duplicate that lookup. Context failure with no admitted envelope records `not_loaded`, without asserting empty observations. `latest_generation_attempt` describes the newest acknowledged attempt. Failure preserves prior title/content/feedback, metrics and successful evidence, including `last_successful_generation_context` when present. Only an acknowledged successful save publishes a ready draft and resets review to PENDING. No failure marks a new draft ready or changes delivery error/retry state. The 32768-byte limit covers only the foundation compact evidence envelope. It does not bound the whole prompt, model tokens, SQL scan, transport, allocation, memory or duration. Source tests are not runtime activation: runtime admission remains null/DENIED and readiness/provider/email flags remain OFF. Permission authorized explicit approval of EVERY email entry, the specific monthly action, recipient approval, provider readiness and canonical parent inbox delivery remain separate held outcomes. Draft save/reload and foreign-teacher topic notification verification are also still required. # Rewise Source: https://docs.tuturuuu.com/platform/applications/rewise Private AI conversations, tool surfaces, and access limitations. Rewise (`rewise.tuturuuu.com`, `apps/rewise`) is an AI conversation surface with app-session, workspace, and AI access gates. It is distinct from the product [AI Studio](/platform/ai/ai-studio), workspace [Chat](/platform/applications/chat), and the long-term AI vision. ## Available source surfaces | Route | Surface | | - | - | | `/{wsId}` | Conversation overview | | `/{wsId}/new` | New conversation | | `/{wsId}/c/{chatId}` | Existing conversation | | `/{wsId}/tools` | Tool listing | | `/{wsId}/tools/{toolId}` | Tool-specific surface | | `/{wsId}/imagine` | Retained image-oriented surface | A retained route is not a claim that its configured model is enabled. The image-oriented page currently supplies a disabled Imagen model configuration; do not describe it as a generally available image-generation product based on route presence alone. Provider/model availability must be checked against the actual UI and server policy. ## Access, usage, and memory AI whitelist/eligibility and workspace access are checked before serving the private experience. Model policy, credits, usage accounting, and tool permissions remain part of the owning AI execution path. Read the [Model catalog](/platform/ai/model-catalog), [Usage guards](/platform/features/usage-accounting-guards), and [Memory service](/platform/ai/memory-service) before extending a flow. Memory is scoped context; it does not authorize publishing or other actions. Conversations, tools, and generated/private content are noindex. Public AI product descriptions belong on the main site's public pages. The [Rewise route reference](/reference/repository/routes/rewise) locates every page and API handler. It should be read alongside the implementation's access checks, not treated as an external public API guarantee. # Shiraoki Source: https://docs.tuturuuu.com/platform/applications/shiraoki How Shiraoki is wired as a Shopify-backed external storefront through Tuturuuu CMS and app coordination. Shiraoki is a standalone headless Shopify storefront in the sibling `../shiraoki` repository. Tuturuuu does not own Shiraoki commerce records. Tuturuuu owns the external-project binding, CMS configuration, launch gate, central login handoff, and app-token access used by Shiraoki admin/account surfaces. ## Ownership Boundary Keep the data split explicit: * Shopify owns products, variants, inventory availability, cart checkout URLs, payment completion, customer addresses, and order history. * Shiraoki owns the storefront runtime, local server helpers, route transitions, cart UI, product gallery, account center, and owner admin workflow. * Tuturuuu owns CMS configuration, workspace binding, external app registration, app-token exchange, launch-gate content, navigation, editorial sections, and shopper-only data that is not naturally Shopify-owned. Do not duplicate Shopify products into Tuturuuu CMS records for normal catalog operation. CMS records should only hold presentation/configuration metadata. ## Platform Adapter The platform adapter ID is `shiraoki`. The adapter is registered in: * `apps/web/src/lib/external-projects/constants.ts` * `apps/web/src/lib/external-projects/fixtures.ts` * `apps/cms/src/features/cms-studio/constants.ts` * `packages/types/src/supabase.ts` * `apps/database/supabase/migrations/20260517141000_add_shiraoki_external_project_adapter.sql` The canonical project created by setup routes should be `shiraoki-main`. Workspace bindings must point at a canonical project whose adapter is `shiraoki`, or app-token exchanges for Shiraoki external-project scopes will be rejected. ## CMS Collections Shiraoki's default CMS collection slugs are: * `site-config`: brand name and portable storefront identity * `launch-gate`: password screen state, copy, and early-access passphrase * `navigation`: storefront nav labels and hrefs * `editorial-sections`: minimal home-page supporting sections * `shopify-settings`: active Shopify presentation settings, such as featured collection handle These collection slugs are defined in both `apps/web` and `apps/cms` so the root platform console and standalone CMS app agree on adapter defaults. ## External App Registration Register Shiraoki from the Infrastructure external-app registry before using live auth: 1. Create external app ID `shiraoki`. 2. Add every allowed Shiraoki origin, for example `http://localhost:3000`, staging origins, and the production storefront domain. 3. Allow only the scopes Shiraoki needs. For admin/CMS setup use `external-projects:*`; for preview or read-only storefront access prefer `external-projects:read`. 4. Issue an app secret and store it in Shiraoki as `TUTURUUU_APP_SECRET`. The secret is shown once. Tuturuuu stores only the hash in root workspace secrets. ## Auth Flow Shiraoki sends users to `apps/web` login with a return URL pointing back to `/verify-token?nextUrl=...` on the Shiraoki origin. After login, `apps/web` validates that the return origin belongs to the registered Shiraoki external app and adds a short-lived cross-app token to the return URL. Shiraoki then calls: ```http theme={null} POST /api/v1/auth/app-token/exchange ``` with `appId: "shiraoki"`, the app secret, the handoff token, requested scopes, and the bound workspace ID when external-project scopes are requested. The exchange succeeds only when: * the Shiraoki app secret is valid * the cross-app token targets `shiraoki` * the workspace has external projects enabled * the workspace binding's canonical adapter is `shiraoki` * the user has the permission required by the requested external-project scope If the user is invited to the bound workspace but has not accepted yet, the exchange returns `403` with `code: "PENDING_WORKSPACE_INVITE"`, the normalized `workspaceId`, and an `invitationUrl`. Shiraoki should route the user to that URL, or show an action that opens it, before displaying generic no-access copy. After the invitation is accepted, Shiraoki should retry the exchange; normal workspace and external-project permission checks still apply. Shiraoki should store the returned bearer token in its own HttpOnly session cookie and call Tuturuuu APIs with that token. Do not give Shiraoki production Supabase service-role credentials. ## Environment Shiraoki expects these runtime variables: ```bash theme={null} SHOPIFY_STORE_DOMAIN=your-shop.myshopify.com SHOPIFY_STOREFRONT_ACCESS_TOKEN=... SHOPIFY_ADMIN_ACCESS_TOKEN=... SHOPIFY_API_VERSION=2026-01 TUTURUUU_WEB_APP_URL=https://tuturuuu.com TUTURUUU_APP_ID=shiraoki TUTURUUU_APP_SECRET=... TUTURUUU_CMS_WORKSPACE_ID=... NEXT_PUBLIC_SHIRAOKI_SITE_URL=https://shiraoki.example SHIRAOKI_STOREFRONT_PASSWORD=... ``` Store Shopify Admin API credentials only on trusted server runtimes or platform workspace secrets. Never expose Admin API tokens to client code. ## Local Development From the Shiraoki repo: ```bash theme={null} bun run lint bun run build bun run dev -- -p 3000 ``` When Shopify credentials are absent, Shiraoki falls back to demo products and a demo cart so product pages, dark mode, responsive catalog layout, and cart UI remain testable. For local Tuturuuu auth, run the central platform app and register the local Shiraoki origin as an external app: ```bash theme={null} TUTURUUU_WEB_APP_URL=http://localhost:7803 NEXT_PUBLIC_SHIRAOKI_SITE_URL=http://localhost:3000 TUTURUUU_APP_ID=shiraoki ``` ## Operational Checks After platform adapter changes, run focused checks first: ```bash theme={null} cd apps/web bun run test src/lib/external-projects/fixtures.test.ts src/lib/external-projects/access.test.ts bun run test src/app/api/v1/auth/app-token/exchange/route.test.ts bun run type-check cd ../cms bun run type-check ``` Run `bun check:changed` from the platform root before pushing, and require the `bun validate` and build workflows to pass in CI for the exact commit. # Shortener Source: https://docs.tuturuuu.com/platform/applications/shortener Workspace link management and the separate redirect runtime. Shortener (`shortener.tuturuuu.com`, `apps/shortener`) is the redirect runtime. Workspace link-management and analytics pages remain in Web under `/{wsId}/link-shortener` where registered. The service and the management UI have separate responsibilities. ## Follow a short link A `/{slug}` request resolves through the configured redirect implementation. The destination and current access/validity checks determine the result. Do not assume a short link is a public content page, an authentication bypass, or a published copy of its target. Inspect the destination's own access rules. ### Redirect rules These rules apply to every Shortener host (`ttr.gg` and its configured aliases) on the native Start + Void runtime: * **Lookup.** Generated slugs and custom aliases share one exact, case-sensitive lookup of the stored slug. * **Redirect.** A found link with a valid destination answers `307` with `Location` set to the stored target, byte for byte. The URL parser serializes the target only when it contains spaces or non-ASCII characters. The short link's own query is not appended, as in the legacy page. The click row is written before the redirect is returned, and an analytics failure never blocks the redirect. * **Destination validation.** A stored target that does not parse, or that uses `javascript:`, `data:` or `vbscript:`, renders the invalid-destination page and records no click. Script schemes were previously parseable; refusing them is an intentional tightening. * **Password links.** These render the password form with the hint, never the destination. `POST /api/verify` keeps its legacy statuses (`400`, `403`, `404`, `500`) and records a click only after a correct password. The browser leaves only for a navigable destination. * **Missing links.** A missing slug renders the not-found page with `200`, as before. Deeper paths return `404`. * **Aliases.** Alias hosts redirect to `ttr.gg`, preserving the path and the raw query, duplicate keys included. `www.ttr.gg` uses `308`; the other five aliases use `307`. * **Analytics.** On Cloudflare, click geolocation comes from the trusted request metadata and the client IP from `CF-Connecting-IP`, while `vercel_region` and `vercel_id` stay null. Vercel Web Analytics is not loaded on the native runtime. Regression coverage lives in `apps/shortener/src/link/link.test.ts` and `apps/shortener/src/native/shortener-request.test.ts`. The emitted Worker suite, `apps/shortener/cloudflare/native-built-worker.test.mjs`, runs in CI. The cutover and rollback profile is in [Shortener on Start + Void](/build/devops/shortener-start-void). ## Manage links Use the workspace management flow to create/manage supported links and inspect available analytics. Analytics represent the events the implementation records; they are not proof of unique people, conversions, or the destination's state. Workspace permissions still govern management and analytics. ## Search policy The redirect host is noindex and advertises no sitemap. Public landing pages should be indexed on their canonical destination host instead of accumulating short-link copies in search. The HTTP noindex policy also applies to API and error responses. See [Shortener routes](/reference/repository/routes/shortener) and the [Web route inventory](/reference/repository/catalog) for the exact source entry points. [Search indexing](/platform/features/search-indexing) explains why redirect execution and public content discovery are separate concerns. # Storefront Source: https://docs.tuturuuu.com/platform/applications/storefront Public and private inventory storefronts with Polar and Square Terminal checkout. `apps/storefront` is the buyer-facing Inventory commerce app. Operators manage catalog, stock, storefront visibility, and checkout-provider settings in `apps/inventory`; buyers browse, cart, and start checkout from `storefront.tuturuuu.com`. ## Hosts * Production: `https://storefront.tuturuuu.com` * Local Portless: `https://storefront.tuturuuu.localhost` * Local fallback port: `7822` The Storefront app rewrites `/api/*` to `apps/web`, matching other satellite apps. It does not read Supabase directly from client code. ## Access Published public storefronts are readable anonymously. Published private storefronts require a Tuturuuu app session and workspace membership; guest-type workspace members are accepted. ## Theme and lifecycle The Inventory storefront editor offers a **Native** accent mode as the safe default. Native mode leaves `accent_color` unset so Storefront inherits its theme-aware primary, focus, and contrast tokens in both light and dark mode. Choose **Custom** only when a fixed hexadecimal brand color must override those tokens. Removing a storefront is deliberately non-destructive. Inventory marks the storefront as removed, releases its former public slug for reuse, invalidates the old public cache entry, and hides it from operator and buyer discovery. Checkout sessions, order history, stock movements, and audit references keep their original storefront row. Archiving remains the reversible choice for a storefront that may return later. ## Polar Checkout Each workspace can save sandbox and production Polar organization tokens from Inventory settings. Tokens are encrypted server-side and only masked metadata is returned to clients. Storefront checkout reserves inventory first, creates a Polar checkout session with the workspace-owned private one-time product, and redirects the buyer to Polar. If Polar checkout creation fails after reservation, the reservation is released immediately. ## Square Terminal Checkout Square Terminal checkout is a staff-only pay-at-terminal handoff. A signed-in member needs the dedicated **Start POS checkout** permission (or Admin), then selects the paired payment station that should receive the order. Storefront validates the member, device, and selling location before creating a local reservation and sending the Square request. Repeated dispatches are rate limited before reservation. Square POS App + Reader uses a different same-device handoff: it opens Square POS on the compatible phone or tablet currently running the Storefront and cannot target another reader remotely. The checkout UI states this distinction instead of presenting phone installation IDs as routable Terminal devices. Square payment success is accepted only from verified Square webhook or status data. Cancellation, failure, or expiry releases the local reservation so stock returns to availability. Abandoned reserved sessions are materialized as expired by the Inventory sweeper as well as lazy checkout reconciliation. Catalog and physical stock can be synchronized in either direction from Inventory settings; Square-side updates are additive and never delete or archive Square objects. ## Cache and invalidation contract Published storefront payloads use Next.js Cache Components with a cache tag per storefront slug. The data cache has a long safety-net lifetime and is refreshed by events rather than by polling. Any operation that changes shopper-visible catalog data or availability must invalidate the affected tag before returning success. This includes product and stock edits, reservations, reservation release or expiry, completed sales, provider reconciliation, and inbound Square catalog sync. Checkout reservation code must continue to read fresh stock directly. A cached browse response is only a presentation optimization and must never be used as the source of truth for reserving or consuming inventory. Storefront routes stream `loading.tsx` and explicit Suspense fallbacks while request-specific buyer and access data resolves. Server data seeds the TanStack Query cache, internal links use Next.js navigation, and the browser must not repeat the initial storefront request on mount. ## Cache E2E test Start local Supabase, then run the Inventory-owned cross-app Playwright suite: ```bash theme={null} bun sb:start bun --cwd apps/inventory test:e2e ``` The test creates a disposable public storefront, warms the cached API payload, changes stock through the authenticated Inventory API, and verifies the next public read sees the new quantity. It also confirms the product route streams a skeleton, uses Next's `@next/playwright` `instant()` helper to prove that the prefetched loading shell commits before dynamic data resumes, keeps Storefront navigation client-side, and removes the entire fixture in cleanup. Keep both Inventory (`7815`) and Storefront (`7822`) server entries in `apps/inventory/playwright.config.ts` whenever either app's local host or startup command changes. The `Inventory / Storefront cache contract` job in `.github/workflows/e2e-tests.yaml` runs this suite in parallel with the broader platform E2E matrix and uploads Playwright traces and the HTML report when it fails. # Tasks - Task Management Source: https://docs.tuturuuu.com/platform/applications/tasks Hierarchical task management with bucket dump and cross-board coordination # Tasks - Smart Task Management Tasks is Tuturuuu's intelligent task management system featuring a 6-level hierarchy, bucket dump for rapid capture, and cross-board project coordination. ## Tasks and Calendar planning Both satellite apps expose local planning views without changing workspace or requiring a cross-app login handoff: | Host | Calendar | Tasks | | - | - | - | | Tasks | `/{wsId}/calendar` | `/{wsId}/tasks` (default board) | | Calendar | `/{wsId}` | `/{wsId}/tasks` (editable task list) | The shared sidebar retains locale and personal/internal workspace aliases, including on mobile. Calendar also serves `/tasks/boards`, `/tasks/boards/{boardId}`, and `/tasks/{taskId}` within the workspace. Task views hide the calendar-only mini-month sidebar to leave more room for task work. Tasks' embedded calendar uses the shared scheduling, connection, event, and task controls and enforces `manage_calendar`. Each host resolves its own app-session actor. Keep the task route context and dialog manager prefix aligned: Tasks uses an empty prefix, while Calendar and Web use `/tasks`. Tasks already owns a dialog provider, so its embedded calendar disables the additional dialog wrapper. When validating this integration, check both locales, personal and team workspace links, board/task detail return paths, and mobile navigation with the sidebar closed. Mutations continue through the existing protected product APIs. ## Overview Tasks provides: * **Hierarchical organization** - 6 levels from workspaces to individual tasks * **Bucket dump** - Capture notes and convert to tasks/projects * **Cross-board projects** - Coordinate tasks across multiple boards * **Task cycles** - Sprint/iteration management * **Smart estimation** - Fibonacci, exponential, linear, and t-shirt sizing * **Custom statuses** - Per-board status workflows * **Labels & priorities** - Flexible categorization ## Task description media retention Task descriptions in the Tasks app accept pasted or selected images and videos. The Tasks app session can read embeds from the task-images directory when the user has `manage_drive_tasks_directory`, the same permission required to upload them. General Drive access is not required for task media, and a Tasks session cannot read unrelated Drive or Finance files through the share route. Uploads made while creating a task remain available when the task is created or saved as a draft. Discarding the new-task dialog clears its local draft and requests immediate deletion of its uploads. A daily Tasks cleanup job removes task media older than 30 days when no current task or saved task draft references it. This includes media removed from an existing description and uploads left behind when a browser closes before the discard request completes. References in task version history do not retain media after removal from the current description. The Tasks Vercel project schedules `/api/cron/tasks/cleanup-media` at 03:17 UTC; the route requires `CRON_SECRET` or `VERCEL_CRON_SECRET`. ## Board And List Name Uniqueness * Active and archived task board names are unique per workspace using `lower(btrim(name))`; only trashed boards with `deleted_at` set release the name. * Non-deleted task list names are unique per board using `lower(btrim(name))`, regardless of status/category. * Duplicate board writes return `409` with `code: "TASK_BOARD_NAME_EXISTS"`. Duplicate list writes return `409` with `code: "TASK_LIST_NAME_EXISTS"`. * Existing duplicate rows are preserved by the forward migration that renames older duplicates with a deterministic ` (duplicate )` suffix before the unique indexes are created. The migration does not move or delete tasks. ## Satellite Auth And API Ownership `apps/tasks` is registered internally as the `tasks` app. App-session checks, cross-app token verification, and Web API allowlists should use `targetApp: 'tasks'` unless a route explicitly accepts another first-party audience such as the CLI's Web-minted `targetApp: 'platform'` task tokens. `apps/tasks` is also the canonical owner for authenticated task product pages and task-owned APIs. Do not add new task UI or task API behavior to `apps/web`. Old authenticated Web task URLs should stay as redirects to the Tasks origin, while `/products/tasks` remains Web-owned marketing content. Task-owned API families include tasks, task boards, board aliases, labels, templates, projects, initiatives, cycles, drafts, task progress, plans, shared task links, admin task embeddings, task webhooks, task cron routes, Mira task endpoints, habits, and habit trackers. First-party task clients should resolve the Tasks origin through `TASKS_APP_URL`, `NEXT_PUBLIC_TASKS_APP_URL`, or `TUTURUUU_TASKS_BASE_URL`. Legacy `TUDO_APP_URL` and `NEXT_PUBLIC_TUDO_APP_URL` are accepted only as compatibility aliases. Local development falls back to the Tasks app origin (`http://localhost:7809` or the matching portless Tasks domain). SDK, CLI, mobile, and `packages/internal-api` task-domain helpers should use that Tasks origin outside `apps/tasks`; inside `apps/tasks`, relative API calls are still preferred. Tasks may serve credentialed browser API traffic from first-party Web/platform origins, but CORS must stay origin-specific. Do not use wildcard credentialed CORS for task APIs. ### Task Embedding Webhook Operations The Supabase task embedding webhook must send its configured shared secret in the `x-webhook-secret` header. Set `SUPABASE_WEBHOOK_SECRET` in the Tasks deployment and use the same value in the Supabase Database Webhook header configuration. Use a secret placeholder in local examples and operational documentation; never record the deployed value. The route fails closed before parsing the payload or creating an admin Supabase client. Missing or empty server configuration returns a server configuration error, while an absent or mismatched request header returns `401 Unauthorized`. CLI task commands call the Tasks origin with bearer app-session tokens minted by `apps/web`. The Tasks proxy must pass `ttr_app_...` bearer tokens to route-level `withSessionAuth` so the route can verify CLI scope, expiry, and target-app allowlists. Production `apps/web` and `apps/tasks` must share `TUTURUUU_APP_COORDINATION_SECRET`, or the same accepted fallback signing secret, or freshly minted CLI tokens will be rejected as `Unauthorized`. The local `/api/auth/verify-app-token` route must delegate token validation to the central Web verifier with `verificationBaseUrl: TTR_URL`. That handoff sets both the host-only Tasks app-session cookie and the Web-issued app-session cookie used by central API requests. Do not reintroduce Tasks-local Supabase session validation for cross-app login. Tasks must also keep a local `/login` page. It is a redirect-only route: valid Tasks app-session cookies continue to `/personal/tasks` or the safe `next` path, while missing or stale cookies redirect to `apps/web` login with a `/verify-token` return URL. Without this route, a successful Web handoff can set cookies and still leave the browser on a Next.js 404. The Tasks app should not authenticate protected product APIs with local Supabase Auth cookies. Fallback `/api/*` traffic is proxied through the local catch-all API route, which strips `sb-*-auth-token` cookies before forwarding to Web. Keep the corresponding Web routes app-session aware for `targetApp: 'tasks'`; otherwise the browser can have valid Tasks cookies while the data layer still loops through `401` and proxy-side `429` responses. Task board/list count endpoints must compute counts in the database, preferably through private service-role RPCs, and return one aggregate row per board/list. Do not hydrate every matching `tasks` row in an API route just to count them. ## Board Capacity Rules Board capacity rules provide reusable work-in-progress controls for task queues. Rules can select lists, labels, and projects; selector dimensions combine with AND, while labels and projects can use Any or All matching. A matching task is counted once even when several relations match. Rules can measure task count or estimation points and can count active tasks (the default) or all non-deleted tasks. Authenticated clients use these Tasks-owned routes: * `GET/POST /api/v1/workspaces/{wsId}/task-boards/{boardId}/capacity-rules` * `PATCH/DELETE /api/v1/workspaces/{wsId}/task-boards/{boardId}/capacity-rules/{ruleId}` Joined workspace members and direct board guests may read capacity status. Only joined members with `manage_projects` may configure rules. Hard limits are enforced in PostgreSQL under a board-scoped transaction lock so browser, CLI, guest, bulk, and API writes share the same admission decision. Rejected writes return `409` with `code: "TASK_CAPACITY_EXCEEDED"` and structured rule usage. Successful task writes may include `capacityWarnings` for exceeded soft rules. Active tasks are non-deleted, not completed or closed, and outside `done` and `closed` lists. Missing estimation points contribute zero. A rule whose selected list, label, or project is deleted is disabled automatically, preventing an empty selector from accidentally broadening its scope. ## Rich Text Editor Notes The task editor includes isolated React roots inside some Tiptap node views, especially task mention chips. * Do not mount `next-themes` `ThemeProvider` inside those isolated `createRoot(...)` islands. `next-themes` injects an inline script, and Next.js 16 will warn or fail when that script is rendered from a client subtree instead of the app root. * Resolve theme for those islands from `document.documentElement` and `prefers-color-scheme`, then pass that resolved value through local component state instead of re-creating app-wide providers. * Add `referrerPolicy="strict-origin-when-cross-origin"` to every YouTube iframe path used by the task editor or its previews. Missing referrer policy can surface as YouTube `Error 153` even when the video URL itself is valid. ## Task Link Notes * Canonical deep links for board tasks should use the board route with the task query parameter: `/{wsId}/tasks/boards/{boardId}?task={taskId}`. * Tuturuuu Mobile normalizes production web links from `https://tuturuuu.com` into native routes for task boards, board task details, task estimates, task portfolio/project routes, and common workspace modules. Mobile accepts both `?task={taskId}` from web and `?taskId={taskId}` from native routes. * Links can opt out of native app opening with `native=0` or `openInBrowser=1`. Use this for flows that must stay in the browser, such as debugging, web-only admin surfaces, or temporary compatibility issues. * Avoid generating or persisting modal-only URLs such as `/{wsId}/tasks/{taskId}` for share/copy flows unless the dedicated task detail page is the explicit target. The board-backed URL is the reliable reloadable path used by the dashboard task dialog. * When reloading or recovering a task deep link, resolve the task through the workspace-scoped task API (`/api/v1/workspaces/{wsId}/tasks/{taskId}`) rather than the current-user task dialog API. The current-user endpoint can 404 for valid board tasks because it is optimized for dialog hydration, not route recovery. * Android opens supported links by default only after App Links verification succeeds. Keep `apps/web/public/.well-known/assetlinks.json` in sync with the production Android signing certificate fingerprint; if Play App Signing uses a different app-signing certificate than the repo release keystore, add the Play Console SHA-256 fingerprint before release. * Keep `GoRouter.overridePlatformDefaultLocation` enabled in mobile. iOS can provide a universal link URL as Flutter's platform default route on cold start, and GoRouter will show a no-route page unless `app_links` is allowed to normalize that URL first. ## Mobile Board List Mode Notes * Mobile board list mode hides `documents`, `done`, and `closed` task lists by default when no explicit list or status filter is selected. * The filter sheet must disclose that default exclusion and indicate when a selected list/status filter overrides it, because those filters intentionally reveal otherwise hidden list categories. * Moving a task between lists, including marking it done or closed, should refresh the affected source and destination lists instead of relying on a full board reload. ## Task Board Realtime And Cache Notes * Successful task mutations must update visible TanStack Query caches in place before broadcasting. Patch all visible task shapes that can render the same card: `['tasks', boardId]`, every `['tasks-full', boardId, ...]` query, `['task', taskId]`, matching `['workspaceTask', wsId, taskId]`, and personal task buckets when present. * Relation-only updates for labels, projects, and assignees should broadcast `task:relations-changed` and call the active board refresh with `{ invalidateTasks: false }`. Do not invalidate `['tasks', boardId]` or `['tasks-full', boardId]` after successful relation-only changes; refetching those visible arrays causes card flicker while the optimistic cache already has the relation data. * Scalar task changes such as priority, dates, estimate, name, and list should patch visible task caches and broadcast `task:upsert` with the changed fields. Rollbacks should restore snapshots of the touched task ids instead of invalidating the whole board task cache. * Realtime receivers may reconcile task detail, history, counts, and personal task queries in the background. The board page should revalidate loaded progressive-list data without invalidating visible task arrays so shared boards stay current without remounting cards. During the Cloudflare migration, the server publishes the same authorized task events to both transports so supported older mobile and cached web clients retain updates; new clients use Cloudflare only. See the [bounded compatibility bridge and removal criterion](/build/devops/programming-realtime-runbook#existing-client-transition) and its [regression coverage](https://github.com/tutur3u/platform/blob/main/packages/tasks-api/src/server/tasks/realtime-broadcast.test.ts). * Task edit dialogs should keep dropdowns and popovers controlled from a single active overlay id within each dialog section. Opening another menu must close the previous one, and outside-click/Escape close behavior should flow through the same `onOpenChange` path. ## AI Journal Capture Notes * The quick-journal endpoint at `/api/v1/workspaces/{wsId}/tasks/journal` is a two-step flow: preview requests may invoke AI, but save requests that already include reviewed `tasks` plus a `listId` must persist directly. * Do not re-resolve the AI model, re-check credits, or regenerate tasks during that save step. A successful preview must be able to save even if model allocation changes afterward. * When the destination picker allows switching workspaces, clear the currently selected board/list immediately in the same UI event before loading the new workspace boards. Effect-only cleanup is too late for save flows and can send a stale `listId` that belongs to a different workspace. * If the final create request fails, reopen the destination-selection step with the reviewed tasks still in memory. Do not clear the journal draft optimistically before the insert succeeds, or users can lose the prompt they just refined. * Any workspace alias accepted by the board/list bootstrap endpoints, such as `personal`, must also be normalized by the journal save route before membership and list checks. Otherwise the picker can show valid destinations while the final save still rejects the same workspace context. * The journal save route should verify workspace membership first with the request-scoped client, then validate the chosen list against that normalized workspace. Admin-backed list checks are fine for consistency with selector data, but they must never bypass the caller's workspace access gate. * Any workspace-scoped project validation in that same save route should follow the same pattern: verify membership with the request-scoped client first, then resolve valid `task_projects` IDs through the admin client scoped to the normalized workspace. Do not read protected workspace project tables directly from the caller-scoped client after access has already been established. * Any top-level `labelIds` or reviewed task `labels[].id` in that save route must be checked against `workspace_task_labels.ws_id` for the normalized workspace before task rows are inserted. Foreign workspace label IDs must fail the request instead of being carried into `task_labels`; labels created by name can still be upserted through the admin-backed workspace path after membership passes. * After membership passes, persist the journal-created `tasks` rows and their relation-table writes (`task_labels`, `task_project_tasks`, `task_assignees`, label upserts) through the same admin-backed workspace path, and stamp actor-owned columns such as `creator_id` explicitly. Do not mix admin-backed validation with caller-scoped writes or the save step can still fail with table-level permission errors. ## Task Hierarchy ``` Workspaces (Top Level) └── Task Initiatives (Strategic grouping) └── Task Projects (Cross-board coordination) └── Workspace Boards (Kanban boards) └── Task Lists (Columns) └── Workspace Tasks (Individual items) ``` ### 1. Workspaces Container for all workspace resources. ```typescript theme={null} // Get workspace const { data: workspace } = await supabase .from("workspaces") .select("*") .eq("id", wsId) .single(); ``` ### 2. Task Initiatives Strategic initiatives grouping related projects. ```sql theme={null} CREATE TABLE task_initiatives ( id text PRIMARY KEY, ws_id text REFERENCES workspaces(id) ON DELETE CASCADE, name text NOT NULL, description text, start_date date, end_date date, created_at timestamptz DEFAULT now() ); ``` **Usage:** ```typescript theme={null} "use server"; import { createClient } from "@tuturuuu/supabase/next/server"; export async function createInitiative(data: { wsId: string; name: string; description?: string; startDate?: Date; endDate?: Date; }) { const supabase = await createClient(); const { data: initiative, error } = await supabase .from("task_initiatives") .insert({ ws_id: data.wsId, name: data.name, description: data.description, start_date: data.startDate?.toISOString().split("T")[0], end_date: data.endDate?.toISOString().split("T")[0], }) .select() .single(); if (error) throw error; return initiative; } ``` ### 3. Task Projects Cross-functional projects coordinating tasks across boards. ```sql theme={null} CREATE TABLE task_projects ( id text PRIMARY KEY, ws_id text REFERENCES workspaces(id) ON DELETE CASCADE, name text NOT NULL, description text, created_at timestamptz DEFAULT now() ); -- Link projects to initiatives CREATE TABLE task_project_initiatives ( project_id text REFERENCES task_projects(id) ON DELETE CASCADE, initiative_id text REFERENCES task_initiatives(id) ON DELETE CASCADE, PRIMARY KEY (project_id, initiative_id) ); -- Link tasks to projects (cross-board) CREATE TABLE task_project_tasks ( project_id text REFERENCES task_projects(id) ON DELETE CASCADE, task_id text REFERENCES workspace_tasks(id) ON DELETE CASCADE, PRIMARY KEY (project_id, task_id) ); ``` **Usage:** ```typescript theme={null} "use server"; import { createClient } from "@tuturuuu/supabase/next/server"; export async function createProject(data: { wsId: string; name: string; description?: string; initiativeIds?: string[]; }) { const supabase = await createClient(); // Create project const { data: project, error } = await supabase .from("task_projects") .insert({ ws_id: data.wsId, name: data.name, description: data.description, }) .select() .single(); if (error) throw error; // Link to initiatives if (data.initiativeIds && data.initiativeIds.length > 0) { await supabase.from("task_project_initiatives").insert( data.initiativeIds.map((initiativeId) => ({ project_id: project.id, initiative_id: initiativeId, })), ); } return project; } export async function addTaskToProject(projectId: string, taskId: string) { const supabase = await createClient(); const { error } = await supabase.from("task_project_tasks").insert({ project_id: projectId, task_id: taskId, }); if (error) throw error; } ``` ### 4. Workspace Boards Kanban-style task boards. Personal workspaces should always have a default active task board named `Tasks`. Web and mobile task-board listing APIs ensure that board exists before returning board data, so users should not see a prompt just to bootstrap their personal task workflow. Mobile opens that default board directly from both the Tasks and Boards surfaces unless the user disables default task-board navigation in mobile Settings. The web settings dialog exposes the same preference for the Boards page, keeping the board picker available for users who prefer the previous flow. The Tasks board header also exposes a global create action. It lists only workspaces where the caller has `manage_projects`, including workspaces that do not yet contain a board, and opens the newly created board immediately. In the Tasks settings dialog, each workspace can store a per-user `TASK_DEFAULT_BOARD_ID`. The Tasks root/proxy entrypoint validates that saved ID against active accessible boards before redirecting and falls back to the first active board when the preference is empty or stale. #### Task list status semantics Task list `status` is a workflow category, not the list display name. The `review` status sits between `active` and `done`: moving a task into a review list resolves the task for deadline/reminder filtering, but it must not set `completed`, `completed_at`, or `closed_at`. Review tasks should keep the same unchecked checkbox and non-completed visual treatment used by active tasks. Review lists are for walkthrough or acceptance queues. Task cards in `review`, `done`, or `closed` lists should not show due-date or overdue treatment because those tasks are already resolved for deadline purposes. Mobile list mode still shows `review` lists by default; only `documents`, `done`, and `closed` are hidden when no explicit list or status filter is selected. #### Task description realtime Task descriptions use a Yjs CRDT document stored in `tasks.description_yjs_state`. Once that state exists, treat it as the authoritative collaborative source. The JSON `tasks.description` field is the read/search/cache projection and must not overwrite a valid Yjs state just because it differs; board caches and recently opened dialogs can hold stale description JSON while another collaborator has newer Yjs edits. Initialization or repair writes that seed the local Yjs document from persisted state must use the provider sync origin so those changes are not broadcast as fresh user edits. Persistence should serialize the description projection from the Yjs update being saved, keeping `description` and `description_yjs_state` from diverging under multi-user edit churn. Focused and fullscreen task dialogs in the shared Tasks UI show a title, details and description skeleton while the task and durable description hydrate. The editor stays mounted once its final task binding exists; settling hides its contents without recreating the Yjs binding or discarding local edits. Short descriptions use a bounded minimum editing area rather than a viewport-sized blank region. Compact creation and readonly shared views retain their existing presentation. Tracked description recovery reconciles equivalent content through the active editor schema, including editor-filled defaults and JSON key ordering. It also recognizes a tracked version that matches both the saved current description and the initial hydrated editor baseline, or a successful save from the same dialog opening, so unsaved edits do not create a recovery prompt for that same version. This changes recovery metadata only: it never writes history into the editor or replaces a valid collaborative document. Genuine differences in text, formatting, media, mentions or unsupported attributes remain available for explicit comparison and restore. Pre-clear history remains recoverable. Regression coverage lives in `description-reconciliation.test.ts` and `task-dialog-loading-shell.test.tsx`. The `ttr` CLI uses the same description endpoint and TipTap/Yjs codec as the web editor. Prefer first-class description commands over raw task update payloads: ```bash theme={null} ttr tasks description get ttr tasks description set --file notes.md --format markdown ttr tasks description append --text "Follow-up note" ttr tasks description edit ``` For local conversion or debugging, use the login-free codec commands: ```bash theme={null} ttr tiptap parse --input notes.md --format markdown --output json ttr tiptap encode --input description.json --format json --output yjs-base64 ttr tiptap decode --input state.txt --format yjs-base64 --output text ``` #### Task templates Task templates are reusable single-task starters and are intentionally separate from board templates. Store workspace templates in `task_templates` with creator ownership, `private` or `workspace` visibility, archived timestamps, default board/list ids, priority, dates, estimate, labels, assignees, projects, and optional TipTap/Yjs description state. Template API routes live under `/api/v1/workspaces/{wsId}/task-templates`. They must accept authenticated workspace members and `tasks` app-session JWTs from `ttr`, reject direct task-board guests, and keep private templates readable only by their creator. Workspace-visible template mutation should follow the task/project management permission used by task-board management flows; private template mutation stays scoped to the member owner. The web templates hub at `/{locale}/{wsId}/tasks/templates` should default to the Task Templates tab while preserving Board Templates as the secondary tab and keeping existing board-template detail links stable. The CLI supports both workspace-stored and local markdown templates: ```bash theme={null} ttr task-templates list --no-update-check ttr task-templates create "Bug report" --key bug-report --title "Investigate bug" ttr task-templates export bug-report --file .tuturuuu/task-templates/bug-report.md ttr task-templates import .tuturuuu/task-templates/bug-report.md ttr tasks create --template bug-report --list --name "Investigate checkout bug" ``` Local files under `.tuturuuu/task-templates/*.md` use YAML frontmatter for template fields and the markdown body as the task description. Explicit `ttr tasks create` flags must override template defaults so users can reuse a starter without losing the current task context. #### Mobile board caching The mobile task-board flow restores workspace boards, board metadata, and per-list task pages from `CacheStore` before network revalidation. Board detail pages prefetch the first three lists on open and the focused Kanban list plus the next two lists on horizontal page changes, so column swipes should not wait for one on-demand request at a time. Cached task-page payloads must preserve the display metadata used by cards, including assignees, labels, projects, and relationship summaries. The mobile board List tab hides tasks in `done` and `closed` lists by default. Explicit status filters or list filters are treated as user intent and can show those terminal lists again. Mobile task details open description in a read-first fullscreen surface. Keep that surface borderless and height-bounded under the task title, with editing entered only from the edit FAB and save actions kept inside the editor chrome. Task create/update API routes silently drop assignee ids that no longer belong to the workspace. This lets stale task assignments be cleaned up during the next save instead of blocking unrelated edits such as description updates. #### Timeline board view The task board Timeline is task-first: `TimelineBoard` keeps its public props stable for board and project views, while the internal model renders one scheduled task per readable row grouped by task list. Task titles and source metadata belong in the sticky left column; timeline bars should communicate the date range only, so narrow zoom levels never hide task names behind clipped bar labels. Keep drag, resize, schedule-from-unscheduled, edit, delete, and context-menu actions routed through the same board mutation path used by the other views. The row model must preserve personal and external task metadata and keep unknown-list tasks grouped under the virtual unknown-list section instead of dropping them from the schedule. #### Personal external tasks Personal task boards can reference tasks from other workspaces without cloning or moving the source task. Assigned tasks from accessible source workspaces appear by default in a virtual `External tasks` lane on each personal board. Explicit personal-board placements can also reference tasks from another board inside the same personal workspace; those cards are external to the destination board even though the source workspace is personal. Native tasks from the same personal board must still move through the normal workspace task route instead of the personal-placement route. The tasks API may use the server-side admin client to hydrate candidate source tasks, but it must filter those rows through the current user's source `workspace_members` rows with `type = 'MEMBER'` before returning personal default or placed external cards. A guest row in the source workspace is not enough to reveal task data through the personal board. The virtual lane is presentation-only: it has no `task_lists` row, no list actions, no create-task form, no list reordering, and can be collapsed per board when the user wants to focus on planned lists. Personal boards default the lane to collapsed when the board has no assigned external task references; once assigned external tasks exist, the lane opens by default unless the user has saved an explicit collapsed or expanded preference for that board. By default the external lane shows only open source tasks from normal task lists. Source tasks in `documents`, `review`, `done`, or `closed` lists are filtered out unless the lane-level compact filters explicitly include resolved tasks. Lane sorting is also local to the external lane, so changing it does not reorder the user's real personal lists. External task cards should show the source workspace and the source board's ticket identifier. Opening an external task must resolve the task by id through the current-user task route so the dialog receives the source workspace, source board, and source lists instead of the personal board context. Per-user placement lives on `task_user_overrides` with `personal_board_id`, `personal_list_id`, `personal_sort_key`, `personal_added_at`, and `personal_placed_at`. Placement writes must go through `upsert_personal_task_placement`. Drag clients should pass the previous and next visible task ids when available, and the RPC uses `calculate_personal_task_placement_sort_key` to compute a sort key against the combined personal list of native personal tasks and placed external task references. Per-list task loading for personal boards must include the personal `boardId` alongside `listId`; the API needs both values to load placed external references for real personal lists and to keep already-placed external tasks out of the virtual external lane. Optimistic personal-placement moves must keep a fresh `_localMutationAt` marker after the placement API response is merged. Loaded-list revalidation may still return a pre-move page briefly, and the marker prevents that stale response from evicting the placed external task until the server view catches up. Optimistic placement writes should upsert the task into both the progressive board task cache and any full-board cache that is already mounted, because stale list reloads can briefly remove the card before the destination list refetches. The card renderer should hide only the active pre-drop drag source; once a placement mutation is optimistic, the real destination card must stay visible even if the sortable layer still reports that task id as dragging. Native task reorders and external personal-placement moves should both stamp a fresh `_localMutationAt` marker on optimistic writes and on the server-confirmed cache merge. Progressive list loading treats that marker as authority for movement fields such as `list_id`, `sort_key`, `personal_list_id`, and `personal_sort_key`, which prevents stale list pages from flashing a card back to its previous position while the mutation response is still settling. Personal-board list badges must use exact `includeCount` responses, not a page-size estimate from progressive loading. External reference counts should be resolved through `get_personal_task_board_external_counts` so placed external tasks, default external-lane tasks, source-workspace access, and external-lane filters stay aligned with the records the board can actually show. Board source filters use `TaskFilters.sourceScope` to decide which task source set is visible. `all_visible` preserves the existing board behavior, `current_board` returns only tasks from the active board, and the two external scopes return assigned-to-me tasks whose source board is not the active board. `external_current_workspace` stays inside the current workspace, while `external_specific` requires selected source workspace ids or source board ids; when nothing is selected, the client should show an empty prompt instead of running an unbounded external query. Source-filtered list and timeline reads must go through the tasks API route, which normalizes the route workspace, verifies request-scoped membership, then uses the server-side Supabase admin client to call the `private.list_task_source_filter_ids` RPC. The RPC rechecks target workspace membership and source workspace access before returning paginated task ids plus `total_count` for API-side hydration. Client UI must not call the private RPC directly or trust client-provided source ids as authorization. * `personal_board_id` points to the destination personal board after an external task is planned there. * `personal_list_id` points to the real personal list that owns the planning position. * Dragging from the virtual lane into a real personal list creates or updates the personal placement. * Dragging a placed external task back to the virtual lane removes the personal placement so the task returns to the default external view. * Personal-only label and project overlays live in `task_user_override_labels` and `task_user_override_projects`. Those rows reference labels/projects owned by the user's personal workspace and are loaded only for that owner. Source task fields, including `tasks.list_id`, `task_labels`, and `task_project_tasks`, must not be changed when a task appears in the external lane, is planned into a personal list, is moved within the personal board, or returns to the external lane unless the personal move changes the task's workflow status. Routes that read personal board tasks should keep filtering inaccessible source tasks out instead of surfacing stale placements to users who no longer have source-workspace access. When a placed external task moves to a personal list with a different workflow status, the source task must also move to the first matching list on its original board. `done` and `closed` targets require the matching terminal source list. Non-terminal targets first try the same source status, then fall back to `active` and `not_started` lists so tasks moved out of source `done` or `closed` queues do not keep completed or closed card state. ```sql theme={null} CREATE TABLE workspace_boards ( id uuid PRIMARY KEY DEFAULT gen_random_uuid(), ws_id text REFERENCES workspaces(id) ON DELETE CASCADE, name text NOT NULL, description text, created_at timestamptz DEFAULT now() ); ``` **Usage:** ```typescript theme={null} "use server"; import { createClient } from "@tuturuuu/supabase/next/server"; export async function createBoard(wsId: string, name: string) { const supabase = await createClient(); const { data: board, error } = await supabase .from("workspace_boards") .insert({ ws_id: wsId, name, }) .select() .single(); if (error) throw error; // Create default lists const defaultLists = ["To Do", "In Progress", "Done"]; await supabase.from("task_lists").insert( defaultLists.map((listName, index) => ({ board_id: board.id, name: listName, position: index, })), ); return board; } ``` ### 5. Task Lists Columns within boards (e.g., "To Do", "In Progress", "Done"). Task boards may contain multiple `closed` lists when teams need distinct terminal buckets such as `Abandoned`, `Not Planned`, or `Duplicate`. Treat `closed` as a status group for sorting/reporting, not a singleton board column. **Access rule:** direct task-table access is server-owned; request-scoped clients have no task read or write grants. Authorized routes verify the actor, workspace membership or share before using the admin client. Task-list RLS requires a `workspace_members` row in the board's workspace. Task RLS adds a defence-in-depth fence: list-bound tasks require list visibility, and list-less tasks require the actor to match `creator_id`. The calendar scheduling route `POST /api/{wsId}/task/create` creates list-less tasks. Board shares, task shares and public share links do not grant direct list or task access. Regression coverage: `apps/database/supabase/tests/security-definer-function-grants.sql`. ```sql theme={null} CREATE TABLE task_lists ( id text PRIMARY KEY, board_id uuid REFERENCES workspace_boards(id) ON DELETE CASCADE, name text NOT NULL, position integer NOT NULL, created_at timestamptz DEFAULT now() ); ``` **Usage:** ```typescript theme={null} "use server"; import { createClient } from "@tuturuuu/supabase/next/server"; export async function reorderLists(boardId: string, listIds: string[]) { const supabase = await createClient(); // Update positions based on array order const updates = listIds.map((listId, index) => ({ id: listId, position: index, })); for (const update of updates) { await supabase .from("task_lists") .update({ position: update.position }) .eq("id", update.id); } } ``` ### 6. Workspace Tasks Individual work items. Task titles support up to `1024` characters. Keep task-only validation on the dedicated task-title limit rather than the generic `name` limit so task routes, drafts, and database checks stay aligned. ```sql theme={null} CREATE TABLE workspace_tasks ( id text PRIMARY KEY, ws_id text REFERENCES workspaces(id) ON DELETE CASCADE, list_id text REFERENCES task_lists(id) ON DELETE SET NULL, name text NOT NULL, description text, priority integer CHECK (priority BETWEEN 0 AND 5), completed boolean DEFAULT false, start_date date, due_date date, created_by uuid REFERENCES workspace_users(id), created_at timestamptz DEFAULT now(), updated_at timestamptz DEFAULT now() ); ``` ## Bucket Dump Feature Rapidly capture thoughts as notes, then convert to tasks or projects. ### Notes Table ```sql theme={null} CREATE TABLE notes ( id uuid PRIMARY KEY DEFAULT gen_random_uuid(), ws_id text REFERENCES workspaces(id) ON DELETE CASCADE, title text NOT NULL, content text, created_by uuid REFERENCES workspace_users(id), created_at timestamptz DEFAULT now() ); ``` ### Convert Note to Task ```typescript theme={null} "use server"; import { createClient } from "@tuturuuu/supabase/next/server"; export async function convertNoteToTask(data: { noteId: string; listId: string; priority?: number; }) { const supabase = await createClient(); // Get note const { data: note } = await supabase .from("notes") .select("*") .eq("id", data.noteId) .single(); if (!note) throw new Error("Note not found"); // Create task from note const { data: task, error } = await supabase .from("workspace_tasks") .insert({ ws_id: note.ws_id, list_id: data.listId, name: note.title, description: note.content, priority: data.priority, created_by: note.created_by, }) .select() .single(); if (error) throw error; // Optionally delete note await supabase.from("notes").delete().eq("id", data.noteId); return task; } ``` ### Convert Note to Project ```typescript theme={null} "use server"; import { createClient } from "@tuturuuu/supabase/next/server"; export async function convertNoteToProject(data: { noteId: string; initiativeId?: string; }) { const supabase = await createClient(); const { data: note } = await supabase .from("notes") .select("*") .eq("id", data.noteId) .single(); if (!note) throw new Error("Note not found"); // Create project from note const { data: project, error } = await supabase .from("task_projects") .insert({ ws_id: note.ws_id, name: note.title, description: note.content, }) .select() .single(); if (error) throw error; // Link to initiative if provided if (data.initiativeId) { await supabase.from("task_project_initiatives").insert({ project_id: project.id, initiative_id: data.initiativeId, }); } // Delete note await supabase.from("notes").delete().eq("id", data.noteId); return project; } ``` ## Task Cycles (Sprints) ```sql theme={null} CREATE TABLE task_cycles ( id text PRIMARY KEY, ws_id text REFERENCES workspaces(id) ON DELETE CASCADE, name text NOT NULL, start_date date NOT NULL, end_date date NOT NULL, created_at timestamptz DEFAULT now() ); -- Link tasks to cycles ALTER TABLE workspace_tasks ADD COLUMN cycle_id text REFERENCES task_cycles(id) ON DELETE SET NULL; ``` **Usage:** ```typescript theme={null} "use server"; import { createClient } from "@tuturuuu/supabase/next/server"; export async function createCycle(data: { wsId: string; name: string; startDate: Date; endDate: Date; }) { const supabase = await createClient(); const { data: cycle, error } = await supabase .from("task_cycles") .insert({ ws_id: data.wsId, name: data.name, start_date: data.startDate.toISOString().split("T")[0], end_date: data.endDate.toISOString().split("T")[0], }) .select() .single(); if (error) throw error; return cycle; } export async function getActiveCycle(wsId: string) { const supabase = await createClient(); const today = new Date().toISOString().split("T")[0]; const { data: cycle } = await supabase .from("task_cycles") .select("*") .eq("ws_id", wsId) .lte("start_date", today) .gte("end_date", today) .single(); return cycle; } ``` ## Task Estimation ```sql theme={null} CREATE TABLE task_estimates ( task_id text PRIMARY KEY REFERENCES workspace_tasks(id) ON DELETE CASCADE, type text NOT NULL, -- fibonacci, exponential, linear, tshirt value numeric NOT NULL, created_at timestamptz DEFAULT now() ); ``` **Estimation Types:** * **Fibonacci**: 1, 2, 3, 5, 8, 13, 21 * **Exponential**: 1, 2, 4, 8, 16, 32 * **Linear**: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 * **T-Shirt**: XS (1), S (2), M (3), L (5), XL (8), XXL (13) ```typescript theme={null} "use server"; import { createClient } from "@tuturuuu/supabase/next/server"; export async function estimateTask( taskId: string, estimationType: "fibonacci" | "exponential" | "linear" | "tshirt", value: number, ) { const supabase = await createClient(); const { error } = await supabase.from("task_estimates").upsert({ task_id: taskId, type: estimationType, value, }); if (error) throw error; } ``` ## Task Labels ```sql theme={null} CREATE TABLE task_labels ( id text PRIMARY KEY, ws_id text REFERENCES workspaces(id) ON DELETE CASCADE, name text NOT NULL, color text, created_at timestamptz DEFAULT now() ); -- Link tasks to labels (many-to-many) CREATE TABLE task_label_assignments ( task_id text REFERENCES workspace_tasks(id) ON DELETE CASCADE, label_id text REFERENCES task_labels(id) ON DELETE CASCADE, PRIMARY KEY (task_id, label_id) ); ``` **Usage:** ```typescript theme={null} "use server"; import { createClient } from "@tuturuuu/supabase/next/server"; export async function createLabel(wsId: string, name: string, color: string) { const supabase = await createClient(); const { data: label, error } = await supabase .from("task_labels") .insert({ ws_id: wsId, name, color }) .select() .single(); if (error) throw error; return label; } export async function assignLabel(taskId: string, labelId: string) { const supabase = await createClient(); const { error } = await supabase .from("task_label_assignments") .insert({ task_id: taskId, label_id: labelId }); if (error) throw error; } ``` ## Custom Task Statuses ```sql theme={null} CREATE TABLE task_statuses ( id text PRIMARY KEY, board_id uuid REFERENCES workspace_boards(id) ON DELETE CASCADE, name text NOT NULL, color text, position integer NOT NULL, is_completed boolean DEFAULT false, created_at timestamptz DEFAULT now() ); -- Link tasks to statuses ALTER TABLE workspace_tasks ADD COLUMN status_id text REFERENCES task_statuses(id) ON DELETE SET NULL; ``` **Usage:** ```typescript theme={null} "use server"; import { createClient } from "@tuturuuu/supabase/next/server"; export async function createBoardWithStatuses(wsId: string, boardName: string) { const supabase = await createClient(); // Create board const { data: board } = await supabase .from("workspace_boards") .insert({ ws_id: wsId, name: boardName }) .select() .single(); if (!board) throw new Error("Failed to create board"); // Create default statuses const statuses = [ { name: "Backlog", color: "#gray", position: 0, is_completed: false }, { name: "To Do", color: "#blue", position: 1, is_completed: false }, { name: "In Progress", color: "#yellow", position: 2, is_completed: false }, { name: "Review", color: "#purple", position: 3, is_completed: false }, { name: "Done", color: "#green", position: 4, is_completed: true }, ]; await supabase.from("task_statuses").insert( statuses.map((status) => ({ board_id: board.id, ...status, })), ); return board; } ``` ## Task Dependencies Track task relationships and blockers. ```sql theme={null} CREATE TABLE task_dependencies ( task_id text REFERENCES workspace_tasks(id) ON DELETE CASCADE, depends_on_task_id text REFERENCES workspace_tasks(id) ON DELETE CASCADE, PRIMARY KEY (task_id, depends_on_task_id), CHECK (task_id != depends_on_task_id) ); ``` **Usage:** ```typescript theme={null} "use server"; import { createClient } from "@tuturuuu/supabase/next/server"; export async function addDependency(taskId: string, dependsOnTaskId: string) { const supabase = await createClient(); const { error } = await supabase.from("task_dependencies").insert({ task_id: taskId, depends_on_task_id: dependsOnTaskId, }); if (error) throw error; } export async function getBlockedTasks(wsId: string) { const supabase = await createClient(); const { data: tasks } = await supabase .from("workspace_tasks") .select( ` *, task_dependencies!task_id ( depends_on:workspace_tasks!depends_on_task_id ( id, name, completed ) ) `, ) .eq("ws_id", wsId) .eq("completed", false); // Filter tasks with incomplete dependencies return tasks?.filter((task) => task.task_dependencies.some((dep: any) => !dep.depends_on.completed), ); } ``` ## User Interface Components ### Board View ```tsx theme={null} "use client"; import { trpc } from "@/trpc/client"; import { DragDropContext, Droppable, Draggable } from "@hello-pangea/dnd"; export function BoardView({ wsId, boardId, }: { wsId: string; boardId: string; }) { const { data: lists } = trpc.boards.lists.useQuery({ boardId }); const moveTask = trpc.tasks.move.useMutation(); function handleDragEnd(result: any) { if (!result.destination) return; moveTask.mutate({ taskId: result.draggableId, listId: result.destination.droppableId, position: result.destination.index, }); } return (

{lists?.map((list) => ( {(provided) => (

{list.name}

{/* Task cards */} {provided.placeholder}

)} ))}

); } ``` ## Best Practices ### ✅ DO 1. **Use hierarchy appropriately** ```typescript theme={null} // Strategic: Initiative // Tactical: Project // Operational: Board → List → Task ``` 2. **Leverage bucket dump** ```typescript theme={null} // Capture quickly, organize later await createNote({ title, content }); ``` 3. **Set task estimates** ```typescript theme={null} await estimateTask(taskId, "fibonacci", 8); ``` 4. **Use labels for categorization** ```typescript theme={null} await assignLabel(taskId, "bug"); await assignLabel(taskId, "high-priority"); ``` 5. **Track dependencies** ```typescript theme={null} await addDependency(taskId, blockerTaskId); ``` ### ❌ DON'T 1. **Don't create deep hierarchies** ```typescript theme={null} // ❌ Bad: Too many nested levels ``` 2. **Don't skip workspace isolation** ```typescript theme={null} // ❌ Bad .eq('id', taskId) // ✅ Good .eq('id', taskId).eq('ws_id', wsId) ``` ## Related Documentation * [Database Schema](/reference/database/schema-overview) * [Data Fetching](/platform/architecture/data-fetching) * [Authorization](/platform/architecture/authorization) ## Returning to a Tasks tab Board views in Tasks and the platform keep cached cards visible while refreshing the loaded pages and board/list metadata on browser focus, visibility restoration, back/forward restoration, or reconnect. Paired wake events are coalesced for one second; a later tab visit refreshes again instead of waiting five minutes. This is scoped to the mounted board and preserves accumulated pagination and local edits. My Tasks uses its separate 30-second TanStack Query freshness policy; unrelated satellite queries retain their defaults. Regression coverage lives in `packages/tasks-ui/src/tu-do/shared/__tests__/board-client.test.tsx` and `use-progressive-board-loader-resume.test.tsx`. ## Durable description hydration and realtime availability All Tasks description editors load the authorized saved Yjs document independently of the peer channel connection. A realtime outage must not hide an otherwise readable saved description. The description stays read-only until both durable hydration and the channel connection succeed; the reconnecting indicator remains visible. Rejected durable reads do not count as an empty document and do not permit initialization writes. Initialization of missing legacy Yjs state remains connection-gated and ignores late results after the dialog or resource changes. Regression coverage: `packages/ui/src/hooks/__tests__/supabase-provider.test.ts` and `packages/tasks-ui/src/tu-do/shared/task-edit-dialog/hooks/__tests__/use-task-yjs-sync.test.ts`. When a production channel request returns an HTML 404, verify the deployed Web source SHA and first-class `/api/v1/realtime/channels` route before changing channel permissions. A green branch or a production sync receipt alone does not prove that the live API deployment contains that route. ## Authorized board hydration Tasks and the shared web board reuse the board metadata already authorized by the server for the current request. The client validates both board and workspace IDs before using that snapshot, so controls and list structure can appear without a second metadata round trip. The snapshot is fresh for 30 seconds; explicit refresh, realtime updates, and returning to a visible tab still revalidate it. Existing loaded cards remain visible while those requests finish. Cached data does not replace server membership or board-access checks. Regression evidence: `board-client.test.tsx` covers immediate authorized metadata, rejection of mismatched snapshots, and focus revalidation. Production timing must be measured after deployment; focused tests do not prove network performance. ## Request-scoped workspace reads Tasks and Calendar dashboard authorization use `getRequestWorkspace` to coalesce identical workspace reads within one server render. The key includes workspace, actor ID, actor email, and admin mode. This is React request memoization, not a persistent authorization cache: separate requests resolve workspace access again. Calendar's layout and page share this reader; shared Meet context retains its existing memoization. The wrapper's actor/mode isolation regression tests live in `packages/utils/src/__tests__/request-workspace.test.ts`. This reduces repeated server reads; it does not replace app build checks or production load measurements. ## Create tasks with a private creative reference `/{wsId}/tasks/new` provides an explicit composer with a task name and board/list selection. Opening this route performs no task or board creation. It requires a Tasks app session and joined workspace; task creation retains the canonical API's destination authorization. A permission failure preserves the entered form. Mutation retries are disabled so this workflow does not automatically repeat a creation request. A Lettin studio handoff includes only source IDs and remains in the same workspace. An unchecked source-reference control lets the creator deliberately attach a canonical private notebook link to the task description. The form states the board visibility and source access boundaries before submission. It never reads source content or changes source permissions/publication. Invalid source IDs return not found, and no caller-provided URL is persisted. Creators can also use the composer without any source reference. See [Lettin](/platform/features/lettin) for the product decision and regression evidence. Focused composer validation can run without workspace builds: ```sh theme={null} bunx vitest run --config apps/tasks/vitest.config.mts \ apps/tasks/src/components/task-plan-composer.test.tsx \ 'apps/tasks/src/app/[locale]/(dashboard)/[wsId]/tasks/new/page.test.tsx' \ packages/utils/src/__tests__/lettin-task-reference.test.ts --maxWorkers 1 ``` The Tasks Vitest configuration lowers JSX with the automatic runtime and resolves its root internal API import to source. A preserved JSX transform otherwise fails Vite import analysis before mounted tests run. Other local suites may still need source aliases for unbuilt dependency subpaths; record those failures separately and use exact-head CI for application builds. Task planning keeps each creation form single-use after submission. If the response cannot confirm creation, the form stays preserved and locked, with a link to the selected board. Check that board before starting another task: the server may have inserted it even when the response failed. This guard does not provide server-side idempotency across new forms or page reloads. ## Explicit task planning priority The Tasks `/{wsId}/tasks/new` composer, including the Lettin handoff, offers an optional priority choice: critical, high, normal, or low. It starts with no priority and omits the API field until the creator chooses one. Clearing a choice omits it again. No notebook content or metadata determines priority. Failed creation preserves the choice in the locked single-use form; mutation retries stay disabled. Check the selected board before starting another form. Source-reference sharing remains unchecked and independently consented, and the destination API retains workspace and task authorization. Regression coverage in `apps/tasks/src/components/task-plan-composer.test.tsx` checks each API priority, clearing, preserved choices after failed creation, and unchanged source consent. The composer fixtures render choices from both English and Vietnamese message bundles. Exact-head Tasks build and repository CI remain separate delivery gates. ## Explicit destination project association Tasks planning, including the Lettin handoff, can associate the new task with one existing destination workspace project. This control starts unchecked. Project choices are loaded through the canonical authenticated internal API only after opt-in, and the creator must select a currently available project. Opening the composer never creates a project, task, or source reference. No notebook content or metadata determines the project; source-link consent remains independent. Pending or failed project reads and a selection removed by refreshed choices block submission with association enabled. The creator can retry the read or uncheck association to continue without a project. Failed task creation preserves the project choice in the locked single-use form. Check the selected board before starting another form; neither read nor creation failures trigger automatic retries. The canonical task API revalidates workspace project ownership and destination task authorization at submission. Existing project and board access rules apply; notebook grants and publication never change. `apps/tasks/src/components/task-plan-composer.test.tsx` covers opt-in-only reads, required current selection, ID-only creation payloads, opt-out, unavailable and removed projects, denial preservation, and both language bundles. These fixtures double the internal API and translation hook; exact-head app builds and API CI remain separate delivery evidence. ## Authored task planning notes The Tasks `/{wsId}/tasks/new` composer, including the Lettin handoff, starts with empty optional planning notes. Creators may enter up to 2,000 characters for the chosen destination task. Notes are visible under the destination task's existing permissions. The composer saves only this authored text as literal rich-document paragraphs; line breaks are retained and markup is treated as text. It does not read or prefill notebook text, artwork or profile data. Notebook-link sharing remains independently off by default, and project association requires its own explicit selection. An opted-in source link is appended as a separate paragraph; unchecking it removes only the link. Empty or whitespace-only notes add no description unless a source link is selected. Changing the destination board preserves the authored plan while requiring a new list choice. Creation still requires explicit submission and current destination permissions. An unconfirmed response retains the form and notes in the existing locked recovery state, preventing an automatic retry or duplicate create. Closing the composer discards these local notes; they are not a durable draft. Regression coverage: `task-plan-description.test.ts` exercises literal text, line breaks, independent link composition and serialized size bounds; `task-plan-composer.test.tsx` covers empty defaults, both shipped languages, optional notes without source/project sharing, source removal, oversized input rejection and uncertain creation recovery. Hosted task creation and the exact-head Tasks build remain separate delivery gates. ## Provider meeting commitments in task previews Task scheduling previews in Tasks, Calendar and Web preserve future Google and Microsoft calendar commitments even when the local event copy is unlocked. The rule recognizes current provider/source IDs and legacy Google event IDs. Native future task slots remain replaceable; locked, in-progress and retained habit slots remain blocked. Preview-only copies are excluded. Provider meetings must not become free time merely because they are not native locked tasks. The shared decision lives in `calendar-preview-blocked.ts`; its unit tests and `unified-scheduler/provider-commitments.test.ts` in all three apps cover the preview integration. This does not add Google Tasks or Microsoft To Do sync. # Teach teacher companion app Source: https://docs.tuturuuu.com/platform/applications/teach Teacher-facing education companion app for Tuturuuu workspaces. Teach lives in `apps/teach` and runs locally on port `7813`. It is the teacher-facing operations app for Tuturuuu education workspaces. Teachers create and publish courses, enroll existing workspace users, author modules, save attendance, write posts and reports, and enter metrics through Teach-owned APIs. Unmatched `/api/workspaces/*` requests, including workspace invitations and workspace details, use the Web fallback with their paths and queries intact. Local Teach API handlers retain precedence. Regression coverage lives in `apps/teach/src/next-config.test.ts`. ## Ownership model Teach owns teacher authoring, administration, and shared education v1 API contracts. Its handlers cover courses, modules, quiz sets, flashcards, enrollment, attendance, posts, reports, metrics, attempts, grading, and related teacher workflows under `apps/teach/src/app/api/v1`. Teach also implements selected education AI handlers locally. Local handlers run before the Next.js fallback rewrites. Only unmatched `/api/*` paths go to Web, which remains responsible for platform login, cross-app token issuance, and explicitly retained platform or central AI services. New Teach-owned flows should add typed helpers in `@tuturuuu/internal-api` and consume those helpers from Teach client components with TanStack Query. `packages/education-core` owns reusable server-only domain logic, not HTTP traffic. `packages/internal-api/src/teach.ts` and `education.ts` select the Teach origin for teacher and shared education contracts; explicit platform exceptions such as storage operations retain the Web origin. When a Teach route uses an admin client to write rows keyed by request-body IDs, the route must validate those body IDs against the URL workspace and course before writing. Workspace permission plus course existence is not enough, because the admin client bypasses RLS; score writes such as `indicator_id` and `user_id` must prove that the indicator belongs to the URL course/workspace and the user is an active course member in the same workspace. Courses are stored as `workspace_user_groups`. The course-level Learn visibility switch is `workspace_user_groups.is_course_published`; module visibility remains `workspace_course_modules.is_published`. New courses default to unpublished drafts, non-guest, active, and empty. Teach can enroll existing workspace users into a course, but this self-serve pass does not create or invite new users. Teach-owned attendance uses the course schedule fields on `workspace_user_groups`: `sessions`, `starting_date`, and `ending_date`. Teachers can generate recurring class sessions inside Teach, and the attendance calendar should mark unscheduled days, scheduled unchecked days, partial days, complete days, late days, and absent days without linking back to the web user-group schedule page. Teach-local logout clears the host-only app-session cookies and stale Supabase Auth cookies on `teach.tuturuuu.*`, then redirects browser form submissions to the central `apps/web` `/logout?from=Teach` continuation. JSON callers can still POST `/api/auth/logout` and receive `{ success: true }`. Teach does not render its own login portal. Its `/login` route first checks for an existing Teach app-session JWT. If the app session is already present, it redirects inside Teach to the requested `next` path, usually `/dashboard`. Otherwise it redirects to the platform login at `apps/web` with a `returnUrl` pointing back to `/verify-token`. After the platform login confirms the account, `apps/web` generates a cross-app token for the `teach` target app and redirects back. Teach's local `POST /api/auth/verify-app-token` route only completes the host-only cookie handoff; token validation is delegated back to the central web app, and Teach does not create a Teach-local Supabase Auth session. The handoff stores a Teach-local app-session cookie for satellite route guards and shared session material used when a retained platform service must be called. If older session material cannot be refreshed, Teach sends the user back through the platform handoff so the coordinated cookies are renewed without manual deletion. The `/dashboard` entry route must only send users to `/login` when the Teach app-session is missing. If the app-session exists but the Teach bootstrap API returns no eligible education workspace, render an empty teacher state instead of redirecting back to login. Learn follows the same platform-login pattern: the learner app keeps `/verify-token` for cross-app session completion, but `/login` delegates account selection to `apps/web`. Teach and Learn both hide locale prefixes from public and protected URLs. Legacy locale-prefixed paths such as `/vi/dashboard` redirect to the unprefixed canonical path while preserving the selected locale in `NEXT_LOCALE`. Teach proxy locale detection must sanitize `Accept-Language` before it reaches `intl-localematcher`. Wildcard or malformed locale tokens can throw a `RangeError` in the proxy and surface as a broken `/login` or protected course page even when the route itself still exists. Teach metadata and auth return URLs must resolve to absolute HTTP(S) app URLs. Prefer `TEACH_APP_URL` or `NEXT_PUBLIC_TEACH_APP_URL` for the Teach origin and `LEARN_APP_URL` or `NEXT_PUBLIC_LEARN_APP_URL` for Learn handoffs. A valid absolute `BASE_URL` can be used as a fallback for Teach, but non-URL environment values such as `development` are ignored so local development falls back to `https://teach.tuturuuu.localhost` through Portless. ## Visual direction All non-`apps/web` education apps use the shared Neobrutalist design language from `apps/learn/DESIGN.md`: heavy foreground borders, offset shadows, paper-like surfaces, compact responsive grids, and theme-adaptive dynamic accents. Teach uses this language for public teacher orientation surfaces and protected dashboards. Teach should read as a teacher operations dashboard, not a landing page. The protected surface should keep courses, module authoring, learner enrollment, schedule-aware attendance, posts, report previews, score metrics, settings, and learner-preview handoffs visible as first-class paths. Use multiple dynamic accent roles across these work loops and keep rails readable in light, dark, and system themes. Teach module generation now accepts optional teacher context in the AI modal. Teachers can add class level, learning goals, or other constraints before uploading source material; the Teach-owned course-generation route passes that context into the AI prompt alongside the document content. Report authoring should include a Teach-local preview before save. The preview should show learner identity, course context, score, report body, feedback, and a metric snapshot so teachers do not need to open `apps/web` report pages for normal course reporting. When a learner-facing check is useful, link intentionally to `apps/learn` course, assignment, report, or marks pages. Teach reads and mutates course groups and module data through its local API handlers. Those routes resolve the Teach app-session actor and verify workspace, course, and resource access before using admin-backed data clients. ## Verification After changing Teach routes, run focused route tests first. Finish Teach API or UI changes with the app typecheck, repository checks, and the owning app build: ```bash theme={null} bun i18n:sort bun type-check:teach bun validate bun run --cwd apps/teach build ``` Run focused route or component tests when login bridging, cross-app token handling, local API authorization, or fallback forwarding changes. ## CI and deployment Teach has dedicated Vercel workflows: * `.github/workflows/vercel-preview-teach.yaml` * `.github/workflows/vercel-production-teach.yaml` Both workflows are registered in `tuturuuu.ts` and use the shared `ci-check.yml` switchboard. They require environment-scoped Vercel credentials plus `VERCEL_TEACH_PROJECT_ID`; production Supabase values should live in the Vercel project environment rather than GitHub Actions. Deployment credentials must stay environment-scoped in GitHub Actions. The preview job is bound to the `vercel-preview-teach` GitHub Environment, and the production job is bound to `vercel-production-teach`. Store `VERCEL_TOKEN`, `VERCEL_ORG_ID`, and `VERCEL_TEACH_PROJECT_ID` in those environments instead of repository-wide or organization-wide secrets. Production Supabase values remain in the Vercel project environment pulled by `vercel pull`. The repository-level `TURBO_TOKEN` and `TURBO_TEAM` variable are passed only to the wrapped `vercel build` step; never place them at workflow or job scope, and never expose the token to pull-request or Dependabot code. Preview dispatch is manual-only. Run `vercel-preview-teach.yaml` from `main`, set `preview_ref` to the reviewed branch, tag, or SHA, and keep `TRUSTED_PREVIEW_DEPLOY_ACTORS` limited to maintainers approved to run secret-backed preview builds. Manual production dispatch is only valid from `refs/heads/production`. ## Personal To do The **To do** sidebar destination (`/{wsId}/todo`) lists this signed-in actor's pending, unresolved tutoring assignments and teaching preparation work. Tutoring is matched by the verified workspace-user's explicit `teacher_user_id`, not by homeroom membership, so tutoring another class works correctly. The teaching categories require actual TEACHER memberships in this workspace's active, non-guest courses. Assignment preparation shows this teacher's own unapproved posts; lesson/test preparation shows unpublished content in the courses assigned to them. It does not label the workspace's whole operations catalog as personal work. Publishing/completing items remains in the existing assigned course views. The same interface and actor cache boundary as Learn apply: category pagination, explicit error/retry states, inherited theme, and no parent-selected subject. Teach's first-class `/api/v1/workspaces/{wsId}/teach/todo` uses verified app-session authentication and private/no-store responses with the shared education loader and internal API transport. These app-owned education routes do not change the live Web API or a Rust-owned migration route. See [Learn personal To do](./learn#personal-to-do) for regression coverage and bounded source-versus-runtime evidence. # Tools Source: https://docs.tuturuuu.com/platform/applications/tools Public QR and random utilities with stable canonical URLs. Tools (`tools.tuturuuu.com`, `apps/tools`) serves public, lightweight web utilities. It uses stable URLs without locale prefixes; language preferences can change copy on the same canonical path. | Tool | Canonical path | Guide | | - | - | - | | Directory | `/` | Tool selection | | QR generator | `/qr` | [QR](/platform/applications/qr) | | Random utilities | `/random` | Options provided by the current random tool UI | The public sitemap lists only these three paths on the Tools host. Old main-site QR aliases redirect to the canonical product destination where configured; they must not be published as duplicate pages with unrelated canonicals. Page-specific metadata names the actual utility. URLs such as `/vi/qr` and `/en/qr` are redirect aliases, not distinct indexed translations. Do not emit hreflang alternates when the app serves only one stable URL per page. The utility input is separate from its public explanatory metadata. Avoid placing user-entered text or private data into canonical URLs, search schemas, or static sitemap entries. Authentication and API paths are excluded by the shared indexing policy. [Tools routes](/reference/repository/routes/tools) and [SEO strategy](/build/development-tools/seo-strategy) describe implementation and public-discovery expectations. # Track Source: https://docs.tuturuuu.com/platform/applications/track Timers, session history, time requests, management, and analytics. Track (`track.tuturuuu.com`, `apps/track`) is the private workspace time-tracking app. Its timer, session history, requests, and management areas share workspace identity and permissions with the platform. | Destination | Route | Use | | - | - | - | | Overview | `/{wsId}` | Review time summaries and the overview timer | | Timer | `/{wsId}/timer` | Work with running time sessions | | History | `/{wsId}/history` | Review and manage recorded sessions | | Requests | `/{wsId}/requests` | Time-entry/request workflow | | Management | `/{wsId}/management` | Permission-gated management workflow | ## A reliable tracking workflow Start the session in the intended workspace, verify the running state, and review the saved session after stopping. History and analytics describe stored records; the live elapsed display is a local presentation of running state. A request or edit can have its own approval/access constraints. An app's summary is not evidence that a pending mutation or offline edit has synchronized. The native timer has additional device behavior documented under [Mobile timer](/platform/features/mobile-timer). Web and mobile share domain concepts, but background execution, offline recovery, and shell navigation are platform-specific. [Calendar](/platform/applications/calendar) scheduling and [Tasks](/platform/applications/tasks) progress remain distinct from recorded actual work time. ## Access and maintenance Track resolves the actor through its app session, then checks workspace access and permissions. Time histories, requests, and management pages are noindex. The public Track description is served by Web's product page. Use the [Track route reference](/reference/repository/routes/track) to locate handlers, and [Data fetching](/platform/architecture/data-fetching) to extend a shared client contract rather than adding app-local raw browser API calls. # Tutoring Source: https://docs.tuturuuu.com/platform/applications/tutoring Schedule make-up and remedial sessions, work the support queue, and enable the module per workspace. Tutoring lives in the Contacts satellite at `/{wsId}/users/tutoring`. It turns two existing signals — attendance deficits and flagged group feedback — into scheduled make-up sessions, then tracks attendance and exports the result for payroll. ## Surfaces * **Schedule** lists every session for a date-range preset (upcoming, today, tomorrow, next 7 days, this month, past, all) and can be narrowed by status, group, learner, teacher, and reason. Filters drive both the table and the export. Forward-looking presets request `sortOrder=asc` so the nearest session is first; `past` and `all` keep the API default of newest-first. * **Needs support** is the queue of learners with an absence deficit within the configured recent attendance window (`ABSENT_RECOVERY`), a `require_attention` feedback (`WEAK_SUPPORT`), or both. Scheduling from a queue row fills the learner, group, reason, and suggested times for the missing sessions. Staff choose the tutoring teacher separately. A pending recovery session reserves one absence, so staff do not schedule the same make-up twice. Feedback already linked to a pending support session does not create another scheduling suggestion. It can still appear as an office-review-only row when its lesson content has remained unchanged for the configured interval. After a completed support session, still-flagged feedback returns for reassessment after the configured interval. Older unscheduled feedback shows a parent follow-up prompt. If flagged feedback keeps the same content across the configured review interval, the queue shows an office-review alert and count. The alert compares consecutive feedback entries for that learner and group; edits made in place to an existing entry have no separate timestamp. * **Settings** stores a workspace tutoring policy with standard and English center presets. Each section starts as a read-only summary; **Edit section** opens only that section with **Save** and **Cancel**. Cancel discards the section draft, and other sections stay read-only while it is open. Saving merges only that section’s fields into the latest loaded policy, preserving refreshed values in other sections. Applying a preset intentionally replaces the full draft. Save, Cancel, and editor inputs are disabled during a pending save; a failed save retains the draft for retry. Operators can adjust session length, lead time, support session count, absence lookback, reassessment and follow-up intervals, scheduling horizon, class-time exceptions, named shifts, scoped group-name exclusion rules, the unchanged-content review interval, group-to-campus labels, and the parent message template. Only members with `manage_workspace_settings` can save it. The English center preset excludes kindergarten group names containing `DDT`, `Mẫu giáo`, or `Kindergarten` from all tutoring suggestions. Existing policies using the earlier unmodified `DDT` preset inherit these rules; custom rules remain as saved. Staff can add other naming patterns used by their workspace. Rule scope (all, make-up, or weak support), name match type, and text are editable; an interval of 0 disables office-review alerts. Older saved English center policies inherit these defaults until staff customize them. * **Headline counts** run as bounded `count: exact` queries, so they stay correct on workspaces with more sessions than one page. The schedule loads first; counts then load behind it. The support queue is requested when its tab is opened, and the client reuses recent results for two minutes. Row actions mark a session done, no-show, cancelled, or back to pending, and generate the parent-facing message for the session. Staff can edit each session's lesson content after creation, so teaching notes from the separate content sheet can be kept with the attendance record. Managers can permanently delete a pending or cancelled session after an in-app confirmation. Completed and no-show sessions stay intact for attendance and payroll history. ## Enablement Tutoring is gated by the `ENABLE_TUTORING` workspace config: | Workspace | `ENABLE_TUTORING` unset | `'true'` | `'false'` | | - | - | - | - | | Shared | Enabled | Enabled | Disabled | | Personal | Disabled | Enabled | Disabled | A disabled workspace renders an enable screen rather than a 404. Members with `manage_workspace_settings` get an **Enable tutoring** button that writes `ENABLE_TUTORING=true` through `PUT /api/v1/workspaces/{wsId}/settings/ENABLE_TUTORING`; everyone else is told to ask an admin. Reading the toggle only needs `view_user_groups`. Tutoring shares this gate with the other Contacts modules — see [Contacts module availability](/platform/applications/contacts-modules) for the full set of toggles and states. > [!NOTE] > > The page previously called `notFound()` for personal workspaces, so the > sidebar link 404'd even though the tutoring APIs normalize `personal` into a > real workspace id. Personal workspaces now opt in explicitly instead. ## Permissions * `view_user_groups` — open tutoring and read sessions, the queue, and exports. * `update_user_groups_scores` — schedule, edit, and delete eligible sessions, mark attendance, and generate parent messages. * `manage_workspace_settings` — enable or disable the module and edit tutoring rules. Three non-404 states replace the old blanket 404 so an operator can tell the cases apart: | State | Cause | Recovery | | - | - | - | | Disabled | `ENABLE_TUTORING` is off for this workspace | Enable it, or ask an admin | | No access | Caller lacks `view_user_groups` | Ask an admin for the permission | | Unavailable | Workspace or `workspace_user_linked_users` profile unresolved | Refresh; if it persists, re-invite the member | ## Scheduling rules One create request can carry up to 50 slots. Overlaps are rejected twice: in the form (the offending rows are highlighted before submit) and again in `POST /api/v1/workspaces/{wsId}/tutoring/sessions` against both the other incoming slots and the sessions already stored. A teacher conflict needs the same teacher on both slots; a learner conflict needs only the same learner. The class managers are displayed as **Homeroom teacher** for context. The **Tutoring teacher** is chosen separately for every slot from a paginated, searchable catalog of verified teacher memberships anywhere in the same center (workspace). Changing the learner’s class does not erase a selected tutoring teacher. Students and people without a teacher role are not teacher options; the create and edit APIs enforce the same workspace eligibility boundary. See [teacher assignment](#tutoring-teacher-assignment) for the API boundary. For an absence, staff enter the missed class date and select **Suggest all sessions**. The form scans the selected group's upcoming scheduled classes and proposes one slot for each missing session. This naturally handles a Monday-to-Wednesday, Saturday-to-Sunday, or Sunday-to-Saturday pattern. For weak-support feedback, the English center preset proposes two consecutive 45-minute sessions before one class. Scheduling from the support queue loads these suggestions before opening the form. Staff still review the teacher, date, and time before creating any session. If too few scheduled classes are available, remaining slots stay blank for manual scheduling. The standard preset places a 45-minute session immediately before class. The Easy Center preset includes the seven named weekday and weekend shifts from the center's schedule. The Monday/Wednesday/Friday 18:00 class uses Wednesday and Friday 17:15–18:00 only: Monday is skipped, even when it is the next scheduled class. The Tuesday/Thursday class uses 17:15–18:00. The weekend 08:00–09:30 class uses **09:30–10:30 after class**, an intentional 60-minute exception to the usual 45 minutes. Other weekend shifts keep the table below. Untouched older Easy Center preset shift rules adopt these corrections when read; staff-edited rules and the standard/custom policies keep their saved behavior, including generic before-class fallback. The canonical Easy Center preset never falls back to an unlisted class day or time. | Class start | Class days | Tutoring time | | - | - | - | | 18:00 | Monday/Wednesday/Friday | 17:15–18:00 Wednesday/Friday only | | 18:00 | Tuesday/Thursday | 17:15–18:00 | | 08:00 | Saturday/Sunday | 09:30–10:30 | | 09:30 | Saturday/Sunday | 08:45–09:30 | | 16:00 | Saturday/Sunday | 15:15–16:00 | | 17:30 | Saturday/Sunday | 16:45–17:30 | | 18:00 | Saturday/Sunday | 17:15–18:00 | Regression coverage: `tutoring-policy.test.ts`, `tutoring-suggestion.test.ts`, and the Contacts `tutoring-policy-card.test.tsx`, `tutoring-teacher-picker.test.tsx`, and `tutoring-create-card.test.tsx` mounted section/teacher controls. `tutoring-policy-save.test.tsx` covers refreshed-section isolation and pending/failed saves. The schedule displays a matching shift name alongside the actual date and time. Staff can rename, add, or change each rule. Suggestions need an existing group schedule; they never create sessions or send parent messages automatically. The parent message is a draft that staff copy after reviewing it. Campus labels are configured per class group; a clear `CS1`, `CS2`, `Cơ sở 1`, or `Cơ sở 2` marker in the group name is inferred when no override exists. The existing generic `Lớp học` group tag does not identify a campus. Ambiguous groups show no campus on the schedule and `Chưa xác định` in the parent draft until staff set an override. The Easy Center template uses the resolved label in the parent draft. The center's tuition remains free to learners; payroll exports count completed teaching time. When scheduling from **Needs support**, a make-up draft copies the recorded lesson description from the missed class date. If that class has no recorded content, the field stays empty for staff to fill. A weak-support draft uses the teacher's flagged feedback content. Staff can review and edit either draft before saving; content is never invented from a class title or an unrelated lesson. Policies are validated at `GET/PUT /api/v1/workspaces/{wsId}/tutoring/policy` and stored under `TUTORING_POLICY` with bounded `TUTORING_POLICY_PART_*` rows in `workspace_configs`. The table enforces a 1,000-character limit per value, so the policy API writes all chunks in one upsert and readers reconstruct the validated policy. Unset or malformed values safely use the standard preset. Existing workspaces need no migration. ## Exports Detailed (per session) and payroll (per teacher, completed sessions and total minutes) exports are available as CSV and XLSX. Exports use the active filters, including the date range, and are generated server-side in pages of 1,000 rows. ## Troubleshooting ### The sidebar link 404s Confirm the caller resolves a workspace profile at all. A missing `workspace_user_linked_users` row now renders the **Unavailable** screen; a still-hard 404 means `WorkspaceWrapper` could not resolve the workspace itself, which points at the app session rather than at tutoring. ### The queue is empty but learners are behind The queue reads absence deficits and `user_feedbacks.require_attention`. Check that group attendance is being recorded and that feedback is flagged. ### The schedule or queue stays empty after loading An API failure now shows a retry button instead of an empty table. Check the workspace permission, then retry. If the same tutoring API works on the central web domain but returns `404 Not found` through Contacts, check that the central route accepts the verified Contacts app session forwarded by the satellite proxy. Schedule and queue loading show table-shaped placeholders while data is in flight. ### A session cannot be created The create button stays disabled until the group, learner, and every slot (date, time, 1–480 minutes, teacher) are complete and no two slots overlap. ## Tutoring teacher assignment In Contacts, a tutoring teacher is selected separately from the student's homeroom teacher. By default, both session creation and editing accept any workspace user with an actual `TEACHER` membership in a group belonging to the same verified workspace. A teacher need not manage the student's selected class. Student membership in that class, staff management permission, and scheduling conflict checks still apply. Users without a teacher role and teachers belonging only to another workspace remain ineligible. The teacher selector uses the paginated, searchable tutoring teacher catalog, not the general people directory or the currently loaded class managers. Multiple teacher memberships produce one catalog identity. This contract applies to the live Next.js API; the teacher catalog and unported tutoring mutations remain tracked Rust migration backlog, while the existing Rust session-list GET is unchanged. Regression coverage: `apps/web/src/lib/tutoring/teachers.test.ts`, `apps/web/src/lib/tutoring/teacher-assignment-routes.test.ts`, and the tutoring teacher catalog's colocated `route.test.ts` cover workspace boundaries, teacher eligibility, permission denial, error handling, pagination, and session writes. ### Queue handoff and missed-date defaults In Contacts, scheduling an absence-recovery queue row selects the oldest supplied outstanding missed-class date in the editable form. This is a suggestion anchor, not a persisted link between an absence and a make-up session. Staff can change it; custom tutoring policy and sequential slot suggestions remain unchanged. Manual creation still starts with no missed date. Changing the learner or group clears that date so another learner's absence is not carried into the new draft. A queue lookup belongs to its committed actor/workspace and current draft interaction. A newer queue selection, form edit, dialog open/close, scope change, or unmount invalidates the older handoff. Late results cannot overwrite a newer draft or reopen a closed dialog. Failed schedule reads retain the existing editable fallback; they do not create sessions automatically. Regression coverage: `tutoring-handoff.test.tsx` mounts the actual Contacts client and create card with a real QueryClient and synthetic transport responses. Its table/dialog presentation harness is bounded component evidence, not customer roster, production provider, or end-to-end dialog proof. ### Archive intent when editing students Contacts student edits preserve the stored `archived` intent when an existing archive-until date is loaded. An unrelated field edit or repeated open/save must not archive an explicitly active student. Selecting a temporary archive date explicitly still marks the student archived; clearing the date and switching to active retains the existing server contract that clears the archive-until value. This changes neither the temporary archive date policy nor enrollment history, and does not repair earlier customer records. Regression coverage exercises the actual student form, calendar, switch and mutation transport in `form-archive.test.tsx`. ### Legacy absence credit matching The support queue matches eligible absence dates and DONE/PENDING absent-recovery session dates chronologically within the configured lookback, independently for each group/student. A reservation consumes at most one absence on or before its session date; earlier make-ups cannot consume later absences. Remaining dates are returned with the same deficit and drive the make-up handoff. This is a fallback for records without a persisted source-attendance link. It does not prove which historical absence staff intended to cover, repair prior records, or alter custom eligibility/exclusion policy. Explicit attendance-row linkage remains separate work, including multiple sessions on the same date. Web queue regressions and the Rust queue parity tests cover the chronological boundary, ordering, same-day multiplicity and group/student isolation. ## Staff-reviewed draft planning Contacts offers compact per-session date/time and eligible teacher choices alongside the existing manual editor. Choices use the workspace policy, scheduled group classes, and a complete bounded read of workspace teacher memberships and tutoring sessions within the policy horizon (including the prior date for overnight conflicts). Date/time ranking is chronological; teacher ties are stable by ID. Staff explicitly select a teacher to apply a choice. Nothing is created until the existing Create action. The planner never fills an unsupported time with an invented 18:00 fallback. Each teacher/session catalog is capped at 20 pages of 100 records. Errors, inconsistent counts, duplicate or truncated pages prevent suggestions and expose Retry. Missing teachers and schedules have distinct feedback. Configured but unmaterialized class occurrences are shown as a schedule-review exception, not confirmed classes. The displayed horizon follows the configured policy rather than a fixed four weeks. Choices exclude recorded learner/teacher tutoring conflicts and other slots in the current draft, with half-open intervals and overnight overlap. Cancellation records are conservatively included to match the existing creation conflict check. These are **no recorded tutoring conflict** choices, not confirmed teacher availability: other classes, rooms, capacity and contractual availability are not modeled. Reads are not an atomic reservation. The server rechecks at Create, but concurrent creation remains a separate unresolved frontier. Existing custom policy, consent, staff edits and actor/workspace lifetimes remain authoritative. A late read never applies choices. Regression coverage: `tutoring-draft-plan.test.ts`, `tutoring-plan-data.test.ts`, `tutoring-draft-choices.test.tsx`, and the actual queue handoff regression. Source tests are not customer runtime or production-data repair evidence. Original absence linkage and automatic planning/teacher notices remain outside this packet. The next teacher-hours foundation is intended to support staff-defined defaults and explicit per-teacher overrides, with the teacher override taking precedence. Those hours are not yet implemented or consulted by this first draft packet; absence of a recorded tutoring conflict must never be treated as availability consent. ## Teacher-hours domain contract The pure `@tuturuuu/utils/tutoring-teacher-hours` model defines staff defaults and per-teacher weekday overrides; it does not yet read or write hours, change Contacts UI, constrain Create, or send notices. Existing custom tutoring policy and staff confirmation remain unchanged. Calendar's automatically created 07:00–23:00 defaults are not teacher-hours authority. An absent staff weekday is **unknown**; an explicit empty array is **closed**. An absent override weekday inherits the current default. Custom teacher windows replace that weekday, rather than widening it by union. Override reset retains an empty, revisioned row; future storage must atomically reject stale revisions, including absent→create→reset races. The model preserves opaque revision strings without numeric/date conversion and rejects unchanged write receipts, but does not itself prove database CAS, role admission or same-content revision advancement. Hours require an explicitly confirmed IANA timezone. Overrides cannot establish availability without that staff frame. Windows are sorted, disjoint, half-open civil times; midnight endings use `24:00`. Overnight windows must be explicitly split across weekdays. Candidate inputs are in the confirmed staff frame, never silently in the browser/class timezone. Gap/fold endpoints and slots crossing DST transitions are conservatively rejected rather than assigned an offset. Unknown coverage stays unknown; any known closed portion denies coverage. Regression coverage in `tutoring-teacher-hours.test.ts` keeps unconfirmed teacher hours unknown and exercises Temporal compatible gap conversion as an unsuitable input, inheritance/replacement, lossless reset receipts, adjacency, midnight, weekly wrapping and DST. The actual Calendar default factory is tested separately in Calendar’s `hour-settings-shared.test.ts`; utils tests stay within their package source boundary. This is pure source evidence, not persisted availability or production scheduling proof. API/schema/authenticated editor, atomic revision storage, staff-default/teacher-role permissions, outside-hours exceptions and planner consumption remain separate reviewed packets. ### Private teacher-hours storage foundation The additive storage foundation keeps confirmed staff defaults and teacher weekday overrides in private tables behind service-only, scoped RPCs. It remains inert: no current API, settings UI or Create action consumes these tables. Reads never initialize defaults. Account actors require explicit workspace MEMBER status plus `view_user_groups` for reads or `manage_workspace_settings` for writes; teacher IDs are separate workspace-user identities. Current same-workspace TEACHER membership is checked and locked for override writes. This proves current admission, not a historical role remove/readd epoch. All writes lock the workspace hours anchor, default and override in that order. Default and override revisions are positive bigint values exposed only as full-precision decimal text. Absent creation requires a null revision; updates, same-content saves and resets advance the revision. Override writes also compare the captured default revision. Reset stores a revisioned empty override instead of deleting it, so old absent/create or pre-reset drafts cannot silently revive. Unknown, explicitly closed and inherited weekdays retain the pure-model contract. The SQL window validator also rejects extra untyped interval properties. Revision-only audit receipts use canonical `audit.to_record_id` table/key identity and explicit account actor, without copying hours content. Audit insertion and hours mutation share one transaction; an audit failure rolls the write back. A transport timeout is still an unknown receipt, not proof of rollback: future clients must refetch and review rather than blindly replay a stale revision. No cross-request idempotency or automatic provider operation is promised. `tutoring-teacher-hours-contract.yaml` applies the complete schema in an owned CI disposable database, runs strict pgTAP and actual two-connection create, default-change and save/reset races, then generates an exact-schema type artifact. Node wiring tests and pure model tests are source checks; only successful exact CI supplies database evidence. The foundation requires that proof before merge. Outside-hours exceptions, API/Rust migration tracking, authenticated editing, teacher-hour consumer integration and atomic tutoring reservations remain separate reviewed work. Existing tutoring policy, workspace timezone and staff Create permissions are unchanged. ### Selected-absence identity foundation (unwired) The additive foundation is service-only and has no Contacts/API activation. Existing historical sessions remain unlinked and use the chronological fallback above; no migration guesses which absence an old make-up covered. The selected date in the current form is still suggestion context, not proof of saved attribution. The new contract identifies an absence by its attendance UUID, including separate class occurrences on the same date. Each linked make-up slot requires a distinct eligible source UUID. PENDING reserves one source; DONE permanently credits it. Cancel, no-show, or a pending reason change releases the reservation while retaining its original identity and history. Reactivation uses revision CAS and must reclaim the same eligible source; another reservation causes a conflict. Allowed deletion retains attribution; DONE credit cannot be released by deletion or a reason/status edit. Ordinary content and parent-message metadata edits preserve credit identity. Linked date/time/duration/teacher and creation actor/timestamp rewrites require an exact canonical permit. Direct schedule edits are rejected until a future validated PATCH operation exists, including moving a make-up before its source absence. No client is wired to these operations in this foundation packet. Correcting active source attendance to PRESENT requires an explicit staff-managed resolution. Silent correction or standalone deletion is rejected. A credited source keeps its history after explicit resolution. Existing workspace/group/student or membership teardown uses narrowly scoped FK cleanup; immutable original IDs/date remain available for retained records. Deleting an actual class occurrence releases pending reservations while preserving DONE credit and immutable occurrence snapshots. Declared teacher/creator SET NULL and parent rekey cascades may change only their live FK fields after the old parent disappears; arbitrary direct rewrites stay denied. Tenant-authorized release is possible after learner archive or enrollment departure; new reservations still require an active enrolled learner. Input-bound replay returns its original receipt before mutable learner/source checks, but only after rechecking the current actor's permission. Revoked actors cannot replay. No generic trigger-depth or caller-writable session flag authorizes a protected write. Only a verified backend actor may call the canonical service-only operations, which also check current MEMBER membership and the existing tutoring permission. Private, ungranted permits exist only during an exact transaction/session/revision/mutation; success removes them and failure rolls them back. Linked status/reason/delete writes outside that boundary are rejected. Full historical schema replay, strict pgTAP, two-connection claim-versus-correction/replay races, and generated types must pass on the exact head before foundation merge. Fixtures and source checks are not live customer proof. Queue/API/UI integration and selected-card-to-transport regression are separate dependent packets; historical customer data is not repaired here. ### Create completion ownership Contacts captures the exact actor/workspace lifetime and draft revision before a make-up create request. Only that still-current intent may close its draft, announce success/failure, or invalidate its scoped queries. Replacing the draft or leaving and returning to an actor/workspace permanently invalidates old completion effects. A new scope remains usable while an old admitted write is pending. This does not cancel or undo a server write: current-scope success and failure remain visible, and synchronous duplicate submission is suppressed. The mounted Client/CreateCard regressions in `tutoring-create-scope.test.tsx` cover these boundaries with held synthetic transports; they are not customer or production-write evidence. The inert absence identity contract checks rejected linked-session mutations against the canonical-operation error and preserved schedule and attribution. Trigger permit lookups use distinct local variable names and qualified columns to avoid ambiguous SQL references before admission. Regression evidence lives in `apps/database/supabase/tests/tutoring-absence-credit-contract.sql` and `apps/database/supabase/tests/tutoring-absence-credit-lifecycle.sql`; the exact-head database contract must pass before this foundation is considered verified. # Parley Source: https://docs.tuturuuu.com/platform/apps/parley Operate the private scenario training application and shared Meet runtime. Parley runs at `parley.tuturuuu.com` with locale-free page URLs. It uses the shared Tuturuuu Supabase session cookie across subdomains and the standard satellite shell (`structure.tsx`), alongside the shared `@tuturuuu/meet-core` runtime. Verified `@tuturuuu.com` accounts have access; external accounts require an enabled entry managed in Infrastructure under **Platform administration → Parley**. Authorization checks the current confirmed account identity. Failed lookups deny access. ## Discovery and session review The scenario library at `/` supports text search and category filters. Discovery also shows the facilitator’s three most recent sessions and a dedicated join area explaining the shared Meet runtime. Recent sessions are scoped to the signed-in facilitator; they are not workspace-wide activity or aggregate progress metrics. An unavailable recent-session archive shows a retry hint without hiding the scenario library or presenting a false empty archive. The **New testing session** navigation item opens `/sessions/new`, where facilitators search and select one published scenario, read its briefing, acknowledge participation, and create a room. Selection starts with the first published scenario. Changing the selection resets the acknowledgement; search does not change the selected scenario, which remains named in the setup panel. Open `/scenarios/[scenarioId]` to read the public briefing, preview role names and confirm participation before creating a session. Hidden role briefs and AI instructions never enter the discovery client payload. `/sessions` is the signed-in facilitator's paginated archive. Each `/sessions/[meetingId]` review reuses Meet's metered AI transcript, summary, decision and follow-up tools. The review includes a **Meeting details in Meet** link targeting the same workspace and meeting, plus invitation controls that copy the Parley room URL or room code. Invitations do not grant app access or bypass room admission. The saved scenario debrief rubric is shown only after facilitator ownership and host checks, and is omitted when empty. It comes from the immutable session snapshot, so later scenario edits cannot rewrite the review guide. Private research notes are shown separately and remain facilitator-only, even when meeting notes are shared with participants. Research notes are paginated newest first, with full-session note and decision totals; the note-type filter applies to the current page. These satellite-only routes are owned by `apps/parley`; the current TanStack migration manifest scans `apps/web`, not satellite app trees. The studio `layout.tsx` owns the sidebar, workspace shell and administrator navigation. Its locale and administrator flag key the cached navigation labels; session, workspace and role checks remain request-scoped. Authentication uses the centralized provider-cookie proxy with MFA verification, then fresh confirmed-email/allowlist authorization. Do not clear shared Supabase cookies or make an app-specific coordination token mandatory. Realtime room signing remains a separate server-to-server requirement. ## Private content Infrastructure administrators manage scenario briefs, private AI instructions, roles, debrief rubrics and publication state directly in Parley at `/manage/scenarios`. The page paginates scenarios and reports field validation errors without losing the administrator's form values. The same authoring tools remain in Infrastructure under **Platform administration → Parley**, which also manages account access and reference uploads. The Parley route checks the current platform administrator role on the server before reading or saving private scenario data. Reference bytes are stored in `private.parley_references`, accessible only through authorized server operations. Source documents are never seeded or committed. Import real content through Infrastructure separately in each intended environment. Starting a session atomically creates a Meet room and an immutable scenario snapshot. Later edits do not change a running session's instructions. The facilitator can save observations, decisions and debrief notes; participants do not receive these private notes or raw source documents. Discuss consent before recording or collecting research observations. Notes describe observable actions, not validated personality or truthfulness assessments. Mira uses the stored scenario instructions for shared chat and live voice. Parley's lightweight avatar follows the local playback audio envelope. It does not analyze participant faces or microphones, and it is not phoneme-accurate viseme synthesis or a full 3D avatar. ## Development and deployment 1. Apply the additive Parley migration locally and regenerate database types. Do not reset a shared development database to test this app. 2. Run `bun --cwd apps/parley dev` with the same Supabase, realtime and provider environment contracts as Meet. Browser authentication uses shared provider cookies; no Parley-specific app-session token is required. The app uses port 7834 and `parley.tuturuuu.localhost`. 3. Run focused non-build tests through `ttr resources run`; require the real Parley build and applicable type, lint and test workflows in CI for the exact commit. Do not run local release builds. Shared runtime changes also require the affected Meet and Infrastructure CI builds. 4. Sync the reviewed release to production through the authorized release workflow. Verify that the production database migration job applies all Parley migrations. Meet and Parley Worker deployments wait for the database readiness marker; do not run a manual production schema push. Publish the central auth registry and Infrastructure management surface before testing. 5. Build Parley with `NEXT_PUBLIC_MEETING_APP=parley`. Its web Worker and cache bucket are separate from Meet. A private `MEETING_AI_PROVIDER` service binding calls Meet’s named provider entrypoint; `MEET_LIVE` references Meet’s Durable Object namespace. The Gemini credential stays in Meet. Deploy Meet first, then Parley; CI waits for the shared runtime readiness endpoint. The common realtime signing secret is provisioned from the protected GitHub environment. Deploy with `bun run deploy:cloudflare` from `apps/parley`, which populates OpenNext's generated R2 cache before publishing the Worker. A direct `wrangler deploy` skips that data and can make rendered routes hang even though middleware redirects succeed. Verify `/access-denied` after each deployment; checking only the root redirect does not test page rendering. 6. Verify denied, internal-domain and allowlisted sign-in; revoke an external account and recheck access. Verify private reference upload/retrieval, scenario persistence after reload, room admission, two-participant audio, Mira response, and audio-driven avatar motion in each environment. Existing live sockets use short-lived credentials. Revocation prevents new requests and tokens; it does not retroactively disconnect an already-open call. Close the session when immediate termination is needed. Do not describe a build or synthetic test as production or physical multi-device verification. ## AI Hub and billing Meet and Parley use the same workspace credit system. Live voice reserves credits before connecting to the provider, settles cumulative modality usage, and refunds the unused reservation. App and room identifiers accompany the reservation and final ledger entry, without scenario text or private documents. Transcription and meeting notes reserve an AI Hub run before generation. They use the purchased output-token limit, settle measured provider cost with the plan markup, and reuse the same run for settlement retries. Missing provider accounting fails closed and leaves the reservation visible for reconciliation. These runs appear in AI Hub observability; chat also reserves and settles an AI Hub run, while live deductions appear in the combined credit ledger. Chat settlement consumes its own hold, including near the quota limit; optional public search is disabled when its additional reservation would exceed the available credits. The usage and credits links open the payer's personal workspace. Apply the research migration plus the meeting attribution and observability migrations before deploying either app's new billing code. A Gemini key marked sensitive in Vercel cannot be exported. Parley uses the private provider binding instead of duplicating that key. Native local development may configure its own development key; do not bind local testing to the production provider. Parley disables public Google Search during scenario roleplay. The scenario configuration is separate from the participant request, so reference text never becomes an explicit public search query. Proxy authentication must resolve explicit request headers through the framework-neutral Supabase request client. Cloudflare proxy execution does not provide the same ambient `next/headers` cookie context as a server component. Keep refreshed cookies on the forwarded request and response, and verify login on the deployed Worker. A local Next server alone does not prove this runtime boundary. ### Shared-cookie forwarding and rollback recovery The centralized auth proxy forwards the verified provider cookie in `x-middleware-request-cookie`. Parley uses that value for its access check and page render. Do not replace it by replaying response cookie deletions: clearing a host-only duplicate must not erase the same-name `.tuturuuu.com` session. Include a shared-domain request in authentication smoke tests; a plain localhost cookie does not exercise this cleanup path. After a Worker rollback, Cloudflare can reject ordinary secret updates with error `10215` because the latest version is not active. Keep the working rollback active while preparing the corrected deployment. If existing required secrets are unchanged, deploy the corrected, validated artifact retaining those secrets, verify authentication, then retry the failed CI deployment. Never reactivate a broken version merely to unblock secret configuration. OpenNext artifacts may contain absolute build-host asset paths; deploy on the original build platform, or relocate only generated imports to the identical included assets. ## Regression evidence and further opportunities `session-setup.test.tsx` checks selection, fresh participation acknowledgement, search recovery and selected-scenario visibility. `session-invitation.test.tsx` checks room-only sharing and clipboard failure recovery. `meet-links.test.ts` checks that a shared-runtime Parley origin cannot misdirect the Meet handoff. `recent-sessions.test.tsx` checks the three-session limit and distinguishes archive errors from an empty archive. The review route tests enforce facilitator ownership before loading the snapshot and rendering the private rubric. These fixtures do not validate hosted authentication, call media, billing or clipboard permissions in every browser. Useful follow-on work includes opt-in scheduled practice through Calendar, explicitly reviewed task creation from debrief decisions, and private comparisons between repeated sessions. These are proposals, not current behavior. Scheduling needs an explicit participant and recording consent flow; task creation must use the destination workspace’s permissions; comparisons should cite source evidence and never infer personality or provide unvalidated psychological scores. # API Route Patterns Source: https://docs.tuturuuu.com/platform/architecture/api-routes Implementing and organizing API routes in the Tuturuuu platform The Tuturuuu platform uses Next.js App Router API routes with consistent patterns for versioning, authentication, error handling, and workspace isolation. During the TanStack Start migration, new backend API ownership should move to `apps/backend` instead of adding more long-lived `apps/web` route handlers. See `platform/architecture/tanstack-rust-migration` for the route manifest, OpenAPI, Docker, E2E, and benchmark gates. ## Route Organization ### Directory Structure ``` apps/web/src/app/api/ ├── v1/ # Versioned public API │ ├── workspaces/ │ │ └── route.ts │ └── users/ │ └── route.ts ├── ai/ # AI-specific endpoints │ ├── chat/ │ │ └── route.ts │ └── generate/ │ └── route.ts ├── [wsId]/ # Workspace-scoped endpoints │ ├── tasks/ │ │ └── route.ts │ └── members/ │ └── route.ts ├── auth/ # Authentication endpoints │ ├── otp/ │ │ └── route.ts │ └── mfa/ │ └── route.ts └── workspaces/ # Workspace management └── route.ts ``` ## Upstream Proxy Routes When an `apps/web` route proxies requests to an upstream service and needs low-level Undici transport controls such as a custom `dispatcher` or larger `maxHeaderSize`, prefer `undici.request(...)` over the global server `fetch`. On Next.js 16, the wrapped route-handler `fetch` can reject custom Undici dispatchers with `UND_ERR_INVALID_ARG` / `invalid onRequestStart method`. Keep custom transport configuration on the direct Undici request instead of passing it through `fetch`. ## Authentication Wrappers `apps/web` routes do not hand-roll `try/catch` + `supabase.auth.getUser()` membership checks. Two wrappers in `apps/web/src/lib` centralize IP blocking, pre-auth rate limiting, payload-size limits, suspension checks, and adaptive abuse controls so handlers only contain business logic. | Wrapper | Module | Auth source | Handler context | | - | - | - | - | | `withSessionAuth` | `@/lib/api-auth` | Signed-in Supabase session (cookie/Bearer JWT, optional AI temp auth / app-session) | `{ user, supabase }` | | `withApiAuth` | `@/lib/api-middleware` | Workspace API key (`Authorization: Bearer ttr_...`) | `{ context, params }` where `context` is the `WorkspaceContext` | Both wrappers receive route params as a **Promise** (Next.js App Router behavior) and resolve them before invoking the handler. The session wrapper exposes a `TypedSupabaseClient` already scoped to the authenticated user, so RLS stays intact. > The older `authorizeRequest`/`authorize` helpers in `@/lib/api-auth` are > `@deprecated`. Prefer `withSessionAuth` for new routes. ## Versioned Public API ### Pattern: `/api/v1/*` Use for product and public-facing APIs. For session-authenticated dashboard surfaces, wrap the handler with `withSessionAuth`. The wrapper provides the authenticated `user` and a request-scoped `supabase` client; the third handler argument is the resolved route params. ```typescript theme={null} // app/api/v1/workspaces/route.ts import { withSessionAuth } from '@/lib/api-auth'; import { NextResponse } from 'next/server'; import { z } from 'zod'; // GET /api/v1/workspaces export const GET = withSessionAuth(async (_request, { user, supabase }) => { // Fetch the caller's workspaces (RLS-scoped via `supabase`) const { data: workspaces, error } = await supabase .from('workspace_members') .select( ` ws_id, role, workspaces ( id, name, logo_url ) ` ) .eq('user_id', user.id) .eq('pending', false); if (error) { return NextResponse.json({ error: error.message }, { status: 500 }); } return NextResponse.json({ data: workspaces?.map((w) => w.workspaces), }); }); // POST /api/v1/workspaces const createWorkspaceSchema = z.object({ name: z.string().min(1).max(100), logo_url: z.url().optional(), }); export const POST = withSessionAuth(async (request, { user, supabase }) => { // Validate request body const body = await request.json(); const parsed = createWorkspaceSchema.safeParse(body); if (!parsed.success) { return NextResponse.json( { error: 'Invalid input', details: parsed.error.issues }, { status: 400 } ); } // Create workspace const { data: workspace, error } = await supabase .from('workspaces') .insert({ name: parsed.data.name, logo_url: parsed.data.logo_url, }) .select() .single(); if (error) { return NextResponse.json({ error: error.message }, { status: 500 }); } // Add creator as owner await supabase.from('workspace_members').insert({ ws_id: workspace.id, user_id: user.id, role: 'owner', }); return NextResponse.json({ data: workspace }, { status: 201 }); }); ``` > When you do need a Supabase client outside a wrapper (Server Components, > background jobs), remember the factory async-ness in > `@tuturuuu/supabase/next/server`: `createClient()` and `createDynamicClient()` > are async and must be awaited; `createAdminClient()` is synchronous (do not > `await` it unless you pass it through another async helper). ## Workspace-Scoped API ### Pattern: `/api/v1/workspaces/[wsId]/*` Use for workspace-scoped operations. Route params are a Promise; the wrapper resolves them and passes them as the third handler argument. Authorize with the workspace helpers from `@tuturuuu/utils/workspace-helper`: * `normalizeWorkspaceId(wsId, supabase)` — resolves `personal`/handle aliases to a concrete UUID. * `getPermissions({ wsId, user })` — returns a `PermissionsResult` with `containsPermission(permissionId)` / `withoutPermission(permissionId)`. It returns `null` when the caller is not a member, which doubles as the membership check. ```typescript theme={null} // app/api/v1/workspaces/[wsId]/tasks/route.ts import { withSessionAuth } from '@/lib/api-auth'; import { getPermissions, normalizeWorkspaceId, } from '@tuturuuu/utils/workspace-helper'; import { NextResponse } from 'next/server'; import { z } from 'zod'; type Params = { wsId: string }; // GET /api/v1/workspaces/[wsId]/tasks export const GET = withSessionAuth( async (request, { user, supabase }, { wsId }) => { const workspaceId = await normalizeWorkspaceId(wsId, supabase); // getPermissions returns null for non-members → 403 const permissions = await getPermissions({ wsId: workspaceId, user }); if (!permissions) { return NextResponse.json({ error: 'Forbidden' }, { status: 403 }); } const searchParams = new URL(request.url).searchParams; const listId = searchParams.get('listId'); const completed = searchParams.get('completed'); let query = supabase .from('workspace_tasks') .select('*') .eq('ws_id', workspaceId); if (listId) query = query.eq('list_id', listId); if (completed !== null) query = query.eq('completed', completed === 'true'); const { data: tasks, error } = await query; if (error) { return NextResponse.json({ error: error.message }, { status: 500 }); } return NextResponse.json({ data: tasks }); } ); // POST /api/v1/workspaces/[wsId]/tasks const createTaskSchema = z.object({ name: z.string().min(1).max(255), description: z.string().optional(), listId: z.string(), priority: z.number().int().min(0).max(5).optional(), dueDate: z.string().datetime().optional(), }); export const POST = withSessionAuth( async (request, { user, supabase }, { wsId }) => { const workspaceId = await normalizeWorkspaceId(wsId, supabase); const permissions = await getPermissions({ wsId: workspaceId, user }); if (!permissions?.containsPermission('manage_projects')) { return NextResponse.json({ error: 'Forbidden' }, { status: 403 }); } const body = await request.json(); const parsed = createTaskSchema.safeParse(body); if (!parsed.success) { return NextResponse.json( { error: 'Invalid input', details: parsed.error.issues }, { status: 400 } ); } const { data: task, error } = await supabase .from('workspace_tasks') .insert({ name: parsed.data.name, description: parsed.data.description, list_id: parsed.data.listId, priority: parsed.data.priority, end_date: parsed.data.dueDate, creator_id: user.id, }) .select() .single(); if (error) { return NextResponse.json({ error: error.message }, { status: 500 }); } return NextResponse.json({ data: task }, { status: 201 }); } ); ``` > Real task-board routes (for example > `apps/web/src/app/api/v1/workspaces/[wsId]/tasks/route.ts`) keep handler logic > in `@tuturuuu/tasks-api/server/tasks/route` and only wire the adapter in the > route file. Task-specific request clients and types live in > `@tuturuuu/tasks-api/progress`, while task-only React surfaces live in > `@tuturuuu/tasks-ui`. This includes board UI, task dialogs and settings, > task-aware rich-text mention renderers, realtime board hooks, and task > scheduling controls used by Calendar. Generic editors and Calendar shells > expose component or renderer interfaces from `@tuturuuu/ui`; the task > package supplies their implementations. Keep this dependency one-way: > `@tuturuuu/tasks-ui` may depend on `@tuturuuu/ui`, but shared UI must not > import task UI. Keep generic modules in `@tuturuuu/apis`, > `@tuturuuu/internal-api`, and `@tuturuuu/ui` free of new task-only > implementations so Turbo can cache and rebuild the task packages > independently. Apps must import task modules directly from > `@tuturuuu/tasks-ui`; do not re-export them through `@tuturuuu/ui`, because > that broadens the affected build graph again. Direct consumer apps must also > import `@tuturuuu/tasks-ui/globals.css` instead of the generic globals so > Tailwind compiles the UI foundation and task-owned utilities together; > keep that source registration out of generic UI globals so task-only changes > do not invalidate unrelated apps. Extract shared handler logic the same way when a route grows > past a simple CRUD shape. Use `containsPermission()` with a real `PermissionId` (such > as `'manage_projects'`); there is no `manage_tasks` permission and no > `@/lib/permissions` module. ## AI Endpoints ### Pattern: `/api/ai/*` Use for AI-specific operations with model selection and token tracking. The repo uses **AI SDK v6** (`ai` ^6.x, `@ai-sdk/google` ^3.x). On v6, `streamText` results expose `result.toUIMessageStreamResponse()` (the v4/v5 `toDataStreamResponse()` no longer exists), and `onFinish` usage is reported as `usage.inputTokens` / `usage.outputTokens` (not `promptTokens` / `completionTokens`). Wrap the route with `withSessionAuth` and pass `allowAiTempAuth` if the endpoint must accept short-lived AI temp tokens. ```typescript theme={null} // app/api/ai/chat/route.ts import { withSessionAuth } from '@/lib/api-auth'; import { createGoogleGenerativeAI } from '@ai-sdk/google'; import { streamText } from 'ai'; import { z } from 'zod'; const chatRequestSchema = z.object({ wsId: z.string(), messages: z.array( z.object({ role: z.enum(['user', 'assistant', 'system']), content: z.string(), }) ), model: z.string().optional(), }); export const POST = withSessionAuth(async (request, { supabase }) => { // Validate input const body = await request.json(); const parsed = chatRequestSchema.safeParse(body); if (!parsed.success) { return new Response('Invalid input', { status: 400 }); } // Check AI feature flag const { data: secret } = await supabase .from('workspace_secrets') .select('value') .eq('ws_id', parsed.data.wsId) .eq('name', 'ENABLE_AI') .single(); if (secret?.value !== 'true') { return new Response('AI not enabled for workspace', { status: 403 }); } const google = createGoogleGenerativeAI({ apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY, }); const model = parsed.data.model || 'gemini-2.0-flash'; const result = streamText({ model: google(model), messages: parsed.data.messages, onFinish: async ({ usage }) => { // Track token usage (AI SDK v6 field names) await supabase.from('workspace_ai_executions').insert({ ws_id: parsed.data.wsId, model, input_tokens: usage.inputTokens ?? 0, output_tokens: usage.outputTokens ?? 0, }); }, }); return result.toUIMessageStreamResponse(); }); ``` Token-usage persistence across the live AI routes (chat, task journal, suggestions, quizzes) consistently reads `usage.inputTokens ?? 0` and `usage.outputTokens ?? 0` — mirror that when adding new AI endpoints. ## Authentication Endpoints ### Pattern: `/api/auth/*` Use edge runtime for auth endpoints. ```typescript theme={null} // app/api/auth/otp/route.ts import { createClient } from '@tuturuuu/supabase/next/server'; import { NextRequest, NextResponse } from 'next/server'; import { z } from 'zod'; const otpRequestSchema = z.object({ email: z.email(), }); export async function POST(request: NextRequest) { try { const supabase = await createClient(); const body = await request.json(); const parsed = otpRequestSchema.safeParse(body); if (!parsed.success) { return NextResponse.json( { error: 'Invalid email' }, { status: 400 } ); } const { error } = await supabase.auth.signInWithOtp({ email: parsed.data.email, options: { emailRedirectTo: `${process.env.NEXT_PUBLIC_APP_URL}/auth/callback`, }, }); if (error) { return NextResponse.json({ error: error.message }, { status: 400 }); } return NextResponse.json({ success: true }); } catch (error) { return NextResponse.json( { error: 'Internal server error' }, { status: 500 } ); } } ``` ## Error Response Standards ### Standard Error Format ```typescript theme={null} interface ErrorResponse { error: string; details?: any; code?: string; } ``` ### HTTP Status Codes * `200` - Success * `201` - Created * `204` - No Content * `400` - Bad Request (validation errors) * `401` - Unauthorized (not authenticated) * `403` - Forbidden (not authorized) * `404` - Not Found * `409` - Conflict * `422` - Unprocessable Entity * `429` - Too Many Requests * `500` - Internal Server Error ### Error Handling Pattern ```typescript theme={null} export async function POST(request: NextRequest) { try { // Implementation } catch (error) { console.error('API error:', error); if (error instanceof z.ZodError) { return NextResponse.json( { error: 'Validation failed', details: error.issues }, { status: 400 } ); } return NextResponse.json( { error: 'Internal server error' }, { status: 500 } ); } } ``` ## API-Key Authenticated Routes ### Pattern: `withApiAuth` External SDK clients authenticate with a workspace API key (`Authorization: Bearer ttr_...`) instead of a Supabase session. Wrap those routes with `withApiAuth` from `@/lib/api-middleware`. It validates the key, enforces IP blocks, applies pre-auth and adaptive rate limits, logs API key usage, optionally checks workspace permissions, and passes the resolved `WorkspaceContext` plus route params to the handler. ```typescript theme={null} // app/api/v1/workspaces/[wsId]/storage/route.ts import { withApiAuth } from '@/lib/api-middleware'; import { NextResponse } from 'next/server'; type Params = { wsId: string }; export const GET = withApiAuth( async (_request, { params, context }) => { // `context.wsId` is the validated workspace from the API key const { wsId } = context; // params.wsId is the resolved (awaited) route segment return NextResponse.json({ wsId, route: params.wsId }); }, { permissions: ['manage_drive'], // checked via the API key's permission set rateLimit: { windowMs: 60000, maxRequests: 100 }, } ); ``` Key points that differ from `withSessionAuth`: * Permissions are declared in the wrapper `options.permissions` (a `PermissionId[]`) and checked against the API key's granted scopes via `hasAnyPermission` / `hasAllPermissions`. Set `requireAll: true` to require every listed permission. * The handler context is `{ context, params }` (not `{ user, supabase }`); the API-key path does not hand you a session-scoped Supabase client. * Rate-limit defaults: GET/HEAD reads are open, mutations default to 100 req/min, and workspace-specific overrides from `workspace_secrets` take precedence. The helper module also exports `validateQueryParams(request, schema)` and `validateRequestBody(request, schema, maxBytes)` for Zod-validated, byte-size-capped input handling. ## CORS Configuration ```typescript theme={null} // app/api/v1/workspaces/route.ts export async function OPTIONS(request: NextRequest) { return new NextResponse(null, { status: 200, headers: { 'Access-Control-Allow-Origin': process.env.ALLOWED_ORIGIN || '*', 'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS', 'Access-Control-Allow-Headers': 'Content-Type, Authorization', }, }); } ``` ## Rate Limiting For signed-in product APIs, prefer `withSessionAuth(...)` over manual `supabase.auth.getUser()` calls. The wrapper resolves the session through local JWT claims first and only falls back to `getUser()` when claims are unavailable, which avoids exhausting Supabase Auth limits on request-heavy dashboard surfaces such as task boards. Default GET/HEAD requests are not rate-limited by the session wrapper; default mutations use the shared mutation budget unless the route provides an explicit `rateLimit` option. The API proxy still protects request-heavy dashboard reads before route auth is validated. High-fanout task-board reads use a dedicated `task-board-read` proxy bucket so normal board loading, per-list pagination, and focused revalidation do not exhaust the generic anonymous read budget. The defaults are 600 requests per minute, 12000 per hour, and 80000 per day, and can be tuned with `API_PROXY_TASK_BOARD_READ_LIMIT_MINUTE`, `API_PROXY_TASK_BOARD_READ_LIMIT_HOUR`, and `API_PROXY_TASK_BOARD_READ_LIMIT_DAY`. Proxy-side `429` responses include support diagnostics when available: `X-RateLimit-Client-IP`, `X-RateLimit-User-Id`, and `X-RateLimit-User-Email`, plus the selected policy/window headers emitted by the proxy guard. Exact server-verified browser sessions ending in `@tuturuuu.com` are allowed through proxy-side rate-limit blocks for debugging with `X-RateLimit-Warning: staff-debug-bypass`, `X-RateLimit-Debug-Bypass: tuturuuu-staff`, and `X-RateLimit-Original-Status: 429`. This bypass only applies after the server revalidates the Supabase session, only to proxy guard rate-limit blocks, and does not bypass malformed auth, permissions, payload-size checks, route-handler errors, or non-staff/anonymous requests. Finance invoice creation support reads use a separate `finance-invoice-create-read` proxy bucket for the shared-IP burst created by the new invoice flow. It covers GET/HEAD reads for customer search, products, wallets, transaction categories, promotions, invoice default settings, linked products, user group data, user promotion data, invoice history, and subscription context. Invoice creation mutations remain on the default mutation policy. The defaults are 600 requests per minute, 6000 per hour, and 40000 per day, and can be tuned with `API_PROXY_FINANCE_INVOICE_CREATE_READ_LIMIT_MINUTE`, `API_PROXY_FINANCE_INVOICE_CREATE_READ_LIMIT_HOUR`, and `API_PROXY_FINANCE_INVOICE_CREATE_READ_LIMIT_DAY`. ### Verified sessions and trusted read uplift Proxy limits default to per-IP anonymous buckets because auth headers and cookies are forgeable at the edge — their presence alone must never raise a budget. To separate genuinely signed-in browser sessions and give legitimate teams (often many people behind one office NAT/VPN IP) higher read throughput, the proxy consults a server-written **trust cache** in Redis, keyed by the same subject keys as the abuse-reputation system (`session:`, `cidr:`, `ip:`): * A genuinely trusted **session** (its key is a hash of the real auth cookie, so it cannot be forged) gets its own per-session read and mutation buckets, so signed-in teammates behind one shared IP no longer collide on the pre-auth proxy budget. * A trusted **location** (office `cidr`/`ip`, learned automatically from organic reputation or set explicitly via an `abuse_trust_overrides` `cidr` entry in the abuse-intelligence admin API) uplifts the shared per-IP read limit for the whole team. Untrusted traffic keeps the legacy per-IP limits, preserving single-IP abuse caps. The cache only ever uplifts read limits (never mutation limits, and never lowers limits — restrictive decisions stay server-side) and fails open to neutral when Redis is unavailable. It is populated by the session write-through in `recordResponseAbuseSignal` and direct session-auth helpers, and reconciled every 10 minutes by the `/api/cron/infrastructure/sync-trust-cache` cron (which also propagates admin trusted-location overrides). Set `API_PROXY_EDGE_TRUST_ENABLED=0` to disable the edge trust cache and fall back to per-IP keying; tune the cache lifetime with `EDGE_TRUST_CACHE_TTL_SECONDS`. ```typescript theme={null} import { Ratelimit } from '@upstash/ratelimit'; import { Redis } from '@upstash/redis'; const ratelimit = new Ratelimit({ redis: Redis.fromEnv(), limiter: Ratelimit.slidingWindow(10, '10 s'), // 10 requests per 10 seconds }); export async function POST(request: NextRequest) { const identifier = request.headers.get('x-forwarded-for') || 'anonymous'; const { success } = await ratelimit.limit(identifier); if (!success) { return NextResponse.json( { error: 'Rate limit exceeded' }, { status: 429 } ); } // Continue with request } ``` ## Best Practices ### ✅ DO 1. **Wrap handlers with the auth wrapper** ```typescript theme={null} // Session routes: getUser/membership/rate limits handled for you export const POST = withSessionAuth(async (request, { user, supabase }) => { /* ... */ }); // API-key routes: key validation + permission scopes export const GET = withApiAuth(handler, { permissions: ['manage_drive'] }); ``` 2. **Always validate input** ```typescript theme={null} const parsed = schema.safeParse(body); if (!parsed.success) return error(400); ``` 3. **Verify workspace permissions** ```typescript theme={null} const workspaceId = await normalizeWorkspaceId(wsId, supabase); const permissions = await getPermissions({ wsId: workspaceId, user }); if (!permissions?.containsPermission('manage_projects')) return error(403); ``` ### ❌ DON'T 1. **Don't expose sensitive errors** ```typescript theme={null} // ❌ Bad return NextResponse.json({ error: error.stack }); ``` 2. **Don't skip workspace isolation** ```typescript theme={null} // ❌ Bad: Can access any workspace .delete().eq('id', taskId) // ✅ Good: Workspace-scoped .delete().eq('id', taskId).eq('ws_id', wsId) ``` 3. **Don't reach for the admin client to skip authorization** ```typescript theme={null} // ❌ Bad: bypasses RLS and the caller's permission set const sbAdmin = createAdminClient(); // sync — do not await await sbAdmin.from('workspace_tasks').delete().eq('id', taskId); // ✅ Good: use the session-scoped `supabase` from withSessionAuth so RLS // and getPermissions() still gate the write await supabase .from('workspace_tasks') .delete() .eq('id', taskId) .eq('ws_id', workspaceId); ``` Use the admin client only for trusted server-side work that has already performed its own authorization (e.g. inside `getPermissions`), and remember it is synchronous. ## Related Documentation * [Authentication](/platform/architecture/authentication) * [Authorization](/platform/architecture/authorization) * [tRPC](/platform/architecture/trpc) * [Data Fetching](/platform/architecture/data-fetching) # App Coordination Source: https://docs.tuturuuu.com/platform/architecture/app-coordination How Tuturuuu coordinates central login and API access for internal and external apps. Tuturuuu apps should not share production Supabase service-role keys or browser sessions. Apps coordinate through web-owned auth routes: * Registered internal apps consume cross-app login tokens generated by `apps/web`, then store a Tuturuuu-managed app-session JWT cookie. They must not create app-local Supabase Auth sessions. * The `ttr` CLI also exchanges central-login handoff tokens for Tuturuuu-managed gateway JWTs. It must not store Supabase Auth access or refresh tokens. * External apps must be registered in the Infrastructure dashboard before they can exchange a central-login token for API access. * App coordination bearer tokens are never minted from a cross-app token alone. The exchange route requires a registered `appId` plus app secret, and external-project APIs require explicit API scopes. * Platform admins issue or rotate external app secrets from `Infrastructure -> External Apps`. The secret is shown once; Tuturuuu stores only a hash in root workspace secrets. ## Registered internal app flow Registered internal apps are the apps listed in `packages/utils/src/internal-domains.ts`, such as `cms`, `calendar`, `nova`, `rewise`, `tasks`, `drive`, `finance`, `inventory`, `track`, `learn`, `teach`, `chat`, `mail`, `mind`, `meet`, and `hive`. 1. The app redirects unauthenticated users to `apps/web` login with a `returnUrl` pointing back to the app's `/verify-token?nextUrl=...` route. That return URL must resolve to the satellite app origin, not the central web origin. Registered apps should use `resolveInternalAppUrl()` for their `BASE_URL`/app URL constants so shared environment variables such as `BASE_URL=https://tuturuuu.com` are rejected for satellite hosts instead of minting the host-only app-session cookie on the wrong domain. If `apps/web` receives a registered internal app `returnUrl` that points at `/login` or a protected product route, it must normalize the token handoff back through that app's `/verify-token` route before redirecting. 2. `apps/web` validates the return target and mints the normal one-time cross-app handoff token. 3. The app `/verify-token` route posts only that handoff token to `/api/auth/verify-app-token`. Registered app proxies should perform this step with `consumeVerifyTokenRequest()` before page rendering; the shared React verifier page is only a fallback. 4. The app-local verifier validates the handoff token and sets host-only `tuturuuu_app_session` and `tuturuuu_app_session_refresh` cookies. Satellites that require rewritten `apps/web` API access must call `createPOST('', { verificationBaseUrl: WEB_APP_URL })` so the central verifier also returns the Web-issued `tuturuuu_web_app_session` and `tuturuuu_web_app_session_refresh` cookies. The cookies are `HttpOnly`, `SameSite=Lax`, `Path=/`, and `Secure` in production. 5. The verifier trusts the `Set-Cookie` response and redirects to `nextUrl`. It must not call `supabase.auth.setSession()` and must not receive Supabase access or refresh tokens. The app-session JWT reuses the app-coordination claim shape: `sub`, `email`, `origin_app`, `target_app`, `scopes`, `iat`, `exp`, and `jti`. Verification rejects expired tokens. Target app and scope checks are enforced by the caller, so every API route that opts into app-session auth must bind the token to the audience and scope it expects. Access tokens carry `internal-app:session`. Refresh tokens carry only `internal-app:refresh`; they are rotation material and must not be accepted as API credentials or bearer access tokens. For internal API calls, apps forward the app-session cookie to `apps/web`. Routes that opt into app-session auth use the verified claims as the actor and must keep authorization explicit. Do not pass `ttr_app_...` HS256 JWTs to Supabase as user access tokens. Satellite API proxies should treat the host-only `tuturuuu_app_session` cookie as an authenticated API signal before applying anonymous proxy rate limits; a signed-in app user doing normal dashboard work must not share anonymous read/mutation buckets with public traffic. Every central `apps/web` API consumed by a registered internal app must accept `tuturuuu_app_session` before falling back to Supabase Auth. Routes using `withSessionAuth` should opt into app-session auth; legacy route handlers should use `resolveSessionAuthContext(request, { allowAppSessionAuth: true })` so local satellite apps do not loop between `/login` and product pages or accumulate `api_auth_failed` IP blocks. `apps/drive` follows the centralized-API satellite model: the standalone Drive app owns the workspace shell and Drive explorer UI, while storage list, analytics, upload, delete, share, export, and migration APIs remain in `apps/web /api/v1/workspaces/:wsId/storage/*`. Those routes authenticate Drive's app-session cookie through the shared storage route auth helper before checking `manage_drive`. Use route-specific app-session constraints instead of accepting any registered internal app token. The legacy `allowAppSessionAuth: true` shorthand is audience-bound in `apps/web/src/lib/api-auth.ts`: it maps known internal API path prefixes to their expected satellite app audience and falls back to the `platform` audience for unmapped routes. For example, CLI-only platform APIs should configure `withSessionAuth` with `targetApp: 'platform'` and `requiredScope: 'cli:access'`; satellite APIs should use that satellite's target app and only the scopes intended for that route. When adding a new boolean app-session route for a satellite API, update the shared audience map or use an explicit `{ targetApp, requiredScope }` object in the route. When a registered app forwards request cookies to `apps/web`, it must strip stale `sb-*-auth-token` Supabase cookies whenever `tuturuuu_app_session` is present. Registered app proxies should also call the shared `clearSupabaseAuthCookies()` helper on API, redirect, and normal middleware responses so stale Supabase session cookies are expired on the satellite host. If both `tuturuuu_app_session` and `tuturuuu_web_app_session` are forwarded, the Web-issued cookie is the preferred actor for central `apps/web` API auth; the local app cookie remains the fallback for routes that cannot verify the Web cookie. Registered app proxies must consume `/verify-token` handoff requests before page rendering. Use the shared `consumeVerifyTokenRequest()` helper from `@tuturuuu/auth/proxy` so the proxy validates the handoff token through the app-local `/api/auth/verify-app-token` route, copies the verifier's `Set-Cookie` headers onto the redirect, and sends the browser directly to the safe `nextUrl`. The shared React verifier page remains a fallback for runtimes where proxy middleware is unavailable; it should not be part of the normal registered-app login path. Registered app proxies must run app-session refresh before page redirects and before API proxy guards. When access is close to expiry, or already expired but a refresh cookie is still valid, the proxy posts to the app-local `/api/auth/refresh-app-session` endpoint. The app-local endpoint asks `apps/web` to validate and rotate the Web-issued refresh token, then sets fresh local and Web-issued cookie pairs. The proxy must forward those refreshed cookie values into the current request headers before the API route or page handler runs. A valid refresh cookie must recover an expired access token on the satellite origin. Do not redirect the browser back to `apps/web` for a new cross-app handoff unless both local refresh credentials and Web-issued refresh credentials are missing or invalid. Gateway API routes for registered apps should resolve the app-session actor before any central-web Supabase Auth fallback, and admin-backed checks must use no-cookie admin clients so satellite responses do not inject Supabase Auth cookies back onto the app host. Shared Supabase server-client helpers must treat requests carrying `tuturuuu_app_session` or `Authorization: Bearer ttr_app_...` as app-session requests and avoid constructing cookie-backed Supabase clients for those requests. When an app-session or CLI route needs an admin-backed Supabase client for shared helpers such as `normalizeWorkspaceId()`, wrap that admin client with `attachSupabaseAuthUser()` from `@tuturuuu/auth/app-session` using the verified actor first. This keeps `personal` workspace resolution, permission checks, and shared route helpers on the same authenticated path without duplicating per-route personal-workspace fallback queries. ## CLI app-session flow The native `ttr` CLI uses the same gateway JWT model without a browser cookie: 1. `ttr login` opens `apps/web` at `/api/cli/auth/start`, or prints that URL in `--copy` mode. 2. The authenticated web session mints the normal short-lived cross-app handoff token for target app `platform` and origin `cli`. 3. The CLI posts the handoff token to `/api/cli/auth/verify`. 4. The verify route returns a Tuturuuu-managed access JWT plus a longer-lived refresh JWT. It does not call Supabase magic-link, OTP, or refresh-session APIs. 5. CLI API requests send the access JWT as `Authorization: Bearer ttr_app_...`. App-session-aware internal API routes resolve the actor from verified claims and use explicit authorization. 6. The CLI refreshes shortly before access-token expiry and retries once after a `401`. Refresh rotates both JWTs and updates the saved config. CLI access JWTs include the app-session scope and can authenticate gateway API requests. CLI refresh JWTs include only the CLI refresh scope, so they cannot be used directly as API bearer tokens. Refresh also resolves the user through an admin-backed lookup before minting new JWTs. Routes used by the native CLI must require both the `platform` target app and the `cli:access` scope before passing the request to admin-backed workspace or task handlers. Do not rely on the generic `internal-app:session` scope for CLI-only APIs. ## External app flow 1. Register the external app ID, allowed origins, and allowed API scopes in the Infrastructure dashboard. 2. Issue an app secret and store it in the external app runtime environment. 3. Send users to the centralized web login with a `returnUrl` pointing back to the registered external app origin. 4. The external app receives a short-lived cross-app `token` on its return URL. 5. The external app server calls `POST /api/v1/auth/app-token/exchange` with `appId`, `appSecret`, `token`, optional `requestedScopes`, and `workspaceId` whenever the requested or issued scopes include `external-projects:*`, `external-projects:manage`, `external-projects:publish`, or `external-projects:read`. This server-to-server route must bypass browser challenges and WAF managed challenges. A Cloudflare response with `cf-mitigated: challenge` is an edge block, not an app-token validation failure, and the external app cannot complete it with `fetch`. 6. For external-project scopes, Tuturuuu validates that the workspace has an enabled external-project binding, that the binding's canonical adapter matches the registered external app ID, that the user is a direct `MEMBER` of the linked workspace, and that the user has the required EPM permission in that workspace. Root EPM admins can manage app registrations and bindings from the platform infrastructure UI, but they cannot enter or call a linked external app unless they are also members of that linked workspace. 7. If the user is not yet a workspace member but has a pending `workspace_invites` or `workspace_email_invites` row for the requested workspace, the exchange returns `403` with `code: "PENDING_WORKSPACE_INVITE"`, `workspaceId`, and `invitationUrl`. External apps must handle this code before showing generic no-access copy so the user can accept or reject the invitation in Tuturuuu first. 8. Tuturuuu validates the app secret and cross-app token, then returns a short-lived bearer token for Tuturuuu APIs plus the normalized authorized `workspaceId`. External apps should store only their own app secret and local session material. They should send Tuturuuu API calls with the returned bearer token and should never require production Supabase keys. Third-party or custom Supabase JWT paths are not used for registered internal apps; Tuturuuu JWTs stay at the gateway and internal API layer. External-project admin apps must store the returned authorized workspace ID in their encrypted local admin session and reject the session if it no longer matches the app's configured linked workspace. They should also revalidate stored local sessions against a protected external-project API route before rendering admin UI or proxying admin API calls; if Tuturuuu returns `401`, `403`, or `404`, the app must clear its local session and send the user through the central login flow again. ### App-owned Drive attachments Registered external apps can request `workspace:drive:read` and `workspace:drive:write` without granting their members the broad `manage_drive` workspace permission. The app must be enabled and linked to the requested workspace, and every call still requires the token actor to be a direct `MEMBER`. These scopes expose only the external-app Drive boundary: * `POST /api/v1/workspaces/{wsId}/external-apps/drive/upload-url` * `POST /api/v1/workspaces/{wsId}/external-apps/drive/finalize` * `POST /api/v1/workspaces/{wsId}/external-apps/drive/read-url` * `DELETE /api/v1/workspaces/{wsId}/external-apps/drive` Chat attachments are isolated under `external-apps/{targetApp}/chat/{conversationId}/{attachmentId}/{filename}`. The upload route accepts metadata only and returns a short-lived direct-upload payload for the workspace's configured Supabase Storage or R2 provider. The app must call `finalize` after upload; Tuturuuu reads the actual object metadata, deletes mismatched objects, and returns canonical metadata. Signed URLs are transient response values and must never be logged or persisted. Use `@tuturuuu/internal-api/external-app-drive` for the shared request and direct upload helpers. The centralized login page validates external and internal `returnUrl` targets before it renders the normal sign-in form or account-confirmation handoff. If the target origin is not registered or cannot be resolved, the page shows a warning and asks the user to clear the broken return URL instead of silently falling back to the generic login form. Rewise at `https://rewise.me` and Nova at `https://nova.ai.vn` are registered internal satellites even though their production domains are outside `tuturuuu.com`. Central login, cross-app return validation, and token targeting accept those exact HTTPS origins alongside their registered Tuturuuu subdomains. The external production origins require an exact origin match: HTTP, custom ports, subdomains, hostname look-alikes, and URLs containing user credentials are rejected. Unregistered preview hosts such as `cms-tuturuuu.vercel.app` remain blocked; CMS uses `https://cms.tuturuuu.com`. Localhost and Portless development registrations retain their existing behavior. Regression coverage lives in `packages/utils/src/internal-domains.test.ts`, `packages/auth/src/cross-app/index.test.ts`, and `apps/web/src/app/api/v1/auth/cross-app-return/route.test.ts`. ## Operational notes Server-side internal API calls identify themselves with `User-Agent: Tuturuuu-Internal-API/1.0` unless a caller supplies an agent. Cloudflare Workers do not supply Node's default fetch agent; a missing agent can produce a middleware `400 Bad Request` before route authentication runs. If an SSO handoff succeeds but a satellite workspace page fails with an internal API 400, inspect the outgoing request headers as well as the token exchange. Browser calls keep their native agent. This header does not grant access or replace authentication, authorization, or abuse-policy checks. App-session and external app bearer tokens are signed with `TUTURUUU_APP_COORDINATION_SECRET`. Token lifetimes are configured from the root workspace Infrastructure app at `/{wsId}/app-coordination` on `INFRA_APP_URL`. The older web and TanStack infrastructure routes are removed rather than redirected. The policy is stored in `workspace_secrets` on `ROOT_WORKSPACE_ID` as `APP_COORDINATION_SESSION_POLICY` and cached in process for at most 60 seconds on auth paths. Defaults and caps are: * Internal app access TTL: 28,800 seconds default, min 300, max 86,400. * Internal app refresh TTL: 2,592,000 seconds default, min 86,400, max 7,776,000. * Internal app refresh-early window: 900 seconds default, min 60, max 7,200. * Browser refresh replay grace: 30 seconds default, min 0, max 300. * External app bearer TTL: 28,800 seconds default, min 300, max 86,400. * CLI access TTL: 28,800 seconds default, min 300, max 86,400. * CLI refresh TTL: 7,776,000 seconds default, min 86,400, max 7,776,000. The policy also supports per-internal-app overrides keyed by registered app id for access TTL, refresh TTL, and refresh-early window. If the Infrastructure secret is missing or invalid, runtime code falls back to compatibility environment variables where available and then to defaults. Existing short-lived tokens are not revoked when the policy changes; new cross-app handoffs and refresh rotations pick up the latest cached policy after the cache window. Refresh tokens remain HttpOnly browser cookies or CLI-local tokens. They are not API credentials, are not exposed to browser JavaScript, and should never be sent as bearer access tokens. When registered internal apps are deployed separately, every deployment that mints or verifies `tuturuuu_app_session` must share the same signing material. Prefer setting `TUTURUUU_APP_COORDINATION_SECRET` on `apps/web` and every registered satellite. For compatibility with existing Vercel satellite deployments, the runtime also accepts the server-side Supabase secret as a fallback verifier so satellites without the explicit coordination secret do not fail immediately after cross-app token validation. When rotating an app secret, deploy the new external app environment first, then rotate from Infrastructure. Existing short-lived bearer tokens keep working until they expire, but future exchanges require the new app secret. Cross-app login tokens are user-bound handoff tokens. The database RPC only mints a token for the authenticated caller's own `auth.uid()`; do not use it as a server-side impersonation primitive or as a replacement for app credentials. Registered apps should clear `tuturuuu_app_session` on local logout and expire stale `sb-*-auth-token` cookies on the app host. Browser form logout should redirect back to the app's landing/login page or to the central `/logout` continuation after local cleanup instead of leaving the browser on `/api/auth/logout`. Logout and browser-state recovery redirects must use the app's configured public URL as the fallback when the request reaches the app through a wildcard listener such as `0.0.0.0`, because that listener address is not a browser destination. Shared satellite UI must not assume every app publishes the full `apps/web` `public/media` tree. Shared brand images such as `TuturuuLogo` should use the canonical hosted Tuturuuu asset URL so apps without local `/media/logos/*` files do not produce repeated 404s. All Next apps configured with `next-intl` are checked by `bun i18n:setup-check` (and therefore `bun validate`). Locale-rooted apps must resolve and validate the explicit `locale` override or awaited `requestLocale` segment in `src/i18n/request.ts`, then resolve the document language from `next/root-params` in the locale root layout and validate it with `resolveRootLocale`. Avoid the legacy `setRequestLocale` path. Do not import `next/root-params` from request configuration: Next supports it in Server Components such as the root layout, while next-intl request configuration also runs for Route Handlers. Do not call request-bound `getLocale()` from the root layout because it opts otherwise static locale roots into runtime rendering. Apps without a `[locale]` root segment use `requestLocale` directly; the checker discovers this architecture from the route tree rather than maintaining an app exception list. ## Satellite shell patterns Workspace-scoped satellite apps (`drive`, `calendar`, `tasks`, `finance`, and similar) should reuse the shared satellite provider shell from `@tuturuuu/satellite/providers`. That shell mounts `next-themes` with `system`, `light`, and `dark`, wraps `NextIntlClientProvider`, and wires the shared TanStack Query client. Public or gateway-only apps such as `apps/qr` and `apps/apps` should use the same provider re-export so theme toggles and shared UI chrome behave consistently even when the app does not own workspace auth. Every user-facing browser app that should appear in the Apps gateway or the global Ctrl/Cmd+K launcher must be registered in `packages/utils/src/launchable-apps.ts`. Keep the registry entry current with the app title, slug, aliases, category, production URL, Portless/dev origin, default path, package root, and workspace path resolver when the app has workspace-scoped routes. `apps/apps/src/lib/apps-registry.ts` reads from that shared registry so the gateway and launcher do not drift. Workspace sidebar apps should keep an app-local `structure.tsx` file, but that file should be a thin wrapper around `@tuturuuu/satellite/sidebar-structure`. The shared structure owns the collapsible sidebar behavior, `SidebarProvider` cookies, workspace switcher placement, mobile header, footer actions, hover expansion, back navigation, and user-nav slots. App wrappers should only provide app-specific navigation links, workspace-select routing, billing URL shape, or small brand/content additions such as Mind boards and Rewise branding. This applies to workspace product apps such as Calendar, CMS, Drive, Finance, Inventory, Mind, Rewise, Tasks, Track, Mail, Chat, and Meet. Learn and Teach intentionally keep their education-specific shells. Meet has a public `/:planId` route surface, so workspace-scoped Meet routes must live under `/workspace/:wsId` instead of `/:wsId`. Use `/workspace/:wsId/plans` for Tuturuuu Meet plans and `/workspace/:wsId/meetings` for meeting-room operations, with `/workspace/:wsId` redirecting to the plans route. Keep public plan-detail URLs on the root plan-id surface. For server-side workspace picker data, do not call `@tuturuuu/ui/lib/workspace-actions` from satellite apps. That helper expects Supabase Auth cookies on the app host and returns empty lists when only `tuturuuu_app_session` is present. Instead, use `fetchSatelliteWorkspaces()` from `@tuturuuu/satellite/workspace-actions`, which forwards the incoming request auth to `GET /api/v1/workspaces` on `apps/web`. When the workspace picker resolves a selected workspace, client code may call the legacy detail route `GET /api/workspaces/:wsId`. That route must also opt into app-session auth through `withSessionAuth(..., { allowAppSessionAuth: CURRENT_USER_APP_SESSION_AUTH })` so satellite sessions do not receive `401 Unauthorized` on `personal` or other workspace aliases. When a workspace-scoped satellite page already has an app-session user, shared permission checks must resolve `personal` from that explicit user context rather than falling back to cookie-bound Supabase Auth on the app host. App-session cookies are Tuturuuu-managed, so the app host may not have a local Supabase Auth user even though the user is authenticated. ## Coordination Worker leases and alarm costs `apps/coordination/src/object.ts` stores one SQLite row per hashed entity. Authenticator acquisitions have a five-minute lease and retention deadline; meeting acquisitions have a ten-minute lease with fingerprint retention initially set to two hours. A busy acquisition does not extend those deadlines. A meeting release clears its lease but preserves fingerprint retention; an authenticator release deletes its row. Completion requires the current owner and an unexpired lease. These are coordination/idempotency contracts, not account-spend caps. The alarm deletes an expired row and reads its remaining expiry. Before expiry it schedules that same deadline; after expiry or release it deletes the alarm. It makes no downstream HTTP calls. Controlled probes of the actual object with local SQLite counted two SQL statements and one alarm-set call per early callback. A due callback changed one row and removed the alarm. Twenty-four reconstructed callbacks after deletion made 72 SQL statements (including each constructor's schema statement), zero changed/read rows, and 24 alarm-delete calls, without scheduling new alarms. Twenty-four busy request retries made 72 SQL statements, read 48 rows and set the same alarm 24 times. Count statements, rows and alarm operations separately; they are not interchangeable billing units. A failed alarm write after acquisition leaves the persisted lease intact: 24 reconstructed request retries still do not acquire it twice, but repeat alarm write attempts. A controlled delayed-write race can leave one alarm after an authenticator release; that callback finds no row and removes the alarm without reviving the lease. This is not a durable authenticated stop-fence guarantee. The probes invoke the object directly with mocked alarm methods and local SQLite; they do not certify Worker ingress auth, hosted SQLite billing, delivered alarm retries, clock rollback, or provider-wide emergency shutdown. Existing `apps/coordination/src/worker.test.mjs` exercises the real local Worker/SQLite request contracts. Keep hosted alarm and independent-stop evidence separate. Repeated authenticated requests, or new acquisitions after expiry, can still create billable work. A finite row lifetime does not bound total ingress, entity count or account spend. Verify applicable alerts and an independent operator stop before certifying this service's cost controls; do not configure production billing or resources merely to qualify an adoption candidate. # Authentication Patterns Source: https://docs.tuturuuu.com/platform/architecture/authentication Authentication implementation patterns in the Tuturuuu platform The Tuturuuu platform uses Supabase Auth for user authentication with support for email/password, OAuth providers, multi-factor authentication (MFA), and cross-app token authentication. ## Framework-independent session core `@tuturuuu/auth/app-session-core` owns app-session token creation, target/scope verification and credential extraction from standard `Request`/`Headers`. It loads no Next.js runtime or Supabase client. The existing `@tuturuuu/auth/app-session` entrypoint retains its exports and owns the Next.js cookie/response/logout adapter and Supabase user projection. A new framework adapter should pass the expected app audience, current clock and configured signing secret explicitly. The shared token implementation still uses Node crypto (Cloudflare Node compatibility is required) and retains its existing secret-resolution fallback for compatibility; this extraction does not establish arbitrary edge-runtime support or change identity policy. Fresh allowlist, workspace, MFA and consent checks remain the owning route/service's responsibility. Do not equate verified token claims with complete resource authorization. Focused coverage in `app-session-core.test.ts` exercises the public export with standard requests, denies Next runtime loading, and checks target/signature/expiry and refresh/access separation. Existing `app-session.test.ts` retains adapter cookie/logout regressions. Require applicable exact-head CI and consumer builds before migrating a host app's session adapter. ## Managed review and external accounts The Infrastructure root workspace's Account Security screen lets operators with `manage_internal_accounts` provision two ordinary-user account types. A review account uses a new organization-controlled `@tutur3u.com` email with a verified inbound route, confirmed by the administrator, and a generated password shown only once. Staff domains such as `@tuturuuu.com` and `@xwf.tuturuuu.com` are not eligible because legacy features grant them internal access based on email alone. Existing staff-domain review accounts must stay disabled. The account is intended for app-store review and production QA. An external quick-create sends an email invitation instead; the recipient must accept it before the account can sign in. Both types get a personal workspace from the normal signup trigger, with no extra platform or workspace permissions. Existing users are never overwritten. The panel lists only accounts tagged by this workflow. Disabled review and external accounts are hidden by default; **Show retired** reveals them without changing sign-in access, deleting data, or removing audit history. This display toggle resets on reload and is separate from the internal directory filters. Active accounts and pending external invitations stay visible. Retired staff-domain reviewers remain disabled and cannot be re-enabled or rotated from this panel. Operators may rotate a review password and disable or re-enable a managed account after confirming its exact email. Password rotation does not claim to revoke all existing sessions. The default is an active reviewer account and an unconfirmed external invitation; these rules apply to the Infrastructure admin panel and the mobile and web sign-in surfaces. The external invitation intentionally has no administrator- visible password, so it cannot serve as an unaccepted App Review login. For mobile password sign-in with a review account, enter its exact `@tutur3u.com` email and continue directly to the password screen. The Apple demo account fields contain the credential; Review Notes contain these steps without the password. Mail access for review is scoped to the account's personal workspace and does not grant staff mailbox or root-workspace access. > [!NOTE] > > The server helpers in `@tuturuuu/supabase/next/server` resolve cookies (and an > optional `request` argument) asynchronously, so `createClient()` and > `createDynamicClient()` are **async** and must be awaited. `createAdminClient()` > is synchronous, but its return type allows awaiting, so existing call sites that > `await createAdminClient()` still work — never `await createClient()` results > without the keyword. ## Email sign-in method preference The canonical web login (including satellite app redirects) and Flutter mobile login intentionally prefer password after **Continue with email** for the exact email domains `tuturuuu.com` and `tutur3u.com`. Matching trims surrounding whitespace and ignores case; internal whitespace, subdomains, lookalikes, and appended suffixes do not qualify. Web's existing username shorthand still expands to `@tuturuuu.com`. External email accounts keep the existing code-first default when OTP is enabled; when it is disabled by the existing app policy, password remains the default. This is a product presentation decision, not a trust or permission classification. It does not establish account existence, enable a disabled account, or grant staff access. Password, code, CAPTCHA, rate limits, passkeys and required MFA continue through their existing authentication checks. Supported code sign-in remains available from the password screen; social sign-in, web passkeys and mobile QR remain available from the email screen via Back. Choosing mobile code sign-in requests the initial code through the existing CAPTCHA flow before showing the sent-code screen. CAPTCHA cancellation keeps the prior screen; an ordinary send failure keeps that screen with the error. A rate-limited send opens the code screen with its retry countdown so password fallback remains available. Method switching retains an active code-request cooldown. An explicit password/code choice is remembered per trimmed, case-insensitive email within the current login flow. Back, retries, and switching to another email and back retain that choice; changing to an email with no explicit choice uses its domain default. OTP policy disablement takes precedence over a saved code choice. Editing the email does not switch screens while typing. A fresh login flow/reload starts with domain defaults; choices and credentials are not persisted by this preference. Web code-send failures stay on the code screen for retry instead of silently changing the chosen method to password. ## Authentication Flow ``` ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Client │──1──>│ Supabase │──2──>│ Database │ │ (Browser/App)│ │ Auth │ │ (RLS) │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ │<─────────3───────────│ │ │ Session Token │ │ │ │ │ │──────4──────────────────────────────────────>│ │ Authenticated Request (w/ session) │ │<─────────────────────────────────────────────│ │ Data (filtered by RLS) │ ``` 1. User signs in via Supabase Auth 2. Supabase validates credentials against database 3. Client receives session token 4. Subsequent requests include session token for RLS ## Cross-App Supabase Cookies Production Tuturuuu browser sessions use one canonical Supabase auth cookie for the configured Supabase project and share it across `*.tuturuuu.com` by setting `Domain=.tuturuuu.com`. Portless local development does the same across `*.tuturuuu.localhost` with `Domain=.tuturuuu.localhost`. Keep the cookie host-only for plain `localhost`, preview deployments, and unrelated domains. Registered satellite apps still keep Tuturuuu app-session JWTs as a fallback and API isolation mechanism, so do not remove app-session refresh or handoff paths when updating shared Supabase cookie behavior. ## Web Multi-Account Sessions `apps/web` stores multi-account sessions in a server-owned vault instead of browser `localStorage`. The browser keeps only an HttpOnly device cookie and loads account summaries from `/api/v1/auth/accounts`; Supabase access and refresh tokens remain encrypted in `private.web_account_sessions`. Use `WEB_MULTI_ACCOUNT_SESSION_SECRET` for vault encryption when available. If it is not configured, the server falls back to `SUPABASE_SECRET_KEY`, `SUPABASE_SERVICE_ROLE_KEY`, then `SUPABASE_SERVICE_KEY`. Never expose those values to client components or upload legacy browser-stored sessions into the vault; users should re-add accounts after storage migrations. ### Keeping stored sessions usable Supabase rotates the refresh token every time the browser refreshes a session, so a stored copy is only good until the account it belongs to refreshes. A switch therefore writes the *outgoing* account's live session into its row before calling `setSession` for the incoming one — without that, switching back fails, the row is deleted as unusable, and a retry reports the account as missing entirely. When a switch does fail, the response carries `requiresReauth: true` and the account has already been dropped from the vault. Clients must re-read `/api/v1/auth/accounts` on failure so the dead entry disappears, and should tell the user to sign into that account again rather than surfacing the raw error. A switch redirect is a navigation instruction, not a stored route: `/login` and `/add-account` are rejected for `last_route` on purpose, so never resolve an explicit `targetRoute` through the persistable-route filter or you will drop a sign-in that is still in flight. After switching on Web, resume the incoming account's last Web route when it is still a valid destination. The vault records a current route only when the switch request comes from Web itself; new satellite app paths do not become Web return routes. Saved workspace routes are checked against Web-owned route segments; direct Mail folders such as `/personal/inbox`, `/personal/sent`, and `/personal/drafts`, and old paths with no Web page or redirect such as `/personal/transactions`, fall back to the workspace home (for example, `/personal`). Explicit login handoffs take precedence over the saved route. Legacy app-prefixed paths that Web redirects to a satellite, such as `/personal/mail/sent` and `/personal/finance/invoices`, remain valid. Regression coverage is in `apps/web/src/lib/auth/multi-account/vault.test.ts` and `apps/web/src/lib/auth/multi-account/vault-switch.test.ts`. ### Notification access after account switches Only unclaimed `workspace_invite` notifications (`user_id IS NULL`) can be matched by recipient email, regardless of the row's `scope` or `ws_id`. The caller must have a confirmed email; matching compares lowercase email addresses and does not require membership in the invited workspace. This rule applies to notification lists, unread counts, mark-read updates, deletion, and metadata updates. When a request contains both a supported Supabase auth cookie and an app-session token, notification routes use the current Supabase cookie identity; a valid app session remains the fallback when the cookie is absent. Regression coverage is in `apps/web/src/legacy-api-routes/v1/notifications/access.test.ts` and `apps/web/src/lib/api-auth.test.ts`. ## Sign Up ### Basic Email/Password Sign Up ```typescript theme={null} "use server"; import { createClient } from "@tuturuuu/supabase/next/server"; import { redirect } from "next/navigation"; export async function signUp(formData: FormData) { const supabase = await createClient(); const email = formData.get("email") as string; const password = formData.get("password") as string; const displayName = formData.get("displayName") as string; const { data, error } = await supabase.auth.signUp({ email, password, options: { data: { display_name: displayName, }, emailRedirectTo: `${process.env.NEXT_PUBLIC_APP_URL}/auth/callback`, }, }); if (error) { return { error: error.message }; } redirect("/verify-email"); } ``` ### Client Component ```tsx theme={null} "use client"; import { signUp } from "./actions"; import { useState } from "react"; export function SignUpForm() { const [error, setError] = useState(null); async function handleSubmit(formData: FormData) { const result = await signUp(formData); if (result?.error) { setError(result.error); } } return ( ); } ``` ## Sign In ### Email/Password Sign In ```typescript theme={null} "use server"; import { createClient } from "@tuturuuu/supabase/next/server"; import { redirect } from "next/navigation"; export async function signIn(formData: FormData) { const supabase = await createClient(); const email = formData.get("email") as string; const password = formData.get("password") as string; const { data, error } = await supabase.auth.signInWithPassword({ email, password, }); if (error) { return { error: error.message }; } redirect("/dashboard"); } ``` ### OAuth Sign In The providers offered on the login page and in account linking come from `AUTH_OAUTH_PROVIDERS` in `apps/web/src/lib/auth/oauth-providers.ts` — one list drives the buttons, the `/api/v1/users/me/identities/link/[provider]` route, and the settings linked-accounts card. Adding a provider anywhere means adding it there. > [!WARNING] > > **The Supabase Azure provider must be pinned to a single tenant.** Microsoft > (`azure`) is offered with the `email` scope, and Supabase links an OAuth > identity into an existing account when the provider reports that address as > verified. On the shared multi-tenant `common` issuer that claim is only an > assertion by whichever directory the user signed in from, so anyone who > controls any Azure directory could claim a Tuturuuu address and take over the > matching account. Set the provider's URL override to your tenant, not > `common`. ```typescript theme={null} "use server"; import { createClient } from "@tuturuuu/supabase/next/server"; export async function signInWithOAuth(provider: "google" | "github") { const supabase = await createClient(); const { data, error } = await supabase.auth.signInWithOAuth({ provider, options: { redirectTo: `${process.env.NEXT_PUBLIC_APP_URL}/auth/callback`, }, }); if (error) { return { error: error.message }; } return { url: data.url }; } ``` Client Component: ```tsx theme={null} "use client"; import { signInWithOAuth } from "./actions"; export function OAuthButtons() { async function handleOAuthSignIn(provider: "google" | "github") { const result = await signInWithOAuth(provider); if (result.url) { window.location.href = result.url; } } return (

); } ``` ### OAuth Callback State For provider-specific OAuth callbacks that need to carry ephemeral verifier or CSRF state across a browser redirect, prefer a short-lived HttpOnly cookie scoped to the callback route. When the callback binds external credentials or mutates a workspace, do not let the cookie value be the sole authority: use a signed, expiry-bound state payload that also binds the workspace or account being connected, then require the callback cookie and query `state` to match before verifying that payload. ### Email-Based Auth Recovery Infrastructure admins can use **Infrastructure > Auth Recovery** when a manually reviewed user cannot complete normal OTP or password sign-in because of email-scoped infrastructure blocks, stale Supabase bans, or OTP counters. The support flow is: 1. Search the email on the Auth Recovery page and inspect diagnostics. 2. Create a recovery override with a support reason. Overrides default to 7 days. 3. Keep both **normal login** and **recovery email** enabled unless the case needs only one path. 4. Use **Send recovery email**. The platform sends the email; admins should not copy tokens or links manually. 5. The user can click the recovery link or enter the 6-digit code on `/auth/recovery`. Recovery credentials expire after 15 minutes and are single-use. 6. Revoke the override once the user has recovered access or the case no longer needs support access. Normal-login overrides bypass only email-scoped infrastructure and OTP/password rate-limit blocks. They still enforce malformed request validation, suspicious user-agent checks, Turnstile, password correctness, MFA, and active IP blocks unless an admin separately clears those IP blocks. When a valid override is used, the service also attempts to clear the Supabase auth ban and confirm the email. Recovery-email sign-in stores token and code hashes in private schema tables and audits sends, consumes, rejects, creates, revokes, and Supabase unban/create attempts. The recovery session is created with the existing admin `generateLink` plus detached `verifyOtp` pattern, then normal auth cookies are set. Redirects are limited to sanitized app paths. Database objects live in: * `private.auth_recovery_overrides` * `private.auth_recovery_tokens` * `private.auth_recovery_events` Use `AUTH_RECOVERY_HASH_SECRET` in production when available. The code falls back to existing Supabase server secrets for local development, but do not expose those values to clients or support tooling. Do not run `bun sb:push` for this change; apply migrations through the normal database release process. ### Passkeys Passkeys use Supabase Auth's experimental WebAuthn APIs. Browser clients created through `@tuturuuu/supabase/next/auth-browser` must pass `auth.experimental.passkey: true`; otherwise Supabase rejects `auth.signInWithPasskey()`, `auth.registerPasskey()`, and `auth.passkey.*` calls. `apps/web` owns passkey UX: 1. The public login form exposes an explicit "Continue with passkey" action so users can open the browser passkey picker without relying only on autofill. 2. Account Security in the apps/web settings dialog owns passkey registration, rename, and delete actions. Do not add separate passkey settings pages. 3. Satellite apps should continue to route user authentication through apps/web cross-app auth. Passkeys are bound to the relying party domain, so the central apps/web origin remains the authority for Tuturuuu account passkeys. Production Supabase Auth must have passkeys enabled with these relying party settings: * Relying Party Display Name: `Tuturuuu` * Relying Party ID: `tuturuuu.com` * Relying Party Origins: `https://tuturuuu.com` Local Supabase Auth must also enable passkeys in `apps/database/supabase/config.toml`. The committed local config uses the Portless apps/web origin: * Relying Party Display Name: `Tuturuuu` * Relying Party ID: `tuturuuu.localhost` * Relying Party Origins: `https://tuturuuu.localhost` Restart local Supabase after changing this config; the Auth service reads these settings on startup. Real WebAuthn ceremonies require a secure origin, so test registration and sign-in from `https://tuturuuu.localhost`. UI-only and unsupported-browser paths can still be exercised without registering a credential. Remote Supabase development auth is different: if a cloud Supabase project has captcha protection enabled, passkey sign-in must send a real Turnstile token. The local E2E bypass is honored only when `NEXT_PUBLIC_SUPABASE_URL` points at local Supabase. When testing remote Supabase from `https://tuturuuu.localhost`, the Turnstile site key must authorize that local hostname; Cloudflare Turnstile error `110200` means the widget cannot mint the token Supabase requires. The login UI keeps passkey sign-in blocked while that token is missing; either add the local hostname to the Cloudflare Turnstile widget used by the Supabase project, or point `NEXT_PUBLIC_SUPABASE_URL` at local Supabase for dev passkey testing. ### Web QR Session Handoff QR-based session handoff must never be a public login bootstrap. An unauthenticated browser cannot prove that it belongs to the account scanning the QR code, so public challenge creation would allow QR phishing where an attacker polls a victim-approved challenge and receives the victim's session. The QR challenge endpoints are therefore constrained to authenticated, same-account handoff: 1. `POST /api/v1/auth/qr-login/challenges` validates the request origin and the request-scoped Supabase session before inserting a `qr_login_challenges` row. The row stores a hashed secret, request metadata, `creatorUserId`, and a two-minute expiry. 2. The client renders a `tuturuuu://auth/qr-login` payload that contains the challenge id, one-time secret, and web origin. 3. The signed-in mobile app scans the code from Settings > Session. Mobile must have app lock enabled, then performs local authentication before approving. 4. `POST /api/v1/auth/qr-login/challenges/:id/approve` validates the mobile Bearer session, challenge secret, and `creatorUserId`. The approver must be the same user that created the challenge. 5. The creator polls `GET /api/v1/auth/qr-login/challenges/:id?secret=...`. Once approved, the server consumes the challenge and creates a fresh detached Supabase session via admin `generateLink` plus detached `verifyOtp`. QR challenge rows never store access or refresh tokens. The table is RLS-enabled without anon/authenticated grants; API routes use the service role for challenge state and the request-scoped client to validate both the challenge creator and the mobile approver. ## Sign Out ```typescript theme={null} "use server"; import { createClient } from "@tuturuuu/supabase/next/server"; import { redirect } from "next/navigation"; export async function signOut() { const supabase = await createClient(); await supabase.auth.signOut(); redirect("/login"); } ``` ## Server-side Auth Resolution (`getClaims` first) For server-side route and helper authorization checks, prefer a claims-first flow: 1. Call `supabase.auth.getClaims()` first. 2. Use `claims.sub` as the authenticated user id when available. 3. Fall back to `supabase.auth.getUser()` when claims are unavailable or insufficient. This reduces auth latency on hot API paths while preserving correctness for call sites that still need canonical user resolution. ```typescript theme={null} async function resolveCurrentUserId(supabase: TypedSupabaseClient) { const getClaims = (supabase.auth as { getClaims?: () => Promise }) .getClaims; if (typeof getClaims === "function") { const { data, error } = (await getClaims.call(supabase.auth)) as { data?: { claims?: { sub?: string } }; error?: unknown; }; if (!error && data?.claims?.sub) { return data.claims.sub; } } const { data: { user }, } = await supabase.auth.getUser(); return user?.id ?? null; } ``` When implementing this pattern, feature-detect `getClaims` first. Some tests and older stubs only mock `getUser`, and unconditional `getClaims` calls will break those environments. ## Multi-Factor Authentication (MFA) ### Enable TOTP MFA ```typescript theme={null} "use server"; import { createClient } from "@tuturuuu/supabase/next/server"; export async function enableMFA() { const supabase = await createClient(); // Enroll in MFA const { data, error } = await supabase.auth.mfa.enroll({ factorType: "totp", }); if (error) throw error; return { qrCode: data.totp.qr_code, // Display to user secret: data.totp.secret, // For manual entry factorId: data.id, }; } ``` ### Verify MFA Enrollment ```typescript theme={null} "use server"; import { createClient } from "@tuturuuu/supabase/next/server"; export async function verifyMFAEnrollment(factorId: string, code: string) { const supabase = await createClient(); const { data, error } = await supabase.auth.mfa.challengeAndVerify({ factorId, code, }); if (error) throw error; return { success: true }; } ``` ### MFA Challenge During Sign In ```typescript theme={null} "use server"; import { createClient } from "@tuturuuu/supabase/next/server"; export async function signInWithMFA(email: string, password: string) { const supabase = await createClient(); // Initial sign in const { data: signInData, error: signInError } = await supabase.auth.signInWithPassword({ email, password, }); if (signInError) throw signInError; // Check if MFA is required const { data: factors } = await supabase.auth.mfa.listFactors(); if (factors && factors.totp.length > 0) { const factorId = factors.totp[0].id; // Create MFA challenge const { data: challengeData, error: challengeError } = await supabase.auth.mfa.challenge({ factorId }); if (challengeError) throw challengeError; return { requiresMFA: true, challengeId: challengeData.id, factorId, }; } return { requiresMFA: false }; } ``` ### Verify MFA Code ```typescript theme={null} "use server"; import { createClient } from "@tuturuuu/supabase/next/server"; export async function verifyMFACode( factorId: string, challengeId: string, code: string, ) { const supabase = await createClient(); const { data, error } = await supabase.auth.mfa.verify({ factorId, challengeId, code, }); if (error) throw error; return { success: true }; } ``` ### Mobile MFA Approval Cookies Mobile approval for web MFA is scoped to the Supabase login session that created and consumed the approval challenge. When the web browser polls an approved mobile MFA challenge, store the current JWT `session_id` in the challenge approval metadata. The auth proxy must compare that stored session id with the current request claims before using `ttr_mfa_mobile_approval` to bypass the MFA redirect. Do not treat the approval cookie as a user-scoped remember-me token. A valid cookie only proves that one challenge secret was approved; it must also match the current Supabase session. Central logout responses should expire the approval cookie, and MFA redirects should clear stale approval cookies that do not satisfy the current-session binding. ## Session Management ### Get Current Session ```typescript theme={null} import { createClient } from "@tuturuuu/supabase/next/server"; export async function getSession() { const supabase = await createClient(); const { data: { session }, error, } = await supabase.auth.getSession(); if (error) throw error; return session; } ``` ### Get Current User ```typescript theme={null} import { createClient } from "@tuturuuu/supabase/next/server"; export async function getCurrentUser() { const supabase = await createClient(); const { data: { user }, error, } = await supabase.auth.getUser(); if (error || !user) { return null; } return user; } ``` ### Refresh Session ```typescript theme={null} "use server"; import { createClient } from "@tuturuuu/supabase/next/server"; export async function refreshSession() { const supabase = await createClient(); const { data, error } = await supabase.auth.refreshSession(); if (error) throw error; return data.session; } ``` ## Password Reset ### Request Password Reset ```typescript theme={null} "use server"; import { createClient } from "@tuturuuu/supabase/next/server"; export async function requestPasswordReset(email: string) { const supabase = await createClient(); const { error } = await supabase.auth.resetPasswordForEmail(email, { redirectTo: `${process.env.NEXT_PUBLIC_APP_URL}/auth/reset-password`, }); if (error) throw error; return { success: true }; } ``` ### Reset Password ```typescript theme={null} "use server"; import { createClient } from "@tuturuuu/supabase/next/server"; export async function resetPassword(newPassword: string) { const supabase = await createClient(); const { data, error } = await supabase.auth.updateUser({ password: newPassword, }); if (error) throw error; return { success: true }; } ``` ## Email Verification ### Resend Verification Email ```typescript theme={null} "use server"; import { createClient } from "@tuturuuu/supabase/next/server"; export async function resendVerificationEmail() { const supabase = await createClient(); const { data: { user }, } = await supabase.auth.getUser(); if (!user?.email) { throw new Error("No user email found"); } const { error } = await supabase.auth.resend({ type: "signup", email: user.email, }); if (error) throw error; return { success: true }; } ``` ## Cross-App Authentication The platform supports token-based authentication across different apps using `@tuturuuu/auth/cross-app`. When a new satellite app participates in centralized login, wire both sides in the same patch: * Register the app URL in `packages/utils/src/internal-domains.ts` so `mapUrlToApp(...)` can recognize its `returnUrl`. * Add `apps//src/app/api/auth/verify-app-token/route.ts` so `/verify-token` can exchange the cross-app token for a host-only `tuturuuu_app_session` cookie. When the satellite requires rewritten `apps/web` API access, use `createPOST('', { verificationBaseUrl: WEB_APP_URL })` so the handoff also stores the Web-issued app-session cookie. * Keep `generate_cross_app_token(...)` bound to the authenticated caller (`p_user_id = auth.uid()`) so verify endpoints cannot mint sessions for arbitrary users. * Do not call `supabase.auth.setSession()` in registered internal apps. The verifier route sets the HttpOnly app-session cookie, and satellite UI should fetch user/profile data by forwarding that cookie to central internal APIs. * Registered internal app source must not call `supabase.auth.*` directly. Use `@tuturuuu/auth/app-session` server helpers and `@tuturuuu/internal-api` profile/default-workspace helpers instead; `bun validate` runs the static guard across all registered app `src` directories. * App-session auth is read/update oriented for satellite apps. Destructive workspace operations such as `DELETE /api/workspaces/[wsId]` require a full Supabase session (cookie or bearer) and `manage_workspace_settings`; they do not opt into `allowAppSessionAuth` because the app-session path uses an admin-backed client that would bypass workspace delete RLS. If either piece is missing, centralized login can stall on the web login spinner or land on `/verify-token` with no token-verification endpoint to finish the handoff. ### Generate Cross-App Token `generateCrossAppToken(supabase, targetApp, originApp, expirySeconds?)` is the real signature. It reads the authenticated user from the passed Supabase client, calls the `generate_cross_app_token` RPC, and returns the token string (or `null` on failure). The origin app (`'web'`) mints the token; the target app (`'shortener'`, `'nova'`, `'rewise'`, etc.) verifies it. ```typescript theme={null} import { generateCrossAppToken } from "@tuturuuu/auth/cross-app"; import { createClient } from "@tuturuuu/supabase/next/server"; export async function createShortenerLink() { const supabase = await createClient(); // Generate a token the shortener app can verify (default expiry: 300s). const token = await generateCrossAppToken( supabase, "shortener", // targetApp "web", // originApp 3600, // expirySeconds (optional) ); if (!token) { throw new Error("Failed to generate cross-app token"); } return { url: `${process.env.SHORTENER_APP_URL}/create?token=${token}`, }; } ``` ### Validate Cross-App Token The target app validates the token with `validateCrossAppToken(supabase, token, targetApp)`, which calls the `validate_cross_app_token_with_session` RPC and returns `{ userId }` (or `null`). The target app is responsible for establishing its own session/app-session from that `userId`; the token never carries access or refresh tokens. ```typescript theme={null} import { validateCrossAppToken } from "@tuturuuu/auth/cross-app"; import { createClient } from "@tuturuuu/supabase/next/server"; export async function handleCrossAppRequest(token: string) { const supabase = await createClient(); const result = await validateCrossAppToken(supabase, token, "shortener"); if (!result) { throw new Error("Invalid token"); } // result contains: { userId } return result; } ``` > [!NOTE] > > `@tuturuuu/auth/cross-app` does **not** export a `verifyCrossAppToken` > function. For the browser-side handoff on `/verify-token`, use the exported > `verifyRouteToken({ searchParams, token, router })` helper, which POSTs the > token to `/api/auth/verify-app-token` and lets the verifier route set the > HttpOnly app-session cookie. `revokeAllCrossAppTokens(supabase)` invalidates a > user's outstanding tokens. ## Proxy (Edge Middleware) Authentication In `apps/web` the edge entry point that protects routes lives in `apps/web/src/proxy.ts` (not a `middleware.ts` file). It exports an async `proxy(req)` function plus a `config.matcher`, and Next.js is configured to use this file as the request middleware. The real implementation delegates the heavy lifting to `createCentralizedAuthProxy` from `@tuturuuu/auth/proxy`, then layers on onboarding checks, workspace-slug normalization, guest-route guards, and locale handling. See [Routing](/platform/architecture/routing) for how the proxy coordinates those concerns. The simplified example below shows the core shape: resolve the user from a request-scoped Supabase client and redirect when unauthenticated. Note that `createDynamicClient()` is async and must be awaited. ```typescript theme={null} // apps/web/src/proxy.ts (simplified) import { createClient } from "@tuturuuu/supabase/next/server"; import { type NextRequest, NextResponse } from "next/server"; export async function proxy(request: NextRequest) { const supabase = await createClient(); const { data: { user }, } = await supabase.auth.getUser(); // Protect dashboard routes if (request.nextUrl.pathname.startsWith("/dashboard") && !user) { return NextResponse.redirect(new URL("/login", request.url)); } // Redirect authenticated users from auth pages if (request.nextUrl.pathname.startsWith("/login") && user) { return NextResponse.redirect(new URL("/dashboard", request.url)); } return NextResponse.next(); } export const config = { matcher: ["/dashboard/:path*", "/login", "/signup"], }; ``` The production proxy resolves the user with `resolveAuthenticatedSessionUser(supabase)` and propagates refreshed auth cookies onto every redirect via `propagateAuthCookies(authRes, response)`. Reuse those helpers instead of re-implementing session resolution and cookie forwarding when you extend the proxy. ## Protected Server Component ```typescript theme={null} import { createClient } from '@tuturuuu/supabase/next/server'; import { redirect } from 'next/navigation'; export default async function ProtectedPage() { const supabase = await createClient(); const { data: { user } } = await supabase.auth.getUser(); if (!user) { redirect('/login'); } return (

Welcome, {user.email}

); } ``` ## Client-Side Authentication > [!WARNING] > > `@tuturuuu/supabase/next/client` is **deprecated** for CRUD/storage and may > throw unless a compatibility flag is set. For browser data access, use > `@tuturuuu/internal-api`. For the narrow case where the browser genuinely > needs an auth client (reacting to live auth-state changes), use > `createAuthClient()` from `@tuturuuu/supabase/next/auth-browser`. Do not fetch > product data on the client through raw Supabase clients, and prefer TanStack > Query over `useEffect` for any data fetching. ### useUser Hook (auth-state subscription) Subscribing to Supabase auth-state changes is a legitimate exception to the "no `useEffect` for data fetching" guidance: this hook does not fetch product data, it mirrors the live session into React state. Use `createAuthClient` and subscribe once. ```tsx theme={null} "use client"; import type { User } from "@supabase/supabase-js"; import { createAuthClient } from "@tuturuuu/supabase/next/auth-browser"; import { useEffect, useMemo, useState } from "react"; export function useUser() { const [user, setUser] = useState(null); const [loading, setLoading] = useState(true); const supabase = useMemo(() => createAuthClient(), []); useEffect(() => { // Resolve the current user once on mount. supabase.auth.getUser().then(({ data: { user } }) => { setUser(user ?? null); setLoading(false); }); // Then keep it in sync with live auth-state changes. const { data: { subscription }, } = supabase.auth.onAuthStateChange((_event, session) => { setUser(session?.user ?? null); }); return () => subscription.unsubscribe(); }, [supabase]); return { user, loading }; } ``` > [!NOTE] > > For authorization decisions, always re-verify the user server-side > (`await supabase.auth.getUser()` or the `getClaims`-first pattern above). Client > auth state is for UX only — never trust it as the sole gate for protected data. ### Usage ```tsx theme={null} "use client"; import { useUser } from "@/hooks/useUser"; export function UserProfile() { const { user, loading } = useUser(); if (loading) return

; if (!user) return

Not authenticated

; return

Logged in as {user.email}

; } ``` ## Identity Linking Link multiple auth providers to same account: ```typescript theme={null} "use server"; import { createClient } from "@tuturuuu/supabase/next/server"; export async function linkIdentity(provider: "google" | "github") { const supabase = await createClient(); const { data, error } = await supabase.auth.linkIdentity({ provider, }); if (error) throw error; return { url: data.url }; } ``` ## Best Practices ### ✅ DO 1. **Always check authentication server-side** ```typescript theme={null} const { data: { user }, } = await supabase.auth.getUser(); if (!user) throw new Error("Unauthorized"); ``` 2. **Redirect after authentication** ```typescript theme={null} redirect("/dashboard"); // Don't return sensitive data ``` 3. **Handle errors gracefully** ```typescript theme={null} if (error) return { error: error.message }; ``` 4. **Implement MFA for sensitive operations** ```typescript theme={null} const mfaRequired = await checkMFAEnabled(userId); ``` ### ❌ DON'T 1. **Don't trust client-side auth state alone** ```typescript theme={null} // ❌ Bad if (localStorage.getItem("user")) { /* ... */ } ``` 2. **Don't expose sensitive data in auth redirects** ```typescript theme={null} // ❌ Bad redirect(`/dashboard?apiKey=${apiKey}`); ``` 3. **Don't store passwords** ```typescript theme={null} // ❌ Bad: Let Supabase handle password storage ``` 4. **Don't use `createAdminClient()` for auth operations** ```typescript theme={null} // ❌ Bad: Use regular client const sbAdmin = await createAdminClient(); await sbAdmin.auth.signUp({ ... }); ``` ## Related Documentation * [Authorization](/platform/architecture/authorization) - Permission system * [Supabase Client](/reference/packages/supabase) - Client creation patterns * [RLS Policies](/reference/database/rls-policies) - Database security ## External Resources * [Supabase Auth Documentation](https://supabase.com/docs/guides/auth) * [Next.js Authentication](https://nextjs.org/docs/app/building-your-application/authentication) ## Required MFA for internal accounts Infrastructure administrators can require MFA or make it optional from Internal Accounts. Requiring MFA creates a new verification boundary: existing AAL2 tokens, app sessions, and mobile approvals from before that boundary cannot satisfy the policy. Users without a factor enroll on the web or mobile sign-in screen before continuing. Making MFA optional retains enrolled authenticators; Reset authenticators removes them and requires enrollment again when policy remains required. Administrators cannot change their own policy through this interface. The policy lives in server-owned `auth.users.raw_app_meta_data` under `tuturuuu_required_mfa`. User metadata and caller-supplied cross-app session data are never authorities. Cross-app handoff uses a separately signed, short-lived proof bound to the user and target. Refresh preserves the original verification time and mobile-approval expiry. Administrative authenticator recovery advances the boundary before deleting factors so partial recovery cannot retain old proof. Administrative password recovery also advances the boundary. AI cached identity tokens are disabled for required accounts; those requests use normal verified session authentication. Existing cached AI tokens are rechecked against fresh policy before use. ### Rollout gate Keep `REQUIRED_MFA_POLICY_ENABLED` unset until the migration and all application changes are deployed and verified. Infrastructure also requires the database `required_mfa_enforcement_version()` capability to return `1` before exposing policy changes. The environment gate is an operational release acknowledgement; the database version alone does not prove application readiness. Production migration application remains user-operated. 1. Apply `20260923130000_required_account_mfa.sql` locally and run `apps/database/supabase/tests/required-account-mfa.sql`. 2. Verify web login, factorless enrollment, native enrollment, existing AAL1/AAL2 sessions, mobile approval expiry, authenticator recovery, and making MFA optional. 3. Verify API guards in custom satellite proxies (including Mail, Infra and Calendar), privileged API reads/writes, browser/CLI/external token exchange, refresh, and invitation decisions. Mixed credentials must not borrow assurance from another session or account. 4. Verify direct PostgREST RPC/table access, Storage and Realtime authorization. Existing open Realtime connections require explicit runtime verification during rollout; checking a reconnect alone is not evidence of immediate revocation. 5. Deploy and verify the exact web/satellite source and mobile beta builds, apply the production migration through the authorized operator, then set `REQUIRED_MFA_POLICY_ENABLED=true` on Infrastructure. A denied interactive API request returns `403` with `MFA_REQUIRED`. Mobile refreshes its provider session so its auth router can show verification/enrollment. Policy lookup failures return `503`; they never grant access. Recovery routes stay reachable but retain their own authentication and challenge checks. Machine and webhook credentials retain their independent authentication contracts. The migration adds restrictive policies to existing application, Storage and Realtime authorization tables. New RLS tables added after this migration must also include the `account_required_mfa` restrictive policy; do not assume the PostgREST hook protects Storage or Realtime traffic. ### Cached clients and reconnect Optional accounts keep instant cached startup and offline access. Native startup and resume revalidate the session in the background; a known required policy with missing, stale, or expired proof routes immediately to the MFA screen. Web and satellite clients perform a background profile check on focus/reconnect; a `MFA_REQUIRED` response reloads through the server auth proxy into the challenge. Rotated provider cookies are retained on MFA responses so recovery does not become a password-login loop. An offline device cannot learn that an administrator has newly required MFA or advanced a recovery boundary. Previously accessible cached content remains bounded by the policy last known to that client until it reconnects. This feature does not remotely erase cached files or revoke previously issued public/signed download URLs. Do not describe it as immediate offline revocation. Administrator recovery blocks required accounts while factors or passwords are being changed. After recovery, both primary sign-in and MFA must happen after the new boundary. Existing web and native sessions show **Sign in again** before allowing enrollment. Signed app-session and mobile-approval proofs also retain the current verified factor identity; deleting that factor invalidates those proofs even if an in-flight verification finishes late. A newly enrolled factor cannot restore a proof tied to the removed factor. The rollout flag controls policy mutations only. It is not an enforcement bypass: existing required policy remains authoritative when the flag is off. Server requests fail with `503 AUTH_UNAVAILABLE` if fresh account policy cannot be read, including requests from previously optional accounts. Optional accounts still retain instant cached startup and offline UI; this does not grant offline server access. Cloudflare realtime tickets authorize a specific account, topic and role for 60 seconds. Refresh at 45 seconds rechecks current account policy and resource access on the same socket; reconnects also reauthorize. Durable Object alarms close quiet expired connections. Revocation is bounded by ticket expiry rather than instantaneous. Service publishing and persistence use separate capabilities; browser tickets cannot manufacture server checkpoints. Supabase remains the authentication, database and storage provider, without realtime subscriptions. See [the realtime runbook](/build/devops/programming-realtime-runbook). Administrative policy/recovery metadata transitions use a row-locked database compare-and-swap with a unique generation. A delayed completion cannot overwrite a newer recovery marker, even after the application coordination lease expires. Provider password changes remain GoTrue operations; optional-account password reset does not promise immediate revocation of every previously issued JWT, including when an administrator concurrently enables required MFA. Fresh required-policy and factor checks still apply to every protected request. # Authorization & Permissions Source: https://docs.tuturuuu.com/platform/architecture/authorization How apps/web evaluates workspace-scoped permissions and where those checks are enforced `apps/web` uses workspace-scoped permissions, not a single coarse role string, to decide what a signed-in user can see or mutate. The important implementation detail is that modern permission checks do **not** read `workspace_members.role`. The effective permission set is computed from: * `workspace_role_members` * `workspace_role_permissions` * `workspace_default_permissions` * workspace creator fallback logic in `getPermissions()` `workspace_default_permissions` is typed by `member_type`: * `MEMBER` rows are the normal workspace defaults for members and API keys. * `GUEST` rows are signed-in guest defaults. Missing guest rows mean denied. Guest defaults use the same `workspace_role_permission` catalog as member defaults, including management and `admin` bits, but guests are still denied on dashboard routes that have no mapped permission. For the full workspace model, including URL resolution and API-key auth, see `platform/architecture/workspaces-permissions`. ## Core Helper The main entry point is `getPermissions()` in `packages/utils/src/workspace-helper.ts`. It evaluates permissions in this order: 1. Authenticate the current user with a request-scoped or cookie-scoped Supabase client. 2. Normalize the incoming workspace identifier so `personal` and `internal` become real workspace IDs. 3. Verify caller membership with `verifyWorkspaceMembershipType(..., requiredType: 'ANY')` so the helper can distinguish `MEMBER` from `GUEST`. 4. For `MEMBER`, load role-derived permissions from `workspace_role_members -> workspace_roles -> workspace_role_permissions`. 5. Load workspace-wide defaults from `workspace_default_permissions` using the resolved `member_type`. 6. Load the workspace creator and treat that member as an implicit superuser. If the user is the workspace creator, `getPermissions()` returns the full permission catalog from `packages/utils/src/permissions.tsx`. If the user is not the creator, `getPermissions()` returns the deduplicated union of: * enabled permissions from every assigned workspace role * enabled default workspace permissions for the resolved membership type If the user has no effective permissions and is not the creator, the helper returns `null`. For `GUEST`, role-derived permissions and creator fallback are skipped. The helper only reads `workspace_default_permissions.member_type = 'GUEST'`, so a guest with no enabled guest defaults receives no effective permissions. ## `admin` Is A Permission Bit `admin` is part of the normal permission catalog. It is not a separate evaluator or a special membership table. Once `containsPermission()` sees `admin` in the effective permission list, it treats every permission check as allowed: ```ts theme={null} const isAdmin = permissions.includes('admin'); const containsPermission = (permission: PermissionId) => { return isCreator || isAdmin || permissions.includes(permission); }; ``` That means creator and `admin` behave similarly at call sites, even though they come from different sources: * creator access is implicit and computed in code * `admin` access is explicit and stored like any other permission For guests, `admin` can satisfy a mapped permission route, but it does not open routes with no permission mapping. The dashboard shell stays default-deny for guest routes that cannot be tied to a permission ID. ## Permission Catalog The permission catalog lives in `packages/utils/src/permissions.tsx`. The non-root workspace groups currently include permissions for: * workspace administration * AI * calendar * projects * documents * time tracking * drive * users * user groups * leads * inventory * finance * workforce * transactions * invoices The root workspace adds an extra infrastructure-only group. Some catalog entries are also conditionally exposed for root or `@tuturuuu.com` users. This matters because creator fallback uses the catalog directly. If a permission is added to the product but not added to the catalog, creator fallback and roles UI drift immediately. ## Where Web Pages Use It Typical server-page flow in `apps/web`: 1. Resolve the workspace with `WorkspaceWrapper` or `getWorkspace()`. 2. Call `getPermissions({ wsId })`. 3. Redirect or `notFound()` when the required permission is missing. 4. Pass `containsPermission` / `withoutPermission` into the page composition. Examples: * `apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/roles/page.tsx` * `apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/members/page.tsx` * `apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/settings/page.tsx` * `apps/web/src/app/[locale]/(dashboard)/[wsId]/navigation.tsx` `navigation.tsx` is especially important because a large part of the UX is permission-driven before the user even clicks into a page. Sidebar items are disabled or hidden from `withoutPermission(...)`, and some cross-workspace admin affordances also compare root-workspace permissions. ## Where API Routes Use It There are three common patterns in `apps/web` routes. ### 1. Session auth only Some routes only verify that the caller is signed in, usually through `createClient(request)` or `withSessionAuth(...)`. Use this when the operation is about the current signed-in user or the route does not grant privileged workspace mutations by itself. ### 2. Membership + workspace normalization Many workspace-scoped routes first convert the route param into a canonical workspace ID with `normalizeWorkspaceId(wsId, supabase)` and then verify membership. This is the baseline for routes that accept `personal` or `internal` in the URL but must query by UUID in the database. For non-permission routes that still require protected workspace access, use `verifyWorkspaceMembershipType(...)` from `packages/utils/src/workspace-helper.ts` and keep the default `requiredType` (`MEMBER`). ```ts theme={null} const membership = await verifyWorkspaceMembershipType({ wsId: normalizedWsId, userId: user.id, supabase, }); if (membership.error === 'membership_lookup_failed') { return NextResponse.json({ message: 'Failed to verify workspace access' }, { status: 500 }); } if (!membership.ok) { return NextResponse.json({ message: "You don't have access to this workspace" }, { status: 403 }); } ``` `workspace_members` now supports `MEMBER` and `GUEST`. If a route is not explicitly guest-capable, it should require `MEMBER` and avoid ad-hoc `.from('workspace_members')` checks that only validate row existence. `normalizeWorkspaceId('personal', ...)` also enforces MEMBER membership on the personal-workspace join path by filtering `workspace_members.type = 'MEMBER'`. Course consumption routes are the exception that combine both models: `MEMBER` workspace rows keep normal course access, while `GUEST` rows must pass `workspace_guest_permissions` resource checks such as `course:view`. ### 3. Membership + explicit permission gate Privileged routes call `getPermissions()` after normalization and reject when `containsPermission(...)` fails. This is the pattern to use for settings, finance, roles, infrastructure, and any other restricted mutation surface. If a route writes workspace membership, invitations, roles, or other authorization data with `createAdminClient()` / service-role privileges, enforce the relevant permission before the admin write. A `workspace_members` row alone is never enough for those flows: invite creation and membership-type changes require `manage_workspace_members`, and `workspace_members.type` is protected at the database layer so non-managers cannot self-promote from `GUEST` to `MEMBER`. When a server page or API route uses `createAdminClient()` after a workspace permission gate, the protected row lookup must still prove the row belongs to the authorized route scope. For nested resources, include every trusted parent identifier in the same query or RPC: ```ts theme={null} await admin .schema('private') .from('user_group_posts') .select('id, group_id, workspace_user_groups!inner(ws_id)') .eq('id', postId) .eq('group_id', groupId) .eq('workspace_user_groups.ws_id', normalizedWsId) .maybeSingle(); ``` Do not load a child row by ID with service-role privileges and then separately validate only the supplied parent route data. A mismatched child ID can expose cross-workspace data before later related lookups return empty results. Education authoring and review APIs are also feature-gated. Routes that expose quiz answer keys, learner attempt metadata, flashcards, quiz sets, or other Education admin surfaces must use `apps/web/src/lib/education/access.ts` so `ENABLE_EDUCATION` and `ai_lab` are enforced server-side before any workspace-scoped read or mutation. Mobile and other clients may hide Education affordances, but API routes remain the source of truth for this gate. ## API Keys Reuse The Same Permission IDs External SDK routes use `withApiAuth(...)` in `apps/web/src/lib/api-middleware.ts`. The API key evaluator: * authenticates a workspace API key from `workspace_api_keys` * binds the request to exactly one workspace * computes the effective permissions as `role permissions ∪ MEMBER default permissions` * rejects requests whose `[wsId]` route param does not match the API key's workspace That keeps permission IDs consistent across browser/session routes and external API routes, even though the authentication mechanism is different. ## Current Design Rules * Use `getPermissions()` for feature-level authorization in server pages and session-auth routes. * Use `normalizeWorkspaceId()` before querying workspace-scoped tables from route params. * Do not assume `workspace_members.role` represents the effective permission model in `apps/web`. * Treat `admin` as a permission that short-circuits checks, not as a separate role system. * When adding new privileged features, update both the permission catalog and the UI/routes that consume it. ## Notification email recipient eligibility The Web immediate and batched notification dispatchers admit confirmed external account destinations as well as existing internal destinations. A public account is not excluded because its address is outside `tuturuuu.com`. External admission requires the notification's user ID to resolve to a confirmed Auth email matching the selected destination. Missing confirmation, stale profile or batch addresses, and external email-only targets remain undeliverable. Existing internal email-only invitations retain their transactional behavior. The deliberate root-workspace email rollout remains in force. This recipient rule does not enable notification email for other workspaces, activate a provider, backfill old notifications, or retry previously skipped deliveries. Push keeps its existing workspace and personal Mail rules. At dispatch, each queued email event rechecks the current account email-channel preference, the account workspace-activity preference for workspace events, and the event's workspace preference with account-event fallback. Missing preferences retain the existing RPC default of enabled. Explicit opt-outs stop delivery; failed or malformed preference lookups fail closed. Queued `security_alert` events also respect the account `security_alerts` category. Transactional account updates and invitations do not acquire a marketing preference gate. Dedicated login, recovery, and security mail outside the notification queue keep their own policy. Age limits, current workspace membership, blacklist checks and the EmailService suppression boundary still apply. Notification senders never request a blacklist bypass. Unsubscribe, complaint, bounce and suppression-lookup failures remain owned by EmailService. Provider acceptance and application delivery status do not prove recipient inbox delivery. Regression coverage: `apps/web/src/lib/notifications/email-eligibility.test.ts`, `cron-helpers.test.ts`, and the immediate and batched notification route tests cover confirmed and unconfirmed external destinations, identity mismatch, account/workspace/event/channel opt-outs, suppression and transactional/security distinctions. These fixtures prove source behavior, not production delivery. # Data Fetching Strategies Source: https://docs.tuturuuu.com/platform/architecture/data-fetching When and how to fetch data using RSC, Server Actions, TanStack Query, and Internal API helpers The Tuturuuu platform uses a layered approach to data fetching, choosing the right strategy based on use case, caching requirements, and user experience needs. > [!NOTE] > > The client-side fetch boundary is **TanStack Query (React Query v5) hooks backed > by `@tuturuuu/internal-api` helpers**, which call the REST `/api/v1/...` > endpoints. tRPC in `apps/web/src/trpc` is an **intentional stub** during the > TanStack + Rust migration (it exposes only a `healthCheck` procedure), so this > page does not use `trpc.*` routers for product data. See > [tRPC Implementation](/platform/architecture/trpc) for the scaffold details. For the dedicated TanStack Start frontend plus Rust backend migration, use `platform/architecture/tanstack-rust-migration`. TanStack loaders and server functions are allowed as a BFF layer, while product data ownership moves behind Rust endpoints and `packages/internal-api` facades. ## Heavy Dashboards For queue-heavy dashboards that run expensive row + summary RPCs (for example posts review): * Keep the route page server-only for auth, permissions, and canonical URL normalization. * Move the actual table + summary fetch into a client shell with TanStack Query. * Fetch through `@tuturuuu/internal-api` helpers, not ad-hoc client fetch calls. * Avoid `router.refresh()` for routine list refreshes; prefer query refetch/invalidation. ## Server And Service Orchestration When a server-side data flow coordinates multiple async resources, expected failures, retry/scheduling policy, or replaceable dependencies, use `@tuturuuu/utils/effect` inside the server/shared helper and keep the route or client boundary plain. Effect complements this page's data-fetching strategy; it does not replace React state, TanStack Query, `packages/internal-api`, Zod, or generated database types. Use Effect for server/service orchestration: ```ts theme={null} import { Effect, fromDataError, runEffectAsResult, } from '@tuturuuu/utils/effect'; const program = fromDataError( () => supabase .from('workspace_tasks') .select('id, name') .eq('ws_id', wsId), { code: 'TASKS_READ_FAILED', message: 'Task list read failed.', context: { wsId }, } ); const result = await runEffectAsResult(Effect.map(program, (tasks) => ({ tasks }))); ``` Client components should still call TanStack Query hooks and internal API helpers. Server Components, Server Actions, API routes, cron jobs, and shared packages may use Effect behind their public boundary when it improves typed failure handling or orchestration clarity. ## Builder Migration Pattern (Education Module Groups) For highly interactive editors (for example the course builder with module groups + drag/drop): * Keep the route page as a thin server-side auth/permission gate. * Move list data loading into a client shell backed by React Query. * Use `@tuturuuu/internal-api` helpers as the client fetch boundary (`listWorkspaceCourseModuleGroups`, `listWorkspaceCourseModules`, and reorder helpers). * Avoid `router.refresh()` for routine drag/drop updates; mutate via API and invalidate the corresponding query keys. * When a drag/drop move changes both membership and order, await the membership mutation before firing any follow-up reorder mutations, and invalidate only the affected query keys instead of every list in the builder. * Keep create/update payload contracts explicit (`module_group_id` is required for new course modules). ## Strategy Preference Order Choose the earliest applicable strategy: 1. **Pure Server Component (RSC)** - Read-only, cacheable, SEO-critical data 2. **Server Action** - Mutations returning updated state to RSC 3. **RSC + Client Hydration** - When background refresh needed 4. **React Query (Client-Side)** - Interactive, rapidly changing state 5. **Realtime Subscriptions** - Live updates materially improve UX ## 1. Pure Server Component (RSC) ### When to Use ✅ **Best For:** * Initial page load data * SEO-critical content * Rarely changing data * Read-only operations * Database queries that don't need real-time updates ❌ **Not For:** * Interactive forms * Frequent updates * Client-side state * Real-time data ### Implementation ```typescript theme={null} // app/[locale]/(dashboard)/[wsId]/tasks/page.tsx import { createClient } from '@tuturuuu/supabase/next/server'; export default async function TasksPage({ params, }: { params: Promise<{ wsId: string }>; }) { const { wsId } = await params; // createClient() from @tuturuuu/supabase/next/server is async — always await it. const supabase = await createClient(); // Direct database query in Server Component const { data: tasks } = await supabase .from('workspace_tasks') .select('*') .eq('ws_id', wsId) .order('created_at', { ascending: false }) .limit(20); return (

Tasks

); } ``` ### Caching Strategy ```typescript theme={null} // app/[locale]/(dashboard)/[wsId]/tasks/page.tsx // Revalidate every hour export const revalidate = 3600; // OR generate static params export async function generateStaticParams() { const supabase = await createClient(); const { data: workspaces } = await supabase.from('workspaces').select('id'); return workspaces?.map((ws) => ({ wsId: ws.id })) || []; } ``` ### Loading States ```typescript theme={null} // app/[locale]/(dashboard)/[wsId]/tasks/loading.tsx export default function Loading() { return ; } ``` ### Error Handling ```typescript theme={null} // app/[locale]/(dashboard)/[wsId]/tasks/error.tsx 'use client'; export default function Error({ error, reset, }: { error: Error; reset: () => void; }) { return (

Something went wrong!

); } ``` ## 2. Server Actions ### When to Use ✅ **Best For:** * Form submissions * Mutations with server-side validation * Operations requiring auth checks * Redirects after mutations * Progressive enhancement ❌ **Not For:** * Read operations (use RSC instead) * Complex client-side state management * Real-time updates ### Implementation ```typescript theme={null} // app/[locale]/(dashboard)/[wsId]/tasks/actions.ts 'use server'; import { createClient } from '@tuturuuu/supabase/next/server'; import { revalidatePath } from 'next/cache'; import { redirect } from 'next/navigation'; import { z } from 'zod'; const createTaskSchema = z.object({ name: z.string().min(1).max(255), description: z.string().optional(), listId: z.string(), }); export async function createTask(formData: FormData) { const supabase = await createClient(); // Check authentication const { data: { user }, } = await supabase.auth.getUser(); if (!user) { throw new Error('Unauthorized'); } // Validate input const parsed = createTaskSchema.safeParse({ name: formData.get('name'), description: formData.get('description'), listId: formData.get('listId'), }); if (!parsed.success) { return { error: 'Invalid input' }; } // Perform mutation const { data, error } = await supabase .from('workspace_tasks') .insert({ name: parsed.data.name, description: parsed.data.description, list_id: parsed.data.listId, created_by: user.id, }) .select() .single(); if (error) { return { error: error.message }; } // Revalidate cache revalidatePath(`/[locale]/(dashboard)/[wsId]/tasks`); return { success: true, task: data }; } export async function deleteTask(taskId: string, wsId: string) { const supabase = await createClient(); const { error } = await supabase .from('workspace_tasks') .delete() .eq('id', taskId); if (error) { return { error: error.message }; } revalidatePath(`/[locale]/(dashboard)/${wsId}/tasks`); redirect(`/${wsId}/tasks`); } ``` ### Client Usage ```tsx theme={null} 'use client'; import { createTask } from './actions'; import { useFormStatus } from 'react-dom'; function SubmitButton() { const { pending } = useFormStatus(); return ( ); } export function CreateTaskForm({ listId }: { listId: string }) { async function handleSubmit(formData: FormData) { const result = await createTask(formData); if (result.error) { console.error(result.error); } } return (

<SubmitButton />
    </form>
  );
}
```

## 3. RSC + Client Hydration

### When to Use

✅ **Best For:**

* Initial server render with client updates
* Data that changes frequently
* Combining SEO with interactivity
* Background refresh patterns

### Implementation

The server renders initial data and passes it as `initialData` to a TanStack
Query hook. Background refresh is handled by Query's `refetchInterval` — **not**
a `useEffect` + `setInterval` loop. AGENTS.md forbids `useEffect` for data
fetching.

```typescript theme={null}
// app/[locale]/(dashboard)/[wsId]/tasks/page.tsx
import { createClient } from '@tuturuuu/supabase/next/server';
import { TaskListClient } from './TaskListClient';

export default async function TasksPage({
  params,
}: {
  params: Promise<{ wsId: string }>;
}) {
  const { wsId } = await params;
  // Async server client — await it.
  const supabase = await createClient();

const { data: initialTasks } = await supabase
    .from('workspace_tasks')
    .select('*')
    .eq('ws_id', wsId);

return <TaskListClient initialTasks={initialTasks || []} wsId={wsId} />;
}
```

```tsx theme={null}
// app/[locale]/(dashboard)/[wsId]/tasks/TaskListClient.tsx
'use client';

import { useQuery } from '@tanstack/react-query';
import { listWorkspaceTasks } from '@tuturuuu/internal-api/tasks';
import type { Database } from '@tuturuuu/types';

type Task = Database['public']['Tables']['workspace_tasks']['Row'];

export function TaskListClient({
  initialTasks,
  wsId,
}: {
  initialTasks: Task[];
  wsId: string;
}) {
  // Server-rendered rows seed the cache via initialData; Query owns refreshes.
  const { data: tasks = initialTasks } = useQuery({
    queryKey: ['workspaces', wsId, 'tasks'],
    queryFn: () => listWorkspaceTasks(wsId),
    initialData: initialTasks,
    staleTime: 30 * 1000,
    // Background refresh without a manual setInterval.
    refetchInterval: 30_000,
  });

return (
    <div>
      {tasks.map((task) => (
        <div key={task.id}>{task.name}</div>
      ))}
    </div>
  );
}
```

The client hook fetches through an `@tuturuuu/internal-api` helper (which calls
the REST `/api/v1` endpoint) rather than re-running Supabase queries from the
browser. This keeps authorization on the server and gives Query a single,
cacheable fetch boundary.

## 4. TanStack Query (Client-Side)

### When to Use

✅ **Best For:**

* Interactive dashboards
* Rapidly changing data
* Complex client-side state
* Optimistic updates
* Automatic background refetching

❌ **Not For:**

* SEO-critical content
* Initial page load (prefer RSC)

### Implementation with Internal API helpers

Client queries call `@tuturuuu/internal-api` helpers, which hit the REST
`/api/v1/...` endpoints where authorization lives. This is the actual fetch
boundary in `apps/web` — there are no `trpc.tasks.*` / `trpc.boards.*` routers
(tRPC is a [stub](/platform/architecture/trpc)).

```tsx theme={null}
'use client';

import { useQuery } from '@tanstack/react-query';
import { listWorkspaceTasks } from '@tuturuuu/internal-api/tasks';

export function TaskList({ wsId }: { wsId: string }) {
  const {
    data: tasks,
    isPending,
    error,
  } = useQuery({
    queryKey: ['workspaces', wsId, 'tasks'],
    queryFn: () => listWorkspaceTasks(wsId),
    staleTime: 5 * 60 * 1000, // Consider data fresh for 5 minutes
    refetchOnWindowFocus: true,
    refetchInterval: 30_000, // Refetch every 30 seconds
  });

if (isPending) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

return (
    <div>
      {tasks?.map((task) => (
        <TaskCard key={task.id} task={task} />
      ))}
    </div>
  );
}
```

### Query Key Conventions

Use stable array query keys:

```typescript theme={null}
// ✅ Good: Specific, cacheable
queryClient.getQueryData(['tasks', wsId, { listId, completed: false }]);

// ❌ Bad: Too generic
queryClient.getQueryData(['tasks']);
```

### Thin Server Gate + Client Query Shell

For dense dashboard surfaces that need URL-driven filtering, pagination, and frequent background refreshes, prefer a **thin server gate** plus a **client query shell**:

1. Keep the route page server-side only for auth, permission checks, redirects, and metadata.
2. Move interactive data loading into client hooks backed by TanStack Query.
3. Back those hooks with workspace-scoped Internal API helpers instead of ad hoc `fetch('/api/...')` calls.
4. Store queryable UI state such as `page`, `pageSize`, `q`, `sortBy`, and `path` in `nuqs`.
5. Invalidate query keys after mutations instead of relying on `router.refresh()`.

This pattern is now the default for file-explorer style dashboard pages such as Drive, where the user expects immediate client-side updates while the server still owns authorization.

### Optimistic Updates

Use `useMutation` with the `queryClient` cache helpers. Drive the mutation
through an `@tuturuuu/internal-api` helper so the write goes through the same
authorized REST boundary as reads.

```tsx theme={null}
'use client';

import { useMutation, useQueryClient } from '@tanstack/react-query';
import { updateWorkspaceTask } from '@tuturuuu/internal-api/tasks';

export function TaskCheckbox({ task, wsId }: { task: Task; wsId: string }) {
  const queryClient = useQueryClient();
  const taskKey = ['workspaces', wsId, 'tasks', task.id];
  const listKey = ['workspaces', wsId, 'tasks'];

const toggleComplete = useMutation({
    mutationFn: (input: { completed: boolean }) =>
      updateWorkspaceTask(wsId, task.id, input),

// Optimistically update before the server responds
    onMutate: async (input) => {
      await queryClient.cancelQueries({ queryKey: taskKey });

const previous = queryClient.getQueryData<Task>(taskKey);

queryClient.setQueryData<Task>(taskKey, (old) =>
        old ? { ...old, completed: input.completed } : old
      );

return { previous };
    },

// Rollback on error
    onError: (_err, _input, context) => {
      if (context?.previous) {
        queryClient.setQueryData(taskKey, context.previous);
      }
    },

// Refetch after success or error
    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: taskKey });
      queryClient.invalidateQueries({ queryKey: listKey });
    },
  });

return (
    <input
      type="checkbox"
      checked={task.completed}
      onChange={() => toggleComplete.mutate({ completed: !task.completed })}
    />
  );
}
```

### Cache Invalidation

```typescript theme={null}
const queryClient = useQueryClient();

// Invalidate a specific task
queryClient.invalidateQueries({ queryKey: ['workspaces', wsId, 'tasks', '123'] });

// Invalidate the workspace task list
queryClient.invalidateQueries({ queryKey: ['workspaces', wsId, 'tasks'] });

// Reset a query to its initial state
queryClient.resetQueries({ queryKey: ['workspaces', wsId, 'tasks'] });

// Refetch immediately
queryClient.refetchQueries({ queryKey: ['workspaces', wsId, 'tasks'] });
```

> [!NOTE]
>
> Query keys are prefix-matched by default, so invalidating
> `['workspaces', wsId, 'tasks']` also invalidates every more specific key under
> it (e.g. `['workspaces', wsId, 'tasks', taskId]`). Keep keys ordered
> broad → narrow so partial invalidation stays predictable.

## 5. Realtime Subscriptions

### When to Use

✅ **Best For:**

* Collaborative features
* Chat applications
* Live dashboards
* Multiplayer features
* Notification systems

❌ **Not For:**

* Infrequent updates
* Static content
* SEO-critical data

### Implementation

The **initial fetch is a TanStack Query hook** (through an `@tuturuuu/internal-api`
helper), never a `useEffect` fetch. A `useEffect` is used only for the
subscription **lifecycle** (a genuine side effect), and the realtime payloads
mutate the **query cache** so the live data and the cached data stay in sync.

```tsx theme={null}
'use client';

import { useEffect } from 'react';
import { useQuery, useQueryClient } from '@tanstack/react-query';
import { createClient } from '@tuturuuu/supabase/next/client';
import { listWorkspaceTasks } from '@tuturuuu/internal-api/tasks';
import type { Database } from '@tuturuuu/types';

type Task = Database['public']['Tables']['workspace_tasks']['Row'];

export function RealtimeTaskList({ wsId }: { wsId: string }) {
  const queryClient = useQueryClient();
  const queryKey = ['workspaces', wsId, 'tasks'];

// Initial + cached data comes from Query, not a useEffect fetch.
  const { data: tasks = [] } = useQuery({
    queryKey,
    queryFn: () => listWorkspaceTasks(wsId),
  });

useEffect(() => {
    const supabase = createClient();

// Subscription lifecycle is a side effect — payloads update the cache.
    const channel = supabase
      .channel(`workspace-tasks-${wsId}`)
      .on(
        'postgres_changes',
        {
          event: '*',
          schema: 'public',
          table: 'workspace_tasks',
          filter: `ws_id=eq.${wsId}`,
        },
        (payload) => {
          queryClient.setQueryData<Task[]>(queryKey, (prev = []) => {
            if (payload.eventType === 'INSERT') {
              return [...prev, payload.new as Task];
            }
            if (payload.eventType === 'UPDATE') {
              return prev.map((task) =>
                task.id === payload.new.id ? (payload.new as Task) : task
              );
            }
            if (payload.eventType === 'DELETE') {
              return prev.filter((task) => task.id !== payload.old.id);
            }
            return prev;
          });
        }
      )
      .subscribe();

return () => {
      channel.unsubscribe();
    };
  }, [wsId, queryClient]);

return (
    <div>
      {tasks.map((task) => (
        <div key={task.id}>{task.name}</div>
      ))}
    </div>
  );
}
```

## TanStack Query Guidelines

The shared `QueryClient` lives in `apps/web/src/trpc/query.ts` (`makeQueryClient`)
and ships a default `staleTime` of 30s plus rate-limit-aware retry handling.
Override per-query options only when a surface needs different freshness.

### Query Configuration

```typescript theme={null}
const { data } = useQuery({
  queryKey: ['workspaces', wsId, 'tasks'],
  queryFn: () => listWorkspaceTasks(wsId),

// How long data is considered fresh
  staleTime: 5 * 60 * 1000, // 5 minutes

// Garbage-collection time after the query has no observers.
  // (React Query v5 renamed `cacheTime` to `gcTime`.)
  gcTime: 10 * 60 * 1000, // 10 minutes

// Refetch on window focus
  refetchOnWindowFocus: true,

// Refetch on network reconnect
  refetchOnReconnect: true,

// Background refetch interval
  refetchInterval: false, // or number in ms

// Retry failed requests
  retry: 3,

// Only run if condition is true
  enabled: !!wsId,
});
```

### Prefetching

```typescript theme={null}
// In a parent component or on hover
const queryClient = useQueryClient();

await queryClient.prefetchQuery({
  queryKey: ['workspaces', wsId, 'tasks', taskId],
  queryFn: () => getWorkspaceTask(wsId, taskId),
});
```

### Parallel Queries

```typescript theme={null}
'use client';

import { useQuery } from '@tanstack/react-query';
import { listWorkspaceTasks, listWorkspaceTaskBoards } from '@tuturuuu/internal-api/tasks';
import { getWorkspaceMembers } from '@tuturuuu/internal-api/workspaces';

export function Dashboard({ wsId }: { wsId: string }) {
  const tasks = useQuery({
    queryKey: ['workspaces', wsId, 'tasks'],
    queryFn: () => listWorkspaceTasks(wsId),
  });
  const boards = useQuery({
    queryKey: ['workspaces', wsId, 'task-boards'],
    queryFn: () => listWorkspaceTaskBoards(wsId),
  });
  const members = useQuery({
    queryKey: ['workspaces', wsId, 'members'],
    queryFn: () => getWorkspaceMembers(wsId),
  });

// All three queries run in parallel
  const isPending = tasks.isPending || boards.isPending || members.isPending;

if (isPending) return <div>Loading...</div>;

return <div>{/* Render dashboard */}</div>;
}
```

For many dynamic queries, prefer `useQueries` over hand-listing hooks.

### Dependent Queries

```typescript theme={null}
'use client';

import { useQuery } from '@tanstack/react-query';
import { getWorkspaceTask, listWorkspaceTaskAssignees } from '@tuturuuu/internal-api/tasks';

export function TaskDetails({ wsId, taskId }: { wsId: string; taskId: string }) {
  const { data: task } = useQuery({
    queryKey: ['workspaces', wsId, 'tasks', taskId],
    queryFn: () => getWorkspaceTask(wsId, taskId),
  });

const { data: assignees } = useQuery({
    queryKey: ['workspaces', wsId, 'tasks', taskId, 'assignees'],
    queryFn: () => listWorkspaceTaskAssignees(wsId, taskId),
    enabled: !!task, // Only run after the task is fetched
  });

return <div>{/* Render task details */}</div>;
}
```

> [!NOTE]
>
> The exact helper names above (`getWorkspaceTask`, `listWorkspaceTaskAssignees`,
> `getWorkspaceMembers`) are illustrative — browse `packages/internal-api/src`
> for the real exports before wiring a hook. `listWorkspaceTasks` and
> `listWorkspaceTaskBoards` exist today.

## Decision Matrix

## Best Practices

### ✅ DO

1. **Start with RSC**
   ```typescript theme={null}
   // Default to server components
   export default async function Page() { ... }
   ```

2. **Use specific query keys**
   ```typescript theme={null}
   queryClient.getQueryData(['tasks', wsId, { listId, status: 'active' }]);
   ```

3. **Set appropriate staleTime**
   ```typescript theme={null}
   queryClient.setQueryDefaults(['user-profiles'], { staleTime: 5 * 60 * 1000 }); // 5 minutes
   ```

4. **Implement optimistic updates for better UX**
   ```typescript theme={null}
   queryClient.setMutationDefaults(['tasks'], { onMutate: async (newData) => { queryClient.setQueryData(['tasks'], newData); } });
   ```

5. **Invalidate narrowly**
   ```typescript theme={null}
   // Target the specific task, not the whole workspace tasks tree
   queryClient.invalidateQueries({
     queryKey: ['workspaces', wsId, 'tasks', taskId],
   });
   ```

6. **Fetch through Internal API helpers**
   ```typescript theme={null}
   // Route client reads/writes through @tuturuuu/internal-api, not raw
   // fetch('/api/...') or trpc.* routers.
   useQuery({ queryKey: ['workspaces', wsId, 'tasks'], queryFn: () => listWorkspaceTasks(wsId) });
   ```

### ❌ DON'T

1. **Don't use client fetching for SEO content**
   ```typescript theme={null}
   // ❌ Bad: Client-side fetch for blog
   useEffect(() => fetchBlogPosts(), []);
   ```

2. **Don't skip staleTime**
   ```typescript theme={null}
   // ❌ Bad: Refetches too often
   useQuery({ ... }) // defaults to 0ms staleTime
   ```

3. **Don't invalidate globally**
   ```typescript theme={null}
   // ❌ Bad: Refetches everything
   queryClient.invalidateQueries();
   ```

4. **Don't use Realtime for infrequent updates**
   ```typescript theme={null}
   // ❌ Bad: Waste of resources
   realtime.channel('user-profiles-changes')
   ```

## Related Documentation

* [tRPC Implementation](/platform/architecture/trpc) — the minimal `healthCheck`
  stub kept alive during the migration (not a product fetch path)
* [TanStack + Rust Migration](/platform/architecture/tanstack-rust-migration)
* [Supabase Client](/reference/packages/supabase)
* [Server Components](https://nextjs.org/docs/app/building-your-application/rendering/server-components)
* [TanStack Query](https://tanstack.com/query/latest)

# Effect Orchestration
Source: https://docs.tuturuuu.com/platform/architecture/effect

How Tuturuuu uses Effect for server and service workflows

# Effect Orchestration

Tuturuuu uses [Effect](https://effect.website/docs/quickstart) as the default
tool for new or substantially edited TypeScript server/service orchestration
when it adds concrete value: typed expected errors, explicit dependencies,
retry/scheduling policy, resource boundaries, or controlled concurrency.

Import Effect through the platform entrypoint:

```ts theme={null}
import {
  Effect,
  Layer,
  runEffectAsResult,
  TuturuuuEffectError,
} from '@tuturuuu/utils/effect';
```

Do not import directly from `effect` in app or package code unless the curated
entrypoint is missing a module that the code genuinely needs. Add that module to
`@tuturuuu/utils/effect` first when it should become a platform pattern.

## Where Effect Fits

Use Effect for:

* Server-side workflows that coordinate several async operations.
* Expected failures that should stay typed until the route/action boundary.
* Service dependencies that need live, test, or mock implementations.
* Retry, timeout, scheduling, queue, stream, or concurrency policy.
* Shared packages that expose additive orchestration subpaths such as
  `@tuturuuu/ai/effect` or `@tuturuuu/trigger/effect`.

Avoid Effect for:

* React UI state and component-local event handlers.
* TanStack Query client fetching and mutation wrappers.
* Zod validation and generated database type contracts.
* Simple pure helpers, formatting utilities, and one-line transforms.
* Existing stable call sites where a rewrite adds churn without improving an
  error boundary or dependency boundary.

## Boundary Pattern

Keep route handlers and client helpers familiar. Build the richer orchestration
inside shared server modules, then convert to existing result shapes at the
boundary.

```ts theme={null}
import {
  Effect,
  fromDataError,
  runEffectAsResult,
} from '@tuturuuu/utils/effect';

export async function loadWorkspaceResult(query: Parameters<typeof loadWorkspace>[0]) {
  return runEffectAsResult(
    Effect.map(loadWorkspace(query), (workspace) => ({ workspace }))
  );
}
```

API routes should still return sanitized public errors. Use
`serializeTuturuuuEffectError` or `runEffectAsResult` to cross the route/action
boundary, and log only sanitized server-side context through the existing
logging path.

## Reliability Policy

Use the Tuturuuu helpers for common server/service reliability controls before
dropping to raw Effect operators. They keep retry, timeout, and concurrency
defaults consistent across packages while still returning typed expected errors.

```ts theme={null}
import {
  Effect,
  forEachConcurrently,
  fromPromise,
  withTuturuuuRetry,
  withTuturuuuTimeout,
} from '@tuturuuu/utils/effect';

const request = fromPromise((signal) => fetch(url, { signal }), {
  code: 'UPSTREAM_REQUEST_FAILED',
  message: 'Upstream request failed.',
});

const resilientRequest = withTuturuuuRetry(
  withTuturuuuTimeout(request, {
    code: 'UPSTREAM_REQUEST_TIMEOUT',
    duration: '10 seconds',
    message: 'Upstream request timed out.',
  }),
  { times: 2, delay: '250 millis' }
);

const hydrateRows = (rows: readonly { id: string }[]) =>
  forEachConcurrently(
    rows,
    (row) => Effect.map(resilientRequest, (response) => ({ row, response })),
    { concurrency: 4 }
  );
```

Retries should be reserved for transient failures such as network errors,
timeouts, `408`, `425`, `429`, and `5xx` responses. Do not retry validation
errors, authorization failures, tenant-binding failures, or non-idempotent
mutations unless the owning service has explicit idempotency protection.

## Services And Layers

For dependencies that need replacement in tests, define a service tag and a live
layer near the owning package:

```ts theme={null}
import { Context, Effect, Layer } from '@tuturuuu/utils/effect';

interface BillingServiceShape {
  readonly charge: (amount: number) => Promise<{ ok: true }>;
}

class BillingService extends Context.Tag('BillingService')<
  BillingService,
  BillingServiceShape
>() {}

export const BillingLive = Layer.succeed(BillingService, {
  charge: async (amount) => ({ ok: true }),
});

export const chargeEffect = (amount: number) =>
  Effect.gen(function* () {
    const billing = yield* BillingService;
    return yield* Effect.promise(() => billing.charge(amount));
  });
```

Prefer package-specific entrypoints such as `@tuturuuu/ai/effect` when the
service belongs to a domain package. Keep the root `@tuturuuu/utils/effect`
entrypoint for shared primitives and small platform helpers.

## App Integration

* Server Components may call Effect programs from server-only helpers and then
  render plain data.
* Server Actions may return existing action result shapes after
  `runEffectAsResult`.
* API routes may use Effect for orchestration but must keep existing auth,
  tenant binding, Zod parsing, and sanitized response rules.
* Client components should consume normal props, TanStack Query hooks, or
  `packages/internal-api` helpers. Do not push Effect requirements into React
  component trees.

## Verification

When adding an Effect workflow:

1. Test the Effect program with a provided service/layer or a fake service.
2. Test the boundary conversion with `runEffectAsResult`.
3. Run the owning package test and type-check commands.
4. Finish with `bun validate` when TypeScript, JavaScript, package metadata, docs,
   or repo guidance changed.

# Routing
Source: https://docs.tuturuuu.com/platform/architecture/routing

How apps/web resolves locale, workspace identity, and canonical dashboard URLs

`apps/web` routing has two jobs:

* map browser-friendly URLs onto the App Router file structure
* canonicalize workspace identity before pages and APIs touch the database

For the complete permission model that sits on top of this routing layer, see `platform/architecture/workspaces-permissions`.

The TanStack migration keeps a route ownership manifest for this route tree.
Use `platform/architecture/tanstack-rust-migration` before moving any
`apps/web/src/app` route to `apps/tanstack-web` or `apps/backend`.

## File Structure Versus Browser URLs

The dashboard uses the App Router structure:

```text theme={null}
apps/web/src/app/[locale]/(dashboard)/[wsId]/...
```

Users do not need to think about the internal route groups. What they see in the browser is effectively:

```text theme={null}
/{workspace-segment}/...
```

where `workspace-segment` is one of:

* a workspace UUID
* `personal`
* `internal`

## Proxy Responsibilities

`apps/web/src/proxy.ts` is the routing coordinator at the edge.

It is responsible for:

* locale negotiation
* auth-cookie propagation during redirects
* onboarding and root-path redirect behavior
* canonical workspace slug redirects
* workspace-aware request preprocessing before the App Router handles the page

## Workspace Slug Canonicalization

Two workspace IDs are intentionally rewritten into stable slugs:

* the current user's personal workspace UUID -> `personal`
* `ROOT_WORKSPACE_ID` -> `internal`

That means the proxy may receive a UUID but still redirect the browser onto a slugged URL for consistency.

### Why this matters

* links are shorter and more stable
* users do not need to memorize internal UUIDs for personal/internal workspaces
* page code can still resolve those slugs back to real UUIDs with shared helpers

## Default Workspace Redirect

When an authenticated user hits `/`, the proxy uses `getUserDefaultWorkspace()` to find the best landing workspace.

Resolution order:

1. `user_private_details.default_workspace_id`, if it still exists and the user is a member
2. the user's personal workspace

The redirect target becomes:

* `personal` for a personal workspace
* `internal` for the root workspace
* the UUID for a normal workspace

## Page-Level Workspace Resolution

Server pages should not parse workspace slugs manually.

Use `WorkspaceWrapper`, which calls `getWorkspace()` and gives the page:

* `workspace`
* canonical UUID `wsId`
* `isPersonal`
* `isRoot`

If the lookup fails, the wrapper calls `notFound()`.

This makes page code simpler because the page receives the normalized UUID even when the URL used `personal` or `internal`.

## API-Level Workspace Resolution

Route handlers should use `normalizeWorkspaceId()`.

That helper:

* accepts the raw route segment
* converts `personal` into the authenticated user's personal workspace UUID
* converts `internal` into `ROOT_WORKSPACE_ID`
* preserves request-scoped auth when passed a request-derived Supabase client

The common rule is:

* URLs may use slugs
* database reads and writes should use canonical UUID workspace IDs

## Routing And Authorization Are Separate Layers

Routing tells the app **which** workspace the request targets.

Authorization tells the app **whether** the current actor may view or mutate something inside that workspace.

That separation is deliberate:

* `WorkspaceWrapper` / `getWorkspace()` handle membership and identity resolution for pages
* `normalizeWorkspaceId()` handles route-param normalization for APIs
* `getPermissions()` handles feature-level access control

Do not collapse those responsibilities into one helper or assume a normalized workspace ID automatically means the caller has feature permissions.

# Satellite Apps
Source: https://docs.tuturuuu.com/platform/architecture/satellite-apps

How satellite apps (contacts, forms, pay, tasks, …) authenticate, proxy their APIs, render under Cache Components, and take ownership of a feature from apps/web.

## What a satellite is

`apps/web` is the central platform app. A **satellite** is a separate Next app on
its own subdomain that owns one slice of the product and shares the session with
web through cross-app auth.

`apps/contacts` (`contacts.tuturuuu.com`, port `7827`) is the largest example: it
owns the entire `workspace_users` CRM surface (`/[wsId]/users/*` plus
`workforce`). `apps/web` no longer has a users section at all.

Shared logic lives in packages so both apps run one implementation:

### Two shapes of ownership

Contacts kept shared logic in packages because `apps/web` still needed some of
it. `apps/forms` (`forms.tuturuuu.com`, port `7828`) is the other shape: a
**clean hard move**. The forms product had no consumers outside itself, so the
feature moved wholesale with no extracted package, and `apps/web` retained
nothing but redirects.

Forms also owns **every API route it needs** — `/api/v1/workspaces/[wsId]/forms/*`
and the public `/api/v1/shared/forms/*` — instead of proxying them to web. Two
things forced that and are worth copying:

* Forms tables live in the Postgres **`private` schema**
  (`getPrivateFormsClient(supabase) => supabase.schema('private')`), so every
  read needs the admin client. An anon/RLS client cannot reach them at all, which
  means proxying to web buys nothing.
* The public form-filling surface at `/f/<shareCode>` is served to **anonymous
  respondents**. See the public-API note under API proxying below.

Legacy public links (`tuturuuu.com/<locale>/shared/forms/<shareCode>`) get a
permanent **308** from web's proxy, issued before the auth proxy runs so
respondents and social crawlers are never bounced to `/login`.

`apps/infrastructure` follows the same hard-ownership rule for internal platform
operations. Infrastructure-only routes such as AI-credit administration,
translation tooling, and holiday administration live in that app. Shared route
shapes that its UI needs, including the root-admin workspace list and workspace
secret management, also have local Infrastructure handlers protected by the
Infrastructure app session and root-workspace membership. Do not add a new
Infrastructure UI call that depends on an `apps/web` fallback rewrite.

## Shared UI translations

Each satellite must ship English and Vietnamese messages for the shared UI it
renders, including its sidebar, account menu, settings dialog, workspace picker,
and lazy dialogs. A product-only namespace check does not cover that shell.
Copy missing shared values from the corresponding `apps/web/messages` locale;
preserve existing app-specific copy and scoped bundles rather than copying an
unrelated app's entire `common` namespace.

Mind's import-aware guard runs in the i18n workflow's namespace check:

```bash theme={null}
bun scripts/i18n-rendered-keys.js
bun scripts/i18n-rendered-keys.js apps/mind --json
```

The JSON report lists every traced module and each required key's source files.
The guard follows runtime imports, re-exports and literal lazy imports from
Mind's App Router entrypoints, excluding API routes and type-only imports. It
checks both locales. It conservatively includes conditional branches and all
runtime imports of a reached module; it does not simulate React props or tree
shaking. Unimported screens and other apps do not contribute requirements.

Template keys expand against Web's matching key family. Finite property keys
such as autosave labels are collected from their literal definitions. Translator
props in framework-independent children have explicit namespace bindings in
`scripts/i18n-rendered-keys.js`; update these when adding another wrapper/child
pair. Unknown dynamic expressions and unresolved workspace imports fail the
guard and need a source trace. This check is currently enabled for Mind; other
satellites retain their existing namespace checks until their translator bindings
are qualified. It does not prove runtime behavior or replace an app's CI build.

`scripts/i18n-rendered-keys.test.js` covers missing keys in either locale, dynamic
families, forwarded translators, unrelated-screen exclusion and the real Mind
closure with its pre-fix keys removed. After adding keys with `bun i18n:add`, run
`bun i18n:sort` and retain only intentional bundle changes.

## Cache Components: `connection()`, not `dynamic`

> [!WARNING]
>
> Every Next app runs with `cacheComponents` (PPR) enabled.
> `export const dynamic` and `export const revalidate` are **rejected at build
> time** — `await connection()` is the only way to opt into request-time rendering.

This matters more than it looks. Supabase-js issues `fetch()` under the hood, so
**every server-component query is a fetch**. A page with no dynamic signal gets
prerendered — and the prerender runs with **no cookies**:

```text theme={null}
Workspace not found: personal
[WorkspaceHelper] Failed to fetch workspace
Error: During prerendering, fetch() rejects when the prerender is complete
```

That is a real production failure mode (it broke `contacts/users/database`).

**Rules**

* Add `await connection()` as the first statement of any authed page or layout
  that touches Supabase, `getPermissions`, `getWorkspace`, or the app session.
  A dynamic *layout* does **not** make its child pages dynamic — each page needs
  its own call.
* `cacheComponents` also prerenders **GET route handlers**. A Supabase-backed GET
  route with no dynamic signal is statically generated and its response is baked
  in at build time. Add `await connection()` there too; every API route should
  report `ƒ (Dynamic)` in the build output.
* Where it fits, prefer the true PPR shape: a static shell with the dynamic part
  inside `<Suspense>` and `await connection()` **inside** the suspended
  component. `apps/meet/[planId]` is the reference.
* Unit tests call pages and handlers outside a request scope, where
  `connection()` throws. Stub it in the app's vitest setup while keeping every
  other export:

```ts theme={null}
vi.mock('next/server', async (importOriginal) => ({
  ...(await importOriginal<typeof import('next/server')>()),
  connection: vi.fn().mockResolvedValue(undefined),
}));
```

> [!NOTE]
>
> `bun validate` does not compile Next apps, so it cannot see any of this. Require
> the app's real build in CI on the exact PR head when you change routes, pages,
> or dependencies. Do not run builds on this machine.

### Browser refresh replay-store outages

The central browser refresh route (`POST /api/v1/auth/cross-app-session/refresh`)
requires available replay state before issuing replacement credentials. First use
and reuse within the configured `browserRefreshReplayGraceSeconds` continue;
reuse after grace returns **401**. Signature, target, refresh scope, expiry,
current-user and required-MFA checks remain in force.

Missing replay storage or failed acquisition, read or write returns **503** with
`Cache-Control: no-store`, code `APP_SESSION_REFRESH_UNAVAILABLE`, and the stable
error `App session refresh temporarily unavailable`. This response contains no
credentials, performs no admin user lookup or token minting, and does not set or
clear session cookies. It indicates a temporary inability to authorize refresh;
it is not evidence that the session credential is invalid. The route does not
extend the configured grace interval or retry storage operations.

Satellite `createRefreshPOST` preserves central **503** and **403 MFA\_REQUIRED**
without minting local credentials or changing cookies. Other non-success refresh
responses remain invalid credentials; unknown errors are not relabeled as replay
storage outages. There are no automatic retries.

The shared proxy keeps using independently verified, unexpired, target-bound
access only after its existing current-MFA check and an expiry check after the
refresh response arrives. Replacement cookies are verified at response time. A refresh outage grants no
session authority and never admits expired access. With no valid access, protected
API and page paths return the same no-store **503**, without login redirects,
credential minting or cookie changes. Custom page proxies and Lettin's login
redirect preserve this distinction. Outer app proxies preserve terminal error
responses before locale, workspace and invite handling. Native runtime proxy
bridges also return terminal responses unchanged, including status, body and
headers; pending request-context cookies must not be appended. Bridge regression
coverage lives in each migrated app's `src/runtime/proxy-bridge.test.ts` and checks
403/503 identity, no-store, no cookies, no redirect and no handler dispatch.
Existing anonymous API exceptions remain anonymous; a refresh outage does not create an authenticated
identity there. Healthy rotation and the existing shared-provider cookie cleanup
policy are unchanged.

Custom page adapters consume session claims only from an `ok: true` refresh
result, including an explicitly permitted fallback. A failed result never permits
reconstructing a session from the original request cookies: access can remain
cryptographically valid after its required MFA proof expires during an await.
Generic invalid-refresh and expired-token failures follow the existing login
redirect policy; dedicated MFA and availability failures retain their terminal
responses. Forms and Storefront public pages, and Forms, Storefront and Inventory
anonymous API exceptions, retain their existing policies. Finance returns terminal
auth failures before deployment pinning, so skew protection cannot add a deployment
cookie to an outage response; healthy responses still receive deployment pinning.

Regression coverage lives in the central refresh route suite, shared cross-app
server suite, `packages/auth/src/proxy/refresh-outage.test.ts`,
`packages/auth/src/proxy/refresh-authority.test.ts`, every custom adapter's
`proxy-refresh.test.ts`, and the Finance, Learn, Calendar and Lettin suites.
Adapter coverage composes real signing, verification and final deadline checks
with mocked provider, refresh transport and locale boundaries. CI and browser
acceptance are required before claiming deployed outage behavior.

The CLI refresh endpoint has an explicit outage-continuation policy and is outside
this browser decision. Changing it requires a separate policy review.

Regression coverage lives in
`apps/web/src/app/api/v1/auth/cross-app-session/refresh/route.test.ts`: unavailable
storage/acquisition/read/write responses, stateful first use, the configured grace
boundary, post-grace rejection, and retained invalid-credential controls. These
handler fixtures do not establish hosted Redis or browser behavior.

## Auth: resolve the actor from the app session

A registered satellite must resolve the acting user from Tuturuuu app-session
auth — never from `@tuturuuu/utils/user-helper`, whose `getCurrentUser` /
`getCurrentWorkspaceUser` read Supabase auth directly. The `internal-app-auth`
guard in `bun validate` enforces this.

When a shared helper needs the actor, give it an **injectable** `userId` instead
of letting it resolve one:

```ts theme={null}
// satellite page
const actor = await getSatelliteAppSessionUser('contacts');
const user = actor?.id
  ? await getWorkspaceUserLinkForUser(wsId, actor.id)
  : null;
```

`getCurrentWorkspaceUser` (web) now delegates to that same
`@tuturuuu/utils/workspace-user-link` helper, so there is one implementation and
web behavior is unchanged.

Workspace-user link repair must not require an optional platform display name.
New auth users initially have only a `public.users.id`; the repair RPC derives a
workspace profile name from display name, private full name, handle, email, and
finally a stable generic fallback. Membership remains mandatory, and the repair
does not create or broaden workspace access.

### Personal workspace aliases in APIs

API routes that accept `personal` must preserve the same authenticated actor
while resolving that alias. Use the actor-explicit helpers from
`@tuturuuu/satellite/workspace-access`: they verify the intended target app
before resolving `personal`, UUID, handle, or internal workspace identifiers,
and fall back to the request-scoped Supabase session only when no app-session
token is present. An invalid, expired, or mismatched app-session token must not
fall through to another identity. Passing only a cookie-backed client on a
satellite loses the app-session identity and incorrectly reports `User not
authenticated`.

Route handlers must keep both values returned by the auth context: use the
explicit `user` for `getPermissions({ user, wsId })`, and the returned admin
client for workspace-scoped data operations. A `request` property is not an
actor for a satellite app session.

An admin-backed app-session client has no `auth.uid()`. Therefore a satellite
must not call a public RPC wrapper whose authorization derives from
`auth.uid()`. Call the private actor-aware RPC and pass the verified user ID in
its actor argument while preserving the route response shape.

### The actorless-call trap

> [!WARNING]
>
> `getWorkspace(id)` and `getPermissions({ wsId })` called **without** an actor fall
> back to a cookie-backed Supabase client. In a satellite that client is
> **anonymous** — the session is an app-session JWT, not a Supabase auth cookie.

The lookup then returns `null`, the page 404s, and — because the render aborts
with Supabase fetches still in flight — those fetches outlive it and surface as:

```text theme={null}
Workspace not found: personal
Error: During prerendering, fetch() rejects when the prerender is complete
digest: 'HANGING_PROMISE_REJECTION'
```

The second error is a *symptom*, not the cause. Chasing the "hanging fetch" leads
nowhere — there is no stray `setTimeout`/`after()` anywhere in the tree. The cause
is the missing actor.

This is also why **a satellite must not use the shared
`@tuturuuu/ui/custom/workspace-wrapper`**: it calls bare `getWorkspace(wsId)`
internally, so every page rendering it inherits the bug. That took down the whole
`apps/contacts` users surface (20 pages) in production.

Give each satellite a `src/lib/workspace.ts` that resolves the actor once and
threads it through, plus an app-local wrapper that uses it:

```ts theme={null}
export async function getContactsWorkspace(id: string) {
  const user = await getSatelliteAppSessionUser('contacts');
  if (!user?.id) return null;
  return getWorkspace(id, { useAdmin: true, user });
}

export async function getContactsWorkspacePermissions(wsId: string) {
  const user = await getSatelliteAppSessionUser('contacts');
  if (!user?.id) return null;
  return getPermissions({ user, wsId });
}
```

`scripts/check-internal-app-auth.js` enforces both halves (no shared wrapper, no
actorless workspace, permission, or alias-normalization call) across every
registered satellite. Compatibility fallback is centralized in audited auth
wrappers and the shared workspace-access helper; individual routes are not
allowlisted.

### One actor for the workspace shell

The workspace layout is the authentication boundary. Pass its verified user ID
into `NavbarActions` and render notifications from that same identity in
expanded, collapsed, and mobile navigation. Do not independently re-resolve
authentication for the notification bell: two resolvers can disagree and hide
the bell while the rest of the layout remains authenticated.

### Reserved route placeholders

Selection sentinels such as Contacts group ID `~` are navigation state, not
database identifiers. Parallel routes can begin rendering child pages before a
parent selection gateway replaces them, so app-local workspace wrappers must
stop those child loaders before any UUID filter runs. The parent gateway remains
responsible for group selection and selected-group navigation.

## API proxying — and the catch-all trap

A satellite's `next.config.ts` has a **fallback** rewrite sending any unmatched
`/api/:path*` to web. That is how contacts reaches endpoints it does not own.

> [!WARNING]
>
> Never add a catch-all page (`[...slug]`) under `[locale]/[wsId]` in a satellite
> that proxies `/api/*`.

### The proxied web route must accept app sessions

> [!WARNING]
>
> A web route that satellites proxy has to opt into app-session actors.
> `createClient(request)` deliberately returns an **unauthenticated** client as soon
> as the forwarded request carries the host-only `tuturuuu_app_session` cookie, so
> `resolveAuthenticatedSessionUser` / `getPermissions({ request })` find no user and
> the route answers `401 Unauthorized` — from every satellite, while the identical
> code keeps working on `tuturuuu.com`.

Opt in explicitly, then authorize on workspace permissions (the calling app grants
nothing by itself):

```ts theme={null}
// Workspace routes
const access = await resolveWorkspaceRouteAccess(req, wsId, [
  'manage_workspace_members',
]);
if (!access.ok) return access.response;

// Or, for withSessionAuth routes
export const GET = withSessionAuth(handler, {
  allowAppSessionAuth: CURRENT_USER_APP_SESSION_AUTH,
});
```

The tell-tale symptom is **one action failing inside an otherwise-working panel**.
Workspace member invites returned "Unauthorized" from Inventory and every other
satellite while the member list, roles, and invite links worked, because those
routes had been migrated and `members/invite` had not. A narrow allowlist behaves
the same way for the apps it omits: `{ targetApp: 'teach' }` on the user-group
storage route 401'd every Contacts request for group files. When you fix one route,
sweep the rest of its surface:

```bash theme={null}
grep -rL "resolveWorkspaceRouteAccess\|allowAppSessionAuth" \
  "apps/web/src/app/api/workspaces/[wsId]/members"
```

### Public (anonymous) API routes on a satellite

> [!WARNING]
>
> The standard satellite `proxy.ts` `/api` branch calls
> `refreshAppSessionForRequest`, which returns `ok: false` when a request carries
> no session credentials at all — and the branch turns that into a **401**. Any
> genuinely public endpoint must be excluded, or it is unreachable for the
> anonymous users it exists to serve.

`apps/storefront` and `apps/forms` both do this: match the public paths, and skip
the app-session refresh unless the caller happens to be signed in.

```ts theme={null}
const isPublicSharedFormApi = isPublicSharedFormApiRequest(request);
const shouldRefreshAppSession =
  !isLocalAuthApi &&
  (!isPublicSharedFormApi || hasApiSessionCredentials(request));
```

Abuse protection for those routes is Turnstile plus rate limiting inside the
handler, not the app session. Note the same trap applies to *page* auth: forms
treats `/f/<shareCode>` as a public path so anonymous respondents are not
redirected to `/login`.

Related: a signed-in user on a satellite has an app-session JWT, **not** a
Supabase cookie. Code that asks `supabase.auth.getUser()` to decide "is this
person signed in" silently answers *no* for everyone. Forms' response-copy
email flow hit exactly this and had to read the actor from the app session.

Next checks `fallback` rewrites **only after dynamic routes**. So
`[locale]/[wsId]/[...catchAll]` happily matches
`/api/v1/workspaces/personal/settings` as `locale="api"`, `wsId="v1"` — shadowing
the proxy. The `[wsId]` layout then calls `getWorkspace('v1')` and every proxied
API call 404s:

```text theme={null}
[WorkspaceHelper] Failed to fetch workspace: { workspaceId: 'v1', … }
```

Put non-migrated-route redirects in the app's `proxy.ts` middleware instead. It
handles `/api` in an earlier branch, so it structurally cannot shadow the proxy.
Contacts lists what it owns in `CONTACTS_OWNED_ROUTE_PREFIXES`; anything else
under `/[wsId]` redirects to web with path and query preserved.

> [!NOTE]
>
> Add an entry to that list whenever you migrate a module, or the middleware will
> bounce the freshly-migrated route straight back to web. Mind prefix-vs-exact
> matching: a bare `users` entry that prefix-matches makes every `/users/*` path
> look owned, so non-migrated routes 404 instead of redirecting.

## Translations

A satellite that renders broad shared UI must be in the **checked** `APPS` list
in `scripts/i18n-namespace-check.js`, not `UNCHECKED_APPS`.

Scanning only the app's own source cannot see namespaces used *inside*
`@tuturuuu/ui` or `@tuturuuu/satellite`. Miss one and it surfaces as a runtime
`MISSING_MESSAGE` in production rather than a CI failure — which is exactly how
contacts shipped without the `notifications` namespace.

> [!WARNING]
>
> Having the namespace is not enough — the namespace can be **half-empty**.

The shell components (`user-nav-client`, `sidebar-structure-header`,
`workspace-select`, `settings-dialog-shell`) read their strings through a **bare**
`useTranslations()` and then call `t('common.dashboard')`. A bare translator
carries no namespace argument, so the key-level scan cannot attribute those keys
to a namespace: it only requires them from apps listed in
`BARE_ROOT_KEY_APP_SCOPES`. Since `common` was scoped to nobody, the keys were
required of **no app at all**.

Contacts therefore passed the namespace check (it *had* `common`) while missing
850+ keys inside it, and shipped `MISSING_MESSAGE: common.dashboard`,
`common.logout`, `nav-upgrade-dialog.*`, and `settings.back_to_app` to production.

An app that renders the full dashboard shell belongs in
`BARE_ROOT_KEY_FULL_SCOPE_APPS`, which requires every bare root-qualified key the
shared packages can request. Use `keyExceptions` to opt out of product surfaces
the app does not render.

For narrower shared surfaces, register the owning apps in the matching scoped
consumer set. The workspace members-and-roles panel uses
`SATELLITE_WORKSPACE_SETTINGS_APPS`, so `bun i18n:namespace-check` requires its
`ws-members.*` and `ws-roles.*` keys from every satellite that mounts that
panel. The source scanner also follows typed shared helpers such as
`t: (key: string) => string`; otherwise helper-owned labels can evade a normal
`useTranslations()` scan and render their key paths in production. Keep
conditional product-only branches covered with an explicit key exception
rather than weakening the whole consumer scope.

## Moving a feature from web to a satellite

Resolve every import to an **absolute path** before moving anything. A
`from '@/'` grep is not sufficient; each of these traps cost a broken build or a
failing test:

* **Relative-sibling** imports (`../../x`) — invisible to a `@/` grep.
* **Dynamic** imports — `await import('@/…')` has no `from` clause.
* **Side-effect** imports — `import '@/lib/dayjs-setup'` has no `from` clause.
* **npm deps of the extracted file** must be added to the *target package*.
* **`vi.mock` paths** silently break: a test mocking `@/lib/x` stops intercepting
  once the extracted module imports the package copy directly, so the real module
  runs unmocked.

Then classify each external dependency:

**1. Already a re-export shim**

Rewrite the import straight to the package it re-exports.

**2. Used only by the moving module**

Move it along. A satellite maps `@/` to its own `src`, so the specifier often
needs no change at all.

**3. Still used by the origin app**

Extract it to `@tuturuuu/users-core` (server) or `@tuturuuu/users-ui`
(client) and point both apps at it. Keep a re-export shim in the origin app
when many files import it; repoint directly when only a few do.

**4. Mutually coupled modules**

Move them **together**. Preserving their relative layout keeps every
cross-import valid with no rewrites at all.

Finish with: `connection()` on data pages, the owned-routes list, removing the
origin app's nav entry, an i18n backfill, active docs inventory, focused local
non-build checks, and exact-commit CI type/lint/test and real Next build evidence.
Rust/TanStack migration manifests remain frozen until explicitly resumed.

> [!NOTE]
>
> Deleting pages from `apps/web` leaves `apps/web/.next/types/validator.ts` stale,
> so type-check fails on paths that no longer exist. `rm -rf apps/web/.next`.

## Debugging a satellite in production

The Vercel CLI is the fastest path to a root cause:

```bash theme={null}
bun add -g vercel
vercel ls contacts --scope tuturuuu
vercel logs <deployment-url> --scope tuturuuu --json
```

Both contacts incidents above were diagnosed straight from those logs — the
`workspaceId: 'v1'` in a `WorkspaceHelper` error is what exposed the catch-all
shadowing the API proxy.

### Lettin deployment verification diagnostics

The Lettin deployment verifier retains its strict health, expected-version, D1,
R2, login, and public-world route checks. Failed attempts record only an ordinal,
fixed stage and failure category, HTTP status, and parse/match/timeout booleans.
It never logs response bodies, exception text, request URLs, or version-tag values.
Twelve attempts retain the 15-second request timeout and five-second delay,
including the final delay. Exhaustion still fails deployment verification; these
diagnostics identify a failed boundary without proving a provider-side cause.
The colocated verifier fixtures run through Lettin’s owning Vitest configuration
and cover those boundaries without live requests.

### Verified refresh authority

The shared Next.js proxy retains the exact access credential selected by the
portable verifier. Initial selection keeps bearer, Web cookie, then local cookie
precedence, with fallback only after cryptographic/scope/target rejection. Current
MFA rejection of the selected credential does not select another actor or proof.
Forwarded Authorization and refresh access input use that selected credential.
A successful rotation verifies the resulting cookies independently of the old
bearer before forwarding its selected replacement.

The required-MFA owner returns whether current policy required the verified proof,
and the bound proof when required, from its existing account/factor lookup. The
proxy carries the earlier of access expiry and required proof expiry. Optional
MFA proofs do not shorten access authority. A local time comparison after the
last asynchronous lookup or refresh response must precede forwarding headers or
cookies; no extra provider request, retry or authority cache supplies this check.
An explicit `now` option remains deterministic at every comparison.

`packages/auth/src/proxy/refresh-authority.test.ts` covers mixed credentials,
expiry during factor lookup, required proof expiry during a 503 while access is
still valid, signed replacement deadlines, optional policy, fixed time, invalid
signature/scope and current-factor rejection of a healthy replacement. The
existing refresh-outage tests retain status and cookie boundaries. Central route
unit tests replace request log draining with a typed pass-through to keep detached
log persistence outside the unit-test provider boundary. These tests require an
admitted isolated execution environment; source presence alone is not execution
evidence.

# SePay Integration
Source: https://docs.tuturuuu.com/platform/architecture/sepay-integration

Architecture and implementation notes for the SePay finance integration.

## Goal

The SePay integration connects a workspace to SePay through OAuth, provisions
webhooks without manual SePay UI setup, ingests transaction events, and writes
normalized finance records into the platform.

## Flow

1. A workspace admin starts the OAuth flow.
2. The platform stores an opaque state token in a short-lived HttpOnly cookie.
3. The OAuth callback exchanges the code, encrypts the SePay tokens, stores
   them in `sepay_connections`, and redirects the browser back to the workspace
   integrations surface with a compact success or error query flag.
4. The platform syncs SePay bank accounts into `sepay_wallet_links`.
5. The platform provisions a SePay webhook endpoint and stores the hashed token
   in `sepay_webhook_endpoints`.
6. SePay sends transaction webhooks to `/api/v1/webhooks/sepay/[token]`.
7. The webhook route validates auth, resolves the workspace and wallet,
   deduplicates/retries safely through `sepay_webhook_events`, classifies the
   transaction, and inserts `wallet_transactions`.

## Data Model

### `sepay_connections`

Stores the workspace-level OAuth connection, encrypted access and refresh
tokens, scopes, expiry, and connection status.

### `sepay_wallet_links`

Maps SePay bank-account metadata to workspace wallets so webhook deliveries can
resolve to the correct wallet without manual per-event routing.

### `sepay_webhook_endpoints`

Stores the hashed endpoint token, optional linked wallet, SePay webhook id, and
active/rotation state for workspace webhook routing. The endpoint `ws_id` is
treated as immutable after insert so existing event rows cannot drift across
workspaces through later admin-backed updates.

### `sepay_webhook_events`

Stores the raw webhook payload, dedupe keys, processing status, failure reason,
and the created `wallet_transactions.id` when processing succeeds.

## Processing Rules

* Incoming `transferAmount` values are normalized to a positive magnitude.
* Direction is derived from `transferType`, not from the sign of
  `transferAmount`.
* `transferType: "in"` is written as a positive wallet transaction amount.
* `transferType: "out"` is written as a negative wallet transaction amount.
* Webhook retries must atomically claim `failed` events by `id`, `ws_id`,
  `status`, and empty `created_transaction_id` before creating a wallet
  transaction. A competing retry that loses the claim is treated as a duplicate.
* `received` events become retriable once they are older than the stale-event
  TTL and still do not have a `created_transaction_id`; stale retries must use
  the same atomic claim with a stale `received_at` predicate.
* `processed` and `duplicate` rows are treated as non-replayable duplicates.
* Auto-classification failures must not block ingestion; the route falls back to
  an uncategorized category.
* SePay AI enrichers reserve fixed workspace-scoped AI credits before each
  classifier/tagger model call and release the reservation on failure, so
  webhook retries do not leak credits or block on long model latency.

## Operational Notes

* Required runtime env vars are documented in
  [Secrets & Configuration](/build/devops/secrets-and-configuration).
* The end-to-end validation flow lives in
  [SePay Testing Guide](/build/devops/sepay-testing-guide).
* OAuth callback state is a short-lived HMAC-signed payload bound to the
  workspace id and stored in a callback-scoped HttpOnly cookie. The callback
  must require the cookie value and query `state` to match before validating the
  signature, expiry, and workspace.
* SePay account sync follows cursor pagination and retries `429` responses using
  SePay's `x-sepay-userapi-retry-after` header, but request-path retry sleeps
  are capped at 2 seconds each so sync and webhook-provisioning handlers do not
  stay open for provider-supplied long delays.
* Webhook provisioning only accepts numeric SePay bank-account ids
  (`bank_account_id` or numeric `id`) and best-effort deletes the remote webhook
  if local persistence of the resulting webhook id fails.
* Fallback uncategorized transaction categories are created through a
  workspace/name/direction advisory-lock RPC so concurrent webhook workers reuse
  one canonical fallback category id.
* Eventless webhook dedupe uses a short `received_at` window for proactive
  duplicate detection, but the post-insert unique-key recovery path can still
  reopen the older canonical row when SePay retries the same event later.

# Core Architectural Decisions
Source: https://docs.tuturuuu.com/platform/architecture/system-design/architectural-decisions

Deep dive into the four fundamental architectural choices that define Tuturuuu's system design

This document explains four foundational architectural decisions that inform Tuturuuu's system design. Each section explores the **rationale**, **detailed justification**, and the **alternatives considered**.

> [!WARNING]
>
> **Conceptual vs. implemented.** This page teaches the reasoning behind several
> classic patterns (microservices, event-driven, hexagonal, modular monolith).
> Tuturuuu adopts some of these in pragmatic, partial form and deliberately does
> **not** adopt others. Each "In Tuturuuu" callout below states what is actually
> true of the codebase today; clearly labelled examples are illustrative and may
> not map to a real file path. Trust the code over any architectural prose.

The maintained runtime is Next.js Web and its satellite apps. Rust
(`apps/backend`) and TanStack Start (`apps/tanstack-web`) are paused and not in
use. Docker setup is inactive and the Docker cron runner is retired. Retained
migration designs describe a possible future, not live traffic or a current
setup requirement. See the [active runtime map](/build/devops/active-runtime).

## 1. Decomposition Into Independently Deployable Apps

Tuturuuu is organized as a Turborepo monorepo containing many independently
deployable applications under `apps/*` plus shared `packages/*`. This is **not**
a textbook distributed-microservices system with per-service data stores and an
inter-service event bus; rather, each app is a conventional deployment unit, and
the apps share one Supabase project for auth and data. The microservices
*reasoning* below explains why we split along app boundaries, with each "In
Tuturuuu" callout grounded in what is actually true today.

### Core Rationale

To support long-term growth by enabling organizational scaling, independent deployment, and technological flexibility.

### Detailed Justification

#### Organizational Scaling and Team Autonomy

A monolithic architecture forces all developers to work on a single, large codebase, leading to high coordination overhead, merge conflicts, and slower development cycles as the team grows.

The microservices approach aligns with **Conway's Law**, allowing us to structure autonomous teams around specific business capabilities (e.g., an "Identity Team," a "Payments Team"). Each team can develop, test, and deploy their services independently, drastically increasing agility.

**In Tuturuuu:** the repo splits responsibility along app boundaries under
`apps/*`:

* `apps/web` (legacy main platform) and `apps/tanstack-web` (its replacement)
* AI surfaces such as `apps/rewise` (chatbot) and `apps/nova` (prompt engineering)
* Productivity surfaces such as `apps/calendar`, `apps/tasks`, and `apps/meet`
* `apps/finance` for finance workflows
* `apps/backend` (Rust API runtime) plus `apps/database` (Supabase migrations) and shared `packages/*`

These are deployment and ownership boundaries within a single monorepo, not
fully isolated services with private databases.

#### Independent Scalability

In a monolith, if one feature (e.g., a real-time data processing endpoint) experiences high load, the entire application must be scaled. This is inefficient and costly.

Separate deployment units allow for **granular scaling**. A high-load app can be
scaled independently of a low-traffic one, optimizing resource utilization
instead of scaling one monolith as a whole.

**Illustrative only (not a real config in the repo):**

```jsonc theme={null}
// Conceptual per-app scaling targets. Each Tuturuuu app deploys independently,
// so it can scale on its own rather than as part of one bundle.
{
  "web": { "min": 2, "max": 100 },   // Main app needs high availability
  "rewise": { "min": 1, "max": 20 }, // AI chat can scale separately
  "finance": { "min": 1, "max": 10 } // Finance moderate scaling
}
```

#### Fault Isolation and Resilience

A critical bug or memory leak in a non-essential module of a monolith can bring down the entire application.

In a microservices architecture, a failure is **contained within the boundary of that service**. A crash in the `ReportingService` will not affect critical user-facing services like `AuthenticationService` or `OrderService`, leading to a much more resilient and available system.

**In Tuturuuu:**

* Because apps deploy independently, a failure in one app's deployment does not take the others down with it
* Supabase Auth runs as a managed service, so authentication stays available even if an individual app deployment fails
* Background jobs (Trigger.dev) run out-of-band and fail independently from user-facing requests

Note that the apps share one Supabase project, so database-level failures are a
shared dependency, not fully isolated per app.

#### Technology Flexibility (Polyglot Architecture)

Microservices communicate over standard protocols (like events or APIs). This allows each service to be built with the technology best suited for its purpose.

While most apps use **TypeScript and Next.js/React**, the new `apps/backend`
runtime is written in **Rust** for the performance-critical API tier, and a
future machine-learning service could be written in **Python**. This flexibility
is hard to achieve in a single-language monolith and keeps the system adaptable.

**Current polyglot examples in Tuturuuu:**

* Most apps: TypeScript + Next.js + React (`apps/web`) and TanStack Start + React (`apps/tanstack-web`)
* `apps/backend`: Rust (dedicated API runtime, port `7820`; see [TanStack Start And Rust Migration](/platform/architecture/tanstack-rust-migration))
* `apps/discord`: Python (Discord bot utilities)
* Database: PostgreSQL (via Supabase)
* Background jobs: TypeScript on Trigger.dev v4 (`packages/trigger`)
* Possible future: Python ML services

### Why Not a Monolith?

While a monolith offers simplicity at the start of a project, it becomes a significant impediment to growth:

A monolith is unsuitable for a complex, long-lived enterprise system designed for agility.

***

## 2. Asynchronous Background Work (Event-Driven Patterns)

Long-running and side-effecting work is pushed off the request path and into
**Trigger.dev v4** background tasks (`packages/trigger`, `@trigger.dev/sdk`
`^4.4.5`). Tuturuuu does **not** run a general-purpose inter-service event bus
where every app publishes and subscribes to a shared broker; instead, it uses
Trigger.dev `task()` definitions that are invoked explicitly (or on a schedule)
to do durable, retryable async work. The event-driven *reasoning* below explains
why async, decoupled background work is valuable, and the examples use the real
v4 `task()` API.

### Core Rationale

To achieve **decoupling between request handling and durable background work**,
which is the foundation for a system that stays resilient, scalable, and
extensible under load.

### Detailed Justification

#### Ultimate Decoupling

If a request handler does its slow work inline, it must know about and wait on
every downstream side effect (email, indexing, analytics). That tightly couples
the user-facing path to all of them.

By offloading that work to a background task, the request handler only needs to
**enqueue the work and return**. The task owns the side effects and can be
changed, retried, or extended without touching the request handler.

**Real v4 task definition (`packages/trigger/src/schedule-tasks.ts`):**

```typescript theme={null}
import { task } from '@trigger.dev/sdk/v3';
import { schedulableTasksHelper } from './schedule-tasks-helper';

// A durable, retryable background task with its own queue/concurrency limit.
export const scheduleTask = task({
  id: 'schedule-task',
  queue: { concurrencyLimit: 10 },
  run: async (payload: { ws_id: string }) => {
    const result = await schedulableTasksHelper(payload.ws_id);
    if (!result.success) {
      throw new Error(result.error || 'Schedule tasks failed');
    }
    return { ws_id: payload.ws_id, ...result, success: true };
  },
});
```

The request handler enqueues this with `scheduleTask.trigger({ ws_id })` and
returns immediately; the task runs out-of-band.

#### Inherent Resilience and Asynchronicity

Synchronous API calls create "chains of failure." If a downstream service is slow or unavailable, the upstream caller is blocked, and the failure can cascade, bringing down the entire user request.

With background tasks, **Trigger.dev acts as a durable buffer**. If a downstream
dependency is slow or temporarily down, the task can retry without blocking the
original request, and the user-facing response is unaffected.

**In Tuturuuu:**

* A request can complete even if a downstream side effect (e.g. an email send) is temporarily failing
* Tasks are retried automatically (Trigger.dev manages retries and backoff)
* Failed runs are visible in the Trigger.dev dashboard for investigation
* A failing background task does not cascade into the user-facing request path

#### Natural Scalability and Load Leveling

A synchronous API can be overwhelmed by sudden traffic spikes.

Background tasks act as a **shock absorber**. Trigger.dev queues bursts of task
runs and processes them at a sustainable rate, governed by per-task
`queue.concurrencyLimit`. Scaling is a matter of letting more runs execute in
parallel rather than overwhelming a synchronous endpoint.

**Illustrative v4 task (patterned on `packages/trigger/src`):**

```typescript theme={null}
import { task } from '@trigger.dev/sdk/v3';

// During a burst, many onboarding runs are enqueued; the concurrency limit
// keeps execution at a sustainable rate.
export const onboardUserTask = task({
  id: 'onboard-user',
  queue: { concurrencyLimit: 25 },
  run: async (payload: { userId: string; email: string; wsId: string }) => {
    await sendWelcomeEmail(payload.email);
    await provisionDefaultResources(payload.userId, payload.wsId);
    return { userId: payload.userId, success: true };
  },
});

// Enqueue from a request handler without blocking the response:
// await onboardUserTask.trigger({ userId, email, wsId });
```

#### Extensibility and Future-Proofing

This is a **key strategic advantage**. EDA allows for new business capabilities to be added by simply deploying new services that listen to existing event streams.

For example, a new background task can be added to perform extra work after an
existing flow, often by triggering it from the same place that already enqueues
related work, without rewriting the core request handler.

**In Tuturuuu:**

* New async features: add a new Trigger.dev v4 `task()` in `packages/trigger` and enqueue it where needed
* Scheduled work: use Trigger.dev scheduling (see `unifiedScheduleTask` / `scheduleTask` in `packages/trigger/src`) without changing request handlers
* Heavier processing: move slow work into a task so the user-facing path stays fast

### Why Not a Purely Synchronous/REST Architecture?

While synchronous APIs are excellent for user-facing queries and commands that require an immediate response (a pattern supported by our API Gateway), using them for core inter-service communication creates a brittle, tightly coupled system.

**Our approach is hybrid:** synchronous APIs (Next.js API routes under
`/api/v1`, the `apps/backend` Rust API, and `packages/internal-api` helpers)
handle user-facing queries and commands, while durable Trigger.dev v4 tasks
handle slow or side-effecting background work. (Note: `apps/web/src/trpc` is a
minimal stub today, not the product API gateway — see Section 4.)

***

## 3. Ports-and-Adapters Thinking (Partial Hexagonal)

> [!WARNING]
>
> Tuturuuu does **not** implement full hexagonal layering. There is no
> `packages/types/src/domain` directory and no
> `apps/web/src/infrastructure/repositories` layer. `apps/web` uses a conventional
> Next.js App Router structure (`app`, `components`, `lib`, `utils`, `hooks`,
> `features`). The code samples in this section are **illustrative pseudo-code** to
> teach the ports/adapters idea, not real file locations. Where Tuturuuu applies
> the *spirit* of this pattern, it does so through shared helper packages
> (`packages/internal-api`, `packages/supabase`) rather than formal domain/port
> interfaces.

### Core Rationale

To **keep business logic separable from technology dependencies** where it pays
off, improving maintainability and testability — applied pragmatically rather
than as a strict architectural mandate.

### Detailed Justification

#### Protection of the Domain Core

In traditional N-Tier architecture, business logic often becomes dependent on infrastructure concerns (e.g., database annotations within domain models). This couples the business rules to the technology.

The Hexagonal Architecture **inverts this dependency**. The core business logic is pure and has **zero knowledge of any external technology**. It defines "Ports" (interfaces) for the functionality it needs, such as `OrderRepository`.

**Illustrative pseudo-code (no such path exists in the repo):**

```typescript theme={null}
// Conceptual domain port (not a real file)
export interface WorkspaceRepository {
  findById(id: string): Promise<Workspace | null>;
  save(workspace: Workspace): Promise<void>;
}

// Business logic doesn't know about Supabase
export class WorkspaceService {
  constructor(private repo: WorkspaceRepository) {}

async activateWorkspace(id: string) {
    const workspace = await this.repo.findById(id);
    workspace.activate(); // Pure domain logic
    await this.repo.save(workspace);
  }
}
```

#### Technology Agnosticism and Interchangeability

External technologies are implemented as "Adapters" that plug into the core's ports. We have a `PostgresOrderRepositoryAdapter` and a `KafkaEventPublisherAdapter`.

If we decide to migrate from PostgreSQL to MongoDB, we only need to write a new `MongoOrderRepositoryAdapter` and plug it in. The core business logic remains **completely unchanged**, making technology migrations low-risk and straightforward.

**Illustrative pseudo-code (no such path exists in the repo):**

```typescript theme={null}
// Conceptual infrastructure adapter (not a real file)
export class SupabaseWorkspaceRepository implements WorkspaceRepository {
  constructor(private client: SupabaseClient) {}

async findById(id: string): Promise<Workspace | null> {
    const { data } = await this.client
      .from('workspaces')
      .select('*')
      .eq('id', id)
      .single();

return data ? this.toDomain(data) : null;
  }

async save(workspace: Workspace): Promise<void> {
    await this.client
      .from('workspaces')
      .upsert(this.toDatabase(workspace));
  }
}

// Easy to swap: Could create DrizzleWorkspaceRepository or PrismaWorkspaceRepository
```

#### Superior Testability

Because the domain core is isolated from the outside world, it can be tested **completely without** a running database, web server, or any other infrastructure.

We can use simple, in-memory mock adapters to test complex business rules. This results in tests that are **extremely fast**, **reliable**, and **easy to write**, leading to higher code quality.

**Illustrative pseudo-code (conceptual test, not a real file):**

```typescript theme={null}
class InMemoryWorkspaceRepository implements WorkspaceRepository {
  private workspaces = new Map<string, Workspace>();

async findById(id: string) {
    return this.workspaces.get(id) || null;
  }

async save(workspace: Workspace) {
    this.workspaces.set(workspace.id, workspace);
  }
}

describe('WorkspaceService', () => {
  it('activates workspace', async () => {
    const repo = new InMemoryWorkspaceRepository();
    const service = new WorkspaceService(repo);

// No database, no network calls - tests run in milliseconds
    await service.activateWorkspace('ws-123');

const workspace = await repo.findById('ws-123');
    expect(workspace.isActive).toBe(true);
  });
});
```

### Why Not a Traditional Layered/N-Tier Architecture?

The primary weakness of the traditional N-Tier architecture is its tendency to create **leaky abstractions** and **tight coupling** between layers.

Business logic often becomes intertwined with persistence logic, making the system rigid, difficult to test in isolation, and hard to adapt to new technology requirements. The Hexagonal Architecture solves this by enforcing a **strict, clean boundary** around the application's core.

***

## 4. A React Modular Monolith & Headless UI

The `apps/web` frontend is architected as a "Modular Monolith" using React, with reusable logic factored into hooks following a "Headless UI" mindset.

> [!NOTE]
>
> This decision describes the **legacy `apps/web`** stack. It is being superseded
> by `apps/tanstack-web` (TanStack Start + TanStack Router/Query) for the frontend
> and `apps/backend` (Rust) for the API tier. The modular-monolith and headless-UI
> *principles* below still inform the new frontend, but treat `apps/web`-specific
> references as legacy. See
> [TanStack Start And Rust Migration](/platform/architecture/tanstack-rust-migration).

### Core Rationale

To balance the **agility of a single codebase** with the **maintainability of a modular design**, while ensuring long-term flexibility in presentation.

### Detailed Justification

#### Maintainability at Scale (Modular Monolith)

A standard Single-Page Application (SPA) can quickly become a "big ball of mud" as it grows.

A **modular monolith** enforces logical boundaries between different features or domains (e.g., `Authentication`, `Dashboard`, `Settings`, `Finance`) within a single codebase. This improves code organization, reduces unintended coupling, and allows teams to work on different features with fewer conflicts.

**In Tuturuuu:**

```
apps/web/src/
├── app/
│   ├── [locale]/(dashboard)/[wsId]/
│   │   ├── finance/          # Finance module
│   │   ├── calendar/         # Calendar module
│   │   ├── tasks/            # Tasks module
│   │   └── settings/         # Settings module
├── components/
│   ├── finance/              # Finance-specific components
│   ├── calendar/             # Calendar-specific components
│   └── shared/               # Shared components
```

Each module is self-contained with clear boundaries, yet benefits from shared infrastructure.

#### Module Size Guardrail

Code that crosses 400 LOC per file or 200 LOC per component/widget should be split automatically before final verification. Prefer focused route modules, cards, panels, hooks, data loaders, and helper modules over monolithic files. When other modules already import an entrypoint, keep that entrypoint as a thin barrel re-export so the refactor improves maintainability without forcing unrelated import churn.

#### UI and Logic Separation (Headless UI)

In this pattern, React components are split into two parts:

1. A "headless" hook that manages all **logic, state, and accessibility** (e.g., `useUserDropdown`)
2. A presentation component that simply **renders the UI** based on the state provided by the hook

This clean separation allows us to **completely change the look and feel** (the "head") of a component by swapping out its presentation layer, without rewriting any of the complex business logic.

**Example from Tuturuuu:**

```typescript theme={null}
// Headless logic hook (packages/ui/src/hooks/useTaskList.ts)
export function useTaskList(boardId: string) {
  const [tasks, setTasks] = useState<Task[]>([]);
  const [isLoading, setIsLoading] = useState(false);

const addTask = useCallback((task: Task) => {
    setTasks(prev => [...prev, task]);
  }, []);

const removeTask = useCallback((id: string) => {
    setTasks(prev => prev.filter(t => t.id !== id));
  }, []);

// All logic, accessibility, keyboard shortcuts
  return { tasks, isLoading, addTask, removeTask };
}

// Presentation component (apps/web/src/components/tasks/TaskList.tsx)
export function TaskList({ boardId }: Props) {
  const { tasks, isLoading, addTask, removeTask } = useTaskList(boardId);

// Only UI rendering, no logic
  return (
    <div className="task-list">
      {tasks.map(task => (
        <TaskCard key={task.id} task={task} onRemove={removeTask} />
      ))}
    </div>
  );
}
```

#### Future-Proofing for Multiple Platforms

The headless hooks are **pure application logic**. This means they can be reused to power completely different UIs.

The same `useUserProfile` hook that powers a web application could later be used to power a **React Native mobile app** or even a command-line interface, providing maximum code reuse and flexibility.

**Future possibilities:**

```typescript theme={null}
// Same hook, different presentations
import { useTaskList } from '@tuturuuu/hooks';

// Web app (current)
<WebTaskList boardId={id} />

// Future: Mobile app
<MobileTaskList boardId={id} />

// Future: Desktop app (Electron/Tauri)
<DesktopTaskList boardId={id} />

// All use the same useTaskList() logic
```

### Why Not Other Frontend Architectures?

#### Micro-frontends

While powerful, this architecture introduces significant complexity in:

* Build tooling and module federation
* Deployment pipelines and version coordination
* Routing and state management across boundaries
* Performance overhead of loading multiple bundles

The modular monolith provides **many of the same organizational benefits** with a fraction of the operational overhead, making it a more pragmatic starting point.

#### Traditional Coupled (Server-Rendered) Frontends

These architectures tightly couple the frontend presentation to the backend logic, making it difficult to create modern, rich user experiences.

| Server-Rendered Limitation | Impact | React Modular Monolith Solution |
| - | - | - |
| **Tight Backend Coupling** | Frontend changes require backend deploys | Clean API separation via `/api/v1` routes and `packages/internal-api` |
| **Limited Interactivity** | Complex UIs are difficult | Full React capabilities |
| **Poor Multi-Client Support** | Can't easily support mobile | Reusable hooks and shared `packages/*` |
| **Slow Iteration** | Full page reloads, slower development | Fast HMR, component-level updates |

They do not provide a clean API separation and are not flexible enough to support multiple client types (e.g., web and mobile) from a single backend.

> [!NOTE]
>
> **On the API gateway.** Earlier system-design pages referred to a tRPC API
> gateway. In the current codebase, `apps/web/src/trpc` is only a minimal stub:
> its router exports a single `healthCheck` procedure and its context is a
> hardcoded placeholder. There are **no** workspace/user/tasks/AI routers and no
> auth middleware there. Product data actually flows through `packages/internal-api`
> helpers and REST `/api/v1` routes (and, increasingly, the `apps/backend` Rust
> API). A repo guard also forbids `/trpc` calls from `apps/tanstack-web/src`.

***

## Architectural Advantages and Drawbacks

The chosen architecture provides significant advantages but also introduces tradeoffs that must be managed. Understanding both sides enables informed decision-making.

> [!NOTE]
>
> For a comprehensive comparison of all architectural patterns (N-Tier, Hexagonal, Clean, Onion, Monolithic, Modular Monolith, Microservices, Event-Driven) with detailed pros and cons, see [Architectural Patterns Comparison](/platform/architecture/system-design/architectural-patterns-comparison).

### Four Key Advantages

#### 1. Superior and Enduring Maintainability through Strong Architectural Boundaries

**Architectural Choice:** The architecture deliberately enforces separation of concerns at two critical levels: between business domains using Microservices, and between business logic and technology using Hexagonal Architecture.

**Impact and Justification:** This layered approach to separation is crucial for long-term project health. At the macro level, isolating business domains like "Web Platform" and "Finance" into separate microservices prevents the system from degrading into a "big ball of mud" where changes in one area have unintended consequences in another. At the micro level, the Hexagonal Architecture's strict isolation of the core domain logic ensures that the most valuable business rules are shielded from technological churn. This means we can upgrade a database, switch a messaging provider, or change a web framework with minimal, predictable impact, drastically reducing the cost and risk of maintenance over the system's lifespan.

**Clarifying Additions:** This structure makes responsibilities clearly defined and easier for teams to understand. Changes stay local to the affected boundary instead of leaking across the system. This reduces the likelihood of unintended side effects and simplifies long-term evolution.

#### 2. High Organizational Agility and Independent Deployability

**Architectural Choice:** The Microservices architecture decomposes the system into a suite of small, autonomous services, each aligned with a specific business capability.

**Impact and Justification:** This architectural choice is a direct enabler of organizational agility. It allows us to structure development teams to have full ownership of their respective services, from code to deployment (the "you build it, you run it" model). This autonomy eliminates the bottlenecks of a monolithic release process. A team can deploy updates to their service multiple times a day without coordinating with or waiting for other teams. This dramatically accelerates the feature delivery lifecycle and allows the organization to respond more quickly to changing business requirements.

**Clarifying Additions:** Teams can deliver updates without waiting on other domains. This separation increases overall development speed and lowers coordination overhead. The architecture naturally supports rapid and continuous improvement.

#### 3. Enhanced Fault Isolation and System-Wide Resilience

**Architectural Choice:** By decomposing the system into separate, independently running Microservices, we contain the "blast radius" of any potential failure.

**Impact and Justification:** In any complex system, failures are inevitable. A monolithic architecture is fragile because a single critical bug (like a memory leak or an unhandled exception) in a non-essential module can bring the entire application down. Our microservices design ensures that a failure in one service—for instance, the Finance app—is completely isolated. Core services like the main Web Platform and Calendar continue to run unaffected. This transforms a potentially catastrophic failure into a manageable, localized degradation of service, leading to a far more resilient and reliable platform for end-users.

**Clarifying Additions:** The system remains partially functional rather than failing entirely. Troubleshooting becomes simpler because issues are naturally localized. This architecture improves uptime and user experience during partial disruptions.

#### 4. UI/Logic Separation for Multi-Platform Potential and Design Flexibility

**Architectural Choice:** A Headless UI pattern is employed on the frontend, cleanly separating the presentation layer (the "head") from the application logic, state management, and accessibility hooks (the "body").

**Impact and Justification:** This choice provides two strategic advantages. Firstly, it offers immense design flexibility. The entire look and feel of the application can be radically redesigned by creating a new presentation layer that plugs into the existing, stable application logic, allowing for rapid rebranding or UX overhauls. Secondly, and more importantly, it makes the application logic platform-agnostic. The "headless" hooks and state management code can be reused to power completely different frontends in the future, such as a native mobile application or a voice-activated interface, maximizing code reuse and ensuring the system can adapt to new user touchpoints.

**Clarifying Additions:** Changes to visual design do not risk breaking functional behavior. Functional logic can be reused across new user interfaces with minimal changes. This future-proofs the frontend against new device types or presentation styles.

### Four Key Drawbacks

#### 1. Significant Inherent Operational Complexity

**Architectural Choice:** A distributed Microservices architecture is not a single application but a system of systems, requiring a sophisticated support infrastructure including Service Discovery, an API Gateway, and centralized observability.

**Impact and Justification:** This introduces a steep increase in operational complexity compared to a monolith. The team must now manage the deployment, networking, and health of multiple independent applications. This requires specialized DevOps expertise and a robust toolchain for logging, metrics, and tracing to understand the system's behavior. The infrastructure itself becomes a critical product that must be built and maintained, representing a significant investment of time and resources.

**Clarifying Additions:** More moving parts require greater architectural discipline. Each service adds overhead that must be monitored and understood. Organizations must prepare for the ongoing effort required to operate a distributed system.

#### 2. Challenges of Distributed Data Management and Consistency

**Architectural Choice:** The principle of decentralized data ownership in a Microservices architecture prohibits the use of traditional, simple ACID transactions across service boundaries.

**Impact and Justification:** This forces the system to embrace Eventual Consistency. Business processes that span multiple services must be carefully designed using complex patterns like Sagas to handle failures and ensure that the system eventually reaches a consistent state. This is a fundamentally harder paradigm for developers to reason about and requires a shift in mindset away from the guarantees provided by a single relational database.

**Clarifying Additions:** Teams must think differently about data reliability across boundaries. Data no longer updates everywhere at the same moment, which requires intentional design. This increases cognitive load when building cross-service workflows.

#### 3. Intrinsic Complexity of Distributed System Debugging and Performance Analysis

**Architectural Choice:** A single user request can trigger a complex, asynchronous chain of interactions that traverses the API Gateway and fans out to multiple backend services and background jobs.

**Impact and Justification:** When something goes wrong, diagnosing the root cause is no longer as simple as looking at a single log file or stack trace. It requires correlating logs, metrics, and traces from multiple services to piece together the full story. This necessitates a mature and well-integrated observability stack (e.g., distributed tracing with OpenTelemetry) to make debugging and performance tuning manageable.

**Clarifying Additions:** Architectural visibility becomes essential for diagnosing the flow of requests. Failures may appear in one service even if the root cause lies elsewhere. This makes system-wide insight a core architectural requirement.

#### 4. Governance Overhead of Maintaining Modularity

**Architectural Choice:** Both the backend Microservices and the frontend Modular Monolith rely on maintaining strict boundaries to be effective.

**Impact and Justification:** This requires active architectural governance. Without discipline, developers can easily create inappropriate dependencies, turning the microservices into a distributed monolith or eroding the boundaries of the frontend modules. The architecture requires ongoing vigilance, clear standards, and automated checks (e.g., dependency analysis tools) to prevent architectural decay over time.

**Clarifying Additions:** Teams must follow agreed-upon boundaries consistently. Regular architecture reviews help identify early signs of erosion. Maintaining clean boundaries becomes an ongoing responsibility rather than a one-time setup.

***

## Decision Summary

| Decision | Adoption in Tuturuuu | Problem Solved | Trade-off Accepted |
| - | - | - | - |
| **Independently deployable apps** | Adopted (Turborepo `apps/*`, shared Supabase) | Monolith scaling/ownership limits | Increased operational complexity |
| **Async background work** | Adopted (Trigger.dev v4 `task()`) | Tight synchronous coupling | More moving parts to observe |
| **Ports-and-adapters thinking** | Partial (shared helper packages, not formal layers) | Technology lock-in | N/A — applied pragmatically |
| **React modular monolith** | Adopted in legacy `apps/web`; principles carry to `apps/tanstack-web` | Frontend chaos at scale | Discipline required for boundaries |

## Next Steps

* [Layering Patterns](/platform/architecture/system-design/layering-patterns) - N-tier vs Hexagonal/Clean architecture comparison
* [Event-Driven Architecture](/platform/architecture/system-design/event-driven-architecture) - Advantages and drawbacks in detail
* [Extensibility, Resilience & Scalability](/platform/architecture/system-design/extensibility-resilience-scalability) - Why these properties matter
* [Quality Attributes](/platform/architecture/system-design/quality-attributes) - Maintainability, testability, and deployability
* [Security Architecture](/platform/architecture/system-design/security-architecture) - Comprehensive security justification
* [Observability & Monitoring](/platform/architecture/system-design/observability-monitoring) - Observability patterns and practices
* [Hexagonal Architecture](/platform/architecture/system-design/hexagonal-architecture) - Implementation patterns
* [Microservices Patterns](/platform/architecture/system-design/microservices-patterns) - Service boundaries in practice

# Architectural Patterns Comparison
Source: https://docs.tuturuuu.com/platform/architecture/system-design/architectural-patterns-comparison

Comprehensive comparison of architectural patterns with design justifications, pros, cons, and usage guidance

This document provides a comprehensive comparison of all major architectural patterns, including their design justifications, advantages, disadvantages, and practical guidance on when to use each pattern.

> [!NOTE]
>
> **Key Insight**: Different architectural patterns solve different problems. Understanding the trade-offs is essential for making informed architectural decisions.

## Pattern Categories

Architectural patterns can be categorized into two main types:

1. **Internal Patterns** - How code is organized within a service or application
   * N-Tier Architecture
   * Hexagonal Architecture (Ports & Adapters)
   * Clean Architecture
   * Onion Architecture

2. **External Patterns** - How services are distributed and communicate
   * Monolithic Architecture
   * Modular Monolith
   * Microservices Architecture
   * Event-Driven Architecture

***

## Internal Architectural Patterns

These patterns define how code is organized and structured within a single deployable unit (application or service).

### N-Tier Architecture

#### Design Justification

N-Tier architecture emerged from the need to separate concerns in applications by organizing code into horizontal layers based on technical responsibilities. Each tier handles a specific aspect of the application (presentation, business logic, data access), making it conceptually simple and straightforward to understand.

**Problem It Solves**: Provides basic separation of concerns in applications, making it easier to understand where different types of code should live.

#### Pros

**1. Simplicity and Familiarity**

* Extremely easy to understand and learn
* Most developers are already familiar with the pattern
* Minimal cognitive overhead for new team members
* Clear separation: UI code in presentation, business rules in BLL, database code in DAL

**2. Rapid Development for Simple Applications**

* Quick to set up and start building
* Minimal architectural overhead
* Straightforward data flow from top to bottom
* Works well for CRUD-heavy applications

**3. Tooling and Framework Support**

* Extensive tooling support (Visual Studio, IntelliJ, etc.)
* Many frameworks designed around this pattern (ASP.NET, Spring MVC)
* Large ecosystem of tutorials and examples
* Well-documented best practices

**4. Clear Technical Separation**

* Easy to assign work based on technical skills
* Frontend developers work in presentation tier
* Backend developers work in business logic tier
* Database specialists work in data access tier

#### Cons

**1. Tight Coupling to Infrastructure**

* Business logic directly depends on data access layer
* Changing databases requires modifying business logic
* Framework dependencies leak into business code
* Hard to test business rules in isolation

**Example:**

```typescript theme={null}
// Business logic tightly coupled to Supabase
export class WorkspaceService {
  async createWorkspace(name: string) {
    // PROBLEM: Business logic knows about database implementation
    const { data } = await supabase.from('workspaces').insert({ name });
    return data;
  }
}
```

**2. Poor Testability**

* Business logic can't be tested without database
* Tests are slow (require database setup/teardown)
* Tests are fragile (break when database changes)
* Mocking is complex and brittle

**3. Technology Lock-In**

* Business logic married to specific ORM or framework
* Difficult to swap technologies
* Framework upgrades can require business logic changes
* Vendor lock-in becomes a serious risk

**4. Leaky Abstractions**

* Database concerns leak into business logic (SQL, transactions)
* Business logic becomes aware of persistence details
* Domain models often have framework annotations
* Violates Single Responsibility Principle

**5. Inflexible for Complex Business Logic**

* Business rules scattered across multiple layers
* Complex domain logic doesn't fit well in BLL tier
* Validation logic duplicated across layers
* No clear place for domain concepts

#### When to Use

✅ **Simple CRUD applications** with minimal business logic
✅ **Rapid prototyping** where speed matters more than quality
✅ **Small teams** unfamiliar with DDD or hexagonal concepts
✅ **Short-lived projects** that won't need long-term maintenance
✅ **Applications that will remain small** (\<10k LOC)

#### When to Avoid

❌ **Complex business logic** that needs to be protected
❌ **Long-term projects** requiring maintainability
❌ **Applications requiring high test coverage**
❌ **Systems that may need technology swaps**
❌ **Domain-driven design** implementations

***

### Hexagonal Architecture (Ports & Adapters)

#### Design Justification

Hexagonal Architecture (invented by Alistair Cockburn) solves the fundamental problem of tight coupling between business logic and infrastructure. By inverting dependencies and isolating the domain core, it ensures that business rules remain pure, testable, and independent of technology choices.

**Problem It Solves**: Protects business logic from infrastructure changes and framework dependencies, enabling true technology agnosticism and superior testability.

```mermaid theme={null}
graph LR
    subgraph External
        UI[UI/API]
        DB[(Database)]
    end

subgraph Hexagon
        subgraph Adapters
            PrimaryAdp[Primary<br/>Adapter]
            SecondaryAdp[Secondary<br/>Adapter]
        end

subgraph Ports
            PrimaryPort[Primary<br/>Port]
            SecondaryPort[Secondary<br/>Port]
        end

Core[Domain<br/>Core]
    end

UI --> PrimaryAdp
    PrimaryAdp --> PrimaryPort
    PrimaryPort --> Core
    Core --> SecondaryPort
    SecondaryPort --> SecondaryAdp
    SecondaryAdp --> DB

style Core fill:#ffd54f,stroke:#f57f17,stroke-width:3px
    style Ports fill:#81c784,stroke:#388e3c,stroke-width:2px
    style Adapters fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
```

#### Pros

**1. Domain Logic is Pure and Technology-Agnostic**

* Business rules have zero infrastructure dependencies
* No database, no frameworks, no external services
* Core logic expresses business concepts directly
* Easy to understand business rules without technical noise

**Example:**

```typescript theme={null}
// Pure domain entity - no infrastructure dependencies
export class Workspace {
  static create(name: string, ownerId: string): Workspace {
    if (name.length < 3 || name.length > 50) {
      throw new DomainError('Workspace name must be 3-50 characters');
    }
    return new Workspace(generateId(), name, ownerId, true, new Date());
  }

archive(): void {
    if (!this._isActive) {
      throw new DomainError('Workspace is already archived');
    }
    this._isActive = false;
  }
}
```

**2. Superior Testability**

* Domain logic tested in isolation without infrastructure
* Tests run in milliseconds (no database, no network)
* Tests are reliable (no external dependencies)
* Easy to write comprehensive test suites

**Example:**

```typescript theme={null}
// Test runs instantly, no infrastructure needed
describe('Workspace', () => {
  it('enforces name length business rule', () => {
    expect(() => Workspace.create('ab', 'owner-123'))
      .toThrow('Workspace name must be 3-50 characters');
  });
});
```

**3. Technology Can Be Swapped Easily**

* Infrastructure implemented as pluggable adapters
* Swap Supabase for Prisma without touching business logic
* Change from REST to GraphQL without domain changes
* Framework upgrades don't affect core business rules

**4. Clear Separation of Concerns**

* Domain core focuses purely on business rules
* Adapters handle technical concerns
* Ports define clear contracts
* Each layer has a single, well-defined responsibility

**5. Supports Test-Driven Development (TDD)**

* Easy to write tests before implementation
* Fast feedback loop encourages TDD practices
* Can develop business logic without infrastructure setup
* Reduces time to first working test

**6. Facilitates Domain-Driven Design (DDD)**

* Natural fit for DDD patterns (entities, value objects, aggregates)
* Business logic expressed in ubiquitous language
* Clear boundaries between domain and infrastructure
* Supports rich domain models

#### Cons

**1. Increased Complexity and Learning Curve**

* More moving parts than N-Tier
* Requires understanding of dependency inversion
* Team needs training on hexagonal concepts
* Harder for junior developers initially

**2. More Code and Boilerplate**

* Need to write ports (interfaces) and adapters
* Mapping between domain models and database models
* Dependency injection configuration
* More files and folders to manage

**Example:**

```typescript theme={null}
// Domain model
class Workspace { ... }

// Port (interface)
interface WorkspaceRepository { ... }

// Adapter implementation
class SupabaseWorkspaceRepository implements WorkspaceRepository { ... }

// Mapping logic
private toDomain(row: any): Workspace { ... }
private toDatabase(workspace: Workspace): any { ... }

// More code than just `await supabase.from('workspaces').insert(...)`
```

**3. Overkill for Simple CRUD Applications**

* Unnecessary complexity for basic data management
* Slows down development of trivial features
* Mapping overhead adds no value for simple cases
* May frustrate team working on straightforward tasks

**4. Requires Architectural Discipline**

* Easy to bypass abstractions and couple to infrastructure
* Needs code reviews to enforce boundaries
* Developers may take shortcuts under pressure
* Degradation is gradual and hard to detect

#### When to Use

✅ **Complex business logic** that requires protection
✅ **Long-term projects** (multi-year lifespan)
✅ **Domain-driven design** implementations
✅ **High test coverage requirements** (>80%)
✅ **Systems that may need technology migration**
✅ **Projects with domain experts** involved

#### When to Avoid

❌ **Simple CRUD applications** with minimal logic
❌ **Rapid prototypes** that won't be maintained
❌ **Teams lacking DDD/hexagonal experience**
❌ **Projects with extreme time constraints**
❌ **Very small codebases** (\<5k LOC)

**In Tuturuuu (aspirational)**: Full ports-and-adapters layering is a target pattern we reach for in genuinely complex domains, not a blanket rule. Today the apps are conventional Next.js App Router apps (`app/`, `components/`, `lib/`, `utils/`) without dedicated `domain/`, `application/`, and `infrastructure/` directories. Business logic that benefits from isolation is factored into shared `packages/*` helpers (for example `packages/internal-api`, `packages/utils`) rather than a strict hexagon.

***

### Clean Architecture

#### Design Justification

Clean Architecture (by Robert C. Martin) extends hexagonal principles by explicitly defining concentric layers with strict dependency rules. Dependencies must always point inward toward the domain core, ensuring the most important business rules are completely isolated from volatile technical details.

**Problem It Solves**: Provides a systematic approach to dependency management, ensuring business logic remains stable while infrastructure changes freely.

```mermaid theme={null}
graph TD
    subgraph L4["Frameworks & Drivers"]
        FW["Database, Web, UI"]
    end

subgraph L3["Interface Adapters"]
        IA["Controllers, Gateways"]
    end

subgraph L2["Application Business Rules"]
        UC["Use Cases"]
    end

subgraph L1["Enterprise Business Rules"]
        E["Entities"]
    end

style L1 fill:#ffd54f,stroke:#f57f17,stroke-width:4px
    style L2 fill:#fff3e0,stroke:#f57c00,stroke-width:3px
    style L3 fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style L4 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
```

#### Pros

**1. Explicit Layer Definitions**

* Four clearly defined layers with specific purposes
* Enterprise Business Rules (entities) - core domain
* Application Business Rules (use cases) - application workflows
* Interface Adapters (controllers) - translation layer
* Frameworks & Drivers (infrastructure) - external tools

**2. Strong Dependency Rule**

* Dependencies can only point inward, never outward
* Inner layers know nothing about outer layers
* Violations are easy to detect
* Architectural integrity is maintainable

**3. Use Cases as First-Class Citizens**

* Application workflows explicitly modeled
* Clear boundary between domain and application logic
* Use cases are testable application-level operations
* Business processes well-documented in code

**Example:**

```typescript theme={null}
// Use case clearly expresses application workflow
export class CreateWorkspaceUseCase {
  constructor(
    private readonly repository: WorkspaceRepository,
    private readonly eventPublisher: EventPublisher
  ) {}

async execute(command: CreateWorkspaceCommand): Promise<Workspace> {
    // 1. Create domain entity (domain logic)
    const workspace = Workspace.create(command.name, command.ownerId);

// 2. Persist (infrastructure)
    await this.repository.save(workspace);

// 3. Publish event (infrastructure)
    await this.eventPublisher.publish(new WorkspaceCreatedEvent(workspace));

return workspace;
  }
}
```

**4. Framework Independence**

* Core business logic has zero framework dependencies
* Can upgrade frameworks without touching entities or use cases
* Frameworks become implementation details
* Reduces framework lock-in risks

#### Cons

**1. More Layers Than Hexagonal**

* Four layers vs hexagonal's simpler structure
* Can feel over-engineered for some applications
* More navigation between files and folders
* Steeper learning curve

**2. Distinction Between Entities and Use Cases Can Be Unclear**

* Developers may struggle with entity vs use case logic
* Business rules can end up in wrong layer
* Requires deep understanding of DDD concepts
* Guidelines needed to maintain clear boundaries

**3. Use Case Explosion**

* Each application workflow becomes a separate use case
* Can lead to many small, similar classes
* Folder structure can become overwhelming
* Feels like boilerplate for simple operations

#### When to Use

Same as Hexagonal Architecture, but especially when:

✅ **Clear separation of entities and use cases** is needed
✅ **Team values explicit architectural boundaries**
✅ **Application workflows are complex** and deserve first-class modeling
✅ **Robert C. Martin's principles** resonate with the team

#### When to Avoid

Same as Hexagonal Architecture, plus:

❌ **Team finds four layers unnecessarily complex**
❌ **Simple workflows don't justify use case classes**

**In Tuturuuu**: Not strictly followed; we prefer simpler hexagonal approach but adopt use case pattern where beneficial.

***

### Onion Architecture

#### Design Justification

Onion Architecture (by Jeffrey Palermo) visualizes layers as concentric circles, emphasizing that all dependencies point inward toward the core. It's similar to Clean Architecture but with slightly different layer names and emphasis on domain-centric design.

**Problem It Solves**: Same as Hexagonal and Clean, but with visual metaphor making dependency direction intuitive.

#### Pros & Cons

Onion Architecture shares the same pros and cons as Hexagonal and Clean Architecture. The main differences are:

**Unique Aspects:**

* Visual metaphor (onion layers) is intuitive
* Slightly simpler than Clean (fewer prescribed layers)
* Emphasizes domain services as a separate layer
* Popular in .NET community

**In Tuturuuu**: Not explicitly used, but principles align with our hexagonal approach.

***

## External Architectural Patterns

These patterns define how applications are deployed, distributed, and communicate with each other.

### Monolithic Architecture

#### Design Justification

A monolithic architecture packages the entire application as a single deployable unit. All features, modules, and layers exist within one codebase and deploy together. This is the traditional, default architecture for most applications.

**Problem It Solves**: Provides simplicity in deployment, development environment setup, and team coordination for small to medium applications.

```mermaid theme={null}
graph TB
    subgraph Monolith["Monolithic Application"]
        UI["UI Layer"]
        BLL["Business Logic"]
        DAL["Data Access"]
        ModA["Module A"]
        ModB["Module B"]
        ModC["Module C"]
    end

DB[("Single Database")]

UI --> BLL
    BLL --> DAL
    DAL --> DB

BLL --> ModA
    BLL --> ModB
    BLL --> ModC

style Monolith fill:#fff3e0,stroke:#f57c00,stroke-width:3px
    style DB fill:#e8f5e9,stroke:#388e3c,stroke-width:2px
```

#### Pros

**1. Simplicity**

* Single codebase, single repository
* Single deployment artifact
* Simple development environment setup
* Easy to reason about the entire system

**2. Easy Development Workflow**

* All code changes happen in one place
* No cross-service coordination needed
* Straightforward debugging (single process)
* IDE works well with single codebase

**3. Simple Deployment**

* Deploy one artifact to production
* Atomic deployments (all or nothing)
* No service orchestration needed
* Rollback is straightforward

**4. Performance**

* In-process function calls (fast)
* No network overhead between modules
* Single database connection pool
* No serialization/deserialization overhead

**5. Easier to Test End-to-End**

* Spin up entire application locally
* Integration tests are straightforward
* No need to mock external services
* Complete system available for testing

#### Cons

**1. Scaling Challenges**

* Must scale entire application as a unit
* Can't scale individual features independently
* Wasteful resource allocation
* Expensive at high scale

**Example:**

```typescript theme={null}
// Problem: Even if only the reporting module needs more resources,
// we must scale the entire monolith

// Monolith running on server:
// - User authentication (low load)
// - CRUD operations (low load)
// - Report generation (HIGH load) ← Only this needs scaling
// - Admin panel (low load)

// Must scale everything to handle report generation load
// This scales authentication, CRUD, and admin unnecessarily
```

**2. Tight Coupling and Dependency Management**

* Modules easily become interdependent
* Changes ripple across the codebase
* Hard to isolate features
* Difficult to enforce module boundaries

**3. Slow Development at Scale**

* Large codebase slows down IDE
* Long build times
* Merge conflicts increase with team size
* Difficult to parallelize work across teams

**4. Deployment Risk**

* Any change requires deploying entire application
* Small bug fix carries high risk
* Downtime affects all features
* Rollback affects entire system

**5. Technology Lock-In**

* Entire application must use same technology stack
* Can't adopt new technologies incrementally
* Framework upgrades affect entire application
* Limited flexibility in technology choices

**6. Team Scaling Issues**

* Difficult to divide work across multiple teams
* High coordination overhead
* Merge conflicts increase
* Conway's Law: Organization mirrors monolith structure

#### When to Use

✅ **Small to medium applications**
✅ **Single, co-located team**
✅ **Limited operational complexity budget**
✅ **Predictable scaling requirements**
✅ **Startup MVP** or proof of concept
✅ **Low traffic applications**

#### When to Avoid

❌ **Large teams** (>20 developers)
❌ **Need independent deployment** of features
❌ **Different scaling requirements** per feature
❌ **High availability requirements** (99.99%+)
❌ **Diverse technology needs** per domain

***

### Modular Monolith

#### Design Justification

A Modular Monolith combines monolithic deployment with modular organization. The application is still deployed as a single unit, but internally structured into well-defined, loosely-coupled modules with clear boundaries. This provides many benefits of microservices without operational complexity.

**Problem It Solves**: Enables team scalability and clear boundaries while avoiding distributed systems complexity.

```mermaid theme={null}
graph TB
    subgraph MM["Modular Monolith"]
        subgraph ModA["Finance Module"]
            FA["Finance API"]
            FL["Finance Logic"]
            FD["Finance Data"]
        end

subgraph ModB["Calendar Module"]
            CA["Calendar API"]
            CL["Calendar Logic"]
            CD["Calendar Data"]
        end

subgraph ModC["Tasks Module"]
            TA["Tasks API"]
            TL["Tasks Logic"]
            TD["Tasks Data"]
        end

Shared["Shared Infrastructure"]
    end

DB[("Single Database<br/>(with module schemas)")]

FD --> DB
    CD --> DB
    TD --> DB

ModA -.-|Module<br/>Boundaries| ModB
    ModB -.-|Module<br/>Boundaries| ModC

style ModA fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style ModB fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style ModC fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px
    style MM fill:#fff,stroke:#000,stroke-width:3px
```

#### Pros

**1. Combines Monolith Simplicity with Modular Benefits**

* Single deployment unit (simple operations)
* Clear module boundaries (organizational clarity)
* Shared infrastructure (reduced duplication)
* Easier than microservices to operate

**2. Team Scalability**

* Teams can own modules independently
* Reduced coordination overhead
* Clear ownership boundaries
* Parallel development possible

**3. Enforced Boundaries Without Distribution**

* Modules communicate through well-defined interfaces
* Can enforce boundaries programmatically
* No network overhead
* Easier to refactor than microservices

**4. Migration Path to Microservices**

* Modules can be extracted as services later
* Boundaries already defined
* Incremental migration possible
* Low-risk evolution strategy

**Example in Tuturuuu:**

```typescript theme={null}
// apps/web/src/ - Modular organization
apps/web/src/
├── app/[locale]/(dashboard)/[wsId]/
│   ├── finance/           # Finance module
│   │   ├── transactions/
│   │   ├── reports/
│   │   └── _components/   # Finance-specific components
│   ├── calendar/          # Calendar module
│   │   ├── events/
│   │   └── _components/   # Calendar-specific components
│   └── tasks/             # Tasks module
│       ├── boards/
│       └── _components/   # Task-specific components
```

**5. Shared Infrastructure and Code**

* Reuse common utilities easily
* Shared authentication, logging, etc.
* No code duplication across modules
* Centralized configuration

#### Cons

**1. Requires Discipline to Maintain Boundaries**

* Easy to create cross-module dependencies
* Boundaries are convention-based, not enforced
* Gradual degradation without governance
* Need automated tools to detect violations

**2. Still Scales as a Unit**

* Can't scale individual modules
* All modules deployed together
* Resource allocation is coarse-grained
* Same scaling limitations as monolith

**3. Shared Database Can Become Bottleneck**

* All modules use same database
* Schema coupling between modules
* Difficult to optimize per-module data access
* Database becomes single point of contention

**4. Not True Isolation**

* Module failure can affect other modules
* Shared resources (memory, CPU) create contention
* Memory leak in one module affects all
* Less fault isolation than microservices

#### When to Use

✅ **Medium to large monoliths** needing better organization
✅ **Growing teams** (10-50 developers)
✅ **Clear domain boundaries** exist
✅ **Want microservices benefits** without operational complexity
✅ **Migration path** from monolith to microservices desired
✅ **Don't need independent deployment** yet

#### When to Avoid

❌ **Very small applications** (overhead not justified)
❌ **Need independent deployment** of modules
❌ **Different scaling requirements** per module
❌ **True fault isolation** is critical
❌ **Modules have very different technology needs**

**In Tuturuuu**: `apps/web` is organized as a modular monolith, with feature folders (Finance, Calendar, Tasks, and more) under `app/[locale]/(dashboard)/[wsId]/` and shared code in `packages/*`. The boundaries are convention-based rather than compiler-enforced. The successor frontend, `apps/tanstack-web`, follows the same modular approach with TanStack Router route trees.

***

### Microservices Architecture

#### Design Justification

Microservices architecture decomposes the system into small, independently deployable services, each focused on a specific business capability. Services communicate via lightweight protocols (HTTP, events) and can be developed, deployed, and scaled independently.

**Problem It Solves**: Enables organizational scalability, independent deployment, technology diversity, and granular scaling for complex, large-scale systems.

```mermaid theme={null}
graph TB
    subgraph MS["Microservices Architecture"]
        Web["Web Service"]
        Finance["Finance Service"]
        Calendar["Calendar Service"]
        Tasks["Tasks Service"]
        AI["AI Service"]
    end

Gateway["API Gateway"]
    Broker["Event Broker"]

WebDB[("Web DB")]
    FinDB[("Finance DB")]
    CalDB[("Calendar DB")]

Gateway --> Web
    Gateway --> Finance
    Gateway --> Calendar

Web --> Broker
    Finance --> Broker
    Calendar --> Broker
    Tasks --> Broker
    AI --> Broker

Web --> WebDB
    Finance --> FinDB
    Calendar --> CalDB

style Web fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style Finance fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style Calendar fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px
    style Tasks fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
    style AI fill:#ffcdd2,stroke:#c62828,stroke-width:2px
```

#### Pros

**1. Independent Deployment and Scalability**

* Deploy services independently without coordination
* Scale services based on individual needs
* Deploy multiple times per day per service
* Reduced deployment risk (only one service affected)

**Example:**

```typescript theme={null}
// Different services scale independently
const scaling = {
  web: { min: 2, max: 100 },      // High traffic, needs scaling
  finance: { min: 1, max: 10 },   // Moderate traffic
  calendar: { min: 1, max: 5 },   // Low traffic
  admin: { min: 1, max: 2 }       // Very low traffic
};
```

**2. Organizational Scalability**

* Teams own services end-to-end ("you build it, you run it")
* Parallel development across teams
* Reduced coordination overhead
* Clear ownership and accountability

**3. Technology Diversity**

* Each service can use different technology stack
* Choose best tool for each job
* Experiment with new technologies in isolation
* Incremental technology adoption

**Example:**

```typescript theme={null}
// Different services, different technologies
const services = {
  web: { language: 'TypeScript', framework: 'Next.js' },
  ml: { language: 'Python', framework: 'FastAPI' },
  realtime: { language: 'Go', framework: 'Gin' },
  batch: { language: 'Rust', framework: 'Actix' }
};
```

**4. Fault Isolation**

* Service failure doesn't bring down entire system
* Blast radius is limited to single service
* Other services continue operating
* System degrades gracefully

**5. Easier to Understand Individual Services**

* Each service is small and focused
* New developers can understand one service quickly
* Cognitive load is reduced
* Domain complexity is bounded

#### Cons

**1. Significant Operational Complexity**

* Need service discovery, API gateway, load balancers
* Distributed logging, tracing, and monitoring essential
* Complex deployment pipelines
* Requires mature DevOps practices

**2. Distributed System Challenges**

* Network latency and unreliability
* Debugging is harder (distributed tracing needed)
* Performance tuning is complex
* Testing end-to-end is difficult

**3. Data Management Complexity**

* Each service has its own database
* No distributed transactions (must use sagas)
* Eventual consistency instead of strong consistency
* Complex queries across services are difficult

**Example:**

```typescript theme={null}
// Complex workflow spanning multiple services
async function createWorkspaceWithResources(data: WorkspaceData) {
  // 1. Create workspace (Web Service)
  const workspace = await webService.createWorkspace(data);

// 2. Setup finance (Finance Service)
  // Problem: What if this fails? Need saga pattern
  await financeService.setupAccount(workspace.id);

// 3. Create calendar (Calendar Service)
  // Problem: What if this fails? How to rollback?
  await calendarService.createCalendar(workspace.id);

// Need complex saga orchestration for rollback
}
```

**4. Increased Infrastructure Costs**

* More servers/containers to run
* More databases to maintain
* More monitoring and logging infrastructure
* Higher cloud bills

**5. Requires Organizational Maturity**

* Teams must be autonomous and skilled
* Need strong DevOps culture
* Requires discipline to maintain service boundaries
* Not suitable for inexperienced teams

**6. Service Versioning and API Compatibility**

* Must maintain backward compatibility
* Breaking changes require careful coordination
* Versioning strategy is essential
* Contract testing is mandatory

#### When to Use

✅ **Large, complex systems** with multiple domains
✅ **Large teams** (>50 developers)
✅ **Different scaling requirements** per feature
✅ **Need independent deployment** per domain
✅ **High availability requirements** (99.99%+)
✅ **Organization has DevOps maturity**
✅ **Different technology needs** per domain

#### When to Avoid

❌ **Small applications** (\<50k LOC)
❌ **Small teams** (\<10 developers)
❌ **Limited operational expertise**
❌ **Tight budget** constraints
❌ **Strong consistency requirements** dominate
❌ **Startup MVP** or proof of concept

**In Tuturuuu**: The monorepo hosts many independently deployable apps (`web`, `finance`, `calendar`, `nova`, `rewise`, and more) that scale separately. This resembles microservices at the deployment layer, but with two important caveats: the apps share a **single Supabase project** rather than per-service databases, and most are built on the same Next.js stack rather than diverse technologies. The notable exception is `apps/backend`, the new Rust API service (port `7820`) introduced by the [TanStack Start And Rust Migration](/platform/architecture/tanstack-rust-migration).

***

### Event-Driven Architecture

#### Design Justification

Event-Driven Architecture (EDA) uses asynchronous events as the primary communication mechanism between services. Services publish events when state changes occur, and other services subscribe to relevant events, reacting accordingly. This creates ultimate decoupling between services.

**Problem It Solves**: Eliminates tight coupling between services, enables asynchronous processing, and provides natural extensibility for adding new functionality.

```mermaid theme={null}
graph LR
    subgraph Producers
        ServiceA["Service A"]
        ServiceB["Service B"]
    end

Broker["Event Broker<br/>(Trigger.dev)"]

subgraph Consumers
        ServiceC["Service C"]
        ServiceD["Service D"]
        ServiceE["Service E"]
    end

ServiceA -->|Publish Events| Broker
    ServiceB -->|Publish Events| Broker

style Broker fill:#ffd54f,stroke:#f57f17,stroke-width:3px
    style Producers fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style Consumers fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px
```

#### Pros

**1. Ultimate Decoupling**

* Producers don't know about consumers
* Consumers don't know about producers
* Services can be added/removed without changes
* Natural extensibility

> [!NOTE]
>
> Tuturuuu uses **Trigger.dev v4** (`@trigger.dev/sdk` `^4.4.5`). The v4 API is built around `task()` with a typed `run` function, triggered with `myTask.trigger(payload)` or fanned out with `batchTrigger(...)`. The older v2 `client.defineJob` / `eventTrigger` / `trigger.event` API is **not** used in this repo. Real tasks live in `packages/trigger/src` (for example `scheduleTask`, `unifiedScheduleTask`, `googleCalendarFullSync`).

**Example (Trigger.dev v4 `task()`):**

```typescript theme={null}
import { task } from '@trigger.dev/sdk/v3';

// Consumer 1: Send welcome email — a standalone task
export const sendWelcomeEmail = task({
  id: 'send-welcome-email',
  run: async (payload: { ownerId: string }) => {
    await sendEmail(payload.ownerId);
  },
});

// Consumer 2: Setup analytics — added later, no producer change
export const setupAnalytics = task({
  id: 'setup-analytics',
  run: async (payload: { workspaceId: string }) => {
    await trackWorkspace(payload.workspaceId);
  },
});

// Consumer 3: AI onboarding — added even later, still independent
export const aiOnboarding = task({
  id: 'ai-onboarding',
  run: async (payload: { workspaceId: string }) => {
    await setupAI(payload.workspaceId);
  },
});

// Producer: fan out to each task when a workspace is created.
// Each task runs independently; new tasks can be added without
// touching this call site beyond adding a new trigger.
async function onWorkspaceCreated(workspaceId: string, ownerId: string) {
  await Promise.all([
    sendWelcomeEmail.trigger({ ownerId }),
    setupAnalytics.trigger({ workspaceId }),
    aiOnboarding.trigger({ workspaceId }),
  ]);
}
```

> [!NOTE]
>
> Trigger.dev v4 dispatches by **task id**, so the producer references each task explicitly rather than publishing to a named topic. To get topic-style fan-out where a producer is fully unaware of consumers, pair Trigger.dev with a database table, Cloudflare realtime channel, or a dedicated dispatcher task that decides which downstream tasks to trigger.

**2. Natural Resilience**

* Broker acts as buffer for failures
* If consumer is down, events are persisted
* Automatic retry mechanisms
* Temporal decoupling (producer doesn't wait)

**3. Asynchronous Processing**

* Producers don't block on consumers
* Fast response times for users
* Long-running operations don't slow down requests
* Better resource utilization

**4. Audit Trail and Debugging**

* Complete history of events
* Can replay events for debugging
* Natural audit log
* Time-travel debugging possible

**5. Extensibility**

* Add new features by adding new consumers
* No changes to existing services
* Supports A/B testing (run old and new consumers in parallel)
* Safe experimentation

#### Cons

**1. Eventual Consistency**

* No immediate consistency guarantees
* System state converges over time
* Complex to reason about for developers
* Debugging race conditions is hard

**Example:**

```typescript theme={null}
// User creates workspace
await webService.createWorkspace(data);

// User immediately tries to access analytics
// Problem: Analytics consumer may not have processed event yet
const analytics = await analyticsService.getWorkspaceAnalytics(workspaceId);
// May return null because event hasn't been processed yet!
```

**2. Increased Complexity**

* Need to manage event broker infrastructure
* Event schema versioning is critical
* Debugging distributed event flows is difficult
* Monitoring and observability are essential

**3. Event Schema Management**

* Breaking changes to events affect all consumers
* Need careful versioning strategy
* Documentation of event schemas is critical
* Contract testing is mandatory

**4. No Immediate Responses**

* Can't return result from consumer to producer
* Must poll or use separate response events
* Complex request-response patterns
* Not suitable for all workflows

**5. Potential for Event Storms**

* Cascading events can amplify load
* Event loops are possible
* Need circuit breakers and rate limiting
* Monitoring for event accumulation essential

#### When to Use

✅ **Highly decoupled microservices** architecture
✅ **Asynchronous workflows** dominate
✅ **Need to add features** without modifying existing services
✅ **Audit trail** and event sourcing needed
✅ **Variable load** that benefits from buffering
✅ **Long-running operations** that can be async

#### When to Avoid

❌ **Strong consistency** is critical
❌ **Immediate responses** always needed
❌ **Simple request-response** patterns dominate
❌ **Team lacks event-driven experience**
❌ **Debugging complexity** is unacceptable
❌ **Real-time guarantees** are essential

**In Tuturuuu**: Trigger.dev v4 runs background and scheduled work — calendar sync, task scheduling, and similar jobs in `packages/trigger/src` — rather than serving as a full cross-service event bus. It is not the primary request path; most product data flows synchronously through `packages/internal-api` helpers and REST `/api/v1` routes (and, increasingly, the Rust `apps/backend`). Treat broad "event broker between every service" framing as illustrative.

***

## Comprehensive Comparison Matrix

***

## Decision Framework

### Choosing Internal Patterns

```mermaid theme={null}
graph TD
    Start["Internal<br/>Pattern Choice"]

Start --> Q1{"Complex<br/>business logic?"}
    Q1 -->|No| NTier["N-Tier<br/>Architecture"]
    Q1 -->|Yes| Q2{"Long-term<br/>project?"}

Q2 -->|No| NTier
    Q2 -->|Yes| Q3{"Team knows<br/>DDD?"}

Q3 -->|No| Training["Provide<br/>training"]
    Q3 -->|Yes| Q4{"Prefer explicit<br/>layers?"}
    Training --> Q4

Q4 -->|Yes| Clean["Clean<br/>Architecture"]
    Q4 -->|No| Hexagonal["Hexagonal<br/>Architecture"]

style NTier fill:#ffcdd2,stroke:#c62828,stroke-width:2px
    style Clean fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px
    style Hexagonal fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px
```

### Choosing External Patterns

```mermaid theme={null}
graph TD
    Start["External<br/>Pattern Choice"]

Start --> Q1{"Team size?"}
    Q1 -->|"<10"| Monolith["Monolith"]
    Q1 -->|"10-50"| Q2{"Need clear<br/>boundaries?"}
    Q1 -->|">50"| Microservices["Microservices"]

Q2 -->|No| Monolith
    Q2 -->|Yes| ModMono["Modular<br/>Monolith"]

Microservices --> Q3{"Services need<br/>tight coupling?"}
    Q3 -->|No| EDA["Event-Driven<br/>Architecture"]
    Q3 -->|Yes| SyncMS["Microservices with<br/>Synchronous Calls"]

style Monolith fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style ModMono fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style Microservices fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px
    style EDA fill:#c8e6c9,stroke:#2e7d32,stroke-width:3px
```

***

## Tuturuuu's Architectural Decisions

Tuturuuu uses a **combination of patterns**, applying each where it provides the most value. The descriptions below reflect the real codebase as of mid-2026; the patterns are applied pragmatically, not dogmatically.

### Deployment: Many Independently Deployable Apps

**Decision**: Split the product surface into separate deployable apps (`web`, `finance`, `calendar`, `nova`, and more) that scale independently

**Reality and caveats**:

* Multiple domains (AI, Finance, Calendar, Tasks) live as distinct apps in the monorepo
* Apps deploy and scale independently, which gives microservice-like operational benefits
* They share a **single Supabase project** rather than per-service databases, so this is not a textbook "database-per-service" microservices topology
* Most apps share the same Next.js stack; the Rust `apps/backend` is the main technology-diversity example

### Background Work: Trigger.dev v4 Tasks

**Decision**: Run asynchronous and scheduled work as Trigger.dev v4 `task()` definitions in `packages/trigger/src`

**Justification**:

* Long-running and scheduled jobs (calendar sync, task scheduling) should not block request handling
* Built-in retries, concurrency controls, and queues add resilience
* This is background processing, not a general cross-service event bus; synchronous flows use `packages/internal-api` helpers and REST `/api/v1` routes

### Internal Code Organization: Conventional Next.js Layering

**Decision**: Organize each app as a conventional Next.js App Router project (`app/`, `components/`, `lib/`, `utils/`), extracting shared logic into `packages/*`

**Reality and caveats**:

* The apps do **not** implement formal hexagonal/clean/onion layering (no `domain/`, `application/`, `infrastructure/` directories)
* Reuse and isolation come from shared workspace packages (`packages/internal-api`, `packages/utils`, `packages/ui`, `packages/types`), not a strict ports-and-adapters hexagon
* Hexagonal/clean principles are an aspirational reference for unusually complex domains rather than an enforced rule

### Frontend: Modular Monolith

**Decision**: The web frontend is a modular monolith with convention-based module boundaries

**Justification**:

* Single deployment per frontend app simplifies operations
* Feature folders (Finance, Calendar, Tasks) provide organizational clarity
* The successor `apps/tanstack-web` keeps the same modular approach using TanStack Router route trees

***

## Related Documentation

* [Layering Patterns](/platform/architecture/system-design/layering-patterns) - Detailed comparison of N-Tier vs Hexagonal
* [Architectural Decisions](/platform/architecture/system-design/architectural-decisions) - Core architectural choices in Tuturuuu
* [Hexagonal Architecture](/platform/architecture/system-design/hexagonal-architecture) - Implementation details
* [Microservices Patterns](/platform/architecture/system-design/microservices-patterns) - Service boundaries and communication
* [Event-Driven Architecture](/platform/architecture/system-design/event-driven-architecture) - Event streaming patterns

# Encapsulation Patterns
Source: https://docs.tuturuuu.com/platform/architecture/system-design/encapsulation-patterns

Strategies for preventing unwanted communication within and between services in Tuturuuu's architecture

Encapsulation is a critical architectural quality that prevents unwanted coupling and maintains clear boundaries. This document covers patterns for preventing unwanted communication both **within an app** (cross-layer) and **between apps** (cross-service).

> [!NOTE]
>
> For a comprehensive comparison of how different architectural patterns handle encapsulation, see [Architectural Patterns Comparison](/platform/architecture/system-design/architectural-patterns-comparison).

> [!WARNING]
>
> **How to read this page.** The cross-layer hexagonal examples below
> (`domain/`, `application/`, `infrastructure/` directories, `WorkspaceRepository`
> ports, rich `Workspace` domain models) are **illustrative teaching patterns**,
> not a description of the current codebase. Tuturuuu apps are conventional
> **Next.js App Router** trees: `apps/web/src` contains `app/`, `components/`,
> `features/`, `hooks/`, `lib/`, and `utils/` — there is no
> `domain/`/`application/`/`infrastructure/` layering and no separate ports/adapters
> package. Likewise, apps communicate primarily through a **shared Supabase
> database** plus **Trigger.dev v4** background tasks, not through a broker with
> event ACLs. Each "in Tuturuuu" snippet below is marked as either *real* or
> *illustrative*. Treat the illustrative ones as design inspiration you could adopt,
> not as files that exist today.

## Preventing Cross-Layer Communication (Inside an App)

Even without formal hexagonal layering, an app benefits from clear internal
boundaries that prevent tight coupling. The patterns below show how dependency
inversion, DTOs, and layered responsibility *could* be applied; where Tuturuuu
already does something equivalent (RLS, package boundaries, `internal-api`
helpers), that is called out as *real*.

### 1. The Dependency Inversion Principle (via Ports)

> [!NOTE]
>
> **Illustrative pattern.** The ports/adapters file paths below
> (`packages/types/src/domain/*`, `apps/web/src/domain/*`,
> `apps/web/src/infrastructure/*`) **do not exist** in the repo today and are shown
> purely to teach the dependency inversion principle. `packages/types/src` exposes
> flat modules (`db.ts`, `index.ts`, `supabase.ts`, `sdk.ts`, …) with no `domain/`
> directory.

High-level business logic can define interfaces ("Ports") it requires, and
low-level infrastructure (like database code) implements them.

**Architectural Principle:** High-level modules should not depend on low-level modules. Both should depend on abstractions.

**Illustrative example:**

```typescript theme={null}
// Hypothetical domain layer defines interface (PORT)
// e.g. packages/types/src/domain/workspace.ts (does not exist today)
export interface WorkspaceRepository {
  findById(id: string): Promise<Workspace | null>;
  findByOwnerId(ownerId: string): Promise<Workspace[]>;
  save(workspace: Workspace): Promise<void>;
  delete(id: string): Promise<void>;
}

// Business logic depends on abstraction, NOT concrete implementation
// e.g. apps/web/src/domain/services/workspace-service.ts (illustrative path)
export class WorkspaceService {
  constructor(
    private readonly repository: WorkspaceRepository  // Depends on interface
  ) {}

async createWorkspace(ownerId: string, name: string): Promise<Workspace> {
    const workspace = new Workspace(ownerId, name);

// Domain logic doesn't know about Supabase, PostgreSQL, etc.
    await this.repository.save(workspace);

return workspace;
  }
}

// Infrastructure layer implements interface (ADAPTER)
// e.g. apps/web/src/infrastructure/repositories/supabase-workspace-repository.ts (illustrative path)
export class SupabaseWorkspaceRepository implements WorkspaceRepository {
  constructor(private readonly supabase: SupabaseClient) {}

async findById(id: string): Promise<Workspace | null> {
    const { data } = await this.supabase
      .from('workspaces')
      .select('*')
      .eq('id', id)
      .single();

return data ? this.toDomainModel(data) : null;
  }

async save(workspace: Workspace): Promise<void> {
    await this.supabase
      .from('workspaces')
      .upsert(this.toDatabaseModel(workspace));
  }

// ... other methods
}
```

**Benefits:**

* Domain logic is **pure** and **testable** without infrastructure
* Can **swap implementations** (Supabase → Drizzle → Prisma) without changing business logic
* **Inversion of control** - domain doesn't depend on infrastructure
* **Technology agnostic** core business logic

**Clarifying Additions:** This enforces a clean separation that preserves the integrity of business rules. Infrastructure choices become replaceable rather than deeply embedded. The architecture stays flexible as technical needs evolve.

**"Anti-pattern" — but also how Tuturuuu actually writes code today:**

```typescript theme={null}
// In the hexagonal sense this "couples business logic to Supabase".
// In practice this IS the current Tuturuuu pattern: route handlers and
// server components call the Supabase client directly.
import { createClient } from '@tuturuuu/supabase/next/server';

export async function createWorkspace(ownerId: string, name: string) {
  // NOTE: createClient() from @tuturuuu/supabase/next/server is ASYNC — await it.
  // (createAdminClient() is synchronous; createDynamicClient() is async.)
  const supabase = await createClient();

const { data } = await supabase
    .from('workspaces')
    .insert({ owner_id: ownerId, name })
    .select()
    .single();

return data;
}
```

The hexagonal critique (harder to unit-test, technology lock-in) is real, but
Tuturuuu deliberately accepts direct Supabase access for app/API code and relies
on **Row-Level Security**, **shared `@tuturuuu/supabase` wrappers**, and
**`packages/internal-api` helpers** for boundaries instead of a ports/adapters
layer. Adopt the repository pattern only where a unit of logic genuinely needs to
be storage-agnostic or heavily unit-tested.

***

### 2. Strict Data Transfer Objects (DTOs)

The outer API layer of a service communicates with its inner Application layer using plain DTOs. This creates a strong boundary that prevents internal, behavior-rich Domain Models from being exposed to external layers, ensuring the core logic remains fully encapsulated.

**Architectural Principle:** External layers communicate via simple data structures, not rich domain objects.

> [!NOTE]
>
> **Illustrative pattern.** The rich `Workspace` domain class and
> `apps/web/src/domain/models/workspace.ts` path are illustrative. Real
> `apps/web` API routes work with plain objects and generated DB row types from
> `@tuturuuu/types/db`, not behavior-rich domain entities. The DTO discipline (keep
> HTTP request/response shapes separate from internal models, serialize dates as
> ISO strings) is still worth applying.

**Illustrative example:**

```typescript theme={null}
// API layer DTO (external contract)
// e.g. apps/web/src/app/api/workspaces/create/route.ts
interface CreateWorkspaceRequest {
  name: string;
  description?: string;
}

interface CreateWorkspaceResponse {
  id: string;
  name: string;
  ownerId: string;
  createdAt: string;  // Serialized as ISO string
}

export async function POST(request: Request) {
  const body: CreateWorkspaceRequest = await request.json();

// Convert DTO to domain command
  const command = new CreateWorkspaceCommand(
    userId,
    body.name,
    body.description
  );

// Execute in domain
  const workspace = await workspaceService.execute(command);

// Convert domain model back to DTO
  const response: CreateWorkspaceResponse = {
    id: workspace.id,
    name: workspace.name,
    ownerId: workspace.ownerId,
    createdAt: workspace.createdAt.toISOString()  // Domain Date → DTO string
  };

return Response.json(response);
}

// Domain model (internal, rich behavior) — illustrative; no such file exists today
// e.g. apps/web/src/domain/models/workspace.ts
export class Workspace {
  constructor(
    public readonly id: string,
    public readonly ownerId: string,
    private _name: string,
    private _isActive: boolean,
    public readonly createdAt: Date
  ) {}

// Rich domain behavior
  rename(newName: string) {
    if (newName.length < 3) {
      throw new DomainError('Workspace name must be at least 3 characters');
    }
    this._name = newName;
  }

activate() {
    if (this._isActive) {
      throw new DomainError('Workspace is already active');
    }
    this._isActive = true;
  }

deactivate() {
    this._isActive = false;
  }

get name() {
    return this._name;
  }

get isActive() {
    return this._isActive;
  }
}
// Domain model NEVER exposed to API layer
// API only sees DTOs
```

**Benefits:**

* **Encapsulation** of domain behavior
* **Clear boundaries** between layers
* **API stability** - internal changes don't break API contract
* **Serialization control** - DTOs are JSON-friendly
* **Versioning** - can support multiple DTO versions

**Clarifying Additions:** Interfaces clarify what the domain requires without exposing internal structures. This allows external systems to interact without knowing implementation details. Such boundaries minimize coupling between layers.

**Anti-pattern to avoid:**

```typescript theme={null}
// BAD: Exposing domain model directly
export async function POST(request: Request) {
  const workspace = await workspaceService.create(data);

// WRONG: Returning domain model directly
  return Response.json(workspace);
}
// Problems:
// - Domain behavior exposed (rename, activate methods in JSON)
// - Date objects don't serialize correctly
// - Internal structure leaked to external API
// - Can't evolve domain without breaking API
```

***

### 3. Explicit Layered Responsibility

The architecture enforces a clear separation of concerns. The **Presentation layer** handles HTTP, the **Application layer** orchestrates workflows, and the **Domain layer** contains pure business logic. This clarity prevents logic from being misplaced and ensures layers only interact through their well-defined public interfaces.

**Architectural Principle:** Each layer has a single, well-defined responsibility and communicates only through defined interfaces.

**Actual `apps/web/src` structure (real):**

```
apps/web/src/
├── app/            # Next.js App Router: pages, layouts, and api/ route handlers
├── components/     # Shared React components for this app
├── features/       # Feature-scoped UI + logic
├── hooks/          # React hooks
├── lib/            # App-level helpers and clients
├── utils/          # Cross-cutting utilities
├── context/        # React context providers
├── data/           # Static/seed data
├── trpc/           # Local tRPC stub (healthCheck only — not a product data layer)
└── i18n/           # Localization config
```

There is **no** `application/`, `domain/`, or `infrastructure/` directory. Cross-app
product data flows through the **shared Supabase database** and
**`packages/internal-api`** helpers calling REST `/api/v1` routes — not through a
ports/adapters layer.

**Illustrative hexagonal structure** (what an explicitly layered service *could*
look like — not present today):

```
src/
├── app/                          # Presentation Layer (HTTP) — real today
│   └── api/workspaces/create/route.ts
├── application/                  # Application Layer (Orchestration) — illustrative
│   └── use-cases/create-workspace.ts
├── domain/                       # Domain Layer (Business Logic) — illustrative
│   ├── models/workspace.ts
│   └── services/workspace-service.ts
└── infrastructure/               # Infrastructure Layer (Technical) — illustrative
    └── repositories/supabase-workspace-repository.ts
```

**Illustrative example with clear layer responsibilities:**

```typescript theme={null}
// PRESENTATION LAYER: HTTP concerns only
// apps/web/src/app/api/workspaces/create/route.ts
export async function POST(request: Request) {
  // 1. HTTP handling (validation, auth)
  const session = await getSession();
  if (!session) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 });
  }

const body = await request.json();

// Validate input schema
  const validation = CreateWorkspaceSchema.safeParse(body);
  if (!validation.success) {
    return Response.json({ error: validation.error }, { status: 400 });
  }

// 2. Delegate to application layer
  const useCase = new CreateWorkspaceUseCase(
    workspaceRepository,
    eventPublisher
  );

try {
    const workspace = await useCase.execute({
      ownerId: session.userId,
      name: validation.data.name,
      description: validation.data.description
    });

// 3. HTTP response
    return Response.json({ workspace }, { status: 201 });
  } catch (error) {
    return Response.json({ error: error.message }, { status: 500 });
  }
}

// APPLICATION LAYER: Workflow orchestration
// apps/web/src/application/use-cases/create-workspace.ts
export class CreateWorkspaceUseCase {
  constructor(
    private readonly repository: WorkspaceRepository,
    private readonly eventPublisher: EventPublisher
  ) {}

async execute(command: CreateWorkspaceCommand): Promise<Workspace> {
    // 1. Create domain entity
    const workspace = Workspace.create(
      command.ownerId,
      command.name,
      command.description
    );

// 2. Persist
    await this.repository.save(workspace);

// 3. Publish domain event
    await this.eventPublisher.publish(
      new WorkspaceCreatedEvent(workspace.id, workspace.ownerId)
    );

return workspace;
  }
}

// DOMAIN LAYER: Pure business logic
// apps/web/src/domain/models/workspace.ts
export class Workspace {
  static create(
    ownerId: string,
    name: string,
    description?: string
  ): Workspace {
    // Business rules
    if (name.length < 3 || name.length > 50) {
      throw new DomainError('Workspace name must be 3-50 characters');
    }

return new Workspace(
      generateId(),
      ownerId,
      name,
      description,
      true,  // isActive
      new Date()
    );
  }

// No HTTP, no database, no events - pure domain logic
}
```

**Layer Communication Rules:**

**Benefits:**

* **Clear responsibility** per layer
* **Easy to reason about** where code belongs
* **Testability** - each layer tested independently
* **Maintainability** - changes confined to appropriate layer

**Clarifying Additions:** This keeps the heart of the system stable despite environmental changes. The domain stays consistent across different execution contexts. This significantly boosts reliability and predictability.

**Anti-pattern to avoid:**

```typescript theme={null}
// BAD: Mixed responsibilities
export async function POST(request: Request) {
  const body = await request.json();

// WRONG: Business logic in API layer
  if (body.name.length < 3) {
    return Response.json({ error: 'Name too short' }, { status: 400 });
  }

// WRONG: Direct database access from API layer
  const { data } = await supabase
    .from('workspaces')
    .insert({ name: body.name });

// WRONG (and outdated API): firing a background task inline with no structure.
  // In Trigger.dev v4 you trigger a defined task, e.g.:
  //   await myTask.trigger({ workspaceId: data.id });
  // (Trigger.dev v2 APIs like trigger.event/client.defineJob do not exist in this repo.)

return Response.json(data);
}
// Problems:
// - Business rules scattered across codebase
// - No single source of truth for validation
// - Hard to test
// - Difficult to change
```

***

## Preventing Unwanted Cross-Service Communication (Between Apps)

> [!WARNING]
>
> **Reality check.** Tuturuuu apps do **not** communicate exclusively through
> published events, and there is **no broker-level event ACL**. The current primary
> inter-app pattern is a **shared Supabase (PostgreSQL) database** with Row-Level
> Security, complemented by **Trigger.dev v4** tasks for asynchronous/background
> work. This matches the
> [Microservices Patterns](/platform/architecture/system-design/microservices-patterns)
> page, which lists "Shared Database (Current)" as the live pattern. The
> event-as-sole-interface material below is therefore an **aspirational pattern**
> showing the encapsulation benefits a fully event-driven design would provide —
> not the way the apps interact today.

### 1. Background Tasks as a Decoupling Boundary

When one app needs to kick off work in another context without a synchronous
dependency, Tuturuuu uses **Trigger.dev v4 `task()`** definitions in
`packages/trigger/src`. A trigger payload acts as a small, explicit contract: the
caller passes only what the task needs, and the task does not reach back into the
caller's internals.

**Architectural Principle:** Cross-context work is dispatched via explicit task payloads, not by calling another app's private functions.

**Real example (Trigger.dev v4):**

```typescript theme={null}
// packages/trigger/src/schedule-tasks.ts (real, abridged)
import { task } from '@trigger.dev/sdk/v3';
import { schedulableTasksHelper } from './schedule-tasks-helper';

export const scheduleTask = task({
  id: 'schedule-task',
  queue: { concurrencyLimit: 10 },
  // The payload is the entire contract this task depends on.
  run: async (payload: { ws_id: string }) => {
    const result = await schedulableTasksHelper(payload.ws_id);
    if (!result.success) {
      throw new Error(result.error || 'Schedule tasks failed');
    }
    return { ws_id: payload.ws_id, ...result, success: true };
  },
});
```

```typescript theme={null}
// Dispatching the task from app code (Trigger.dev v4):
import { scheduleTask } from '@tuturuuu/trigger';

// Fire-and-forget; returns a run handle, does not block on completion.
await scheduleTask.trigger({ ws_id: workspaceId });
```

> [!NOTE]
>
> The import path is `@trigger.dev/sdk/v3` even though the installed package is
> `@trigger.dev/sdk@^4.4.5` — the `/v3` subpath is the v4 SDK's stable entrypoint
> for `task()`. The Trigger.dev **v2** APIs referenced in older drafts
> (`client.defineJob`, `eventTrigger`, `io.runTask`, `trigger.event`) **do not
> exist** in this repo.

***

### 2. (Aspirational) Published Event Contracts as the Sole Interface

In a fully event-driven design, the only way services interact is through the
events they publish; internal implementation, database schema, and private
functions stay **completely hidden**. Tuturuuu does **not** implement this today
(apps share a database), but the pattern is the strongest form of cross-service
encapsulation and is worth understanding.

**Architectural Principle:** Services communicate only via well-defined event contracts.

**Aspirational example (expressed in real Trigger.dev v4 syntax):**

```typescript theme={null}
// Producer side: instead of a v2 trigger.event(...) broadcast,
// dispatch a typed task with an explicit payload contract.
import { setupAiWorkspaceTask } from '@tuturuuu/trigger';

export async function createWorkspace(data: CreateWorkspaceData) {
  const supabase = await createClient(); // async client — await it
  const { data: workspace } = await supabase
    .from('workspaces')
    .insert(data)
    .select()
    .single();

// Public contract = the task payload shape, nothing more.
  await setupAiWorkspaceTask.trigger({
    workspaceId: workspace.id,
    ownerId: workspace.owner_id,
  });
}

// Consumer side (Trigger.dev v4): a task() definition, not client.defineJob.
import { task } from '@trigger.dev/sdk/v3';

export const setupAiWorkspaceTask = task({
  id: 'setup-ai-workspace',
  run: async (payload: { workspaceId: string; ownerId: string }) => {
    // Only knows about the payload contract, not the producer's internals.
    return await createAIConfig(payload);
  },
});
```

**Event Schema Governance (aspirational):**

```typescript theme={null}
// Illustrative: e.g. packages/types/src/events/workspace.ts (no such file today)
import { z } from 'zod';

// Versioned schemas keep payload contracts backward compatible.
export const WorkspaceCreatedEventV1 = z.object({
  workspaceId: z.string().uuid(),
  ownerId: z.string().uuid(),
  name: z.string().min(1).max(100),
  createdAt: z.string().datetime()
});

export const WorkspaceCreatedEventV2 = z.object({
  workspaceId: z.string().uuid(),
  ownerId: z.string().uuid(),
  name: z.string().min(1).max(100),
  createdAt: z.string().datetime(),
  // New optional fields (backward compatible)
  description: z.string().optional(),
  plan: z.enum(['free', 'pro', 'enterprise']).optional()
});

export type WorkspaceCreatedEventV1 = z.infer<typeof WorkspaceCreatedEventV1>;
export type WorkspaceCreatedEventV2 = z.infer<typeof WorkspaceCreatedEventV2>;
```

**Benefits:**

* **Complete encapsulation** of service internals
* **Clear API contract** via event schemas
* **Versioning support** for evolution
* **Independent deployment** of services
* **No direct dependencies** between services

**Clarifying Additions:** Clients remain simple and unaffected by internal changes. Service boundaries stay intact because external access is tightly controlled. This enforces a clean separation between client-facing and internal concerns.

**Anti-pattern to avoid:**

```typescript theme={null}
// BAD: Direct service-to-service HTTP calls
export async function createWorkspace(data: CreateWorkspaceData) {
  const workspace = await db.workspaces.insert(data);

// WRONG: Direct HTTP call to another service
  await fetch('http://rewise-service/api/setup', {
    method: 'POST',
    body: JSON.stringify({ workspaceId: workspace.id })
  });

// Problems:
  // - Tight coupling to rewise-service
  // - Must know its URL and API
  // - Synchronous dependency (cascading failures)
  // - Hard to add new services
}
```

***

### 3. (Hypothetical) Broker-Level Access Control (ACLs)

> [!WARNING]
>
> **Hypothetical pattern — not implemented.** There is **no message broker** and
> **no event ACL system** in Tuturuuu. The file `packages/trigger/src/events/acl.ts`
> and the `EVENT_PRODUCERS`/`EVENT_CONSUMERS` maps below **do not exist** —
> `packages/trigger/src` contains task definitions (`schedule-tasks.ts`,
> `google-calendar-sync.ts`, etc.), not an ACL layer. This section is kept only to
> illustrate what infrastructure-enforced boundaries would look like if Tuturuuu
> moved to a true event-driven broker.

In a broker-based design you would not rely on trust; the broker itself enforces
communication boundaries. Using ACLs you could declare that only one service may
produce `user.registered` events, and only specific downstream services may
consume them.

**Architectural Principle:** Enforce service boundaries at the infrastructure level, not just by convention.

**Hypothetical example (does not reflect repo code):**

```typescript theme={null}
// Hypothetical: packages/trigger/src/events/acl.ts (no such file exists)
export const EVENT_PRODUCERS = {
  'user.registered': ['apps/web'],
  'workspace.created': ['apps/web'],
  'payment.processed': ['apps/web', 'apps/finance'],
  'ai.chat.message': ['apps/rewise'],
  'task.created': ['apps/tasks']
} as const;

export const EVENT_CONSUMERS = {
  'user.registered': ['apps/rewise', 'apps/web', 'analytics-service'],
  'workspace.created': ['apps/rewise', 'apps/nova', 'apps/finance'],
  'payment.processed': ['apps/web', 'billing-service'],
  'ai.chat.message': ['apps/web'],
  'task.created': ['apps/web', 'apps/calendar']
} as const;

// Validation middleware
export function validateEventProducer(
  eventName: string,
  serviceId: string
): boolean {
  const allowedProducers = EVENT_PRODUCERS[eventName];
  if (!allowedProducers) {
    throw new Error(`Unknown event: ${eventName}`);
  }
  if (!allowedProducers.includes(serviceId)) {
    throw new Error(
      `Service ${serviceId} not allowed to produce ${eventName}`
    );
  }
  return true;
}
```

**Benefits:**

* **Enforced boundaries** at infrastructure level
* **Security** - services can't spoof events from other services
* **Audit trail** - know exactly which services produce/consume events
* **Documentation** - ACL config documents allowed communication

**Clarifying Additions:** This ensures services evolve internally without breaking others. External dependencies rely on stable contracts rather than hidden details. This strengthens overall modularity across the architecture.

***

### 4. Elimination of Synchronous Coupling

Dispatching background work asynchronously avoids direct, synchronous calls
between contexts for slow or non-critical flows. This prevents the tight coupling
that arises when one caller must know the network location, API signature, and
live availability of another. Tuturuuu applies this with **Trigger.dev v4** tasks:
the request returns immediately while follow-up work runs out of band.

**Architectural Principle:** Don't block a user request on slow, non-critical downstream work.

**Async flow (real Trigger.dev v4 syntax):**

```typescript theme={null}
import { createAdminClient } from '@tuturuuu/supabase/next/server';
import { setupUserAiTask, sendWelcomeEmailTask } from '@tuturuuu/trigger';

// apps/web: User registers
export async function registerUser(data: UserRegistrationData) {
  const supabase = createAdminClient(); // SYNC factory — do NOT await it
  const user = await createUser(supabase, data);

// Dispatch background tasks (non-blocking); each returns a run handle.
  await setupUserAiTask.trigger({ userId: user.id });
  await sendWelcomeEmailTask.trigger({ email: user.email });

return user;  // Returns immediately
}

// packages/trigger/src: each consumer is a task() definition.
import { task } from '@trigger.dev/sdk/v3';

export const setupUserAiTask = task({
  id: 'setup-user-ai',
  run: async (payload: { userId: string }) => {
    return await createAIProfile(payload.userId);
  },
});

export const sendWelcomeEmailTask = task({
  id: 'send-welcome-email',
  run: async (payload: { email: string }) => {
    return await sendEmail(payload.email, 'welcome');
  },
});

// Each task runs independently; registration never blocks on them.
```

**Benefits:**

* **No cascading failures**
* **Independent availability** of services
* **Faster user responses**
* **Easier to add new services**

**Clarifying Additions:** Controlled communication prevents accidental or unauthorized interactions. Service boundaries stay clear as the system grows. This improves safety and consistency in distributed communication.

**Anti-pattern to avoid:**

```typescript theme={null}
// BAD: Synchronous service-to-service calls
export async function registerUser(data: UserRegistrationData) {
  const user = await createUser(data);

// WRONG: Blocking calls to other services
  await rewiseService.setupAI(user.id);        // 2 seconds
  await emailService.sendWelcome(user.email);  // 1 second
  await analyticsService.track(user.id);       // 1 second

return user;  // User waits 4+ seconds
}
// Problems:
// - User waits for all services
// - If rewise service is down, registration fails
// - Tight coupling to multiple services
```

***

## Encapsulation in Practice

### Workspace Isolation via RLS (real)

This is Tuturuuu's actual primary encapsulation mechanism: because apps share one
Supabase database, **Row-Level Security** — defined by migrations under
`apps/database/supabase/migrations/` — keeps every app inside its permitted data
scope at the database level, regardless of which app issues the query.

```sql theme={null}
-- apps/database/supabase/migrations/
-- Row-Level Security ensures data encapsulation at database level
CREATE POLICY "Users can only see their workspaces"
ON workspaces
FOR SELECT
USING (
  id IN (
    SELECT workspace_id
    FROM workspace_members
    WHERE user_id = auth.uid()
  )
);

-- Services cannot access data outside their scope
-- Enforced at database level, not application level
```

### Package Boundaries (real)

Apps depend on shared `workspace:*` packages and never import another app's
internals. (Add or update these with scoped installs, e.g.
`cd apps/web && bun add <pkg>` — never `bun add --workspace`.)

```jsonc theme={null}
// apps/web/package.json (illustrative subset)
{
  "dependencies": {
    "@tuturuuu/ui": "workspace:*",        // ✅ Allowed
    "@tuturuuu/types": "workspace:*",     // ✅ Allowed
    "@tuturuuu/supabase": "workspace:*"   // ✅ Allowed
    // ❌ Do not import from apps/rewise or apps/finance directly
  }
}
```

## Summary

Status legend: **real** = implemented today; **illustrative/aspirational** =
teaching pattern not implemented in the repo.

## Related Documentation

* [Layering Patterns](/platform/architecture/system-design/layering-patterns) - N-tier vs Hexagonal/Clean architecture comparison
* [Hexagonal Architecture](/platform/architecture/system-design/hexagonal-architecture) - Detailed ports and adapters pattern
* [Event-Driven Architecture](/platform/architecture/system-design/event-driven-architecture) - Event-based communication
* [Microservices Patterns](/platform/architecture/system-design/microservices-patterns) - Service boundaries
* [Authorization](/platform/architecture/authorization) - RLS policies and permissions

# Event-Driven Architecture
Source: https://docs.tuturuuu.com/platform/architecture/system-design/event-driven-architecture

Asynchronous, event-driven patterns in Tuturuuu: advantages, drawbacks, and how background work actually runs on Trigger.dev v4

Event-Driven Architecture (EDA) is a useful lens for the asynchronous,
fire-and-forget work in Tuturuuu — calendar syncs, auto-scheduling, and other
background jobs that should not block a user request. This document explains the
general advantages and drawbacks of EDA, then grounds each idea in how Tuturuuu
**actually** runs background work today: [Trigger.dev](https://trigger.dev) v4
tasks.

> [!NOTE]
>
> **Read this as patterns, not literal architecture.** Tuturuuu is not built on a
> Kafka-style event bus with an immutable event log, replayable streams, or
> dead-letter queues. It runs conventional Next.js apps that enqueue
> background **tasks** on Trigger.dev (a managed jobs platform) and persist state
> in a shared Supabase Postgres database. Sections below are labelled
> **Concept** (general EDA theory) or **In Tuturuuu** (verified against real
> code). Treat any capability not shown in real code as illustrative.

## Overview

**Concept.** In a fully event-driven system, services communicate asynchronously
through events published to a central broker. Services are **producers**
(publishing events) and **consumers** (subscribing to and processing events),
with the broker handling delivery, persistence, and reliability.

```mermaid theme={null}
graph LR
    A[Producer<br/>API route] -->|enqueue task| B[Trigger.dev<br/>managed jobs]
    B -->|run| C[Task: calendar sync]
    B -->|run| D[Task: auto-schedule]
    B -->|fan out via task.trigger| E[Per-workspace tasks]

style B fill:#4f46e5,stroke:#3730a3,color:#fff
```

**In Tuturuuu.** There is no central event bus. Instead:

* A request handler (an `apps/web` API route or a cron entrypoint) does its
  synchronous work and then **enqueues a Trigger.dev task** for follow-up work.
* Trigger.dev runs that task on its managed infrastructure, with retries,
  concurrency control, and queues.
* An "orchestrator" task can **fan out** by triggering one child task per
  workspace via `task.trigger(...)`.

The Trigger.dev tasks live in `packages/trigger/src` — for example
`google-calendar-sync.ts`, `google-calendar-full-sync.ts`,
`unified-schedule.ts`, and `schedule-tasks.ts`. They are defined with the
Trigger.dev v4 `task()` API (`@trigger.dev/sdk` `^4.4.5`), imported from the
`@trigger.dev/sdk/v3` entrypoint.

## Advantages of Event-Driven Design

### 1. Decoupling work from the request path

**Concept.** A producer publishes an event and is done; it does not know which
consumers react. This is the loosest possible coupling and lets you add or
remove downstream behavior without touching the producer.

**In Tuturuuu.** We get a pragmatic version of this: an API route finishes its
synchronous work, then **enqueues a task** instead of doing the slow work
inline. The route does not care how the task is implemented, and the task can
evolve independently.

```typescript theme={null}
// Conceptual: an API route enqueues background work instead of blocking.
// Real task definitions live in packages/trigger/src.
import { googleCalendarFullSync } from '@tuturuuu/trigger/google-calendar-full-sync';

export async function POST(request: Request) {
  const workspace = await createWorkspace(data);

// Hand off slow work to Trigger.dev; the response returns immediately.
  await googleCalendarFullSync.trigger({
    ws_id: workspace.id,
    access_token,
    refresh_token,
  });

return Response.json({ workspace });
}
```

**Benefits:**

* Keep user-facing requests fast by moving slow work off the request path.
* Change a task's internals without changing its callers.
* Add new background behavior by adding a new task, not by editing the producer.

> [!NOTE]
>
> Tuturuuu does **not** broadcast a single event to many anonymous subscribers.
> Callers explicitly enqueue named tasks. There is no event-name pub/sub fan-in
> layer between producer and consumer.

***

### 2. Resilience through retries

**Concept.** A durable broker keeps events until a consumer processes them, so a
consumer outage does not lose work — it just delays it.

**In Tuturuuu.** Trigger.dev persists each enqueued task run and retries failed
runs on its managed infrastructure, so a transient failure (an expired Google
token, a flaky network call) does not silently drop the work. Tasks are written
to return a structured `{ success, error }` result and to log failures rather
than crash the caller.

```typescript theme={null}
// packages/trigger/src/schedule-tasks.ts (real task)
import { task } from '@trigger.dev/sdk/v3';
import { schedulableTasksHelper } from './schedule-tasks-helper';

export const scheduleTask = task({
  id: 'schedule-task',
  queue: {
    concurrencyLimit: 10,
  },
  run: async (payload: { ws_id: string }) => {
    try {
      const result = await schedulableTasksHelper(payload.ws_id);

if (!result.success) {
        throw new Error(result.error || 'Schedule tasks failed');
      }

return { ws_id: payload.ws_id, ...result, success: true };
    } catch (error) {
      console.error(`[${payload.ws_id}] Error in schedule task:`, error);
      return {
        ws_id: payload.ws_id,
        success: false,
        error: error instanceof Error ? error.message : 'Unknown error',
      };
    }
  },
});
```

**Benefits:**

* **No cascading failures**: the API route that enqueued the task is unaffected
  if the task fails.
* **Automatic retries**: Trigger.dev re-runs failed task runs.
* **Durability**: enqueued runs survive a worker restart.

> [!NOTE]
>
> **Concept, not implemented in Tuturuuu:** an immutable event log you can
> re-read from the beginning, plus dead-letter queues for permanently failed
> events. Trigger.dev retries and surfaces failed runs in its dashboard; our
> tasks additionally swallow errors into a structured result so an orchestrator
> can continue with the next workspace. There is no `*.dlq` wildcard trigger or
> DLQ topic in this repo.

***

### 3. Scalability through concurrency control

**Concept.** Multiple consumer instances can process the same stream in
parallel, and the broker levels load by buffering spikes.

**In Tuturuuu.** Trigger.dev runs many task runs concurrently, and we cap that
concurrency per task with a `queue` so a burst of work cannot overwhelm shared
resources (Postgres, the Google Calendar API). An orchestrator fans out one
child run per workspace and gives each its own `concurrencyKey`.

```typescript theme={null}
// packages/trigger/src/google-calendar-full-sync.ts (real orchestrator, abridged)
export const googleCalendarFullSyncOrchestrator = task({
  id: 'google-calendar-full-sync-orchestrator',
  run: async () => {
    const workspaces = await getWorkspacesForSync();
    const results: SyncOrchestratorResult[] = [];

for (const workspace of workspaces) {
      try {
        // Fan out: one child run per workspace, isolated by concurrencyKey.
        const handle = await googleCalendarFullSync.trigger(workspace, {
          concurrencyKey: `google-calendar-full-sync-${workspace.ws_id}`,
        });
        results.push({ ws_id: workspace.ws_id, handle, status: 'triggered' });
      } catch (error) {
        results.push({
          ws_id: workspace.ws_id,
          error: error instanceof Error ? error.message : 'Unknown error',
          status: 'failed',
        });
      }
    }

return results;
  },
});
```

**Benefits:**

* **Bounded throughput**: `queue.concurrencyLimit` (e.g. `10` for
  `scheduleTask`, `5` for `unifiedScheduleTask`) protects shared dependencies.
* **Per-key isolation**: `concurrencyKey` keeps each workspace's runs from
  stepping on each other.
* **Spike absorption**: Trigger.dev queues work it cannot run immediately.

***

### 4. Temporal decoupling

**Concept.** With a persistent, replayable event log, a brand-new consumer can
read the entire history of events to bootstrap itself — useful for rebuilding
read models, training models, or running new analyses on past data.

> [!WARNING]
>
> **This is the part Tuturuuu does not have.** There is no event-sourcing store
> and no "replay all events from launch" capability. Trigger.dev tasks are
> fire-and-run jobs, not an append-only event log. State of record lives in the
> shared Supabase Postgres database; to re-derive something, you query Postgres,
> you do not replay an event stream. Treat this section as EDA theory only.

If you genuinely need history-as-a-stream in the future, you would build it
explicitly (e.g. an append-only Postgres table plus a job that reads it) — it is
not a free property of the current stack.

***

## Drawbacks of Event-Driven Design

### 1. Harder to reason about and debug

**Concept.** Asynchronous, choreographed work has no single linear call stack, so
tracing "why did this fail?" spans multiple independent runs.

**In Tuturuuu.** The same trade-off applies the moment work moves off the request
path. A failing calendar sync does not show up in the API route's stack trace;
you find it in the Trigger.dev run logs. We lean on:

* The Trigger.dev dashboard for per-run logs, retries, and status.
* Structured `console.log`/`console.error` inside tasks, keyed by `ws_id`, so
  runs are correlatable.
* Returning a structured `{ ws_id, success, error }` result from each task so an
  orchestrator can report per-workspace outcomes.

> [!NOTE]
>
> There is no `@tuturuuu/logging` or `@tuturuuu/observability` package and no
> cross-service distributed-tracing system wired into these tasks today.
> Inside runtime code, use the native console method matching severity; the
> Trigger.dev tasks in `packages/trigger` log the same way to Trigger.dev run
> logs.

***

### 2. Eventual consistency

**Concept.** Because processing is asynchronous, there is a delay between when
work is enqueued and when its effects are visible. The system is "eventually
consistent," and the UX must accommodate that.

**In Tuturuuu.** A calendar sync or auto-schedule run completes some time after
it is enqueued, so freshly triggered changes are not instantly reflected. Handle
this the way the rest of the platform does:

* **Optimistic UI** and **loading states** via TanStack Query while background
  work settles.
* Design flows so the user is not blocked waiting on a background task.

```typescript theme={null}
// Conceptual: enqueue, then let the UI reconcile when the task lands.
await unifiedScheduleManualTrigger.trigger({ ws_id, forceReschedule: true });
// The schedule updates in Postgres once the task finishes; the client
// re-fetches (TanStack Query) rather than blocking on the task result.
```

**Mitigation strategies:**

* Optimistic UI updates with background reconciliation.
* Clear loading/processing states.
* Read-your-own-writes via a direct query path when a value must be immediate.

***

### 3. Payload/schema governance

**Concept.** Event payloads become a contract between producer and consumer, so
schema evolution must be backward compatible or versioned.

**In Tuturuuu.** Each task's `payload` type is its contract. Because callers and
tasks live in the same monorepo and TypeScript checks both sides, breaking a
payload shape surfaces at type-check time rather than silently at runtime. Keep
payload changes additive (new optional fields) and validate untrusted input with
`zod` where a payload crosses a trust boundary.

```typescript theme={null}
// Real task payloads are plain typed objects, e.g.:
//   { ws_id: string }                                  // scheduleTask
//   { ws_id: string; windowDays?: number; forceReschedule?: boolean } // unifiedScheduleTask
//   { ws_id: string; access_token: string; refresh_token: string }    // full sync
//
// Prefer additive changes (new optional fields) so existing callers keep working.
```

**Mitigation strategies:**

* Additive payload changes only; avoid removing or retyping existing fields.
* Let the monorepo's shared types and `bun validate` catch mismatches.
* Validate external/untrusted payloads with `zod`.

***

### 4. Operational dependency on the jobs platform

**Concept.** A central broker is critical infrastructure that must be operated,
tuned, and monitored.

**In Tuturuuu.** Using **managed Trigger.dev** removes most of that operational
burden — there is no broker to run. What remains is application-level care:

* Make task work **idempotent** where possible, since runs can retry.
* Set sane `queue.concurrencyLimit` values to protect Postgres and external APIs.
* Watch the Trigger.dev dashboard for failure rates and run latency.
* Keep secrets (e.g. `INTERNAL_TRIGGER_SECRET_KEY`,
  `GOOGLE_CLIENT_ID`/`GOOGLE_CLIENT_SECRET`) in environment variables, never in
  code.

**Mitigation strategies:**

* Managed platform (Trigger.dev) instead of self-hosting a broker.
* Idempotent, retry-safe task bodies.
* Concurrency limits and per-workspace `concurrencyKey`s.

***

## How Background Work Actually Runs in Tuturuuu

### Defining a task (Trigger.dev v4)

Tasks are defined with `task()` and exported from `packages/trigger/src`. The SDK
is `@trigger.dev/sdk` `^4.4.5`; tasks import `task` from `@trigger.dev/sdk/v3`.

```typescript theme={null}
// packages/trigger/src/unified-schedule.ts (real task, abridged)
import { task } from '@trigger.dev/sdk/v3';
import { unifiedScheduleHelper } from './unified-schedule-helper';

export const unifiedScheduleTask = task({
  id: 'unified-schedule-task',
  queue: {
    concurrencyLimit: 5, // Limit concurrent workspace scheduling
  },
  run: async (payload: {
    ws_id: string;
    windowDays?: number;
    forceReschedule?: boolean;
  }) => {
    const result = await unifiedScheduleHelper(payload.ws_id, {
      windowDays: payload.windowDays,
      forceReschedule: payload.forceReschedule,
    });

if (!result.success) {
      throw new Error(result.error || 'Unified schedule failed');
    }

return { ws_id: payload.ws_id, success: true, ...result.data };
  },
});
```

### Enqueuing and fanning out

Other code triggers a task by calling `.trigger(payload, options?)` on the
exported task. An orchestrator triggers one child run per workspace, isolating
each with a `concurrencyKey` (see `googleCalendarFullSyncOrchestrator` above).

```typescript theme={null}
const handle = await unifiedScheduleTask.trigger({ ws_id, forceReschedule: true });
```

### Scheduling

> [!WARNING]
>
> Recurring **Calendar** scheduling does **not** live in `packages/trigger` as a
> `schedules.task` cron job. As documented in
> [the Trigger.dev package reference](/reference/packages/trigger), production
> Calendar scheduling runs through `apps/web` cron, which calls the internal
> `/api/<wsId>/calendar/auto-schedule` route (authenticated with
> `INTERNAL_TRIGGER_SECRET_KEY`). The `scheduleTask` /
> `unifiedScheduleTask` definitions here are wrappers kept for manual
> Trigger.dev runs and tests.

## When to Reach for Asynchronous (Event-Driven) Work

**Enqueue a background task when:**

* The work is slow and should not block the HTTP response (calendar sync, bulk
  processing, external-API fan-out).
* Eventual consistency is acceptable for the use case.
* Retries and bounded concurrency add real value.
* The work fans out across many workspaces or items.

**Do it synchronously instead when:**

* The caller needs the result immediately to return a response.
* The user is waiting in real time and cannot tolerate a delay.
* It is a simple CRUD operation with no slow side effects.
* The added indirection would only make debugging harder.

## Related Documentation

* [Architectural Decisions](/platform/architecture/system-design/architectural-decisions) — system-design trade-offs
* [Extensibility, Resilience & Scalability](/platform/architecture/system-design/extensibility-resilience-scalability) — these benefits in detail
* [Trigger.dev Package](/reference/packages/trigger) — the real task implementations and conventions
* [TanStack + Rust Migration](/platform/architecture/tanstack-rust-migration) — where background work is heading
* [Development Tools](/build/development-tools/overview) — local development and verification workflow

# Extensibility, Resilience & Scalability
Source: https://docs.tuturuuu.com/platform/architecture/system-design/extensibility-resilience-scalability

15 reasons why event-driven architecture prioritizes extensibility, resilience, and scalability

Event-driven architecture is fundamentally designed for evolution, stability, and growth. This document explores **15 key reasons** (5 for each property) why these qualities matter, and shows how Tuturuuu applies the practical subset of these patterns today.

> [!NOTE]
>
> To understand how different architectural patterns compare in terms of these quality attributes, see [Architectural Patterns Comparison](/platform/architecture/system-design/architectural-patterns-comparison).

> [!WARNING]
>
> **How to read this page.** The patterns below are general event-driven concepts. Tuturuuu is not a Kafka-style microservice mesh: the apps under `apps/` are conventional applications that share a single Supabase Postgres project, and asynchronous/background work runs on **[Trigger.dev v4](/reference/packages/trigger)** (`@trigger.dev/sdk` v4) using the `task()` API, not a self-managed broker with consumer groups or topic partitions. Code samples that use Trigger.dev show the real v4 `task()` shape; samples that describe broker primitives (partitions, DLQ topics, replay windows) are **conceptual pseudo-code** that illustrate the pattern rather than implemented Tuturuuu behavior. Each section calls out which is which.

## Extensibility (5 Reasons)

The event-driven architecture is fundamentally designed for evolution and the seamless addition of new functionality.

### 1. The "Add a Consumer" Pattern (Open/Closed Principle)

To introduce new business functionality, you add a new handler that reacts to existing work rather than editing the existing code path. In Tuturuuu that handler is a new Trigger.dev task (and, conceptually in a broker-based system, a new consumer subscribed to an event stream).

**Example:** To add a fraud-detection capability, we can introduce a new Trigger.dev task that runs whenever a payment is attempted or fails, without modifying the code that initiates payments. In Trigger.dev v4, a task is a plain `task()` export; an upstream handler triggers it by name (`yourTask.trigger(payload)` / `tasks.trigger(...)`).

```typescript theme={null}
// NEW task - zero changes to the code that initiates payments
import { task, tasks } from '@trigger.dev/sdk/v3';

export const fraudDetection = task({
  id: 'fraud-detection',
  queue: { concurrencyLimit: 10 },
  run: async (payload: { paymentId: string; amount: number }) => {
    const riskScore = await analyzeFraudRisk(payload);

if (riskScore > 0.8) {
      // Fan out to a follow-up task instead of a broker "sendEvent"
      await tasks.trigger('alert-fraud-team', { ...payload, riskScore });
    }

return { paymentId: payload.paymentId, riskScore };
  },
});
```

The payment flow only adds a single `fraudDetection.trigger(...)` call (or none, if a shared dispatcher already fans out payment events). The existing charge logic is untouched.

**Benefits:**

* **Zero modification** to the payment logic
* **Independent deployment** of the fraud-detection task
* **No regression risk** to existing functionality
* **Team autonomy** - the fraud team works independently

**Clarifying Additions:** This ensures growth does not disrupt existing areas. New capabilities arrive as new components rather than modifications to old ones. This avoids large, risky refactors as the system expands.

***

### 2. Introduction of New, Non-Breaking Events

When a new data source is introduced, like a new type of IoT sensor, we can introduce new event types (e.g., `SensorReadingRecorded`). Existing services will simply ignore these new events, ensuring they are not impacted. New, specialized services can then be built to handle this new stream, allowing the system to grow organically.

**Example:** in a Trigger.dev v4 model, a "new event type" becomes a new task plus the call site that triggers it. Existing tasks never see the new payload, so they are unaffected.

```typescript theme={null}
// New IoT feature - add a NEW task; nothing existing changes
import { task } from '@trigger.dev/sdk/v3';

export const iotDataProcessor = task({
  id: 'iot-data-processor',
  run: async (payload: {
    sensorId: string;
    reading: number;
    timestamp: string;
    location: string;
  }) => {
    return await storeIoTReading(payload);
  },
});

// The producer adds one line to fan the new work out:
//   await iotDataProcessor.trigger({ sensorId, reading, timestamp, location });
// Existing tasks are never invoked with this payload - no impact.
```

**Benefits:**

* **Non-breaking changes** to system
* **Gradual adoption** of new features
* **Backward compatibility** maintained
* **Experimentation** with low risk

**Clarifying Additions:** Teams are not forced into a single technology path. Different services evolve using the most suitable tools for their domain. This architectural freedom supports innovation over time.

***

### 3. Compatible Schema Evolution

The architecture utilizes schema validation (Zod) to govern event structures. This allows us to evolve event payloads in a compatible manner, such as adding a new, optional `correlationId` field to an existing event without breaking any older consumer services that are not yet aware of the new field.

**Example:**

```typescript theme={null}
// Version 1: Original schema
const WorkspaceCreatedV1 = z.object({
  workspaceId: z.string(),
  ownerId: z.string(),
  createdAt: z.date()
});

// Version 2: Add optional fields (backward compatible)
const WorkspaceCreatedV2 = z.object({
  workspaceId: z.string(),
  ownerId: z.string(),
  createdAt: z.date(),
  correlationId: z.string().optional(),  // NEW: optional
  source: z.string().optional()           // NEW: optional
});

// Old consumers still work (ignore new fields)
// New consumers can use new fields
```

**Benefits:**

* **Gradual migration** of consumers
* **No breaking changes** for existing services
* **Type safety** with Zod validation
* **Clear documentation** of event structure

**Clarifying Additions:** Infrastructure changes stay isolated from business logic. Adapters act as interchangeable layers without affecting the core. This keeps the system adaptable to new technical requirements.

***

### 4. Modular Data Ownership

> **Conceptual pattern.** In a full microservice mesh each service owns a private database. **Tuturuuu does not do this today** - all apps share a single Supabase Postgres project, and per-feature isolation is enforced through schema boundaries, table ownership conventions, and RLS rather than separate physical databases. The pattern below shows how decoupled ownership *would* look and is useful when reasoning about future extraction; it is not the current deployment.

To support a new feature requiring geospatial queries, you can isolate the new data shape behind a dedicated module (its own tables, or its own database extension such as PostGIS) so it evolves independently of unrelated tables.

```typescript theme={null}
// Conceptual: a feature-owned task that writes to its own geospatial tables.
import { task } from '@trigger.dev/sdk/v3';

export const updateUserLocation = task({
  id: 'update-user-location',
  run: async (payload: { userId: string; lat: number; lng: number }) => {
    // Writes to geolocation-owned tables (e.g. a PostGIS extension),
    // without touching unrelated schemas.
    return await storeUserLocation(payload);
  },
});

// In Tuturuuu today this lives in the shared Supabase project; isolation is
// schema/RLS-based rather than a physically separate database.
```

**Benefits (of the pattern):**

* **Right tool for the job** - choose the optimal storage for each feature
* **Independent evolution** of data models
* **Bounded blast radius** for schema changes
* **Module isolation** - feature data evolves without cross-feature migrations

**Clarifying Additions:** Each module grows independently while remaining part of a cohesive whole. UI changes become safer because the blast radius stays limited. This supports consistent long-term UI development.

***

### 5. Frontend Composability

The modular frontend can be extended with new components that drive new interactions. A new dashboard widget can call a REST route (`/api/v1/...` in `apps/web`, or a Rust `apps/backend` endpoint in the migrated stack), and that route either responds directly or kicks off background work by triggering a Trigger.dev task. The widget never talks to a broker; it talks to an HTTP endpoint that owns the side effects.

**Example:**

```typescript theme={null}
// apps/web/src/components/dashboard/NewWidget.tsx
'use client';

import { useMutation } from '@tanstack/react-query';

export function NewDashboardWidget() {
  // Use TanStack Query for client mutations - never fetch in useEffect.
  const refresh = useMutation({
    mutationFn: () =>
      fetch('/api/v1/widgets/refresh', {
        method: 'POST',
        body: JSON.stringify({ widgetId: 'new-widget' }),
      }),
  });

return (
    <div className="widget">
      <button onClick={() => refresh.mutate()}>Refresh Data</button>
      {/* Widget UI */}
    </div>
  );
}

// Backend route: apps/web/src/app/api/v1/widgets/refresh/route.ts
import { tasks } from '@trigger.dev/sdk/v3';

export async function POST(request: Request) {
  const { widgetId } = await request.json();

// Kick off background work by triggering a task (no broker publish).
  await tasks.trigger('refresh-widget', { widgetId });

return Response.json({ success: true });
}
```

**Benefits:**

* **Frontend-driven innovation** - the UI team can add features
* **Clean integration** via stable HTTP routes that own the side effects
* **Backend extensibility** without tight coupling to the client
* **Feature experimentation** with low risk

**Clarifying Additions:** Frontends stay insulated from backend restructuring. The HTTP route is the stable interface even as the work behind it moves between an inline handler and a background task. This continuity simplifies client-side development and survives the `apps/web` to `apps/tanstack-web` + `apps/backend` migration.

***

## Resilience (5 Reasons)

Resilience is an intrinsic property of this loosely coupled, asynchronous architecture.

### 1. The Queue as a Stability Buffer (Temporal Decoupling)

If downstream processing is slow or temporarily unavailable, the code that triggers it is unaffected: triggering a Trigger.dev task enqueues a run and returns immediately. Trigger.dev persists and retries runs, so work is not lost while a task's worker capacity catches up. The same buffering property holds in a full broker too; in Tuturuuu it is provided by Trigger.dev's managed run queue rather than a self-hosted broker.

**Example:**

```typescript theme={null}
import { task, tasks } from '@trigger.dev/sdk/v3';

// The caller continues working even if processing is backed up.
await tasks.trigger('process-report', { reportId, data });
// Returns immediately - it does not wait for the run to complete.

// The task drains its backlog at its own sustainable pace.
export const processReport = task({
  id: 'process-report',
  queue: { concurrencyLimit: 5 },
  run: async (payload: { reportId: string; data: unknown }) => {
    return await generateReport(payload);
  },
});
```

**Benefits:**

* **Zero data loss** during outages
* **Automatic recovery** when service restarts
* **Producer isolation** from consumer failures
* **System resilience** to partial failures

**Clarifying Additions:** Failures stay local rather than affecting the entire system. The architecture encourages designing for graceful degradation. This improves overall system continuity.

***

### 2. Asynchronous, Non-Blocking Communication

Producers "fire and forget" events without waiting for a response. This prevents cascading failures, where a slow consumer would otherwise block an upstream service and cause a system-wide slowdown.

**Example:**

```typescript theme={null}
// SYNCHRONOUS (problematic):
async function createWorkspace(data) {
  const workspace = await db.createWorkspace(data);

// Blocks if email service is slow (5 seconds)
  await sendWelcomeEmail(workspace.ownerId);  // BLOCKS HERE

// Blocks if provisioning is slow (10 seconds)
  await provisionResources(workspace.id);      // BLOCKS HERE

return workspace;  // User waits 15+ seconds
}

// EVENT-DRIVEN (resilient):
import { tasks } from '@trigger.dev/sdk/v3';

async function createWorkspace(data) {
  const workspace = await db.createWorkspace(data);

// Non-blocking - enqueues background work and returns immediately
  await tasks.trigger('workspace-created-followups', { workspaceId: workspace.id });

return workspace;  // User gets a response in <1 second
}

// Tasks run asynchronously.
// If the email step is slow, it does not affect the user-facing response.
```

**Benefits:**

* **Fast user responses** - no blocking on background work
* **Isolation from slow consumers**
* **Better resource utilization**
* **Improved user experience**

**Clarifying Additions:** Resilience logic becomes consistent for all services. The system handles temporary failures automatically without client-side complexity. This stabilizes user experience during partial outages.

***

### 3. Idempotent Consumer Design

A core resilience pattern is to make task handlers idempotent so they can safely run on the same payload more than once without duplicate side effects. Trigger.dev retries failed runs (and supports an `idempotencyKey` on trigger), so a task that crashes after sending an email but before recording it may run again; idempotency ensures that retry does not corrupt state.

**Example:**

```typescript theme={null}
import { task } from '@trigger.dev/sdk/v3';

export const sendWelcomeEmail = task({
  id: 'send-welcome-email',
  run: async (payload: { userId: string; email: string }) => {
    const { userId, email } = payload;

// Idempotent: check if already sent before sending.
    const existingEmail = await db.sentEmails.findOne({
      userId,
      type: 'welcome',
    });

if (existingEmail) {
      // Already sent - skip (idempotent behavior).
      return { skipped: true };
    }

await sendEmail({ to: email, template: 'welcome' });

await db.sentEmails.insert({ userId, type: 'welcome', sentAt: new Date() });

return { sent: true };
  },
});

// If this run is retried, the user does not get a duplicate email.
// Triggering with an idempotencyKey also deduplicates the run itself:
//   sendWelcomeEmail.trigger(payload, { idempotencyKey: `welcome-${userId}` });
```

**Benefits:**

* **Safe retries** without side effects
* **Data consistency** even with failures
* **Simple error recovery** - just retry
* **Reliable processing** guarantees

**Clarifying Additions:** Availability remains high because traffic avoids unhealthy components. Failover happens without requiring operator involvement. This supports seamless recovery.

***

### 4. Retries and a Dead-Letter Path for Error Handling

> **Conceptual + partial.** A true dead-letter *queue* (a separate topic the broker auto-routes poison messages to) is a broker primitive Tuturuuu does not run. Trigger.dev v4 *does* provide the durable building blocks: per-task `retry` policies and the ability to hand a permanently failing payload off to a dedicated "dead-letter" follow-up task for offline analysis. The example below uses real v4 `retry` config and models the dead-letter step as an explicit follow-up trigger.

For payloads that consistently fail (e.g., malformed data), configure bounded retries and route the still-failing payload to a dedicated task instead of letting it block the rest of the workload.

```typescript theme={null}
import { task, tasks } from '@trigger.dev/sdk/v3';

export const processPayment = task({
  id: 'process-payment',
  // Real v4 retry policy: bounded, exponential backoff.
  retry: { maxAttempts: 3, factor: 2, minTimeoutInMs: 1000 },
  run: async (payload: { id: string }) => {
    return await chargePaymentMethod(payload);
  },
  // Runs after all retries are exhausted - the "dead-letter" hand-off.
  handleError: async (payload, error) => {
    await tasks.trigger('payment-dead-letter', {
      originalPayload: payload,
      error: error instanceof Error ? error.message : 'Unknown error',
    });
  },
});

// Dedicated task that records failures and alerts for manual review.
export const paymentDeadLetter = task({
  id: 'payment-dead-letter',
  run: async (payload: { originalPayload: { id: string }; error: string }) => {
    await recordFailedPayment(payload);
    await alertOnCallTeam(payload.originalPayload.id);
  },
});
```

> [!NOTE]
>
> Confirm the exact `retry` / `handleError` field names against the installed `@trigger.dev/sdk` v4 types before copying this verbatim; the shape above illustrates the pattern, and Tuturuuu's own tasks in `packages/trigger/src` favor catching errors inside `run` and returning a `{ success: false }` result.

**Benefits:**

* **Poison pill isolation** - one bad message doesn't stop queue
* **Automatic retry** for transient errors
* **Manual review** for persistent errors
* **Pattern detection** for systemic issues

**Clarifying Additions:** Workloads continue flowing even when some services are unavailable. Components operate at different speeds without blocking each other. This improves stability in distributed workflows.

***

### 5. Replayability for Disaster Recovery

> **Conceptual - not implemented in Tuturuuu.** This is a classic *event-sourcing* property: when an immutable, ordered log of domain events is the source of truth, you can rebuild any derived state by replaying that log from a known-good point. **Tuturuuu is not event-sourced** - state lives in Supabase Postgres tables, recovery relies on Postgres backups/PITR, and Trigger.dev v4 has no "replay this date range of events" trigger like the one previous versions of this page implied. Keep this section as a mental model for derived/cached state, not as an operational runbook.

**How it would work (event-sourcing concept):**

```text theme={null}
DISASTER: a derived read model (e.g. a cache or projection) is corrupted by a bug.
1. Stop the consumer that builds the read model.
2. Deploy the fixed projection logic.
3. Discard the corrupted derived state.
4. Re-process the durable source events in order to rebuild the read model.
```

```typescript theme={null}
// Conceptual rebuild loop - a plain task that re-applies events you have
// stored durably. There is no built-in Trigger.dev "replay by date" trigger;
// you supply the events yourself (e.g. from an append-only table).
import { task } from '@trigger.dev/sdk/v3';

export const rebuildUserProjection = task({
  id: 'rebuild-user-projection',
  run: async (payload: { event: UserEvent }) => {
    const { event } = payload;
    if (event.type === 'user.registered') await db.users.insert(event);
    else if (event.type === 'user.updated') await db.users.update(event.userId, event);
    else if (event.type === 'user.deleted') await db.users.delete(event.userId);
  },
});
```

**Why Tuturuuu relies on backups instead:** without an append-only event log as the system of record, the durable truth is the Postgres tables themselves. Disaster recovery uses Supabase backups and point-in-time recovery rather than log replay.

**Benefits (of the event-sourcing pattern, where adopted):**

* **State reconstruction** from a durable event log
* **Bug-fix validation** by re-deriving projections
* **Audit trail** for compliance

**Clarifying Additions:** Treat derived/cached data as rebuildable from a durable source. For Tuturuuu that durable source is Postgres plus its backups; for a true event-sourced subsystem it would be the event log.

***

## Scalability (5 Reasons)

The event-driven model is inherently designed for high-throughput and elastic scaling.

### 1. Parallel Processing via Concurrency

To increase throughput, you raise the task's allowed concurrency and let more runs execute in parallel. In a Kafka-style system this is done with consumer groups; in Tuturuuu it is Trigger.dev's managed concurrency - you define the task once and set a `queue.concurrencyLimit` (and queue-level controls) rather than running and balancing your own consumer instances.

**Example:**

```typescript theme={null}
import { task } from '@trigger.dev/sdk/v3';

export const processAnalytics = task({
  id: 'process-analytics',
  // Higher concurrency = more parallel runs = more throughput.
  queue: { concurrencyLimit: 50 },
  run: async (payload: { userId: string; activity: unknown }) => {
    return await aggregateMetrics(payload);
  },
});

// Trigger.dev schedules many runs of this task in parallel up to the limit,
// so raising the concurrency limit raises throughput without code changes.
```

**Benefits:**

* **Throughput scales with concurrency** - raise the limit, process more in parallel
* **Managed scheduling** - no consumer instances to run or balance yourself
* **No code changes** required to scale
* **Cost-effective** - tune concurrency up or down as needed

**Clarifying Additions:** Each service grows according to its actual demand rather than the needs of the system as a whole. This leads to better resource distribution. It prevents unnecessary scaling of unrelated components.

***

### 2. Per-Entity Ordering with Parallelism Across Entities

A common scaling goal is: process work for a single entity (e.g. one workspace) in order, while processing different entities fully in parallel. Kafka achieves this with topic partitions keyed by a business key; Tuturuuu does not run Kafka topics. The closest Trigger.dev mechanism is a **concurrency key** plus per-queue concurrency limits, which serialize runs that share a key while letting different keys run in parallel.

**Example:**

```typescript theme={null}
import { task } from '@trigger.dev/sdk/v3';

export const updateWorkspace = task({
  id: 'update-workspace',
  // Serialize runs per workspace (one in flight per concurrencyKey),
  // while different workspaces run in parallel.
  queue: { concurrencyLimit: 25 },
  run: async (payload: { workspaceId: string; data: unknown }) => {
    return await applyWorkspaceUpdate(payload);
  },
});

// Trigger per workspace so same-workspace runs are ordered:
//   updateWorkspace.trigger(payload, { concurrencyKey: payload.workspaceId });
//
// Workspace A runs: serialized (ordered)
// Workspace B runs: serialized (ordered), in parallel with A
// Workspace C runs: serialized (ordered), in parallel with A & B
```

> [!NOTE]
>
> This maps the partitioning *concept* onto Trigger.dev v4. Verify the `concurrencyKey` option name against the installed SDK before relying on it; there are no Kafka topics, partitions, or broker ACLs in Tuturuuu.

**Benefits:**

* **Ordering guarantees** per entity (per concurrency key)
* **Maximum parallelism** across distinct entities
* **Optimal throughput** with consistency
* **Scalable architecture**

**Clarifying Additions:** Stateless components are easy to duplicate and coordinate. Scaling becomes predictable and controllable. Traffic fluctuations can be handled efficiently.

***

### 3. Independent Scaling per Workload

Different workloads scale on their own axis. In Tuturuuu this shows up two ways: the deployable apps (`apps/web`, the migration target `apps/tanstack-web`, and the Rust `apps/backend`) scale at the deployment layer, and each Trigger.dev task carries its own concurrency budget so a heavy task can run wide while a light one stays narrow - without coupling either to a single shared scale knob.

**Example:**

```typescript theme={null}
import { task } from '@trigger.dev/sdk/v3';

// Heavy, high-volume work: allow many parallel runs.
export const processAnalytics = task({
  id: 'process-analytics',
  queue: { concurrencyLimit: 100 },
  run: async (payload) => aggregateMetrics(payload),
});

// Low-volume, rate-sensitive work: keep it narrow.
export const sendReport = task({
  id: 'send-report',
  queue: { concurrencyLimit: 2 },
  run: async (payload) => deliverReport(payload),
});

// Each task scales independently via its own concurrency limit -
// no need to scale the whole app to speed up one workload.
```

**Benefits:**

* **Granular scaling** per service
* **Cost optimization** - only scale what's needed
* **Resource efficiency**
* **Performance optimization** per workload

**Clarifying Additions:** Uniform request handling promotes system stability. Load is shared automatically without service-specific logic. This ensures consistent performance at scale.

***

### 4. The Run Queue as a Load Absorber

A managed run queue can absorb sudden bursts of triggered work. It smooths out load so tasks process at their own sustainable pace (bounded by concurrency) without being overwhelmed. In Tuturuuu this absorber is the Trigger.dev run queue; the same role would be played by a broker in a Kafka-style system.

**Example:**

```mermaid theme={null}
graph LR
    A[Traffic Spike<br/>10,000 triggers/sec] -->|Enqueues all| B[Trigger.dev Run Queue<br/>Buffers runs]
    B -->|Drains at<br/>concurrency limit| C[Task Workers<br/>Process sustainably]

style B fill:#4f46e5,stroke:#3730a3,color:#fff
```

**Benefits:**

* **Spike protection** - absorbs bursts
* **Sustainable processing** rates
* **No service overload**
* **Improved reliability**

**Clarifying Additions:** Separating reads from writes avoids resource contention. High-traffic paths get dedicated scaling strategies. This improves responsiveness and throughput.

***

### 5. CQRS for Optimized Read Performance

An asynchronous, task-based flow is a natural fit for Command Query Responsibility Segregation (CQRS). A "command" writes the authoritative record and then triggers a background task; that task maintains a read-optimized model (for example a denormalized cache), letting read-heavy paths scale independently and deliver low latency.

> **Conceptual.** Tuturuuu does not run a formal CQRS split today; this shows how the pattern maps onto the real `task()` API if you adopt it for a read-heavy surface.

**Example:**

```typescript theme={null}
import { task, tasks } from '@trigger.dev/sdk/v3';

// COMMAND: write the authoritative record, then trigger the projection.
async function updateWorkspace(id: string, data: unknown) {
  await db.workspaces.update(id, data);
  await tasks.trigger('update-workspace-cache', { workspaceId: id, data });
}

// QUERY: maintain a read-optimized cache.
export const updateWorkspaceCache = task({
  id: 'update-workspace-cache',
  run: async (payload: { workspaceId: string; data: Record<string, unknown> }) => {
    await redis.set(
      `workspace:${payload.workspaceId}`,
      JSON.stringify({
        ...payload.data,
        memberCount: await getMemberCount(payload.workspaceId),
        lastActivity: new Date(),
      })
    );
  },
});

// Reads hit the cache (fast); writes go to Postgres (consistent).
```

**Benefits:**

* **Read/write optimization** separately
* **Low-latency reads** from cache
* **Consistent writes** to database
* **Independent scaling** of read vs write paths

**Clarifying Additions:** The system adapts naturally to changes in workload. Instances come and go without manual reconfiguration. This makes scaling continuous and flexible.

***

## Summary Matrix

## Related Documentation

* [Event-Driven Architecture](/platform/architecture/system-design/event-driven-architecture) - Detailed advantages and drawbacks
* [Architectural Decisions](/platform/architecture/system-design/architectural-decisions) - Why we chose this architecture
* [Trigger.dev Package](/reference/packages/trigger) - Implementation reference

# Hexagonal Architecture
Source: https://docs.tuturuuu.com/platform/architecture/system-design/hexagonal-architecture

An educational guide to the ports and adapters pattern, with notes on where Tuturuuu applies its ideas

# Hexagonal Architecture (Ports and Adapters)

Hexagonal Architecture, also known as Ports and Adapters, is a design pattern
for achieving **technology independence**, **testability**, and
**maintainability** by isolating core business logic from the technologies that
surround it.

> [!NOTE]
>
> This page is an **educational pattern guide**, not a description of Tuturuuu's
> current directory layout. The Tuturuuu apps (`apps/web`, `apps/finance`) are
> conventional Next.js App Router apps organized by `app/`, `components/`, `lib/`,
> and `utils/` — they do **not** use formal `domain/`, `application/`, and
> `infrastructure/` layers. The code samples below are illustrative; their file
> paths are aspirational and do not exist in the repo. Where Tuturuuu genuinely
> borrows an idea from this pattern, the text says so explicitly.

> [!NOTE]
>
> **Active runtime.** Web and satellite apps use Next.js. Rust and TanStack Start
> are paused and not in use; their retained designs are not a setup or parity
> requirement. See the [active runtime map](/build/devops/active-runtime).
> Treat the patterns below as portable design ideas, not a structural mandate.

## Core Concept

The hexagon represents your application's core business logic. **Ports** are interfaces that define how the outside world can interact with your application, and **Adapters** are implementations that connect external technologies to these ports.

```mermaid theme={null}
graph TB
    subgraph "External World"
        A[HTTP/API]
        B[Database]
        C[Event Broker]
        D[External Services]
    end

subgraph "Adapters (Infrastructure)"
        E[API Adapter]
        F[Database Adapter]
        G[Event Adapter]
        H[Service Adapter]
    end

subgraph "Hexagon (Core)"
        I[Business Logic]
        J[Domain Models]
        K[Use Cases]
    end

A --> E
    B --> F
    C --> G
    D --> H
    E --> I
    F --> I
    G --> I
    H --> I
    I --> J
    I --> K

style I fill:#4f46e5,stroke:#3730a3,color:#fff
    style J fill:#4f46e5,stroke:#3730a3,color:#fff
    style K fill:#4f46e5,stroke:#3730a3,color:#fff
```

## How Tuturuuu Actually Structures Apps

Before the conceptual layers below, here is the real layout you will find in the
codebase today. The Next.js apps are organized by concern, not by hexagonal
layer:

```
apps/web/src/
├── app/          # Next.js App Router routes + /api/v1 REST handlers (presentation)
├── components/   # React components (presentation)
├── features/     # Feature-scoped UI and logic
├── hooks/        # Client hooks (TanStack Query, etc.)
├── lib/          # Cross-cutting helpers and clients
├── utils/        # Pure utilities
├── constants/    # Static config
└── trpc/         # Minimal tRPC stub (health-check only — not the product data path)
```

Product data flows through shared helpers in `packages/internal-api` and the
REST `/api/v1` routes — **not** through tRPC, which in `apps/web/src/trpc` is
only a `healthCheck` stub today. Cross-app concerns live in `packages/*`
(`packages/supabase`, `packages/payment`, `packages/trigger`,
`packages/internal-api`, `packages/ui`, ...), which is where most "swap the
adapter" flexibility actually lives in practice.

The sections that follow describe the **idealized hexagonal layers** as a
learning model. Read them for the concepts; do not expect to find these exact
directories in the repo.

## The Idealized Layers (Conceptual)

### 1. Domain Layer (Core Business Logic)

**Conceptual location:** `domain/` (illustrative — not a real directory in Tuturuuu)

**Responsibilities:**

* Pure business logic and rules
* Domain models (entities, value objects)
* Domain services (complex business operations)
* Domain events

**Characteristics:**

* No dependencies on external libraries
* No knowledge of databases, APIs, or frameworks
* Fully unit-testable without infrastructure

**Example (illustrative — this file does not exist in the repo):**

```typescript theme={null}
// Illustrative: domain/models/workspace.ts
export class Workspace {
  private constructor(
    public readonly id: string,
    public readonly ownerId: string,
    private _name: string,
    private _isActive: boolean,
    private _plan: WorkspacePlan,
    public readonly createdAt: Date,
    private _updatedAt: Date
  ) {}

static create(ownerId: string, name: string, plan: WorkspacePlan): Workspace {
    // Business rules
    this.validateName(name);

return new Workspace(
      generateId(),
      ownerId,
      name,
      true,
      plan,
      new Date(),
      new Date()
    );
  }

rename(newName: string): void {
    Workspace.validateName(newName);
    this._name = newName;
    this._updatedAt = new Date();
  }

upgrade(newPlan: WorkspacePlan): void {
    if (newPlan.tier <= this._plan.tier) {
      throw new DomainError('Can only upgrade to higher tier');
    }
    this._plan = newPlan;
    this._updatedAt = new Date();
  }

deactivate(): void {
    if (!this._isActive) {
      throw new DomainError('Workspace already inactive');
    }
    this._isActive = false;
    this._updatedAt = new Date();
  }

private static validateName(name: string): void {
    if (name.length < 3 || name.length > 50) {
      throw new DomainError('Workspace name must be 3-50 characters');
    }
    if (!/^[a-zA-Z0-9\s-]+$/.test(name)) {
      throw new DomainError('Workspace name contains invalid characters');
    }
  }

// Getters only - no setters (encapsulation)
  get name() { return this._name; }
  get isActive() { return this._isActive; }
  get plan() { return this._plan; }
  get updatedAt() { return this._updatedAt; }
}
```

### 2. Application Layer (Use Cases / Orchestration)

**Conceptual location:** `application/` (illustrative — not a real directory in Tuturuuu)

**Responsibilities:**

* Orchestrate domain objects
* Implement use cases (business workflows)
* Transaction management
* Call infrastructure services via ports

**Example (illustrative):**

```typescript theme={null}
// Illustrative: application/use-cases/create-workspace.ts
export interface WorkspaceRepository {
  save(workspace: Workspace): Promise<void>;
  findById(id: string): Promise<Workspace | null>;
  findByOwnerId(ownerId: string): Promise<Workspace[]>;
}

export interface EventPublisher {
  publish(event: DomainEvent): Promise<void>;
}

export class CreateWorkspaceUseCase {
  constructor(
    private readonly repository: WorkspaceRepository,  // PORT
    private readonly eventPublisher: EventPublisher     // PORT
  ) {}

async execute(command: CreateWorkspaceCommand): Promise<Workspace> {
    // 1. Business logic (domain)
    const workspace = Workspace.create(
      command.ownerId,
      command.name,
      command.plan
    );

// 2. Persist (via port)
    await this.repository.save(workspace);

// 3. Publish event (via port)
    await this.eventPublisher.publish(
      new WorkspaceCreatedEvent(workspace.id, workspace.ownerId)
    );

return workspace;
  }
}
```

### 3. Infrastructure Layer (Adapters)

**Conceptual location:** `infrastructure/` (illustrative — not a real directory in Tuturuuu)

**Responsibilities:**

* Implement ports defined by application/domain
* Handle technology-specific details
* Database access, API calls, event publishing

**Example (illustrative):**

```typescript theme={null}
// Illustrative: infrastructure/repositories/supabase-workspace-repository.ts
import { WorkspaceRepository } from '@/application/use-cases/create-workspace';

export class SupabaseWorkspaceRepository implements WorkspaceRepository {
  constructor(private readonly supabase: SupabaseClient) {}

async save(workspace: Workspace): Promise<void> {
    const data = this.toDatabaseModel(workspace);

await this.supabase
      .from('workspaces')
      .upsert(data);
  }

async findById(id: string): Promise<Workspace | null> {
    const { data } = await this.supabase
      .from('workspaces')
      .select('*')
      .eq('id', id)
      .single();

return data ? this.toDomainModel(data) : null;
  }

async findByOwnerId(ownerId: string): Promise<Workspace[]> {
    const { data } = await this.supabase
      .from('workspaces')
      .select('*')
      .eq('owner_id', ownerId);

return (data || []).map(row => this.toDomainModel(row));
  }

private toDomainModel(data: any): Workspace {
    // Map database row to domain model
    return new Workspace(
      data.id,
      data.owner_id,
      data.name,
      data.is_active,
      new WorkspacePlan(data.plan_tier, data.plan_features),
      new Date(data.created_at),
      new Date(data.updated_at)
    );
  }

private toDatabaseModel(workspace: Workspace): any {
    // Map domain model to database row
    return {
      id: workspace.id,
      owner_id: workspace.ownerId,
      name: workspace.name,
      is_active: workspace.isActive,
      plan_tier: workspace.plan.tier,
      plan_features: workspace.plan.features,
      created_at: workspace.createdAt.toISOString(),
      updated_at: workspace.updatedAt.toISOString()
    };
  }
}
```

### 4. Presentation Layer (API / UI)

**Real location:** `apps/web/src/app/api/v1/` (REST handlers) or `apps/web/src/app/`
(routes/pages). This is the one layer that maps cleanly onto Tuturuuu's actual
structure.

**Responsibilities:**

* HTTP request/response handling
* Input validation (DTOs)
* Authentication/authorization
* Call application use cases

In real Tuturuuu code, a route handler does its own validation, gets an
**awaited** Supabase client (`createClient()` from `@tuturuuu/supabase/next/server`
is async), checks auth via `supabase.auth.getUser()`, and then calls a helper.
The example below keeps the use-case indirection for teaching purposes:

**Example (illustrative use-case wiring; Supabase client usage is real):**

```typescript theme={null}
// Illustrative: apps/web/src/app/api/v1/workspaces/create/route.ts
import { createClient } from '@tuturuuu/supabase/next/server';
import { CreateWorkspaceUseCase } from '@/application/use-cases/create-workspace';

const CreateWorkspaceRequestSchema = z.object({
  name: z.string().min(3).max(50),
  plan: z.enum(['free', 'pro', 'enterprise'])
});

export async function POST(request: Request) {
  // 1. Authentication — createClient() is async; await it
  const supabase = await createClient();
  const {
    data: { user },
  } = await supabase.auth.getUser();
  if (!user) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 });
  }

// 2. Validation
  const body = await request.json();
  const validation = CreateWorkspaceRequestSchema.safeParse(body);

if (!validation.success) {
    return Response.json(
      { error: validation.error.issues },
      { status: 400 }
    );
  }

// 3. Execute use case
  const useCase = new CreateWorkspaceUseCase(
    new SupabaseWorkspaceRepository(supabase),
    new TriggerWorkspaceEventPublisher()
  );

try {
    const workspace = await useCase.execute({
      ownerId: user.id,
      name: validation.data.name,
      plan: new WorkspacePlan(validation.data.plan)
    });

// 4. Response (DTO)
    return Response.json({
      id: workspace.id,
      name: workspace.name,
      ownerId: workspace.ownerId,
      plan: workspace.plan.tier,
      createdAt: workspace.createdAt.toISOString()
    }, { status: 201 });
  } catch (error) {
    if (error instanceof DomainError) {
      return Response.json({ error: error.message }, { status: 400 });
    }
    return Response.json({ error: 'Internal error' }, { status: 500 });
  }
}
```

## Key Benefits

### 1. Technology Independence

The core business logic has **zero knowledge** of the technologies used. We can swap Supabase for Prisma, Drizzle, or even MongoDB without touching business logic.

**Example migration:**

```typescript theme={null}
// OLD: Supabase adapter
class SupabaseWorkspaceRepository implements WorkspaceRepository { /* ... */ }

// NEW: Drizzle adapter (same interface)
class DrizzleWorkspaceRepository implements WorkspaceRepository {
  constructor(private readonly db: DrizzleDB) {}

async save(workspace: Workspace): Promise<void> {
    await this.db
      .insert(workspaces)
      .values(this.toDatabaseModel(workspace));
  }

// Same interface, different implementation
}

// Business logic unchanged!
```

### 2. Testability

Domain logic can be tested **without any infrastructure**:

```typescript theme={null}
// tests/domain/workspace.test.ts
describe('Workspace', () => {
  it('enforces name length rules', () => {
    expect(() => {
      Workspace.create('user-1', 'ab', FreePlan);
    }).toThrow('Workspace name must be 3-50 characters');
  });

it('prevents downgrade', () => {
    const workspace = Workspace.create('user-1', 'Test', ProPlan);

expect(() => {
      workspace.upgrade(FreePlan);
    }).toThrow('Can only upgrade to higher tier');
  });
});
// No database, no HTTP, no network - millisecond tests
```

Application layer with mocks:

```typescript theme={null}
// tests/application/create-workspace.test.ts
class InMemoryWorkspaceRepository implements WorkspaceRepository {
  private workspaces = new Map<string, Workspace>();

async save(workspace: Workspace): Promise<void> {
    this.workspaces.set(workspace.id, workspace);
  }

async findById(id: string): Promise<Workspace | null> {
    return this.workspaces.get(id) || null;
  }
}

describe('CreateWorkspaceUseCase', () => {
  it('creates workspace and publishes event', async () => {
    const repository = new InMemoryWorkspaceRepository();
    const eventPublisher = new InMemoryEventPublisher();
    const useCase = new CreateWorkspaceUseCase(repository, eventPublisher);

const workspace = await useCase.execute({
      ownerId: 'user-1',
      name: 'Test Workspace',
      plan: FreePlan
    });

expect(workspace.name).toBe('Test Workspace');
    expect(eventPublisher.events).toHaveLength(1);
    expect(eventPublisher.events[0]).toBeInstanceOf(WorkspaceCreatedEvent);
  });
});
```

### 3. Maintainability

**Clear boundaries** make it obvious where code belongs:

* Business rules → Domain layer
* Workflows → Application layer
* Technology details → Infrastructure layer
* HTTP handling → Presentation layer

## Ports (Interfaces)

Ports are **contracts** defined by the application/domain:

```typescript theme={null}
// Inbound ports (driving - from outside to core)
export interface CreateWorkspaceCommand {
  ownerId: string;
  name: string;
  plan: WorkspacePlan;
}

// Outbound ports (driven - from core to outside)
export interface WorkspaceRepository {
  save(workspace: Workspace): Promise<void>;
  findById(id: string): Promise<Workspace | null>;
  findByOwnerId(ownerId: string): Promise<Workspace[]>;
  delete(id: string): Promise<void>;
}

export interface EventPublisher {
  publish(event: DomainEvent): Promise<void>;
}

export interface EmailService {
  sendWorkspaceInvitation(email: string, workspaceId: string): Promise<void>;
}
```

## Adapters (Implementations)

Adapters **implement** the ports:

```typescript theme={null}
// Repository adapter
export class SupabaseWorkspaceRepository implements WorkspaceRepository { /* ... */ }

// Event publisher adapter.
// Tuturuuu uses Trigger.dev v4 (@trigger.dev/sdk ^4.x). There is no
// `trigger.event(...)` / `eventTrigger` API — background work is modeled as
// tasks defined with `task({ id, run })` (see packages/trigger/src) and
// invoked with `.trigger(payload)`.
import { type DomainEvent } from '@/domain/events';
import { task } from '@trigger.dev/sdk/v3';

// A real Trigger.dev v4 task lives in packages/trigger/src, e.g.:
export const workspaceCreatedTask = task({
  id: 'workspace-created',
  run: async (payload: { workspaceId: string; ownerId: string }) => {
    // ...side effects: notifications, projections, etc.
    return { ok: true };
  },
});

// The adapter just enqueues the task — keeping the core ignorant of Trigger.dev.
export class TriggerWorkspaceEventPublisher implements EventPublisher {
  async publish(event: DomainEvent): Promise<void> {
    await workspaceCreatedTask.trigger({
      workspaceId: event.payload.workspaceId,
      ownerId: event.payload.ownerId,
    });
  }
}

// Email service adapter.
// Tuturuuu sends transactional email through packages/transactional and
// packages/email-service rather than a raw provider SDK in app code; the body
// here is illustrative of how any provider would sit behind the port.
export class TransactionalEmailService implements EmailService {
  async sendWorkspaceInvitation(email: string, workspaceId: string): Promise<void> {
    await sendInvitationEmail({ to: email, workspaceId });
  }
}
```

## Dependency Injection

Wire adapters to use cases. Note that `createClient()` is async, so the factory
must be async too:

```typescript theme={null}
// Illustrative: lib/container.ts (no such DI container exists in Tuturuuu today)
import { createClient } from '@tuturuuu/supabase/next/server';

export async function createWorkspaceUseCase(): Promise<CreateWorkspaceUseCase> {
  const supabase = await createClient();
  return new CreateWorkspaceUseCase(
    new SupabaseWorkspaceRepository(supabase),
    new TriggerWorkspaceEventPublisher()
  );
}

// Usage in API route
const useCase = await createWorkspaceUseCase();
const result = await useCase.execute(command);
```

> [!NOTE]
>
> Tuturuuu does **not** ship a formal DI container. Route handlers and
> `packages/internal-api` helpers wire their dependencies directly. The factory
> above shows the pattern conceptually.

## Directory Structure Example (Illustrative)

The tree below shows what a **fully layered** hexagonal app could look like. It
is a teaching illustration — **Tuturuuu does not use this layout.** For the
actual structure, see [How Tuturuuu Actually Structures Apps](#how-tuturuuu-actually-structures-apps)
above.

```
src/                                 # Illustrative hexagonal layout (NOT the real apps/web layout)
├── domain/                          # Core (no dependencies)
│   ├── models/
│   │   ├── workspace.ts             # Domain entities
│   │   └── workspace-plan.ts
│   ├── services/
│   │   └── workspace-service.ts     # Domain logic
│   └── events/
│       └── workspace-created.ts     # Domain events
├── application/                     # Use cases (depends on domain)
│   └── use-cases/
│       ├── create-workspace.ts      # Defines ports
│       ├── update-workspace.ts
│       └── delete-workspace.ts
├── infrastructure/                  # Adapters (implements ports)
│   ├── repositories/
│   │   └── supabase-workspace-repository.ts
│   ├── events/
│   │   └── trigger-workspace-publisher.ts
│   └── email/
│       └── transactional-email-service.ts
└── app/                             # Presentation
    └── api/v1/workspaces/
        ├── create/route.ts          # HTTP adapter
        └── [id]/route.ts
```

## C4 Component Diagram Explanations

The C4 model provides a structured way to visualize software architecture at different levels of abstraction. At the Component level, we focus on the major structural building blocks and their interactions within a system.

### Backend – Applying Ports and Adapters to Payments

> [!NOTE]
>
> The original version of this section described a Java/Kafka/Redis/Stripe payment
> microservice. **None of that exists in Tuturuuu.** Payments are handled by
> `packages/payment`, which currently has a single provider integration: **Polar**
> (`packages/payment/src/polar`, with `checkout/`, `client.ts`, `server.ts`, and
> Next.js helpers under `next/`). There is no Kafka, no Redis, no Stripe SDK, and
> no Java. The dedicated backend is the **Rust** service in `apps/backend`
> (route modules such as `inventory.rs`, `aurora.rs`, `nova.rs`,
> `onboarding_progress.rs`), not a JVM microservice.

The ports-and-adapters *idea* still maps cleanly onto how `packages/payment` is
organized, even though the package does not enforce formal layers:

**Inbound (Outside → Core):**

Requests enter through HTTP route handlers (in `apps/web` `/api/v1` today, and
increasingly in `apps/backend` Rust routes) and provider webhooks. These
translate transport payloads into typed inputs and call payment helpers — the
"inbound adapter" role.

**Core (Business Rules):**

Subscription tier logic, entitlement checks, and checkout orchestration are the
domain concern. Keeping these decisions independent of the provider is the goal:
the rest of the platform asks "what tier is this workspace?" without caring that
Polar answers it.

**Outbound (Core → Outside):**

The **Polar provider** in `packages/payment/src/polar` is the outbound adapter
to the payment processor. Persistence flows through the shared Supabase project
(`packages/supabase`), not a dedicated payment database. If Tuturuuu added a
second processor, it would implement the same client/checkout contract behind
the existing interface — which is exactly the substitutability hexagonal
architecture is designed to give you.

**Why the pattern still helps here:**

Even without formal `domain/`/`application/`/`infrastructure/` directories,
isolating the provider behind `packages/payment` keeps the swap surface small.
That is the practical, real-world takeaway from this pattern in Tuturuuu — a
clean seam around an external dependency, not a strict layered file tree.

### Frontend – Headless UI React Architecture (C4 Component Diagram)

The frontend separates rendering from state and behavioural logic to maintain
scalability and reusability. This part of the description **does** broadly match
Tuturuuu's real conventions (Server Components by default, client hooks for
interactivity, shared UI in `packages/ui`).

**Presentation Layer:**

Each **route/page** acts as a top-level container that orchestrates data loading
and renders UI components. Visual components stay purely presentational, while
stateful or behavioural logic is delegated to **hooks** (`apps/web/src/hooks`,
typically TanStack Query for fetching and mutations). Per the platform rules,
data fetching is **not** done in `useEffect`.

**Communication Layer:**

Client-side data access flows through **TanStack Query** hooks, and app API
access is routed through the shared **`packages/internal-api`** helpers rather
than raw client-side `fetch` against app endpoints. Backend calls target the
REST `/api/v1` routes today and, increasingly, the Rust `apps/backend` service.

**Shared Component Library:**

Reusable UI building blocks live in **`packages/ui`** (imported via
`@tuturuuu/ui/*`), with shared icons in **`packages/icons`** (`@tuturuuu/icons`),
supporting composability and reducing duplication across apps.

**Layer Separation:**

This architecture clearly separates **Presentation → Logic → Communication** layers, enabling maintainable state management, easier testability, and clean integration with backend APIs (Tuturuuu's `/api/v1` routes and the emerging Rust `apps/backend`). Since the diagram operates at C4 Component Level, it intentionally excludes internal React implementation details (such as local state, props, or context) and instead focuses on component roles, interactions, and the flow of data through the system.

**Key Principles:**

1. **Separation of Concerns**: UI components are purely presentational; hooks handle state and behavior
2. **Reusability**: Shared components and utilities reduce code duplication
3. **Testability**: Clear boundaries enable isolated testing of presentation, logic, and communication layers
4. **Type Safety**: Typed HTTP clients ensure contract adherence between frontend and backend

## Related Documentation

* [Architectural Decisions](/platform/architecture/system-design/architectural-decisions) - Why we chose hexagonal architecture
* [Encapsulation Patterns](/platform/architecture/system-design/encapsulation-patterns) - Layer boundaries
* [Data Fetching](/platform/architecture/data-fetching) - Integration with React

# Layering Patterns in Architecture
Source: https://docs.tuturuuu.com/platform/architecture/system-design/layering-patterns

Comprehensive comparison of N-tier, layer-based, and microservices architectural patterns in Tuturuuu

Understanding how to structure code within services is critical for maintainability and testability. This document compares traditional N-Tier architecture with modern layer-based patterns, and explains how layering works within microservices.

> [!NOTE]
>
> **Key Insight**: Layering is an **internal** concern (how code is organized within a service), while microservices is an **external** concern (how services are distributed). These patterns are complementary, not mutually exclusive.

> [!WARNING]
>
> **How to read this page.** The N-Tier, Hexagonal, Clean, and Onion sections
> below are **conceptual / educational** material that explains layering theory
> with illustrative TypeScript. Tuturuuu's apps do **not** ship a formal hexagonal
> directory layout (no `domain/`, `application/`, or `infrastructure/` folders).
> Each app is a conventional **Next.js App Router** app (`app/`, `components/`,
> `lib/`, `utils/`, `features/`) that talks to a shared Supabase project, with the
> newer backend logic moving into the Rust service in `apps/backend`. Treat the
> layered code samples as patterns to learn from, not as a map of the current
> codebase. The "Tuturuuu's Implementation" section near the end describes the
> **actual** layout.

> [!NOTE]
>
> For a comprehensive comparison of all architectural patterns with detailed pros and cons, see [Architectural Patterns Comparison](/platform/architecture/system-design/architectural-patterns-comparison).

## Architectural Layering Patterns Compared

### 1. Traditional N-Tier Architecture

#### What Is N-Tier Architecture?

N-Tier (also called "N-Layer") is a traditional architectural pattern that organizes code into horizontal layers, each responsible for a specific technical concern. The most common form is 3-tier architecture:

```mermaid theme={null}
graph TD
    A["Presentation Tier (UI)<br/>User interaction, rendering"]
    B["Business Logic Tier (BLL)<br/>Business rules, validation"]
    C["Data Access Tier (DAL)<br/>Database operations, persistence"]
    D[("Database")]

A -->|Calls| B
    B -->|Calls| C
    C -->|Queries| D

style A fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style B fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style C fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
    style D fill:#e8f5e9,stroke:#388e3c,stroke-width:2px
```

#### Characteristics of N-Tier

**Dependencies Flow Downward:**

* Presentation → Business Logic → Data Access → Database
* Each layer can only call the layer directly below it
* Upper layers depend on concrete implementations in lower layers

**Example (Traditional N-Tier):**

```typescript theme={null}
// Presentation Layer
export async function GET(request: Request) {
  const workspaceService = new WorkspaceService();
  const workspaces = await workspaceService.getWorkspaces();

return Response.json(workspaces);
}

// Business Logic Layer
export class WorkspaceService {
  async getWorkspaces() {
    // Business logic mixed with data access
    const dal = new WorkspaceDAL();
    const workspaces = await dal.findAll();

// Validation happens here
    return workspaces.filter(w => w.isActive);
  }
}

// Data Access Layer
export class WorkspaceDAL {
  async findAll() {
    // Direct database coupling
    const { data } = await supabase
      .from('workspaces')
      .select('*');

return data;
  }
}
```

#### Problems with Traditional N-Tier

1. **Tight Coupling to Infrastructure**
   * Business logic depends directly on data access layer
   * Changing databases requires modifying business logic
   * Hard to test business rules without a database

2. **Leaky Abstractions**
   * Database concerns leak into business logic (SQL, ORM entities)
   * Business logic becomes aware of persistence details
   * Domain models often have database annotations

3. **Circular Dependencies**
   * Business layer creates data access objects
   * Data access returns domain models
   * Creates tight coupling between layers

4. **Technology Lock-In**
   * Business logic married to specific ORM or database
   * Difficult to swap technologies
   * Framework dependencies throughout codebase

**Example of the Problem:**

```typescript theme={null}
// Business logic layer - TIGHTLY COUPLED to database
export class WorkspaceService {
  async createWorkspace(name: string, ownerId: string) {
    // PROBLEM: Business logic knows about Supabase
    const { data, error } = await supabase
      .from('workspaces')
      .insert({ name, owner_id: ownerId })
      .select()
      .single();

if (error) throw error;

// PROBLEM: Business validation after database insert
    if (data.name.length < 3) {
      // Too late - already in database!
      await supabase.from('workspaces').delete().eq('id', data.id);
      throw new Error('Name too short');
    }

return data;
  }
}
```

***

### 2. Modern Layer-Based Architectures

Layer-based architectures (Hexagonal, Clean, Onion) solve N-Tier's problems by inverting dependencies and organizing around business domains rather than technical layers.

#### Hexagonal Architecture (Ports & Adapters)

```mermaid theme={null}
graph TB
    subgraph External["External Systems"]
        HTTP["HTTP REST"]
        GQL["GraphQL"]
        CLI["CLI"]
        Events["Event Consumers"]
        DB[("Database")]
        MsgBus[("Message Bus")]
        Email["Email Service"]
        API["External API"]
    end

subgraph Hexagon["Hexagonal Architecture"]
        subgraph Primary["Primary Adapters<br/>(Inbound/Driving)"]
            RestCtrl["REST Controllers"]
            GqlResolv["GraphQL Resolvers"]
            CliCmd["CLI Commands"]
            EventCons["Event Consumers"]
        end

subgraph PrimaryPorts["Primary Ports<br/>(Interfaces)"]
        end

subgraph DomainCore["DOMAIN CORE<br/>(Business Logic)"]
            Entities["Entities"]
            VOs["Value Objects"]
            DomainSvc["Domain Services"]
            BizRules["Business Rules"]
        end

subgraph SecondaryPorts["Secondary Ports<br/>(Interfaces)"]
        end

subgraph Secondary["Secondary Adapters<br/>(Outbound/Driven)"]
            RepoImpl["Repository Impl"]
            EventPub["Event Publisher"]
            EmailSend["Email Sender"]
            HttpClient["HTTP Client"]
        end
    end

HTTP --> RestCtrl
    GQL --> GqlResolv
    CLI --> CliCmd
    Events --> EventCons

RestCtrl --> PrimaryPorts
    GqlResolv --> PrimaryPorts
    CliCmd --> PrimaryPorts
    EventCons --> PrimaryPorts

PrimaryPorts --> DomainCore
    DomainCore --> SecondaryPorts

SecondaryPorts --> RepoImpl
    SecondaryPorts --> EventPub
    SecondaryPorts --> EmailSend
    SecondaryPorts --> HttpClient

RepoImpl --> DB
    EventPub --> MsgBus
    EmailSend --> Email
    HttpClient --> API

style DomainCore fill:#ffd54f,stroke:#f57f17,stroke-width:3px
    style PrimaryPorts fill:#81c784,stroke:#388e3c,stroke-width:2px
    style SecondaryPorts fill:#81c784,stroke:#388e3c,stroke-width:2px
    style Primary fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style Secondary fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
```

**Key Principles:**

1. **Dependency Inversion**: Domain defines interfaces (ports), infrastructure implements them (adapters)
2. **Domain Core is Pure**: No infrastructure dependencies, no framework code
3. **Testability**: Domain can be tested in isolation with test doubles
4. **Technology Agnostic**: Infrastructure can be swapped without changing business logic

**Example (Hexagonal Architecture):**

```typescript theme={null}
// ===== DOMAIN CORE (Pure Business Logic) =====

// Domain Entity - No infrastructure dependencies
export class Workspace {
  private constructor(
    public readonly id: string,
    private _name: string,
    private _ownerId: string,
    private _isActive: boolean,
    public readonly createdAt: Date
  ) {}

static create(name: string, ownerId: string): Workspace {
    // Business rule: Name must be 3-50 characters
    if (name.length < 3 || name.length > 50) {
      throw new DomainError('Workspace name must be 3-50 characters');
    }

return new Workspace(
      generateId(),
      name,
      ownerId,
      true,
      new Date()
    );
  }

rename(newName: string): void {
    if (newName.length < 3 || newName.length > 50) {
      throw new DomainError('Workspace name must be 3-50 characters');
    }
    this._name = newName;
  }

archive(): void {
    if (!this._isActive) {
      throw new DomainError('Workspace is already archived');
    }
    this._isActive = false;
  }

get name(): string { return this._name; }
  get ownerId(): string { return this._ownerId; }
  get isActive(): boolean { return this._isActive; }
}

// Secondary Port - Interface defined by domain
export interface WorkspaceRepository {
  findById(id: string): Promise<Workspace | null>;
  findByOwnerId(ownerId: string): Promise<Workspace[]>;
  save(workspace: Workspace): Promise<void>;
  delete(id: string): Promise<void>;
}

// Domain Service - Pure business logic
export class WorkspaceService {
  constructor(
    private readonly repository: WorkspaceRepository  // Depends on interface
  ) {}

async createWorkspace(name: string, ownerId: string): Promise<Workspace> {
    // Business validation happens BEFORE persistence
    const workspace = Workspace.create(name, ownerId);

await this.repository.save(workspace);

return workspace;
  }

async archiveWorkspace(id: string): Promise<void> {
    const workspace = await this.repository.findById(id);
    if (!workspace) {
      throw new DomainError('Workspace not found');
    }

// Domain method encapsulates business rule
    workspace.archive();

await this.repository.save(workspace);
  }
}

// ===== INFRASTRUCTURE (Adapters) =====

// Secondary Adapter - Implements domain interface
export class SupabaseWorkspaceRepository implements WorkspaceRepository {
  constructor(private readonly supabase: SupabaseClient) {}

async findById(id: string): Promise<Workspace | null> {
    const { data } = await this.supabase
      .from('workspaces')
      .select('*')
      .eq('id', id)
      .single();

return data ? this.toDomain(data) : null;
  }

async save(workspace: Workspace): Promise<void> {
    await this.supabase
      .from('workspaces')
      .upsert(this.toDatabase(workspace));
  }

// Mapping between database schema and domain model
  private toDomain(row: any): Workspace {
    return new Workspace(
      row.id,
      row.name,
      row.owner_id,
      row.is_active,
      new Date(row.created_at)
    );
  }

private toDatabase(workspace: Workspace): any {
    return {
      id: workspace.id,
      name: workspace.name,
      owner_id: workspace.ownerId,
      is_active: workspace.isActive,
      created_at: workspace.createdAt.toISOString()
    };
  }
}

// Primary Adapter - API endpoint
export async function POST(request: Request) {
  const body = await request.json();

// Dependency injection - provide implementation.
  // Note: Tuturuuu's createClient() (@tuturuuu/supabase/next/server) is async.
  const repository = new SupabaseWorkspaceRepository(await createClient());
  const service = new WorkspaceService(repository);

const workspace = await service.createWorkspace(
    body.name,
    body.ownerId
  );

return Response.json({ workspace });
}
```

#### Benefits of Hexagonal Architecture

✅ **Domain Logic is Pure and Testable**

```typescript theme={null}
// Test without any infrastructure
describe('Workspace', () => {
  it('enforces name length business rule', () => {
    expect(() => {
      Workspace.create('ab', 'owner-123');  // Too short
    }).toThrow('Workspace name must be 3-50 characters');
  });

it('prevents archiving already archived workspace', () => {
    const workspace = Workspace.create('Test', 'owner-123');
    workspace.archive();

expect(() => workspace.archive()).toThrow('Workspace is already archived');
  });
});
```

✅ **Technology Can Be Swapped Easily**

```typescript theme={null}
// Switch from Supabase to Drizzle - domain unchanged
const repository = new DrizzleWorkspaceRepository(db);
const service = new WorkspaceService(repository);
// All business logic works identically
```

✅ **Fast, Reliable Tests**

```typescript theme={null}
// In-memory test double - runs in milliseconds
class InMemoryWorkspaceRepository implements WorkspaceRepository {
  private workspaces = new Map<string, Workspace>();

async findById(id: string) {
    return this.workspaces.get(id) || null;
  }

async save(workspace: Workspace) {
    this.workspaces.set(workspace.id, workspace);
  }
}

// Test runs instantly, no database needed
const repo = new InMemoryWorkspaceRepository();
const service = new WorkspaceService(repo);
await service.createWorkspace('Test', 'owner-123');
```

***

### 3. Clean Architecture

Clean Architecture (by Robert C. Martin) is similar to Hexagonal but emphasizes concentric circles of dependencies.

```mermaid theme={null}
graph TD
    subgraph Layer4["Frameworks & Drivers<br/>(Outermost)"]
        FW["Database, Web,<br/>External APIs, UI"]
    end

subgraph Layer3["Interface Adapters"]
        IA["Controllers,<br/>Presenters,<br/>Gateways"]
    end

subgraph Layer2["Application Business Rules"]
        ABR["Use Cases,<br/>Application Services"]
    end

subgraph Layer1["Enterprise Business Rules<br/>(Innermost)"]
        EBR["Entities,<br/>Domain Services"]
    end

style Layer1 fill:#ffd54f,stroke:#f57f17,stroke-width:4px
    style Layer2 fill:#fff3e0,stroke:#f57c00,stroke-width:3px
    style Layer3 fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style Layer4 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
```

**Key Rule**: Dependencies can only point inward. Inner circles know nothing about outer circles.

**Example Structure** (illustrative — these paths are not present in the repo):

```typescript theme={null}
// ===== INNERMOST: Enterprise Business Rules =====
// Illustrative: packages/types/src/domain/workspace.ts
export class Workspace {
  // Pure domain entity - no dependencies
}

// ===== APPLICATION LAYER: Use Cases =====
// Illustrative: src/application/use-cases/create-workspace.ts
export class CreateWorkspaceUseCase {
  constructor(
    private readonly repository: WorkspaceRepository,
    private readonly eventPublisher: EventPublisher
  ) {}

async execute(command: CreateWorkspaceCommand): Promise<Workspace> {
    // Orchestrates domain entities and infrastructure
    const workspace = Workspace.create(command.name, command.ownerId);
    await this.repository.save(workspace);
    await this.eventPublisher.publish(new WorkspaceCreatedEvent(workspace));
    return workspace;
  }
}

// ===== INTERFACE ADAPTERS: Controllers =====
// Illustrative: src/app/api/workspaces/create/route.ts
export async function POST(request: Request) {
  const useCase = new CreateWorkspaceUseCase(repository, eventPublisher);
  const workspace = await useCase.execute(command);
  return Response.json(toDTO(workspace));
}

// ===== OUTERMOST: Frameworks & Drivers =====
// Infrastructure implementations (Supabase, Trigger.dev, etc.)
```

***

### 4. Onion Architecture

Onion Architecture is similar to Clean but visualizes layers as concentric circles with explicit layer names.

```mermaid theme={null}
graph TD
    subgraph Outer["Infrastructure Layer<br/>(Outer)"]
        Infra["Database,<br/>HTTP, etc"]
    end

subgraph AppSvc["Application Services Layer"]
        App["Use Cases,<br/>Commands"]
    end

subgraph DomSvc["Domain Services Layer"]
        DS["Business<br/>Operations"]
    end

subgraph Core["Domain Model<br/>(Inner Core)"]
        DM["Entities,<br/>Value Objects,<br/>Rules"]
    end

Infra --> AppSvc
    AppSvc --> DomSvc
    DomSvc --> Core

style Core fill:#ffd54f,stroke:#f57f17,stroke-width:4px
    style DomSvc fill:#fff3e0,stroke:#f57c00,stroke-width:3px
    style AppSvc fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style Outer fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
```

All three patterns (Hexagonal, Clean, Onion) share the same core principle: **Dependency Inversion** to keep business logic pure and independent.

***

## Layering Within Microservices

### Microservices ≠ No Layering

**Common Misconception**: "Microservices replace layering."

**Reality**: Microservices is an **external** architectural pattern (how services are distributed across the network). Layering is an **internal** pattern (how code is organized within each service).

```mermaid theme={null}
graph TB
    subgraph MS["MICROSERVICES<br/>(External Architecture)"]
        subgraph ServiceA["Service A"]
            DomainA["Domain Core"]
            AdaptersA["Adapters"]
            DomainA ---|Internal<br/>Layers| AdaptersA
        end

subgraph ServiceB["Service B"]
            DomainB["Domain Core"]
            AdaptersB["Adapters"]
            DomainB ---|Internal<br/>Layers| AdaptersB
        end

subgraph ServiceC["Service C"]
            DomainC["Domain Core"]
            AdaptersC["Adapters"]
            DomainC ---|Internal<br/>Layers| AdaptersC
        end
    end

Note["Each service has internal layers<br/>(Hexagonal, Clean, or Onion)"]

style DomainA fill:#ffd54f,stroke:#f57f17,stroke-width:2px
    style DomainB fill:#ffd54f,stroke:#f57f17,stroke-width:2px
    style DomainC fill:#ffd54f,stroke:#f57f17,stroke-width:2px
    style AdaptersA fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style AdaptersB fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style AdaptersC fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style ServiceA fill:#f5f5f5,stroke:#616161,stroke-width:2px
    style ServiceB fill:#f5f5f5,stroke:#616161,stroke-width:2px
    style ServiceC fill:#f5f5f5,stroke:#616161,stroke-width:2px
    style MS fill:#fff,stroke:#000,stroke-width:3px
    style Note fill:#ffeb3b,stroke:#f57f17,stroke-width:2px
```

### Illustrative: Hexagonal Architecture Within a Service

> [!WARNING]
>
> The directory tree below is an **illustrative target** showing how a service
> *could* be organized with strict hexagonal layers. It is **not** the current
> Tuturuuu layout — `apps/web/src` and `apps/finance/src` do not contain
> `domain/`, `application/`, or `infrastructure/` folders. See
> [Tuturuuu's Implementation](#tuturuuus-implementation) for the real structure.

```text theme={null}
# Aspirational hexagonal layout for a single service (not the current repo)
src/
├── domain/                    # Domain Core (Pure business logic)
│   ├── models/
│   │   └── workspace.ts       # Entities, Value Objects
│   └── services/
│       └── workspace-service.ts
├── application/               # Application Layer (Use Cases)
│   └── use-cases/
│       └── create-workspace.ts
├── infrastructure/            # Infrastructure (Adapters)
│   ├── repositories/
│   │   └── supabase-workspace-repository.ts
│   └── events/
│       └── trigger-publisher.ts
└── app/                       # Presentation (API Endpoints)
    └── api/workspaces/create/route.ts
```

**Why a team might adopt this approach:**

1. **Service Isolation**: Each deployable unit stays independently shippable
2. **Internal Quality**: Each service maintains clean internal architecture
3. **Technology Freedom**: Each service can use different infrastructure
4. **Testability**: Domain logic in each service is pure and testable
5. **Maintainability**: Clear structure within each service

In practice, Tuturuuu keeps most code in conventional Next.js folders and pushes
heavier backend logic into the Rust service (`apps/backend`) rather than
introducing a formal hexagonal folder hierarchy inside each frontend app.

***

## Layer-Based Architecture Inside Microservices (Deep Dive)

While microservices define how services communicate externally, the internal structure of each service is equally important. This section provides a comprehensive guide to implementing layer-based architecture within microservices.

### Why Layering Matters in Microservices

Many teams make the mistake of thinking: "We have microservices, so we don't need internal structure." This leads to:

* Business logic mixed with HTTP handling
* Database queries scattered throughout the codebase
* Difficult-to-test services
* Technology coupling within services

**The reality**: Each microservice should have clean internal architecture to maintain quality as services grow.

### Complete Layer-by-Layer Breakdown

#### Layer 1: Domain Core (Innermost)

**Purpose**: Contains pure business logic with zero external dependencies.

**Contents**:

* Entities (business objects with identity)
* Value Objects (immutable business concepts)
* Domain Services (complex business operations)
* Business Rules (validation, constraints)
* Domain Events (things that happened)

**Example - Complete Domain Layer** (illustrative path; the repo does not
contain a `src/domain/` folder):

```typescript theme={null}
// Illustrative: src/domain/models/workspace.ts
// Pure business entity - no infrastructure dependencies

export class Workspace {
  private constructor(
    public readonly id: string,
    private _name: string,
    private _ownerId: string,
    private _isActive: boolean,
    private _memberLimit: number,
    public readonly createdAt: Date
  ) {}

// Factory method - enforces business rules
  static create(name: string, ownerId: string, memberLimit: number = 10): Workspace {
    // Business Rule: Name length
    if (name.length < 3 || name.length > 50) {
      throw new DomainError('Workspace name must be 3-50 characters');
    }

// Business Rule: Member limit
    if (memberLimit < 1 || memberLimit > 1000) {
      throw new DomainError('Member limit must be 1-1000');
    }

return new Workspace(
      generateId(),
      name,
      ownerId,
      true,
      memberLimit,
      new Date()
    );
  }

// Domain behavior - business operations
  rename(newName: string): void {
    if (newName.length < 3 || newName.length > 50) {
      throw new DomainError('Workspace name must be 3-50 characters');
    }

if (newName === this._name) {
      throw new DomainError('New name must be different');
    }

this._name = newName;
  }

archive(): void {
    if (!this._isActive) {
      throw new DomainError('Workspace is already archived');
    }
    this._isActive = false;
  }

reactivate(): void {
    if (this._isActive) {
      throw new DomainError('Workspace is already active');
    }
    this._isActive = true;
  }

// Business rule encapsulated in method
  canAddMember(currentMemberCount: number): boolean {
    return currentMemberCount < this._memberLimit;
  }

// Getters
  get name(): string { return this._name; }
  get ownerId(): string { return this._ownerId; }
  get isActive(): boolean { return this._isActive; }
  get memberLimit(): number { return this._memberLimit; }
}

// Illustrative: src/domain/value-objects/email.ts
// Value Object - immutable, validated business concept
export class Email {
  private constructor(private readonly value: string) {}

static create(email: string): Email {
    // Business rule: Valid email format
    if (!this.isValidEmail(email)) {
      throw new DomainError('Invalid email format');
    }
    return new Email(email.toLowerCase());
  }

private static isValidEmail(email: string): boolean {
    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
  }

toString(): string {
    return this.value;
  }

equals(other: Email): boolean {
    return this.value === other.value;
  }
}
```

**Testing Domain Layer:**

```typescript theme={null}
// Domain tests - no infrastructure needed
describe('Workspace Domain', () => {
  describe('create', () => {
    it('creates valid workspace', () => {
      const workspace = Workspace.create('My Workspace', 'owner-123', 50);

expect(workspace.name).toBe('My Workspace');
      expect(workspace.ownerId).toBe('owner-123');
      expect(workspace.memberLimit).toBe(50);
      expect(workspace.isActive).toBe(true);
    });

it('rejects short names', () => {
      expect(() => Workspace.create('ab', 'owner-123'))
        .toThrow('Workspace name must be 3-50 characters');
    });

it('rejects invalid member limits', () => {
      expect(() => Workspace.create('Test', 'owner-123', 0))
        .toThrow('Member limit must be 1-1000');
    });
  });

describe('rename', () => {
    it('allows renaming', () => {
      const workspace = Workspace.create('Test', 'owner-123');
      workspace.rename('New Name');
      expect(workspace.name).toBe('New Name');
    });

it('rejects renaming to same name', () => {
      const workspace = Workspace.create('Test', 'owner-123');
      expect(() => workspace.rename('Test'))
        .toThrow('New name must be different');
    });
  });

describe('canAddMember', () => {
    it('allows adding when under limit', () => {
      const workspace = Workspace.create('Test', 'owner-123', 10);
      expect(workspace.canAddMember(5)).toBe(true);
    });

it('prevents adding when at limit', () => {
      const workspace = Workspace.create('Test', 'owner-123', 10);
      expect(workspace.canAddMember(10)).toBe(false);
    });
  });
});

// Tests run in milliseconds - no database, no network
```

#### Layer 2: Application Layer (Use Cases)

**Purpose**: Orchestrates domain entities and infrastructure to fulfill application workflows.

**Contents**:

* Use Cases (application workflows)
* Commands (input data structures)
* Application Services (workflow orchestration)
* DTOs (data transfer objects)

**Example - Complete Application Layer:**

```typescript theme={null}
// Illustrative: src/application/commands/create-workspace.command.ts
export interface CreateWorkspaceCommand {
  name: string;
  ownerId: string;
  memberLimit?: number;
}

// Illustrative: src/application/use-cases/create-workspace.usecase.ts
import { Workspace } from '@/domain/models/workspace';
import { WorkspaceRepository } from '@/domain/interfaces/workspace-repository';
import { EventPublisher } from '@/domain/interfaces/event-publisher';
import { WorkspaceCreatedEvent } from '@/domain/events/workspace-created.event';

export class CreateWorkspaceUseCase {
  constructor(
    private readonly repository: WorkspaceRepository,
    private readonly eventPublisher: EventPublisher,
    private readonly logger: Logger
  ) {}

async execute(command: CreateWorkspaceCommand): Promise<Workspace> {
    this.logger.info('Creating workspace', { command });

// 1. Create domain entity (business logic)
    const workspace = Workspace.create(
      command.name,
      command.ownerId,
      command.memberLimit || 10
    );

// 2. Persist (infrastructure)
    await this.repository.save(workspace);
    this.logger.info('Workspace persisted', { workspaceId: workspace.id });

// 3. Publish domain event (infrastructure)
    await this.eventPublisher.publish(
      new WorkspaceCreatedEvent(
        workspace.id,
        workspace.ownerId,
        workspace.name,
        new Date()
      )
    );
    this.logger.info('Workspace created event published', { workspaceId: workspace.id });

return workspace;
  }
}

// Illustrative: src/application/use-cases/archive-workspace.usecase.ts
export class ArchiveWorkspaceUseCase {
  constructor(
    private readonly repository: WorkspaceRepository,
    private readonly eventPublisher: EventPublisher
  ) {}

async execute(workspaceId: string, userId: string): Promise<void> {
    // 1. Load entity
    const workspace = await this.repository.findById(workspaceId);
    if (!workspace) {
      throw new ApplicationError('Workspace not found');
    }

// 2. Check authorization (application-level concern)
    if (workspace.ownerId !== userId) {
      throw new UnauthorizedError('Only owner can archive workspace');
    }

// 3. Execute domain operation
    workspace.archive();

// 4. Persist changes
    await this.repository.save(workspace);

// 5. Publish event
    await this.eventPublisher.publish(
      new WorkspaceArchivedEvent(workspace.id, userId, new Date())
    );
  }
}
```

**Testing Application Layer:**

```typescript theme={null}
// Use case tests - with test doubles
describe('CreateWorkspaceUseCase', () => {
  let useCase: CreateWorkspaceUseCase;
  let mockRepository: MockWorkspaceRepository;
  let mockEventPublisher: MockEventPublisher;
  let mockLogger: MockLogger;

beforeEach(() => {
    mockRepository = new MockWorkspaceRepository();
    mockEventPublisher = new MockEventPublisher();
    mockLogger = new MockLogger();
    useCase = new CreateWorkspaceUseCase(
      mockRepository,
      mockEventPublisher,
      mockLogger
    );
  });

it('creates and persists workspace', async () => {
    const command = {
      name: 'Test Workspace',
      ownerId: 'owner-123',
      memberLimit: 50
    };

const workspace = await useCase.execute(command);

// Verify workspace created correctly
    expect(workspace.name).toBe('Test Workspace');
    expect(workspace.ownerId).toBe('owner-123');

// Verify repository called
    expect(mockRepository.saved).toHaveLength(1);
    expect(mockRepository.saved[0]).toBe(workspace);

// Verify event published
    expect(mockEventPublisher.published).toHaveLength(1);
    expect(mockEventPublisher.published[0]).toBeInstanceOf(WorkspaceCreatedEvent);
  });

it('propagates domain errors', async () => {
    const command = {
      name: 'ab', // Too short
      ownerId: 'owner-123'
    };

await expect(useCase.execute(command))
      .rejects
      .toThrow('Workspace name must be 3-50 characters');
  });
});
```

#### Layer 3: Infrastructure Layer (Adapters)

**Purpose**: Implements infrastructure concerns and connects to external systems.

**Contents**:

* Repository Implementations (database access)
* Event Publishers (message brokers)
* External Service Clients (HTTP, gRPC)
* Caching Implementations
* File Storage Implementations

**Example - Complete Infrastructure Layer:**

```typescript theme={null}
// Illustrative: src/infrastructure/repositories/supabase-workspace.repository.ts
import { Workspace } from '@/domain/models/workspace';
import { WorkspaceRepository } from '@/domain/interfaces/workspace-repository';
import { SupabaseClient } from '@supabase/supabase-js';

export class SupabaseWorkspaceRepository implements WorkspaceRepository {
  constructor(private readonly supabase: SupabaseClient) {}

async findById(id: string): Promise<Workspace | null> {
    const { data, error } = await this.supabase
      .from('workspaces')
      .select('*')
      .eq('id', id)
      .single();

if (error || !data) return null;

return this.toDomain(data);
  }

async findByOwnerId(ownerId: string): Promise<Workspace[]> {
    const { data, error } = await this.supabase
      .from('workspaces')
      .select('*')
      .eq('owner_id', ownerId)
      .order('created_at', { ascending: false });

if (error || !data) return [];

return data.map(row => this.toDomain(row));
  }

async save(workspace: Workspace): Promise<void> {
    const dbModel = this.toDatabase(workspace);

const { error } = await this.supabase
      .from('workspaces')
      .upsert(dbModel);

if (error) {
      throw new InfrastructureError(`Failed to save workspace: ${error.message}`);
    }
  }

async delete(id: string): Promise<void> {
    const { error } = await this.supabase
      .from('workspaces')
      .delete()
      .eq('id', id);

if (error) {
      throw new InfrastructureError(`Failed to delete workspace: ${error.message}`);
    }
  }

// Mapping: Database schema → Domain model
  private toDomain(row: any): Workspace {
    // Use a reflection or factory method to create Workspace
    // bypassing constructor if needed for reconstruction
    return Object.assign(
      Object.create(Workspace.prototype),
      {
        id: row.id,
        _name: row.name,
        _ownerId: row.owner_id,
        _isActive: row.is_active,
        _memberLimit: row.member_limit,
        createdAt: new Date(row.created_at)
      }
    );
  }

// Mapping: Domain model → Database schema
  private toDatabase(workspace: Workspace): any {
    return {
      id: workspace.id,
      name: workspace.name,
      owner_id: workspace.ownerId,
      is_active: workspace.isActive,
      member_limit: workspace.memberLimit,
      created_at: workspace.createdAt.toISOString()
    };
  }
}

// Illustrative: src/infrastructure/events/trigger-publisher.ts
//
// Tuturuuu uses Trigger.dev v4. Background work is modelled as `task()`
// definitions (in packages/trigger/src) that you enqueue with
// `myTask.trigger(payload)` — there is no v2-style `trigger.event(...)`,
// `client.defineJob`, or `eventTrigger`. The real tasks live in
// packages/trigger/src (e.g. scheduleTask, unifiedScheduleTask).
import { EventPublisher } from '@/domain/interfaces/event-publisher';
import { DomainEvent } from '@/domain/events/domain-event';
import { workspaceCreatedTask } from '@tuturuuu/trigger';

export class TriggerEventPublisher implements EventPublisher {
  async publish(event: DomainEvent): Promise<void> {
    // Enqueue a Trigger.dev v4 task run for the event.
    await workspaceCreatedTask.trigger({
      eventName: event.eventName,
      eventId: event.eventId,
      occurredAt: event.occurredAt.toISOString(),
      ...event.payload,
    });
  }

async publishMany(events: DomainEvent[]): Promise<void> {
    await Promise.all(events.map((event) => this.publish(event)));
  }
}
```

For reference, the matching Trigger.dev v4 task definition looks like the real
tasks in `packages/trigger/src`:

```typescript theme={null}
// packages/trigger/src/<your-task>.ts (Trigger.dev v4 task() API)
import { task } from '@trigger.dev/sdk/v3';

export const workspaceCreatedTask = task({
  id: 'workspace-created',
  queue: { concurrencyLimit: 10 },
  run: async (payload: {
    eventName: string;
    eventId: string;
    occurredAt: string;
    [key: string]: unknown;
  }) => {
    // ...react to the event (notifications, projections, etc.)
    return { ok: true };
  },
});
```

#### Layer 4: Presentation Layer (API/UI)

**Purpose**: Handles HTTP requests, validates input, and returns responses.

**Contents**:

* API Route Handlers
* Request/Response DTOs
* Input Validation
* Authentication/Authorization
* HTTP Status Codes

**Example - Complete Presentation Layer:**

```typescript theme={null}
// Illustrative: src/app/api/workspaces/create/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';
import { CreateWorkspaceUseCase } from '@/application/use-cases/create-workspace.usecase';
import { SupabaseWorkspaceRepository } from '@/infrastructure/repositories/supabase-workspace.repository';
import { TriggerEventPublisher } from '@/infrastructure/events/trigger-publisher';
// In Tuturuuu, createClient() from @tuturuuu/supabase/next/server is ASYNC.
import { createClient } from '@tuturuuu/supabase/next/server';

// Request validation schema
const CreateWorkspaceSchema = z.object({
  name: z.string().min(3).max(50),
  memberLimit: z.number().min(1).max(1000).optional()
});

export async function POST(request: NextRequest) {
  try {
    // 1. Authentication (await the async client factory)
    const supabase = await createClient();
    const { data: { session } } = await supabase.auth.getSession();

if (!session) {
      return NextResponse.json(
        { error: 'Unauthorized' },
        { status: 401 }
      );
    }

// 2. Parse and validate request body
    const body = await request.json();
    const validation = CreateWorkspaceSchema.safeParse(body);

if (!validation.success) {
      return NextResponse.json(
        { error: 'Invalid request', details: validation.error.issues },
        { status: 400 }
      );
    }

// 3. Dependency injection - wire up layers
    const repository = new SupabaseWorkspaceRepository(supabase);
    const eventPublisher = new TriggerEventPublisher();
    const logger = console; // Or proper logger

const useCase = new CreateWorkspaceUseCase(
      repository,
      eventPublisher,
      logger
    );

// 4. Execute use case
    const workspace = await useCase.execute({
      name: validation.data.name,
      ownerId: session.user.id,
      memberLimit: validation.data.memberLimit
    });

// 5. Return response
    return NextResponse.json(
      {
        workspace: {
          id: workspace.id,
          name: workspace.name,
          ownerId: workspace.ownerId,
          isActive: workspace.isActive,
          memberLimit: workspace.memberLimit,
          createdAt: workspace.createdAt.toISOString()
        }
      },
      { status: 201 }
    );

} catch (error) {
    // Error handling
    if (error instanceof DomainError) {
      return NextResponse.json(
        { error: error.message },
        { status: 400 }
      );
    }

if (error instanceof UnauthorizedError) {
      return NextResponse.json(
        { error: error.message },
        { status: 403 }
      );
    }

console.error('Unexpected error:', error);
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}
```

### Layer Communication Patterns

```mermaid theme={null}
graph TD
    User["User/Client"]

subgraph Service["Microservice"]
        Presentation["Presentation Layer<br/>(API Route)"]
        Application["Application Layer<br/>(Use Case)"]
        Domain["Domain Layer<br/>(Entity)"]
        Infrastructure["Infrastructure Layer<br/>(Repository)"]
    end

DB[("Database")]

Presentation -.->|Response| User

style Domain fill:#ffd54f,stroke:#f57f17,stroke-width:3px
    style Application fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style Presentation fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style Infrastructure fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
```

### Testing Strategy Per Layer

### Comparison: N-Tier vs Hexagonal in Microservices

```mermaid theme={null}
graph TB
    subgraph NTier["Microservice with N-Tier"]
        NT_API["API Layer"]
        NT_BLL["Business Logic Layer"]
        NT_DAL["Data Access Layer"]

NT_API --> NT_BLL
        NT_BLL --> NT_DAL
        NT_DAL -.->|Tight Coupling| NT_BLL
    end

subgraph Hex["Microservice with Hexagonal"]
        H_API["API Adapter"]
        H_UseCase["Use Case"]
        H_Domain["Domain Core"]
        H_Repo["Repository Adapter"]

H_API --> H_UseCase
        H_UseCase --> H_Domain
        H_Domain --> H_Repo
    end

style NT_BLL fill:#ffcdd2,stroke:#c62828,stroke-width:2px
    style H_Domain fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px
```

**N-Tier within Microservice:**

* ❌ Business logic coupled to database
* ❌ Hard to test without infrastructure
* ❌ Technology lock-in within service
* ✅ Simpler for trivial services

**Hexagonal within Microservice:**

* ✅ Business logic is pure and testable
* ✅ Technology can be swapped per service
* ✅ High test coverage achievable
* ❌ More code and structure needed

### Deployment Considerations

Each app deploys independently. Tuturuuu does **not** expose `bun deploy:web` /
`bun deploy:finance` / `bun deploy:calendar` scripts — deployment is driven by
CI/CD (GitHub Actions) and Docker images, and each app's `package.json` ships
conventional `dev`, `build`, `start`, and `test` scripts (for example
`apps/web` builds with `next build --turbopack`). Verify the current scripts in
each app's `package.json` before quoting commands.

```bash theme={null}
# Build / run a single app locally (real scripts in apps/web/package.json)
$ cd apps/web && bun run build   # next build --turbopack
$ cd apps/web && bun start       # next start on port 7803

# Each app is a conventional Next.js App Router app sharing one Supabase
# project; heavier backend logic increasingly lives in apps/backend (Rust).
```

### Key Takeaways

1. **Microservices ≠ No Internal Structure**: Each service needs clean internal architecture
2. **Hexagonal Within Services**: Provides testability and maintainability per service
3. **Layer Discipline**: Strict layer boundaries prevent architectural decay
4. **Independent Evolution**: Each service can evolve its internals independently
5. **Consistent Patterns**: Same layering approach across services aids understanding

***

## Comparison Matrix

***

## When to Use Each Pattern

### Use N-Tier When:

* ✅ Building simple CRUD applications
* ✅ Team is unfamiliar with DDD/Hexagonal concepts
* ✅ Rapid prototyping with acceptable technical debt
* ✅ Application will remain small (\<10k LOC)

### Use Hexagonal/Clean/Onion When:

* ✅ Complex business logic requires protection
* ✅ Long-term maintainability is critical
* ✅ Need to swap infrastructure components
* ✅ High test coverage is required
* ✅ Domain experts are involved in development

### Use Microservices When:

* ✅ Multiple teams working on different domains
* ✅ Need independent deployment and scaling
* ✅ Different parts of system have different technology needs
* ✅ Can handle distributed system complexity
* ✅ Have DevOps maturity for service orchestration

### Tuturuuu's Pragmatic Choice

Tuturuuu favors pragmatism over textbook purity:

* **Multiple deployable apps** (`apps/web`, `apps/finance`, `apps/calendar`,
  the Rust `apps/backend`, ...) for organizational agility and independent
  deployment.
* **Conventional Next.js App Router structure** inside each frontend app
  (`app/`, `components/`, `lib/`, `utils/`, `features/`) rather than a formal
  hexagonal `domain/application/infrastructure` hierarchy. Shared logic lives in
  `packages/*`; cross-app data access goes through `packages/internal-api`
  helpers and REST `/api/v1` routes.
* **Heavier backend logic moving into the Rust service** (`apps/backend`),
  where layering and typed domain modules increasingly live as part of the
  [TanStack + Rust migration](/platform/architecture/tanstack-rust-migration).

The hexagonal samples above remain useful for *reasoning about* boundaries and
testability, even though the repository does not enforce that exact folder
shape.

***

## Evolution Path

Many systems evolve through these patterns:

```mermaid theme={null}
graph TD
    Step1["Simple App<br/>(N-Tier)"]
    Step2["Modular Monolith<br/>(Hexagonal)"]
    Step3["Microservices with<br/>Hexagonal Architecture"]

Step1 -->|"Business logic<br/>becomes complex"| Step2
    Step2 -->|"Team grows,<br/>need independent<br/>deployment"| Step3

style Step1 fill:#ffcdd2,stroke:#c62828,stroke-width:2px
    style Step2 fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style Step3 fill:#c8e6c9,stroke:#2e7d32,stroke-width:3px
```

**Where Tuturuuu sits today.** Rather than formally adopting "Step 3"
(microservices with strict hexagonal layering), Tuturuuu runs several
conventional Next.js App Router apps backed by a shared Supabase project, with
shared logic in `packages/*` and an emerging Rust backend (`apps/backend`). The
practical trajectory is toward the TanStack Start frontend
(`apps/tanstack-web`) plus the Rust backend rather than toward per-app
hexagonal folder hierarchies — see the
[TanStack + Rust migration](/platform/architecture/tanstack-rust-migration).
Treat the steps above as a conceptual maturity model, not a literal description
of the repository.

***

## Anti-Patterns to Avoid

### ❌ Hexagonal Architecture Without Discipline

```typescript theme={null}
// BAD: "Hexagonal" in name only
export class WorkspaceService {
  constructor(private readonly repository: WorkspaceRepository) {}

async createWorkspace(name: string, ownerId: string) {
    // WRONG: Direct Supabase usage bypasses repository
    const { data } = await supabase.from('workspaces').insert({ name, owner_id: ownerId });
    return data;
  }
}
// This defeats the purpose of Hexagonal Architecture
```

### ❌ Distributed Monolith

```typescript theme={null}
// BAD: Microservices with tight coupling
// Service A
export async function createWorkspace(data: CreateWorkspaceData) {
  const workspace = await db.insert(data);

// WRONG: Synchronous HTTP call to Service B
  await fetch('http://service-b/setup', {
    method: 'POST',
    body: JSON.stringify({ workspaceId: workspace.id })
  });

return workspace;
}
// This is a distributed monolith, not microservices
```

### ❌ No Layering in Microservices

```typescript theme={null}
// BAD: API route with all logic mixed together
export async function POST(request: Request) {
  const body = await request.json();

// Validation
  if (body.name.length < 3) return Response.json({ error: 'Too short' }, { status: 400 });

// Database
  const { data } = await supabase.from('workspaces').insert(body);

// Events (Trigger.dev v4: enqueue a task run, not v2 trigger.event(...))
  await workspaceCreatedTask.trigger({ ...data });

return Response.json(data);
}
// No separation of concerns, hard to test, hard to maintain
```

***

## Tuturuuu's Implementation

### Actual Project Structure

This is the **real** repository layout (verified against the codebase). Apps are
conventional Next.js App Router apps — there are no `domain/`, `application/`, or
`infrastructure/` folders.

```text theme={null}
tuturuuu/
├── apps/                          # Independently deployable apps
│   ├── web/                       # Main platform (Next.js, port 7803)
│   │   └── src/
│   │       ├── app/               # App Router routes + /api endpoints
│   │       ├── components/
│   │       ├── features/          # Feature modules (forms, reports, ...)
│   │       ├── hooks/
│   │       ├── lib/
│   │       └── utils/
│   ├── finance/                   # Finance app (Next.js)
│   │   └── src/                   # app/, components/, lib/, utils/, ...
│   ├── calendar/                  # Calendar app (Next.js)
│   │   └── src/                   # app/, components/, lib/, constants/, ...
│   ├── tanstack-web/              # TanStack Start replacement for apps/web
│   └── backend/                   # Rust backend (port 7820)
│       └── src/                   # aurora.rs, inventory.rs, lib.rs, ...
└── packages/                      # Shared libraries (workspace:*)
    ├── types/                     # Shared types (DB types in @tuturuuu/types/db)
    ├── ui/                        # Shared UI components
    ├── supabase/                  # Shared Supabase client factories
    ├── internal-api/              # Cross-app data access helpers
    └── trigger/                   # Trigger.dev v4 task() definitions
```

> [!NOTE]
>
> **Where backend layering lives.** Newer/heavier backend logic is implemented in
> the Rust service (`apps/backend/src`, e.g. `aurora.rs`, `inventory.rs`,
> `onboarding_progress.rs`) rather than as a layered TypeScript hierarchy inside
> each frontend app. Frontends reach shared app data through
> `packages/internal-api` and REST `/api/v1` routes. (A repo guard,
> `check-tanstack-api-access`, forbids `apps/tanstack-web/src` from calling
> `/trpc` — the tRPC surface in `apps/web/src/trpc` is a stub, not the product
> data path.)

### How the Real Flow Maps to These Layers

You can still reason about a real Tuturuuu request in layered terms, even though
the folders are flat:

* **Presentation** — an App Router route handler in `apps/web/src/app/api/...`
  (or a TanStack Start route in `apps/tanstack-web`).
* **Application / orchestration** — helpers in `lib/`, `features/`,
  `packages/internal-api`, or background `task()` runs in `packages/trigger`.
* **Domain rules** — validation and business logic colocated with the feature
  (or enforced in the Rust backend).
* **Infrastructure** — the shared Supabase client from
  `@tuturuuu/supabase/next/server` and the Rust backend's data access.

```typescript theme={null}
// Real shape: an App Router API route in apps/web/src/app/api/...
import { NextRequest, NextResponse } from 'next/server';
import { createClient } from '@tuturuuu/supabase/next/server';
import { workspaceCreatedTask } from '@tuturuuu/trigger';

export async function POST(request: NextRequest) {
  // createClient() is ASYNC in Tuturuuu — await it.
  const supabase = await createClient();
  const body = await request.json();

// Presentation-level validation
  if (typeof body.name !== 'string' || body.name.length < 3) {
    return NextResponse.json({ error: 'Name too short' }, { status: 400 });
  }

// Infrastructure: shared Supabase project
  const { data, error } = await supabase
    .from('workspaces')
    .insert({ name: body.name, owner_id: body.ownerId })
    .select()
    .single();

if (error) {
    return NextResponse.json({ error: error.message }, { status: 500 });
  }

// Background work via Trigger.dev v4 task()
  await workspaceCreatedTask.trigger({ workspaceId: data.id });

return NextResponse.json({ workspace: data }, { status: 201 });
}
```

The layered patterns earlier in this page are a lens for keeping responsibilities
clear; the snippet above shows what that looks like in the conventional
structure Tuturuuu actually ships.

***

## Related Documentation

* [Hexagonal Architecture](/platform/architecture/system-design/hexagonal-architecture) - Detailed ports and adapters implementation
* [Microservices Patterns](/platform/architecture/system-design/microservices-patterns) - Service boundaries and communication
* [Architectural Decisions](/platform/architecture/system-design/architectural-decisions) - Why we chose this architecture
* [Quality Attributes](/platform/architecture/system-design/quality-attributes) - Maintainability and testability benefits
* [Encapsulation Patterns](/platform/architecture/system-design/encapsulation-patterns) - Preventing unwanted coupling

# Microservices Patterns
Source: https://docs.tuturuuu.com/platform/architecture/system-design/microservices-patterns

Service boundaries, communication patterns, and deployment strategies in Tuturuuu's monorepo architecture

Tuturuuu uses a **monorepo of conventional Next.js App Router apps** that share one
Supabase project plus a growing set of workspace packages. We describe this as a
"microservices-within-a-monorepo" style: each app deploys independently and owns a
product surface, but they are not isolated services with private databases or an
inter-service token mesh. This page documents the patterns we actually use today,
and distinguishes active services from paused runtime designs.

## Service Boundaries

### Active services and retained targets

Additional product apps (`apps/chat`, `apps/drive`, `apps/mail`, `apps/cms`,
`apps/mind`, `apps/teach`, `apps/track`, `apps/storefront`, and others) follow the
same conventional Next.js App Router shape and share the same Supabase project.

> [!WARNING]
>
> All these apps share **one** Supabase project. There are no per-app distinct
> Supabase keys, no per-service databases, and no inter-service token system in
> the codebase today. "Service-specific databases" and an inter-service token
> mesh are aspirational patterns discussed later, not implemented reality.

### Shared Packages

All services share common infrastructure via workspace packages:

```
packages/
├── ui/           # Shared UI components (Shadcn)
├── ai/           # AI integration utilities
├── supabase/     # Supabase client wrappers
├── types/        # Shared TypeScript types (including generated DB types)
├── utils/        # Cross-cutting utilities
├── trigger/      # Background job definitions (Trigger.dev v4)
├── payment/      # Payment processing (Polar provider)
├── internal-api/ # Typed helpers for app REST endpoints
└── ... (many shared packages)
```

## Monorepo Architecture

### Benefits

1. **Shared Code**: Common utilities, UI components, types shared across services
2. **Atomic Changes**: Change types in one commit, update all services
3. **Simplified Tooling**: Single build system (Turborepo + Bun)
4. **Easy Refactoring**: Move code between services, extract packages
5. **Consistent Standards**: Shared linting, testing, deployment configs

### Structure

```
platform/
├── apps/                  # Independent microservices
│   ├── web/              # Main app (port 7803)
│   ├── rewise/           # AI chat
│   ├── nova/             # Prompt engineering
│   └── ... (other apps)
├── packages/              # Shared libraries
│   ├── ui/               # Component library
│   ├── types/            # Shared types
│   └── ... (other packages)
├── turbo.json            # Turborepo configuration
└── package.json          # Workspace root
```

### Workspace Dependencies

Services declare dependencies on shared packages:

```json theme={null}
// apps/web/package.json
{
  "name": "@tuturuuu/web",
  "dependencies": {
    "@tuturuuu/ui": "workspace:*",
    "@tuturuuu/types": "workspace:*",
    "@tuturuuu/supabase": "workspace:*",
    "@tuturuuu/ai": "workspace:*",
    "@tuturuuu/utils": "workspace:*"
  }
}

// apps/rewise/package.json
{
  "name": "@tuturuuu/rewise",
  "dependencies": {
    "@tuturuuu/ui": "workspace:*",
    "@tuturuuu/types": "workspace:*",
    "@tuturuuu/ai": "workspace:*"
    // Note: Different subset of packages
  }
}
```

## Communication Patterns

### 1. Background Jobs (Trigger.dev v4)

**When to use:** Asynchronous workflows, background processing, scheduled work

**Implementation:** Trigger.dev v4 (`@trigger.dev/sdk` `^4.4.5`), using the
`task()` API. Task definitions live in `packages/trigger/src`.

The v2/v3 `client.defineJob` / `eventTrigger` / `io.runTask` APIs do **not** exist
in this repo. Define a task with `task()` and run it from app code with
`tasks.trigger(...)` (or `<task>.trigger(...)`):

```typescript theme={null}
// packages/trigger/src/schedule-tasks.ts
import { task } from '@trigger.dev/sdk/v3';
import { schedulableTasksHelper } from './schedule-tasks-helper';

export const scheduleTask = task({
  id: 'schedule-task',
  queue: { concurrencyLimit: 10 },
  run: async (payload: { ws_id: string }) => {
    const result = await schedulableTasksHelper(payload.ws_id);
    if (!result.success) {
      throw new Error(result.error || 'Schedule tasks failed');
    }
    return { ws_id: payload.ws_id, ...result, success: true };
  },
});
```

```typescript theme={null}
// Producer: trigger the task from app code (e.g. an apps/web API route)
import { tasks } from '@trigger.dev/sdk/v3';
import type { scheduleTask } from '@tuturuuu/trigger';

await tasks.trigger<typeof scheduleTask>('schedule-task', {
  ws_id: workspaceId,
});
```

> The import path is `@trigger.dev/sdk/v3` even though the installed SDK is the
> v4 line — that path is the current entrypoint for the `task()` API.

**Characteristics:**

* Loose coupling: producers fire-and-forget, tasks run out of band
* Resilient to failures, with built-in retries and queue concurrency limits
* Asynchronous processing
* Run history and replay in the Trigger.dev dashboard

### 2. Shared Database (Current)

**When to use:** Strong consistency requirements, complex queries across entities

**Implementation:** Supabase PostgreSQL with RLS

```typescript theme={null}
import { createClient } from '@tuturuuu/supabase/next/server';

// Both apps/web and apps/finance access the same Supabase project.
// createClient() is async — await it.
const supabase = await createClient();

// Row-Level Security ensures data isolation
const { data } = await supabase
  .from('workspaces')
  .select('*')
  .eq('id', workspaceId);
// RLS automatically filters by user permissions
```

**Characteristics:**

* Strong consistency
* ACID transactions
* Complex joins possible
* Shared schema (requires coordination)

**Trade-offs:**

* ✅ Simple implementation
* ✅ Strong consistency
* ❌ Tight coupling at data layer
* ❌ Schema changes affect multiple services

### 3. tRPC (legacy `apps/web`, currently a stub)

**Status:** The tRPC layer in `apps/web/src/trpc` is intentionally a **stub**. The
router (`apps/web/src/trpc/routers/_app.ts`) exports a single `healthCheck`
`baseProcedure` to keep the type system wired up:

```typescript theme={null}
// apps/web/src/trpc/routers/_app.ts (actual contents)
import { baseProcedure, createTRPCRouter } from '../init';

export const appRouter = createTRPCRouter({
  healthCheck: baseProcedure.query(() => {
    return { status: 'ok', timestamp: Date.now() };
  }),
});

export type AppRouter = typeof appRouter;
```

The real exports are `createTRPCRouter`, `createTRPCContext`, `baseProcedure`, and
`createCallerFactory`. There is **no** `protectedProcedure`, no auth middleware,
and no workspace/user/tasks/ai routers — the context is not a product data layer.
Product data flows through `@tuturuuu/internal-api` helpers and REST
`/api/v1/*` routes (below), not through tRPC. In `apps/tanstack-web` a guard
(`check-tanstack-api-access`) forbids `/trpc` calls entirely.

Do not document tRPC as the canonical internal API surface — it is a thin
compatibility shim that may be removed during the migration.

### 4. REST API (`/api/v1`, legacy `apps/web`) and the Rust backend

**When to use:** Public APIs, webhook endpoints, third-party integrations, and
product read/write endpoints.

**Legacy implementation:** Next.js App Router route handlers under
`apps/web/src/app/api/v1/*` (e.g. `workspaces`, `inventory`, `nova`, `storage`):

```typescript theme={null}
// apps/web/src/app/api/v1/workspaces/route.ts
import { createClient } from '@tuturuuu/supabase/next/server';

export async function POST(request: Request) {
  const supabase = await createClient(); // async — await it
  const body = await request.json();

// Validate, authenticate, execute
  const workspace = await createWorkspace(supabase, body);

return Response.json({ workspace }, { status: 201 });
}
```

**Migration target:** The Rust backend (`apps/backend`, port `7820`) is
progressively taking ownership of these endpoints. Route groups live in
`apps/backend/src/*.rs` (for example `inventory.rs`, `nova.rs`,
`onboarding_progress.rs`, `aurora.rs`), and the contract is documented in
`apps/backend/api/openapi.yaml`. Migration progress per endpoint is tracked in
`apps/tanstack-web/migration/route-manifest.json`.

**Characteristics:**

* Standard HTTP / JSON
* Versioned endpoints (`/api/v1/...`)
* Rate limiting and authentication
* OpenAPI documentation for the Rust backend (`apps/backend/api/openapi.yaml`)

## Service Communication Matrix

Most cross-surface coordination is **not** direct service-to-service RPC: apps
share the Supabase database (guarded by RLS) and hand off long-running work to
Trigger.dev. This keeps coupling at the data and job layers rather than in a
service mesh.

## Deployment Strategies

### Next.js apps: Vercel

Each Next.js app deploys independently to Vercel. CI builds the selected app,
packages prebuilt artifacts, and deploys the production artifact through the
matching GitHub Actions workflow.

There is one Vercel workflow per app, named by product surface. For example,
`vercel-production-platform.yaml` builds `apps/web` on pushes to the `production`
branch and deploys the prebuilt production artifact:

```yaml theme={null}
# .github/workflows/vercel-production-platform.yaml (abridged)
name: Vercel Platform Production Deployment
on:
  push:
    branches: [production]
  workflow_dispatch:

jobs:
  Deploy-Production:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v6
        with:
          node-version: 24
      - uses: ./.github/actions/setup-bun-with-retry
        with:
          bun-version: 1.4.4
      - run: bash scripts/ci/run-with-backoff.sh bun install
      # Pull env, build the Vercel artifact, and deploy the prebuilt output.
      - run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
      - run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
      - run: vercel deploy --archive=tgz --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}
```

Matching `vercel-preview-*.yaml` workflows run for pull requests. Node engines are
`>=22` (CI uses Node 24) and Bun is pinned to `1.4.4`.

### Rust backend

`apps/backend` is built and validated by `.github/workflows/rust-backend.yml`.
It runs as a native container and keeps a Cloudflare Workers Rust entrypoint
(`apps/backend/wrangler.jsonc`) ready for edge preview deployment, per the
[migration contract](/platform/architecture/tanstack-rust-migration).

### Independent Scaling

Each app scales independently on its hosting platform (Vercel autoscaling for the
Next.js apps; container/edge scaling for the Rust backend). The per-app
`minInstances`/`maxInstances` objects shown in earlier versions of this page were
illustrative, not a real config file in the repo — scaling is configured in the
Vercel project settings and the backend's container/edge runtime, not in
versioned source.

## Service Boundary Decisions

### When to Create a New Service

✅ **Extract to new service when:**

* Feature is logically independent (e.g., URL shortener)
* Different scaling requirements (high-traffic vs low-traffic)
* Different technology needs (Python for ML vs TypeScript for web)
* Team ownership boundary (separate team owns feature)
* Independent deployment cycle needed

❌ **Keep in existing service when:**

* Shares most code with existing service
* Tight coupling to core domain
* Low complexity (\< 1000 LOC)
* No special scaling or technology needs

### Example: Why `finance` is a separate app

```
Reasons:
✅ Logically independent domain (finance vs tasks)
✅ Can be worked on by dedicated team
✅ Independent deployment for finance updates
✅ Future: Could use different database for financial data

Alternatives considered:
❌ Module in web app - harder to maintain boundaries
❌ Separate package - loses deployment independence
```

## Data Ownership

### Current: Shared Database Pattern

**Pros:**

* Simple joins across entities
* Strong consistency
* ACID transactions
* Single source of truth

**Cons:**

* Tight coupling at data layer
* Schema changes affect multiple services
* Harder to scale independently

### Aspirational: Service-Specific Databases

> [!NOTE]
>
> This is **not implemented today.** Every app shares one Supabase project. The
> following is a future option, not current architecture.

**When to consider:**

* A surface needs a specialized database (e.g., PostGIS for geolocation)
* Independent scaling requirements for specific data
* Strong service boundaries needed

**Illustrative pattern (not in the codebase):**

```typescript theme={null}
import { createClient } from '@tuturuuu/supabase/next/server';

// Today: every app uses the shared Supabase project.
const db = await createClient(); // createClient() is async — await it

// Hypothetical future: a dedicated DB plus a background task to keep
// derived data in sync, triggered via Trigger.dev's task() API.
// await tasks.trigger('record-transaction', { /* ... */ });
```

## Package Extraction Strategy

### When to Extract to Package

The repo's root `AGENTS.md` carries the package-extraction decision matrix. As a
rough heuristic, **extract when ≥3 HIGH signals:**

**Example extractions in Tuturuuu:**

```
@tuturuuu/ui → Shared across all apps
@tuturuuu/types → Used by all services
@tuturuuu/supabase → Client wrapper used everywhere
@tuturuuu/ai → Shared AI utilities (rewise, nova, web)
```

## Testing Strategies

### Unit Tests

Test individual services in isolation:

```typescript theme={null}
// apps/web/src/__tests__/workspace.test.ts
import { createWorkspace } from '../lib/workspace';

describe('Workspace Service', () => {
  it('creates workspace with valid data', async () => {
    const workspace = await createWorkspace({
      ownerId: 'user-1',
      name: 'Test Workspace'
    });

expect(workspace.name).toBe('Test Workspace');
  });
});
```

### Integration Tests

Test service interactions:

```typescript theme={null}
// apps/web/src/__tests__/integration/workspace-creation.test.ts
// Tests run under Vitest. There is no event-store to assert against;
// instead, mock the Trigger.dev task trigger and assert it was invoked.
import { vi } from 'vitest';
import { tasks } from '@trigger.dev/sdk/v3';

vi.spyOn(tasks, 'trigger');

describe('Workspace Creation Flow', () => {
  it('creates a workspace and schedules follow-up work', async () => {
    const workspace = await POST('/api/v1/workspaces', {
      name: 'Test Workspace',
    });

expect(tasks.trigger).toHaveBeenCalledWith(
      'schedule-task',
      expect.objectContaining({ ws_id: workspace.id })
    );
  });
});
```

### End-to-End Tests

Test full user workflows across services (future):

```typescript theme={null}
// e2e/workspace-onboarding.spec.ts
test('user creates workspace and receives AI setup', async ({ page }) => {
  await page.goto('/workspaces/create');
  await page.fill('[name="name"]', 'Test Workspace');
  await page.click('button[type="submit"]');

// Wait for AI setup completion
  await page.waitForSelector('[data-testid="ai-ready"]');
});
```

## Monitoring & Observability

### Service Health

```typescript theme={null}
// apps/web/src/app/api/health/route.ts
export async function GET() {
  const health = {
    service: 'web',
    status: 'healthy',
    uptime: process.uptime(),
    dependencies: {
      database: await checkDatabaseConnection(),
      eventBroker: await checkTriggerConnection()
    }
  };

return Response.json(health);
}
```

### Correlation IDs

There is no dedicated `@tuturuuu/logging` or `@tuturuuu/observability` package and
no event-store; the example below is an illustrative pattern. Runtime server
code should log diagnostics with the native console method matching severity.

```typescript theme={null}
import { tasks } from '@trigger.dev/sdk/v3';

export async function POST(request: Request) {
  const correlationId =
    request.headers.get('x-correlation-id') ?? crypto.randomUUID();

// Hand off async work to a Trigger.dev task, threading the correlation id.
  await tasks.trigger('schedule-task', { ws_id: workspaceId, correlationId });

console.log('Queued schedule task', { correlationId, workspaceId });
}
```

## Migration Paths

### Current State → Future State

**Current:** A monorepo of Next.js apps over one shared Supabase project, with
background work on Trigger.dev v4.

**Paused:** Rust (`apps/backend`) and TanStack Start (`apps/tanstack-web`) are not
in use. Their source, tests, dependency updates, and migration CI remain inactive
until further notice. Web remains the live central API, alongside satellite-owned
routes. See the [active runtime map](/build/devops/active-runtime).

**Longer-term options (not committed):**

1. **Service-Specific Databases** (when needed)
   * Extract finance data to dedicated DB
   * Communicate via events
   * Maintain consistency with sagas

2. **API Gateway Layer** (if REST APIs grow)
   * Single entry point for external clients
   * Route to appropriate services
   * Handle auth, rate limiting centrally

3. **GraphQL Federation** (if complex queries needed)
   * Each service exposes GraphQL schema
   * Gateway federates schemas
   * Clients query unified graph

**Migration principle:** Evolve gradually based on real needs, not speculation.

## Related Documentation

* [Architectural Decisions](/platform/architecture/system-design/architectural-decisions) - Why microservices
* [Event-Driven Architecture](/platform/architecture/system-design/event-driven-architecture) - Inter-service communication
* [Monorepo Architecture](/build/development-tools/monorepo-architecture) - Turborepo setup
* [Database Schema](/reference/database/schema-overview) - Shared schema details

# Observability & Monitoring
Source: https://docs.tuturuuu.com/platform/architecture/system-design/observability-monitoring

How Tuturuuu observes the platform today, and the patterns that guide where it is heading

Observability gives you the ability to understand system behavior by examining
its outputs—logs, request records, and metrics. This page explains the core
observability patterns and, for each one, describes **what Tuturuuu actually
implements today** versus what is conceptual or aspirational.

> [!NOTE]
>
> **Observability vs Monitoring**: Monitoring tells you when something is wrong.
> Observability tells you why it's wrong and how to fix it. Tuturuuu leans on a
> self-hosted, Postgres-backed log drain rather than a third-party observability
> vendor.

> [!WARNING]
>
> **Ground-truth scope.** Tuturuuu's apps are conventional Next.js App Router and
> TanStack Start apps plus a Rust backend—not a hexagonal microservice mesh.
> There is no OpenTelemetry pipeline, no `@vercel/otel`, no
> `@tuturuuu/logging`/`@tuturuuu/observability` package, and no event-sourcing
> store. Where this page describes a pattern Tuturuuu has not adopted, it says so
> plainly and keeps the pattern only for its teaching value.

## Architecture in Transition

***

## 1. Request-Scoped Correlation (Not Distributed Tracing)

### The pattern

Distributed tracing assigns each request a **trace ID** that flows through every
service, with each service recording **spans** (units of work) linked by that
trace ID. This is invaluable in a deep microservice mesh where one user action
fans out across dozens of services.

### What Tuturuuu actually does

Tuturuuu does **not** run OpenTelemetry or `@vercel/otel`, and there is no
`instrumentation.ts` that registers an OTel exporter. The real
`apps/web/src/instrumentation.ts` does not install a console drain:

```typescript theme={null}
// apps/web/src/instrumentation.ts (real)
export async function register() {
  return;
}
```

Instead of cross-service spans, Tuturuuu correlates work **within a single
request** using an `AsyncLocalStorage` context that carries a generated
`requestId`. API and cron handlers run inside `withRequestLogDrain` /
`withCronLogDrain`, and every log emitted during that request is stamped with
the same `requestId`, route, deployment color/stamp, and (once known)
`userId`/`userEmail`:

```typescript theme={null}
// apps/web/src/lib/infrastructure/log-drain.ts (real shape, abridged)
export async function withRequestLogDrain<T extends Response>(
  options: RequestDrainOptions,
  handler: () => Promise<T>
) {
  // Runs handler inside an AsyncLocalStorage context.
  // Retained request/cron events are persisted with a shared requestId.
}
```

When the handler finishes, the request and its captured `log_events` are written
to Postgres in one transaction, so you can later query every log line for a
single `requestId`. This gives per-request correlation and timing without an OTel
backend—but it does **not** propagate a trace across the `apps/web` → Rust
backend boundary. True cross-service tracing remains aspirational.

> [!NOTE]
>
> **Takeaway:** Correlate by `requestId`, not by OTel spans. There is no
> `getActiveTrace()`, `trace.span()`, or `io.getSpan()` API in this codebase.

***

## 2. Centralized Logging via the Log Drain

### The pattern

In a distributed system, scattered per-instance log files are impractical.
Centralized logging streams structured logs to a unified store where they can be
searched, filtered, and correlated across boundaries.

### What Tuturuuu actually does

This pattern **is partially implemented**. `apps/web/src/lib/infrastructure/log-drain.ts`
is a self-hosted Postgres store for retained request, cron, deployment, and
usage events. Server runtime logs use the native console method that matches
severity; do not add `serverLogger` runtime imports or automatic console
log-drain installation.
Captured retained events are persisted to dedicated tables:

Each event carries `level`, `message`, `route`, `requestId`, deployment
color/stamp, optional `userId`/`userEmail`, and a JSON `metadata` bag. The drain
redacts bearer tokens and `token`/`key`/`secret`/`password` query params before
persisting, and is designed to **never throw into the caller**—logging failures
are swallowed.

```typescript theme={null}
console.info('Payment processing started', { workspaceId });
console.error('Payment failed', error);
```

Configuration is environment-driven (referenced by name, not value):

* `PLATFORM_LOG_DRAIN_ENABLED` — set to `0`/`false`/`off` to disable.
* `PLATFORM_LOG_DRAIN_DATABASE_URL` — Postgres connection for the drain.
* `PLATFORM_LOG_DRAIN_RAW_RETENTION_DAYS` — raw `log_events` retention
  (default 30 days).
* `PLATFORM_LOG_DRAIN_SUMMARY_RETENTION_DAYS` — summary table retention
  (default 90 days).
* `PLATFORM_BLUE_GREEN_COLOR`, `PLATFORM_DEPLOYMENT_STAMP`,
  `PLATFORM_PROJECT_ID` — deployment stamping.

The drain also prunes old rows on write, so retention is enforced without an
external job.

### Querying logs

Logs are read back through the internal observability API under
`apps/infrastructure/src/app/api/v1/infrastructure/observability/*` (for example `logs`,
`requests`, `cron-runs`, `deployments`, `overview`, `resources`, `analytics`),
which power the in-app infrastructure/observability dashboard. There is no
third-party log platform (no Datadog/ELK) in the loop.

***

## 3. Metrics and Usage Telemetry

### The pattern

Per-service metrics—request rates, error rates, latency percentiles, resource
utilization—let you detect and localize failures quickly and scale individual
services on their own load.

### What Tuturuuu actually does

Tuturuuu does **not** run Prometheus, a `metrics.counter()/histogram()/gauge()`
client, or a `@tuturuuu/observability` package. Instead, metrics are derived
from the same Postgres-backed drain:

* The `requests` table already encodes per-request **status** and
  **duration\_ms**, so request rate, error rate, and latency are computed by
  aggregating that table over a time window.
* The `usage_events` table stores arbitrary numeric samples
  (`metric`, `value`, `unit`)—the place to record product/business telemetry
  such as tokens consumed or workspaces created.
* `apps/web/src/lib/infrastructure/observability.ts` aggregates these (and
  container resource metrics like CPU percent / memory bytes) for the
  observability `overview`, `analytics`, and `resources` endpoints.

So per-service Prometheus metrics are **conceptual/aspirational** here; the
implemented reality is SQL aggregation over request, cron, and usage rows. If you
need a new metric, write `usage_events` rows through the infrastructure layer
rather than reaching for a Prometheus client that does not exist.

***

## 4. Health Checks

### The pattern

Services expose standardized health endpoints. Orchestrators probe them and stop
routing to—or replace—instances that fail, enabling self-healing deployments.
A common refinement splits **liveness** ("is the process running?") from
**readiness** ("is it ready to serve traffic?").

### What Tuturuuu actually does

The `apps/web` health endpoint is intentionally trivial—it does **not** probe
the database, Supabase, or Trigger.dev, and there are no `liveness`/`readiness`
sub-routes:

```typescript theme={null}
// apps/web/src/app/api/health/route.ts (real, complete)
import { connection, NextResponse } from 'next/server';

export async function GET() {
  await connection();

return NextResponse.json(
    { status: 'ok' },
    {
      headers: {
        'Cache-Control': 'no-store',
      },
    }
  );
}
```

The Rust backend (`apps/backend`) goes further and **does** separate liveness
from readiness:

* `GET /api/health` → `{ "status": "ok" }` (parity with the web app, `no-store`).
* `GET /healthz` → liveness, returning service name, runtime (`"rust"`), and
  environment.
* `GET /readyz` → readiness; returns `200` only when the backend is fully
  configured (for example, `BACKEND_INTERNAL_TOKEN` is present), otherwise `503`.

These are simple HTTP probes suitable for container orchestration and the
blue/green deployment watcher. The Kubernetes `livenessProbe`/`readinessProbe`
YAML shown in earlier revisions of this page is illustrative only—Tuturuuu's
deployment model is the blue/green container watcher, not raw Kubernetes pods.

***

## 5. Scheduled Background Work (Not Event Sourcing)

### The pattern

Event sourcing persists an immutable, ordered history of domain events and
rebuilds state by replaying them—enabling audit trails, time-travel debugging,
and projection rebuilds.

### What Tuturuuu actually does

Tuturuuu does **not** implement event sourcing. There is no event store,
no `eventStore.append/query`, and no `rebuildProjection`. Background work runs on
**Trigger.dev v4** (`@trigger.dev/sdk` `^4.4.5`) using the `task()` API—not the
removed v2 `client.defineJob` / `eventTrigger` / `io.runTask` APIs.

```typescript theme={null}
// packages/trigger/src/schedule-tasks.ts (real)
import { task } from '@trigger.dev/sdk/v3';
import { schedulableTasksHelper } from './schedule-tasks-helper';

if (!result.success) {
        throw new Error(result.error || 'Schedule tasks failed');
      }

The historical-insight need that event sourcing addresses is partially met by
the log drain's `requests`, `cron_runs`, and `log_events` tables: cron and
request history is queryable for a retention window, and cron outcomes are
recorded as success/failure with duration and HTTP status. That is operational
history, **not** a replayable domain-event log.

***

## What Is Implemented vs. Conceptual

## Observability Best Practices Here

1. **Use native server logs.** In API, cron, and infrastructure runtime code,
   log diagnostics with the native console method that matches severity. Include
   structured metadata in the same call so retained platform views and deployment
   logs stay readable.
2. **Correlate by `requestId`.** When debugging, find the request row, then pull
   its `log_events`—that is the unit of correlation, not a trace ID.
3. **Record metrics as `usage_events`.** New product/business metrics belong in
   the usage table via the infrastructure layer, surfaced through the
   observability API.
4. **Never let logging break the caller.** The drain swallows its own errors by
   design; preserve that property in any extension.
5. **Reference config by name.** Tune retention and enablement through the
   `PLATFORM_LOG_DRAIN_*` environment variables; never commit connection values.

## Related Documentation

* [TanStack Start And Rust Migration](/platform/architecture/tanstack-rust-migration) - Frontend/backend runtime split and ports
* [Microservices Patterns](/platform/architecture/system-design/microservices-patterns) - Service design and deployment
* [Event-Driven Architecture](/platform/architecture/system-design/event-driven-architecture) - Event/queue patterns
* [Extensibility, Resilience & Scalability](/platform/architecture/system-design/extensibility-resilience-scalability) - System quality attributes
* [Security Architecture](/platform/architecture/system-design/security-architecture) - Security observability and audit trails

# System Design Overview
Source: https://docs.tuturuuu.com/platform/architecture/system-design/overview

Comprehensive overview of Tuturuuu's architectural patterns, principles, and design philosophy

Tuturuuu's architecture is built on a foundation of proven design patterns and principles that prioritize **extensibility**, **resilience**, **scalability**, and **maintainability**. This section provides a comprehensive guide to the system's architectural decisions and implementation patterns.

> [!NOTE]
>
> Several pages in this bucket describe patterns as general design guidance, not
> as fully-adopted Tuturuuu implementations. The platform apps are conventional
> Next.js App Router apps (`apps/web`) plus a TanStack Start frontend
> (`apps/tanstack-web`) and a Rust backend (`apps/backend`) that share one
> Supabase project. There is no hexagonal layering, event-store, or inter-service
> event bus in the codebase today. Where a pattern below is conceptual rather
> than implemented, treat it as a "when you would reach for this" guide and trust
> the cited source files over the prose.

## Architectural Philosophy

Our architectural approach is guided by several core principles:

1. **Loose Coupling, High Cohesion**: Services and components are independently deployable with well-defined boundaries
2. **Evolutionary Design**: The system can adapt to changing requirements without extensive rewrites
3. **Resilience by Default**: Failures are isolated and don't cascade across the system
4. **Developer Experience First**: Architecture choices prioritize maintainability and developer productivity
5. **Pragmatic Trade-offs**: We make conscious decisions about complexity vs. simplicity based on actual needs

## Architectural Layers

```mermaid theme={null}
graph TB
    subgraph "Presentation Layer"
        A["React UI (apps/web, legacy)"]
        A2["TanStack Start (apps/tanstack-web, target)"]
        B[Shared @tuturuuu/ui Components]
    end

subgraph "API Layer"
        C["Next.js API Routes /api/v1 (legacy)"]
        D["tRPC stub (healthCheck only)"]
        R["Rust backend (apps/backend, target)"]
        IA["packages/internal-api facades"]
    end

subgraph "Application Surfaces"
        E[Web App]
        F[Rewise - AI Chat]
        G[Nova - Prompt Engineering]
        H[Calendar]
        I[Finance]
        J[Tuturuuu Tasks]
        K[Other Apps]
    end

subgraph "Background Tasks"
        L["Trigger.dev v4 task() — calendar sync, scheduling"]
    end

subgraph "Data Layer"
        N[Supabase PostgreSQL]
        O[RLS Policies]
        P[Realtime Subscriptions]
    end

A --> C
    A2 --> IA
    B --> A
    B --> A2
    IA --> R
    IA --> C
    C --> E
    R --> N
    E --> L
    F --> N
    G --> N
    H --> L
    H --> N
    I --> N
    J --> N
    C --> N
    L --> N
```

> [!NOTE]
>
> The `tRPC` node is intentionally small: `apps/web/src/trpc` is a stub that
> exports only a `healthCheck` `baseProcedure` with a hardcoded context. Real
> product data flows through `packages/internal-api` helpers calling REST
> `/api/v1` routes (legacy `apps/web`) or the Rust backend (`apps/backend`). A
> guard (`check-tanstack-api-access`) forbids direct `/trpc`, `/api`, and
> `/internal` calls from `apps/tanstack-web/src`.

## Core Architectural Patterns

### 1. Background And Scheduled Tasks (Trigger.dev)

Asynchronous, long-running work runs as Trigger.dev v4 `task()` definitions in
`packages/trigger`. Today this is scoped to a handful of concrete jobs —
Google Calendar full/incremental sync and the unified habit/task scheduler —
not a general cross-service event bus.

```ts theme={null}
// packages/trigger/src/unified-schedule.ts (Trigger.dev v4 task API)
import { task } from '@trigger.dev/sdk/v3';

export const unifiedScheduleTask = task({
  id: 'unified-schedule-task',
  queue: { concurrencyLimit: 5 },
  run: async (payload: { ws_id: string; windowDays?: number }) => {
    // ...scheduling work for one workspace
  },
});
```

> [!NOTE]
>
> The `@trigger.dev/sdk` is on v4 (`^4.4.5`). The v4 `task()` API is imported
> from `@trigger.dev/sdk/v3` (the path is unchanged across the v3→v4 SDK). The
> older v2 patterns (`client.defineJob`, `eventTrigger`, `io.runTask`,
> `io.sendEvent`) are not used in this repo.

**When to use:**

* Background processing that shouldn't block user requests
* Long-running operations (calendar full sync, batch scheduling)
* Scheduled/recurring work coordinated through Trigger.dev queues and concurrency limits

**Read more:** [Event-Driven Architecture](/platform/architecture/system-design/event-driven-architecture)

### 2. Hexagonal Architecture (Ports & Adapters)

Clean separation between business logic and infrastructure concerns within a
service.

> [!NOTE]
>
> Tuturuuu apps do not implement full hexagonal layering: there are no
> `domain/`, `application/`, or `infrastructure/` directories in `apps/web`.
> The closest real boundary is `packages/internal-api` (a typed facade in front
> of REST/backend endpoints) and the Rust backend's per-domain route modules in
> `apps/backend/src` (for example `inventory`, `changelog`, `aurora`). Treat
> this section as guidance for where a port/adapter seam is worth introducing,
> not a description of an existing layered structure.

**When to use:**

* Complex business logic that needs protection from technology changes
* Services requiring high testability
* When multiple adapters might be needed (REST + tRPC + GraphQL)

**Read more:** [Hexagonal Architecture](/platform/architecture/system-design/hexagonal-architecture)

### 3. Microservices in a Monorepo

Logical service boundaries with shared tooling and dependencies via Turborepo.

**When to use:**

* Independent teams working on different features
* Services with different scaling needs
* Features that benefit from technological flexibility

**Read more:** [Microservices Patterns](/platform/architecture/system-design/microservices-patterns)

### 4. Shared UI With Per-App Frontends

Organized frontend with a shared `@tuturuuu/ui` component library consumed by
each app. The legacy `apps/web` is a Next.js App Router app (Server Components
by default); the target `apps/tanstack-web` is a TanStack Start app. Both pull
from the same shared packages.

> [!NOTE]
>
> This was previously framed as a single "React Modular Monolith." In practice
> the frontend is split across distinct apps (`apps/web`, `apps/tanstack-web`,
> the Flutter `apps/mobile`) sharing packages, and the web frontend is mid-
> migration from Next.js to TanStack Start.

**When to use:**

* Complex UIs with shared component libraries
* Multiple client types (web, mobile) sharing logic
* Teams that value fast iteration over distributed deployments

**Related:** [Data Fetching](/platform/architecture/data-fetching)

## Decision Matrix

> [!NOTE]
>
> tRPC is **not** the user-facing API layer in Tuturuuu. The `apps/web/src/trpc`
> module is a stub (`healthCheck` only). Use `packages/internal-api` helpers in
> front of the Rust backend (`apps/backend`, target) or legacy `apps/web`
> `/api/v1` routes.

## Key Design Documents

### Foundational Decisions

* [Architectural Decisions](/platform/architecture/system-design/architectural-decisions) - Why we chose microservices, EDA, hexagonal architecture, and React patterns

### Pattern Deep Dives

* [Event-Driven Architecture](/platform/architecture/system-design/event-driven-architecture) - Advantages, drawbacks, and implementation
* [Extensibility, Resilience & Scalability](/platform/architecture/system-design/extensibility-resilience-scalability) - 15 reasons these properties are prioritized
* [Encapsulation Patterns](/platform/architecture/system-design/encapsulation-patterns) - Preventing unwanted coupling

### Implementation Guides

* [Hexagonal Architecture](/platform/architecture/system-design/hexagonal-architecture) - Ports, adapters, and layering
* [Microservices Patterns](/platform/architecture/system-design/microservices-patterns) - Service boundaries and communication

## Integration with Existing Docs

This system design documentation complements our existing architecture guides:

* **[Routing](/platform/architecture/routing)**: Workspace-scoped routing implementation
* **[Data Fetching](/platform/architecture/data-fetching)**: RSC, Server Actions, TanStack Query patterns
* **[Authentication](/platform/architecture/authentication)**: Supabase Auth integration
* **[Authorization](/platform/architecture/authorization)**: RLS and permission system
* **[tRPC](/platform/architecture/trpc)**: Type-safe API layer (currently a stub; not the product API path)
* **[API Routes](/platform/architecture/api-routes)**: REST endpoint patterns (legacy `apps/web` `/api/v1`)
* **[TanStack Start And Rust Migration](/platform/architecture/tanstack-rust-migration)**: Target frontend/backend split and route-ownership contract

> [!NOTE]
>
> The Routing, Data Fetching, tRPC, and API Routes guides above describe the
> legacy `apps/web` runtime. For the target architecture, the equivalent path is
> TanStack Start loaders/server functions plus Rust backend endpoints fronted by
> `packages/internal-api`.

## Quality Attributes

Our architecture explicitly optimizes for:

1. **Extensibility**: New features can be added with minimal changes to existing code
2. **Resilience**: Failures are isolated and the system degrades gracefully
3. **Scalability**: Services can scale independently based on demand
4. **Maintainability**: Code is organized, testable, and understandable
5. **Developer Experience**: Fast feedback loops and productive workflows

Each of these attributes is explored in depth in the linked documents above.

## Getting Started

For developers new to the codebase:

1. Start with [Architectural Decisions](/platform/architecture/system-design/architectural-decisions) to understand the "why"
2. Review [Microservices Patterns](/platform/architecture/system-design/microservices-patterns) to understand service boundaries
3. Explore [Hexagonal Architecture](/platform/architecture/system-design/hexagonal-architecture) for code organization within services
4. Read [Event-Driven Architecture](/platform/architecture/system-design/event-driven-architecture) for async communication patterns

For implementing new features:

1. Determine which app the work belongs to (`apps/web`, `apps/tanstack-web`, `apps/backend`, `apps/mobile`)
2. Route shared/typed API access through `packages/internal-api` rather than scattered raw `fetch`
3. Use Trigger.dev v4 `task()` definitions in `packages/trigger` for background/scheduled work
4. Follow data fetching patterns (TanStack Query; no `useEffect` fetching) for frontend integration
5. Keep boundaries clean and add tests; for new TanStack frontend ports, check the migration contract and the `check-tanstack-api-access` guard

## Architecture Evolution

This architecture is not static. The most significant in-flight change is the
migration of the web frontend from Next.js (`apps/web`) to TanStack Start
(`apps/tanstack-web`) plus a dedicated Rust backend (`apps/backend`), tracked
route-by-route in
[TanStack Start And Rust Migration](/platform/architecture/tanstack-rust-migration).
As the platform grows, we continuously evaluate:

* When to extract shared logic into new packages
* When to move product API surface from legacy `apps/web` routes to the Rust backend
* When to introduce new communication patterns
* When to adopt new technologies

All architectural changes are documented and follow the principles outlined in [AGENTS.md](https://github.com/tutur3u/platform/blob/main/AGENTS.md).

# Quality Attributes
Source: https://docs.tuturuuu.com/platform/architecture/system-design/quality-attributes

Maintainability, testability, and deployability in Tuturuuu's architecture

This document covers three critical quality attributes that are foundational to long-term system success: **Maintainability** (the ease of evolving and fixing the system), **Testability** (the ability to verify system correctness), and **Deployability** (the ease and safety of releasing changes).

> [!NOTE]
>
> These quality attributes are not added after the fact but are designed into the architecture from the beginning, ensuring the system remains healthy and productive as it grows.

> [!WARNING]
>
> **How to read this page.** Several patterns below (Hexagonal Architecture, ports/adapters, event sourcing, replay testing) are presented as **teaching models**, not as a description of the current codebase. Tuturuuu's apps are conventional **Next.js App Router** apps (plus a Rust backend) that share a single Supabase project — there are no `domain/`/`infrastructure/` hexagonal layers, no event store, and no per-app inter-service contracts package. Code samples that show those layers are **illustrative**; sections labeled **"In Tuturuuu today"** describe the real, verifiable structure. Treat the rest as design guidance for how we want isolated modules to behave.

> [!NOTE]
>
> To understand how different architectural patterns affect these quality attributes, see [Architectural Patterns Comparison](/platform/architecture/system-design/architectural-patterns-comparison).

## Maintainability

Maintainability determines how easily the system can be modified to fix bugs, add features, or adapt to changing requirements. Poor maintainability leads to increasing development costs and slower delivery over time.

### 1. Clear Domain Boundaries Reduce Cognitive Load

#### Architectural Choice

The microservices architecture and modular frontend design establish clear boundaries between different business domains, each with well-defined responsibilities and interfaces.

#### Impact and Justification

In a monolithic, tightly-coupled system, understanding how to make a change requires comprehending vast swaths of interconnected code. A developer wanting to modify the billing logic might need to understand authentication, user management, and inventory systems simply because they're all tangled together.

**Clear domain boundaries** solve this by ensuring each service or module has a focused responsibility. A developer working on the `FinanceService` only needs to understand finance-related concepts and the clearly-defined interfaces for interacting with other services. This dramatically reduces cognitive load and enables faster, more confident changes.

**In Tuturuuu today:**

```text theme={null}
apps/
├── web/          // Main Next.js platform (port 7803) - workspace management
├── tanstack-web/ // TanStack Start successor to apps/web (migration paused)
├── backend/      // Rust backend (port 7820)
├── finance/      // Finance surface
├── calendar/     // Calendar surface
├── tasks/        // Tasks surface
├── nova/         // AI challenges
├── rewise/       // AI chat
└── mobile/       // Flutter mobile app

// Each app owns a focused surface. The web-facing apps are conventional
// Next.js App Router apps; they share one Supabase project rather than
// each owning a private datastore. Cross-cutting product logic lives in
// shared packages (packages/internal-api, packages/types, packages/ui).
```

The boundary that reduces cognitive load here is the **app + feature folder**, not a separate per-service runtime with its own database. A developer working on finance can stay inside `apps/finance` (and the finance helpers in `packages/apis`/`packages/internal-api`) without learning the calendar surface.

**Module boundaries in frontend:**

```typescript theme={null}
// apps/web/src/app/[locale]/(dashboard)/[wsId]/
finance/
├── layout.tsx              // Finance-specific layout
├── transactions/           // Transaction management
├── reports/                // Financial reports
└── settings/               // Finance settings

// Finance module is self-contained
// Changes here don't affect calendar or tasks modules
```

#### Clarifying Additions

**Engineers focus on one area at a time without understanding the entire system.** New team members can become productive quickly by mastering a single domain rather than the entire codebase.

**This reduces onboarding complexity.** Clear boundaries make it obvious where to find code related to specific features, accelerating the learning curve for new developers.

**Maintenance tasks become easier to isolate and execute.** Bug fixes and feature additions are scoped to specific services or modules, reducing the risk of unintended side effects.

***

### 2. Technology Independence Prevents Legacy Lock-In

#### Architectural Choice

Isolating technology choices (databases, frameworks, external services) behind well-defined interfaces keeps core business logic decoupled from the tools that implement it.

#### Impact and Justification

Technology evolves rapidly. Frameworks fall out of favor, databases become outdated, and new tools emerge. Systems that tightly couple business logic to specific technologies become **legacy systems**—expensive and risky to modernize.

**Technology independence** protects the valuable business logic (which changes rarely) from technological churn (which happens frequently). When infrastructure details sit behind an interface, you can upgrade or replace technologies without rewriting business rules.

> [!NOTE]
>
> **Illustrative pattern.** The `WorkspaceRepository` / `SupabaseWorkspaceRepository` example below is a teaching model. Tuturuuu does **not** ship `packages/types/src/domain/workspace.ts` or `apps/web/src/infrastructure/repositories/*`; there is no repository-interface layer. In the real code, route handlers and shared helpers in `packages/internal-api` and `packages/apis` call the Supabase client directly (see "In Tuturuuu today" below). Read this as how to keep a swappable seam if you introduce one.

```typescript theme={null}
// Illustrative: business logic expressed against an interface, not an implementation
export interface WorkspaceRepository {
  findById(id: string): Promise<Workspace | null>;
  save(workspace: Workspace): Promise<void>;
  delete(id: string): Promise<void>;
}

// Core business logic depends on the interface
export class WorkspaceService {
  constructor(private repo: WorkspaceRepository) {}

async archiveWorkspace(id: string) {
    const workspace = await this.repo.findById(id);
    if (!workspace) throw new Error('Workspace not found');

workspace.archive(); // Pure business logic
    await this.repo.save(workspace);
  }
}

// Illustrative infrastructure implementation (the swappable seam)
export class SupabaseWorkspaceRepository implements WorkspaceRepository {
  constructor(private client: SupabaseClient) {}

async findById(id: string) {
    const { data } = await this.client
      .from('workspaces')
      .select('*')
      .eq('id', id)
      .single();

return data ? this.toDomain(data) : null;
  }

async save(workspace: Workspace) {
    await this.client
      .from('workspaces')
      .upsert(this.toDatabase(workspace));
  }

async delete(id: string) {
    await this.client
      .from('workspaces')
      .delete()
      .eq('id', id);
  }
}

// Future: Can swap Supabase for Prisma, Drizzle, or any other ORM
// WITHOUT changing business logic
```

**Example technology evolution:**

```typescript theme={null}
// Today: Supabase
const repo = new SupabaseWorkspaceRepository(supabaseClient);

// Tomorrow: Drizzle ORM (business logic unchanged)
const repo = new DrizzleWorkspaceRepository(drizzleClient);

// Next year: Different database (business logic still unchanged)
const repo = new MongoWorkspaceRepository(mongoClient);

// Business logic stays the same:
const service = new WorkspaceService(repo);
await service.archiveWorkspace('ws-123');
```

**In Tuturuuu today:** technology independence comes from a few concrete seams rather than a full ports/adapters layer:

* Supabase access is centralized behind the `@tuturuuu/supabase/next/server` factories (`createClient()` and `createDynamicClient()` are async, `createAdminClient()` is sync). Swapping how a client is built happens in one place.
* Generated DB types are imported from `@tuturuuu/types/db`, so schema changes propagate through types instead of hand-written mappers.
* Shared product logic lives in `packages/internal-api` and `packages/apis`, so the web app and its TanStack successor can reuse the same helpers as the migration proceeds.

The biggest real-world example of this independence is the in-progress move of `apps/web` to `apps/tanstack-web` + a Rust `apps/backend`: shared packages let the data layer be re-pointed without rewriting every call site.

#### Clarifying Additions

**No single technical choice restricts future evolution.** The architecture accommodates technological progress without requiring expensive rewrites of core business logic.

**Components modernize incrementally as needed.** Instead of "big bang" technology migrations that put the entire system at risk, individual components can be upgraded independently.

**This protects the system from long-term stagnation.** The architecture remains flexible enough to adopt new technologies as they mature, preventing technical debt accumulation.

***

### 3. Hexagonal Architecture Minimizes Ripple Effects

#### Architectural Choice

The Hexagonal Architecture's strict separation between core domain logic and external concerns ensures that changes to infrastructure do not ripple into business rules.

#### Impact and Justification

In traditional layered architectures, changes to infrastructure (like upgrading a database library or switching message brokers) often require modifications to business logic because the layers are tightly coupled.

Hexagonal Architecture **inverts the dependency direction**. The core domain is completely isolated and defines interfaces (ports) for what it needs. Infrastructure adapters implement these interfaces but the core remains ignorant of implementation details.

This means infrastructure changes stay contained in the adapter layer. Upgrading from PostgreSQL 14 to PostgreSQL 16, changing from REST to GraphQL, or switching message brokers requires modifying only the relevant adapters—the domain core remains untouched.

> [!NOTE]
>
> **Illustrative pattern, not current code.** Tuturuuu does **not** implement a `TaskService` with injected `TaskRepository` / `EventBus` / `Logger` ports, and there is no `@tuturuuu/logging` or `@tuturuuu/observability` package. Task logic lives in conventional Next.js route handlers and shared helpers. The example below shows the *shape* of a hexagonal seam so you can recognize where one would help if a piece of logic becomes worth isolating. For background work, Tuturuuu uses **Trigger.dev v4 `task()`** definitions in `packages/trigger/src` — not a custom `EventBus`.

```typescript theme={null}
// Illustrative domain core (unchanged when infrastructure changes)
export class TaskService {
  constructor(
    private taskRepo: TaskRepository,
    private eventBus: EventBus,
    private logger: Logger
  ) {}

async createTask(data: CreateTaskData) {
    const task = Task.create(data);

await this.taskRepo.save(task);
    await this.eventBus.publish(new TaskCreated(task));
    this.logger.info('Task created', { taskId: task.id });

return task;
  }
}

// Infrastructure layer (changeable without affecting domain)
// Version 1: Supabase + Trigger.dev + Console logging
const service = new TaskService(
  new SupabaseTaskRepository(supabase),
  new TriggerEventBus(trigger),
  new ConsoleLogger()
);

// Version 2: Drizzle + NATS + Structured logging
// Domain core completely unchanged!
const service = new TaskService(
  new DrizzleTaskRepository(drizzle),
  new NatsEventBus(nats),
  new StructuredLogger(winston)
);
```

**Real-world example - Upgrading Next.js:**

```typescript theme={null}
// Business logic and components remain the same
// Only infrastructure adapters need updates

// Before Next.js 16
export function getWorkspaceData(id: string) {
  // Implementation using Next.js 15 patterns
}

// After Next.js 16
export function getWorkspaceData(id: string) {
  // Implementation using Next.js 16 patterns
  // Component code using this function unchanged
}
```

#### Clarifying Additions

**Core logic remains stable even during broad technical changes.** The most valuable part of the codebase (business rules) is shielded from the volatility of technology trends.

**Adaptation happens at edges rather than at the center.** When technology changes, only the outer layers (adapters) need modification, keeping changes localized and predictable.

**This protects business rules against unnecessary modification.** Domain experts can rely on business logic remaining stable, reducing the risk of introducing bugs when upgrading infrastructure.

***

### 4. Modular Frontend Prevents UI-Level Entanglement

#### Architectural Choice

The React Modular Monolith pattern organizes the frontend into self-contained modules with clear boundaries, preventing the "big ball of mud" problem common in large SPAs.

#### Impact and Justification

As frontend applications grow, they often become tangled webs of interdependent components, shared state, and implicit dependencies. Making a change in one area unexpectedly breaks seemingly unrelated features.

The **modular monolith** approach enforces architectural discipline by organizing code into feature-based modules with explicit boundaries. Each module (Finance, Calendar, Tasks, etc.) owns its components, state management, and business logic. Inter-module dependencies are explicit and minimized.

This structure makes maintenance dramatically easier because changes stay localized within module boundaries.

**In Tuturuuu today:** `apps/web` follows exactly this shape — feature folders under `app/[locale]/(dashboard)/[wsId]/` (finance, calendar, tasks, ...) each own their routes and colocated `_components/`. Client state uses **Jotai** (and TanStack Query for server data); the per-module `state.ts` paths below are a representative shape rather than fixed filenames.

```text theme={null}
apps/web/src/
├── app/[locale]/(dashboard)/[wsId]/
│   ├── finance/                    // Finance module
│   │   ├── layout.tsx
│   │   ├── transactions/
│   │   ├── reports/
│   │   └── _components/           // Finance-specific components
│   ├── calendar/                   // Calendar module
│   │   ├── layout.tsx
│   │   ├── events/
│   │   └── _components/           // Calendar-specific components
│   └── tasks/                      // Tasks module
│       ├── layout.tsx
│       ├── boards/
│       └── _components/           // Task-specific components
├── components/
│   ├── finance/                   // Shared finance components
│   ├── calendar/                  // Shared calendar components
│   ├── tasks/                     // Shared task components
│   └── common/                    // Truly shared components
```

**Module independence:**

```typescript theme={null}
// Finance module - self-contained state management
// apps/web/src/app/[locale]/(dashboard)/[wsId]/finance/state.ts
import { atom } from 'jotai';

export const financeTransactionsAtom = atom<Transaction[]>([]);
export const financeFiltersAtom = atom<Filters>({});

// Calendar module - separate state management
// apps/web/src/app/[locale]/(dashboard)/[wsId]/calendar/state.ts
import { atom } from 'jotai';

export const calendarEventsAtom = atom<Event[]>([]);
export const calendarViewAtom = atom<'month' | 'week' | 'day'>('month');

// Modules don't share state - clear boundaries
```

#### Clarifying Additions

**UI concerns grow independently instead of interfering with each other.** Finance features can evolve without touching calendar code, and vice versa.

**Teams can refactor modules safely.** Because module boundaries are clear, teams can confidently restructure their module knowing they won't break other features.

**Visual and functional changes stay well-scoped.** UI redesigns or feature enhancements affect only the relevant module, reducing regression testing burden.

***

### 5. Operational Independence per Service

#### Architectural Choice

Each microservice can be deployed, scaled, monitored, and maintained independently without coordinating with other services.

#### Impact and Justification

In a monolithic architecture, operational tasks affect the entire system. Deploying a minor bug fix to the reporting module requires rebuilding and redeploying the entire application. Scaling requires scaling everything, even if only one feature is under load.

**Operational independence** means each service is a separate deployable unit with its own lifecycle. Teams can:

* Deploy updates to their service multiple times per day
* Scale their service based on its specific load patterns
* Monitor their service's health independently
* Apply operational changes (like upgrading Node.js) on their own schedule

This independence accelerates development velocity and reduces the coordination overhead that plagues monolithic systems.

**In Tuturuuu today:** there are no `deploy:web` / `deploy:finance` / `deploy:calendar` package scripts. Independence is achieved through **per-app Vercel projects** wired up by dedicated GitHub Actions workflows. Each app has its own preview workflow under `.github/workflows/` (for example `vercel-preview-finance.yaml`, `vercel-preview-calendar.yaml`, `vercel-preview-drive.yaml`), and Turborepo only rebuilds the apps affected by a change:

```bash theme={null}
# Build a single workspace and its dependency graph (Turborepo filters by app)
bun turbo run build --filter=@tuturuuu/web

# Run an app locally (each app owns its own dev script)
cd apps/finance && bun dev
```

```yaml theme={null}
# Real per-app preview workflow — .github/workflows/vercel-preview-finance.yaml
name: Vercel Finance Preview Deployment
# Builds only the shared deps the finance app needs, then deploys it to Vercel:
#   bun turbo:local run build --filter=@tuturuuu/types --filter=@tuturuuu/supabase --filter=@tuturuuu/internal-api
```

Because each app is its own Vercel project, finance can deploy without rebuilding or redeploying the web or calendar apps.

**Monitoring:** Tuturuuu does not ship a custom per-service metrics SDK. Runtime/server logs in API, cron, and infrastructure code use the native console method matching severity, while retained request, cron, deployment, and usage data still flows through the internal log-drain storage where those wrappers are wired. Vercel provides per-project deployment and runtime insight. Treat the `monitorErrorRate(...)` snippet style as conceptual.

#### Clarifying Additions

**Services update without impacting other services.** A finance service deployment doesn't require coordination with the calendar team or risk affecting calendar functionality.

**Maintenance tasks stay focused and manageable.** Security patches, dependency updates, and refactoring efforts are scoped to individual services.

**This encourages timely updates and better long-term health.** Teams aren't hesitant to deploy updates because the blast radius is limited to their service.

***

## Testability

Testability determines how easily we can write and maintain automated tests that verify system correctness. High testability leads to better quality, faster development, and greater confidence in changes.

### 1. Pure Logic Enables Fast Unit Testing

#### Architectural Choice

Keeping pure logic free of infrastructure dependencies enables fast unit tests that don't require databases, network calls, or other external systems. (A full Hexagonal layer is one way to enforce this; Tuturuuu does not implement that layering, but the *principle* — isolate decision logic from I/O — still applies inside conventional modules.)

#### Impact and Justification

In traditional architectures, business logic is often tightly coupled to infrastructure (database access, API calls, file I/O). This makes testing painful because every test requires:

* Setting up test databases
* Mocking network requests
* Managing test data cleanup
* Dealing with test environment flakiness

These tests are slow (seconds per test instead of milliseconds), fragile (break when infrastructure changes), and difficult to write (require complex setup).

Isolating pure logic solves this by making the decision code free of infrastructure dependencies. Tests instantiate the object and verify rules with simple in-memory inputs. These tests run in milliseconds and never fail due to infrastructure issues.

> [!NOTE]
>
> **Illustrative pattern.** The `Workspace` class below does not exist at `packages/types/src/domain/workspace.ts` (there is no `domain/` directory). It models how a pure, framework-free unit would look. Real tests in the repo run on **Vitest** (`vitest run`) and live next to the code they cover as `*.test.ts` — for example the route handler tests under `packages/apis/src/finance/**`.

```typescript theme={null}
// Illustrative pure logic — no I/O, fully testable
export class Workspace {
  private constructor(
    public readonly id: string,
    public name: string,
    public status: 'active' | 'archived',
    public memberLimit: number
  ) {}

static create(data: CreateWorkspaceData): Workspace {
    if (data.name.length < 3) {
      throw new Error('Workspace name must be at least 3 characters');
    }

return new Workspace(
      uuid(),
      data.name,
      'active',
      data.memberLimit || 10
    );
  }

archive() {
    if (this.status === 'archived') {
      throw new Error('Workspace already archived');
    }
    this.status = 'archived';
  }

addMember() {
    // Business rule: enforce member limit
    if (this.getMemberCount() >= this.memberLimit) {
      throw new Error('Member limit reached');
    }
    // ... add member logic
  }
}

// Test - no infrastructure required (Vitest, colocated *.test.ts)
describe('Workspace', () => {
  describe('create', () => {
    it('creates workspace with valid name', () => {
      const workspace = Workspace.create({
        name: 'My Workspace',
        memberLimit: 10
      });

expect(workspace.name).toBe('My Workspace');
      expect(workspace.status).toBe('active');
      expect(workspace.memberLimit).toBe(10);
    });

it('rejects workspace with short name', () => {
      expect(() => {
        Workspace.create({ name: 'ab', memberLimit: 10 });
      }).toThrow('Workspace name must be at least 3 characters');
    });
  });

describe('archive', () => {
    it('archives active workspace', () => {
      const workspace = Workspace.create({ name: 'Test', memberLimit: 10 });

workspace.archive();

expect(workspace.status).toBe('archived');
    });

it('rejects archiving already archived workspace', () => {
      const workspace = Workspace.create({ name: 'Test', memberLimit: 10 });
      workspace.archive();

expect(() => workspace.archive()).toThrow('Workspace already archived');
    });
  });
});

// Tests run in <1ms each, no database required
```

#### Clarifying Additions

**Domain logic is easy to verify because it avoids external dependencies.** Tests focus purely on business rules without the complexity of infrastructure setup.

**Tests remain fast and reliable.** Unit tests execute in milliseconds, enabling tight feedback loops and encouraging developers to run tests frequently.

**This leads to strong coverage of critical business rules.** Because tests are easy to write, developers write more of them, leading to better quality and fewer bugs.

***

### 2. Adapter Design Enables Test Doubles

#### Architectural Choice

All external dependencies are accessed through interfaces (ports), allowing test implementations (test doubles) to be easily substituted during testing.

#### Impact and Justification

Real external systems (databases, APIs, message brokers) are problematic for testing:

* **Slow**: Network calls and database queries add latency
* **Flaky**: External systems can be temporarily unavailable
* **Stateful**: Tests can interfere with each other through shared state
* **Complex**: Require extensive setup and teardown

**Test doubles** (in-memory implementations of interfaces) solve all these problems. They're fast, reliable, isolated, and simple. The pattern works wherever a dependency is reachable behind an interface or an injected client.

> [!NOTE]
>
> **Illustrative pattern.** `TaskRepository` / `InMemoryTaskRepository` is a model, not repo code. In practice, Tuturuuu tests usually mock the Supabase client (or use Vitest mocks) at the boundary of a route handler rather than swapping a hand-written repository port. The shape below shows the underlying idea: keep the seam mockable.

```typescript theme={null}
// Illustrative interface seam
export interface TaskRepository {
  findById(id: string): Promise<Task | null>;
  save(task: Task): Promise<void>;
  findByWorkspace(workspaceId: string): Promise<Task[]>;
}

// Production implementation (Supabase)
export class SupabaseTaskRepository implements TaskRepository {
  // ... real database implementation
}

// Test implementation (in-memory)
export class InMemoryTaskRepository implements TaskRepository {
  private tasks = new Map<string, Task>();

async findById(id: string): Promise<Task | null> {
    return this.tasks.get(id) || null;
  }

async save(task: Task): Promise<void> {
    this.tasks.set(task.id, task);
  }

async findByWorkspace(workspaceId: string): Promise<Task[]> {
    return Array.from(this.tasks.values())
      .filter(task => task.workspaceId === workspaceId);
  }

// Test helpers
  clear() {
    this.tasks.clear();
  }

count() {
    return this.tasks.size;
  }
}

// Test using in-memory repository
describe('TaskService', () => {
  let taskRepo: InMemoryTaskRepository;
  let service: TaskService;

beforeEach(() => {
    taskRepo = new InMemoryTaskRepository();
    service = new TaskService(taskRepo);
  });

it('creates task', async () => {
    const task = await service.createTask({
      title: 'Test task',
      workspaceId: 'ws-123'
    });

expect(task.title).toBe('Test task');
    expect(taskRepo.count()).toBe(1);

// Verify task was saved
    const saved = await taskRepo.findById(task.id);
    expect(saved).toBeDefined();
  });

it('finds tasks by workspace', async () => {
    await service.createTask({ title: 'Task 1', workspaceId: 'ws-1' });
    await service.createTask({ title: 'Task 2', workspaceId: 'ws-1' });
    await service.createTask({ title: 'Task 3', workspaceId: 'ws-2' });

const tasks = await taskRepo.findByWorkspace('ws-1');

expect(tasks).toHaveLength(2);
  });
});
```

#### Clarifying Additions

**External interactions can be simulated cleanly.** Test doubles provide predictable, controllable implementations of external systems.

**Testing becomes predictable and thorough.** Tests aren't affected by external system availability or performance, leading to consistent, reliable test suites.

**Complex conditions are easier to replicate.** Error scenarios (network failures, database constraints) can be easily simulated with test doubles that would be difficult to reproduce with real systems.

***

### 3. Contract Testing for Microservices

#### Architectural Choice

Service boundaries are verified through contract tests that ensure APIs and event schemas remain compatible as services evolve independently.

#### Impact and Justification

In a microservices architecture, services evolve independently. A breaking change to a service's API can silently break consumers without the producer knowing until runtime. Traditional integration tests that spin up all services are slow, complex, and brittle.

**Contract testing** solves this by verifying that:

1. **Producer** honors the contract (API/event schema) that consumers expect
2. **Consumer** can handle the responses/events that producers emit

This catches breaking changes early (at build time) without requiring full integration test environments.

> [!NOTE]
>
> **Illustrative pattern.** There is no `packages/apis/src/contracts/workspace.contract.ts`, and Tuturuuu does not run formal producer/consumer contract tests today. `packages/apis` (`@tuturuuu/apis`) holds **REST route handlers** (e.g. `src/finance/debts/route.ts`) with colocated `*.test.ts` files — not contract schemas. The closest real practice is validating request/response payloads with **Zod** inside route handlers and asserting on them in tests. The schema/contract code below is a conceptual model for how an explicit contract would look if introduced.

```typescript theme={null}
// Illustrative API contract definition
import { z } from 'zod';

export const WorkspaceContract = {
  getWorkspace: {
    input: z.object({
      id: z.guid()
    }),
    output: z.object({
      id: z.guid(),
      name: z.string(),
      status: z.enum(['active', 'archived']),
      memberCount: z.number(),
      createdAt: z.string().datetime()
    })
  },

createWorkspace: {
    input: z.object({
      name: z.string().min(3),
      memberLimit: z.number().optional()
    }),
    output: z.object({
      id: z.guid(),
      name: z.string(),
      status: z.literal('active'),
      memberLimit: z.number()
    })
  }
};

// Producer test - verify service honors contract
describe('WorkspaceAPI - Producer Contract', () => {
  it('getWorkspace returns valid response', async () => {
    const workspace = await createTestWorkspace();

const response = await api.getWorkspace({ id: workspace.id });

// Verify response matches contract
    expect(() => {
      WorkspaceContract.getWorkspace.output.parse(response);
    }).not.toThrow();
  });

it('createWorkspace accepts valid input and returns valid output', async () => {
    const input = { name: 'Test Workspace', memberLimit: 20 };

// Verify input is valid
    expect(() => {
      WorkspaceContract.createWorkspace.input.parse(input);
    }).not.toThrow();

const response = await api.createWorkspace(input);

// Verify output matches contract
    expect(() => {
      WorkspaceContract.createWorkspace.output.parse(response);
    }).not.toThrow();
  });
});

// Consumer test - verify consumer can handle producer responses
describe('WorkspaceAPI - Consumer Contract', () => {
  it('handles workspace response', () => {
    // Mock response that matches contract
    const mockResponse = {
      id: '123e4567-e89b-12d3-a456-426614174000',
      name: 'My Workspace',
      status: 'active' as const,
      memberCount: 5,
      createdAt: '2024-11-17T00:00:00Z'
    };

// Consumer code should handle this
    expect(() => {
      const workspace = parseWorkspaceResponse(mockResponse);
      expect(workspace.name).toBe('My Workspace');
    }).not.toThrow();
  });
});
```

**Event contract testing:**

```typescript theme={null}
// Event schema contract
export const WorkspaceEvents = {
  'workspace.created': z.object({
    workspaceId: z.guid(),
    name: z.string(),
    ownerId: z.guid(),
    createdAt: z.string().datetime()
  }),

'workspace.member.added': z.object({
    workspaceId: z.guid(),
    userId: z.guid(),
    role: z.enum(['owner', 'admin', 'member']),
    addedAt: z.string().datetime()
  })
};

// Producer test
it('emits valid workspace.created event', async () => {
  const event = await captureEvent('workspace.created', () => {
    return createWorkspace({ name: 'Test' });
  });

// Verify event matches schema
  expect(() => {
    WorkspaceEvents['workspace.created'].parse(event);
  }).not.toThrow();
});

// Consumer test
it('handles workspace.created event', async () => {
  const mockEvent = {
    workspaceId: '123e4567-e89b-12d3-a456-426614174000',
    name: 'Test Workspace',
    ownerId: '234e5678-e89b-12d3-a456-426614174000',
    createdAt: '2024-11-17T00:00:00Z'
  };

// Consumer should handle valid events
  expect(async () => {
    await handleWorkspaceCreated(mockEvent);
  }).not.toThrow();
});
```

#### Clarifying Additions

**Service boundaries remain stable through contract checks.** Breaking changes are caught by failing contract tests before code reaches production.

**Teams catch breaking changes early.** Instead of discovering API incompatibilities in staging or production, contract tests fail during CI/CD.

**Collaboration between services stays reliable.** Contract tests act as executable documentation of service interfaces, ensuring compatibility as teams work independently.

***

### 4. Event-Driven Systems Support Replay Testing

#### Architectural Choice

The event-driven architecture preserves event history, enabling powerful testing techniques like event replay and scenario recreation.

#### Impact and Justification

Traditional request-response systems are ephemeral. Once a request completes, reproducing the exact conditions that led to a bug is difficult or impossible. Debugging production issues often involves guesswork.

**Event replay** provides a time machine for testing. Because all events are preserved, we can:

1. **Capture** event sequences from production
2. **Replay** them in test environments to reproduce bugs
3. **Verify** that fixes resolve the issue
4. **Test** edge cases by constructing specific event sequences

This makes debugging significantly more reliable and enables regression testing for complex, multi-step workflows.

> [!WARNING]
>
> **Aspirational pattern — not implemented.** Tuturuuu has **no event store and no event-sourcing layer**, so there is no `eventStore.query(...)` or production event replay. Background work runs as **Trigger.dev v4 `task()`** definitions (`packages/trigger/src`), which are individually testable but are not a replayable event log. The code below illustrates the *concept* of replay testing; do not treat it as an available API.

```typescript theme={null}
// Aspirational: capture events from an event store (not present in Tuturuuu)
export async function captureEventSequence(
  workspaceId: string,
  startTime: Date,
  endTime: Date
): Promise<DomainEvent[]> {
  return await eventStore.query({
    workspaceId,
    from: startTime,
    to: endTime,
    orderBy: 'timestamp'
  });
}

// Replay events in test environment
export async function replayEvents(events: DomainEvent[]) {
  // Reset test environment
  await resetTestDatabase();

// Replay each event in order
  for (const event of events) {
    await eventBus.publish(event);
    await waitForEventProcessing();
  }
}

// Test by replaying production scenario
describe('Bug: Workspace members not receiving invitations', () => {
  it('reproduces production bug', async () => {
    // Capture events from production incident
    const events = await captureEventSequence(
      'ws-problematic',
      new Date('2024-11-15T14:00:00Z'),
      new Date('2024-11-15T14:05:00Z')
    );

// Replay in test environment
    await replayEvents(events);

// Verify bug is reproduced
    const invitations = await getInvitations('ws-problematic');
    expect(invitations).toHaveLength(0); // Bug: no invitations sent
  });

it('verifies fix resolves the issue', async () => {
    // Apply the fix (code changes)

// Replay same event sequence
    const events = await captureEventSequence(
      'ws-problematic',
      new Date('2024-11-15T14:00:00Z'),
      new Date('2024-11-15T14:05:00Z')
    );

await replayEvents(events);

// Verify fix worked
    const invitations = await getInvitations('ws-problematic');
    expect(invitations).toHaveLength(3); // Fix: invitations sent correctly
  });
});

// Test edge cases by constructing event sequences
describe('Workspace state transitions', () => {
  it('handles rapid member additions and removals', async () => {
    const events = [
      createEvent('workspace.created', { id: 'ws-1' }),
      createEvent('member.added', { userId: 'user-1' }),
      createEvent('member.added', { userId: 'user-2' }),
      createEvent('member.removed', { userId: 'user-1' }),
      createEvent('member.added', { userId: 'user-3' }),
      createEvent('member.removed', { userId: 'user-2' }),
    ];

await replayEvents(events);

const workspace = await getWorkspace('ws-1');
    expect(workspace.members).toHaveLength(1);
    expect(workspace.members[0].userId).toBe('user-3');
  });
});
```

#### Clarifying Additions

**Capturing event sequences makes reproducing issues easier.** Production bugs can be reliably recreated in test environments by replaying the exact sequence of events that led to the failure.

**Historical flows can be studied and validated.** Teams can analyze how the system responded to past events and verify that fixes prevent recurrence.

**This strengthens debugging across distributed processes.** Complex, multi-service workflows can be tested end-to-end by replaying events, making it easier to verify system behavior.

***

### 5. Independent CI Pipelines

#### Architectural Choice

Each microservice has its own independent CI/CD pipeline that runs tests, builds, and deploys the service without coordinating with other services.

#### Impact and Justification

In a monolithic architecture, all tests run in a single, long CI pipeline. A failure in any part of the system blocks the entire deployment, and slow tests create bottlenecks.

**Independent CI pipelines** for each service provide:

* **Parallelism**: All services test simultaneously, dramatically reducing feedback time
* **Isolation**: Failures in one service don't block others from deploying
* **Focus**: Teams see only their service's test results, reducing noise
* **Speed**: Smaller test suites run faster than monolithic suites

**In Tuturuuu today:** there are no `web-ci.yml` / `finance-ci.yml` per-app pipeline files. Instead, shared workflows test the whole graph with Turborepo's affected-package filtering, and **per-app Vercel preview workflows** handle build/deploy. Real workflows under `.github/workflows/` include:

* `turbo-unit-tests.yaml` — runs unit tests across affected workspaces
* `type-check.yaml` — type checking
* `biome-check.yaml` — lint/format (Tuturuuu uses **Biome**, not ESLint/Prettier)
* `ci-check.yml` — validates CI configuration
* `vercel-preview-finance.yaml`, `vercel-preview-calendar.yaml`, `vercel-preview-drive.yaml`, ... — one preview-deploy workflow per app
* `rust-backend.yml` — builds/tests `apps/backend`

The independence comes from Turborepo only running tasks for changed packages plus separate Vercel projects per app, rather than from one CI file per service.

```bash theme={null}
# How affected work is scoped locally and in CI
bun turbo run test --filter=@tuturuuu/web
bun turbo run build --filter=@tuturuuu/finance
```

**Turborepo task configuration.** The repo runs **Turborepo 2.x**, which uses the `tasks` key (the older `pipeline` key was removed in v2):

```json theme={null}
// turbo.json (real key is "tasks", not "pipeline")
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "test": {
      "cache": true
    },
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**", "dist/**"],
      "cache": true
    }
  }
}
```

#### Clarifying Additions

**Tests run in parallel without interfering with each other.** Multiple teams can have their tests running simultaneously, reducing wait times.

**Failures stay localized to the affected service.** A failing test in the finance service doesn't prevent the web app from deploying.

**Delivery becomes smoother and less risky.** Smaller, focused deployments are easier to verify and roll back if needed.

***

## Deployability

Deployability determines how easily and safely we can release changes to production. Good deployability enables frequent, low-risk deployments.

### 1. Independent Deployment Pipelines

#### Architectural Choice

Each microservice is independently deployable with its own release cycle, allowing teams to ship updates without coordinating across the organization.

#### Impact and Justification

Monolithic architectures force **all-or-nothing deployments**. Every change, no matter how small or isolated, requires rebuilding and redeploying the entire application. This creates:

* **Deployment bottlenecks**: Teams must coordinate release windows
* **High-risk releases**: Large deployments contain many changes, increasing failure probability
* **Slow feedback**: Small fixes take days to reach production
* **Deployment fear**: Teams avoid deploying due to coordination overhead

**Independent deployment** eliminates these problems. Each service ships on its own schedule:

* **Fast iteration**: Deploy bug fixes minutes after they're written
* **Low risk**: Small, focused deployments are easier to verify and roll back
* **Team autonomy**: No cross-team coordination required for deployments
* **Continuous delivery**: Deploy multiple times per day without fear

**In Tuturuuu today:** there is no `bun deploy:web` / `bun deploy:finance` / `bun deploy:calendar` command. Each app is a **separate Vercel project**, driven by its own GitHub Actions workflow, so deploys are already decoupled per app:

```text theme={null}
.github/workflows/
├── vercel-preview-finance.yaml    // Finance app preview/deploy
├── vercel-preview-calendar.yaml   // Calendar app preview/deploy
├── vercel-preview-drive.yaml      // Drive app preview/deploy
├── vercel-preview-apps.yaml       // Shared preview orchestration
└── rust-backend.yml               // apps/backend (Rust) build + deploy
```

Each workflow builds only the shared dependencies that app needs (via Turborepo `--filter`) and ships that one Vercel project. Deploying finance does not rebuild or redeploy web or calendar.

> [!NOTE]
>
> The Rust `apps/backend` (port `7820`) deploys on its own track (`rust-backend.yml`), independent of the Vercel front-ends — another axis of deployment independence introduced by the migration.

#### Clarifying Additions

**Teams ship updates without affecting others.** Finance deployments don't trigger web redeployments or risk breaking calendar functionality.

**Releases become smaller and less risky.** Instead of deploying 50 changes from 10 teams, each team deploys 5 changes independently.

**This improves overall delivery speed.** Removing coordination overhead and deployment fear leads to more frequent, confident releases.

***

### 2. Controlled Rollout Strategies Through Architectural Boundaries

#### Architectural Choice

Service boundaries enable granular deployment strategies like canary releases, blue-green deployments, and feature flags, allowing changes to be introduced gradually.

#### Impact and Justification

Even with small deployments, risk remains. A bug can slip through testing and impact production users. **Controlled rollout strategies** mitigate this risk by:

* **Gradual exposure**: New versions serve only a small percentage of traffic initially
* **Monitoring**: Observe error rates and performance before full rollout
* **Quick rollback**: Instantly revert to previous version if issues detected
* **Confidence**: Deploy with confidence knowing failures impact minimal users

Service boundaries make these strategies practical because each service can have independent routing and versioning.

> [!NOTE]
>
> **Mixed: real platform capability + illustrative code.** Per-app Vercel projects give Tuturuuu **atomic, instantly-revertible deployments** and preview URLs per change — that part is real. However, Tuturuuu does **not** ship the `featureFlags.get/enable(...)` service or the `switchTraffic('blue' -> 'green')` / `supabase.rpc('run_migration')` orchestration shown below; those are conceptual illustrations of canary, feature-flag, and blue-green strategies, not repo APIs. (Tuturuuu's Supabase migrations are plain SQL applied via the migration workflow, not an RPC call.)

```typescript theme={null}
// Conceptual: canary deployment (Vercel handles atomic deploy + instant rollback)
// New version serves 10% of traffic initially

// vercel.json
{
  "name": "tuturuuu-finance",

// Vercel automatically does canary deployments
  // 1. Deploy new version
  // 2. Route 10% traffic to new version
  // 3. Monitor error rates
  // 4. Gradually increase to 100% if healthy
  // 5. Automatic rollback if error rates spike
}

// Feature flags for gradual feature rollout
export async function getFinanceFeatures(workspaceId: string) {
  const flags = await featureFlags.get(workspaceId);

return {
    advancedReports: flags.has('finance.advanced-reports'),
    aiForecasting: flags.has('finance.ai-forecasting'),
    multiCurrency: flags.has('finance.multi-currency'),
  };
}

// Enable feature for specific workspaces first
await featureFlags.enable('finance.ai-forecasting', {
  workspaces: ['ws-beta-1', 'ws-beta-2'] // Beta test
});

// Monitor performance and errors
const metrics = await monitorFeature('finance.ai-forecasting', '24h');

if (metrics.errorRate < 0.01 && metrics.userSatisfaction > 0.8) {
  // Gradually roll out to more users
  await featureFlags.enable('finance.ai-forecasting', {
    percentage: 50 // 50% of all workspaces
  });
}

// Full rollout after validation
await featureFlags.enable('finance.ai-forecasting', {
  percentage: 100 // Everyone
});
```

**Blue-green deployment (conceptual snippet).** Tuturuuu's self-hosted Docker deploy does use a real blue/green release watcher (snapshot + cutover) for the web app, but it is driven by deployment scripts, not the `switchTraffic(...)` / `supabase.rpc(...)` calls shown here. Read this as the idea, not the API:

```typescript theme={null}
// Run migrations on "green" environment
// Switch traffic after validation

// 1. Green environment: Apply migration
await supabase.rpc('run_migration', {
  migration: '20241117_add_ai_forecasting'
});

// 2. Verify green environment health
const healthy = await verifyGreenEnvironment();

if (healthy) {
  // 3. Switch traffic from blue to green
  await switchTraffic('blue' -> 'green');

// 4. Monitor for issues
  setTimeout(() => {
    if (metricsLookGood()) {
      // 5. Destroy blue environment
      destroyBlueEnvironment();
    } else {
      // Rollback: Switch back to blue
      switchTraffic('green' -> 'blue');
    }
  }, 3600000); // Monitor for 1 hour
}
```

#### Clarifying Additions

**New versions introduce changes gradually instead of all at once.** Risk is minimized by limiting exposure to a small percentage of users or specific cohorts.

**Issues surface early in controlled conditions.** Problems are detected when only 10% of users are affected, allowing quick rollback before widespread impact.

**This improves deployment safety.** Teams deploy confidently knowing that issues will be caught early and can be mitigated quickly.

***

### 3. Architecture-Supported Environment Consistency

#### Architectural Choice

Infrastructure as Code (IaC) and containerization ensure that development, staging, and production environments are consistent and reproducible.

#### Impact and Justification

The classic "works on my machine" problem stems from environment inconsistencies. Code behaves differently in production than in development due to different:

* Dependencies and versions
* Environment variables and configuration
* Infrastructure and scaling behavior
* Operating systems and system libraries

**Architecture-supported environment consistency** eliminates this by:

* **Defining environments as code** that can be version-controlled
* **Using containers** to ensure identical runtime across environments
* **Automating setup** to prevent manual configuration drift
* **Validating consistency** through automated checks

**In Tuturuuu - Environment consistency:**

```typescript theme={null}
// .env.example - template for all environments
// Developers, staging, and production use same variables

NEXT_PUBLIC_SUPABASE_URL=
SUPABASE_SECRET_KEY=
TRIGGER_API_KEY=
DATABASE_URL=

// Environment-specific .env files
// .env.local (development)
// .env.staging (staging)
// .env.production (production)

// All have same structure, different values
```

**Vercel environment configuration:**

```json theme={null}
// vercel.json ensures consistency
{
  "env": {
    // Required in all environments
    "NEXT_PUBLIC_SUPABASE_URL": "@supabase-url",
    "SUPABASE_SECRET_KEY": "@supabase-service-key"
  },

"build": {
    "env": {
      // Build-time variables. The platform version is owned by Release Please
      // and read from TUTURUUU_PLATFORM_VERSION in
      // packages/utils/src/platform-release.ts — do not hard-code a literal here.
      "NEXT_PUBLIC_APP_VERSION": "$TUTURUUU_PLATFORM_VERSION"
    }
  }
}
```

**Pinned toolchain ensures runtime consistency.** The repo pins its toolchain so every environment resolves identical versions: `packageManager` is `bun@1.4.4`, and Node `engines` require `>=22`. A container image would mirror those pins:

```dockerfile theme={null}
# Illustrative Dockerfile — keep versions aligned with package.json pins
FROM oven/bun:1.4.4 as base

WORKDIR /app

# Install dependencies (frozen lockfile => same versions everywhere)
COPY package.json bun.lock ./
RUN bun install --frozen-lockfile

COPY . .
RUN bun run build

# Production image (identical across environments)
FROM oven/bun:1.4.4-slim
WORKDIR /app
COPY --from=base /app/.next ./.next
COPY --from=base /app/node_modules ./node_modules
COPY --from=base /app/package.json ./

CMD ["bun", "run", "start"]
```

**Supabase local development matches production.** Migrations are written once and applied identically; type generation keeps types in sync:

```bash theme={null}
# Start local Supabase (mirrors the production schema)
bun sb:start

# Author and apply migrations locally
bun sb:new      # scaffold a new migration
bun sb:up       # apply migrations to the local database

# Regenerate DB types after schema changes
bun sb:typegen
```

> [!WARNING]
>
> Production migrations are applied by a maintainer, not from agent/CI prose. Do **not** run `bun sb:push` / `bun sb:linkpush` from this workflow — prepare the migration and let the owner apply it.

#### Clarifying Additions

**Environments remain aligned through structured definitions.** Configuration as code prevents drift between development, staging, and production.

**Deployment steps become predictable across stages.** The same deployment process works identically in all environments, reducing deployment-specific issues.

**This reduces surprises when promoting changes.** Code that works in staging will work in production because environments are consistent.

***

## Quality Attributes Summary

The table separates what is **implemented today** from patterns presented as **teaching models / aspirational** so the mechanisms aren't read as all-adopted.

| Attribute | Implemented today | Illustrative / aspirational | Primary Benefit |
| - | - | - | - |
| **Maintainability** | App + feature-folder boundaries, shared Supabase + `@tuturuuu/types/db`, shared `packages/internal-api` / `packages/apis`, modular Next.js frontend, per-app Vercel projects | Hexagonal ports/adapters, repository interfaces, technology-swap seams | Sustainable long-term evolution |
| **Testability** | Vitest unit + colocated `*.test.ts`, Zod payload validation, Turborepo affected-package CI | Pure domain objects, in-memory test doubles, formal contract tests, event replay | High confidence in changes |
| **Deployability** | Per-app Vercel preview/deploy workflows, separate Rust `apps/backend` track, pinned toolchain (`bun@1.4.4`, Node `>=22`), Supabase migrations + typegen | Canary/blue-green orchestration scripts, custom feature-flag service | Frequent, low-risk releases |

> [!NOTE]
>
> These properties are being preserved through the `apps/web` → `apps/tanstack-web` + Rust `apps/backend` migration. See [TanStack + Rust Migration](/platform/architecture/tanstack-rust-migration).

## Related Documentation

* [Core Architectural Decisions](/platform/architecture/system-design/architectural-decisions) - Why we chose this architecture
* [Layering Patterns](/platform/architecture/system-design/layering-patterns) - N-tier vs Hexagonal/Clean architecture
* [Hexagonal Architecture](/platform/architecture/system-design/hexagonal-architecture) - Ports and adapters in detail
* [Microservices Patterns](/platform/architecture/system-design/microservices-patterns) - Service boundaries and deployment
* [Event-Driven Architecture](/platform/architecture/system-design/event-driven-architecture) - Event streaming patterns
* [Observability & Monitoring](/platform/architecture/system-design/observability-monitoring) - Testing in production

# Security Architecture
Source: https://docs.tuturuuu.com/platform/architecture/system-design/security-architecture

Comprehensive security justification and architectural security patterns in Tuturuuu

Security is a foundational architectural concern in Tuturuuu, embedded at every level of the system design. This document explains the core architectural patterns that provide comprehensive security coverage.

> [!NOTE]
>
> This document focuses on **architecture-level security patterns**. For implementation details, see:
>
> * [Authentication](/platform/architecture/authentication) - User authentication flows
> * [Authorization](/platform/architecture/authorization) - Permission system
> * [RLS Policies](/reference/database/rls-policies) - Row-level security implementation

> [!WARNING]
>
> **What is real vs. illustrative.** Tuturuuu's web tier (`apps/web`) is a conventional Next.js App Router app, not a network of independently keyed microservices. Several patterns below (a single API gateway, service-to-service token exchange, an immutable event-sourced audit log) are presented as **conceptual / target patterns** to explain the reasoning — they are explicitly labeled where they are not implemented as written. The concrete code examples (the `withApiAuth` wrapper, Supabase Row-Level Security, the Rust backend's Supabase auth) reflect the real codebase.
>
> The maintained runtime is Next.js Web and its satellite apps. Rust
> (`apps/backend`) and TanStack Start (`apps/tanstack-web`) are paused and not in
> use. Docker setup is inactive and the Docker cron runner is retired. Retained
> migration designs describe a possible future, not live traffic or a current
> setup requirement. See the [active runtime map](/build/devops/active-runtime).

## Residual dependency advisories

`@tuturuuu/ai` no longer declares `bash-tool`. Source inspection found no
static/dynamic imports, require calls, re-exports, test consumers or string-based
tool registrations in the repository. The Chat SDK dynamic loader selects from
its static adapter definitions, which contain no bash/glob packages. Removing
the unused dependency removes the AI installation edge to
`bash-tool → fast-glob → micromatch → braces`; adding an unused validator would
not protect an existing call. Customer-facing AI behavior is unchanged.

[GHSA-vfj7-8cjw-p6xm](https://github.com/advisories/GHSA-vfj7-8cjw-p6xm)
still affects `braces@3.0.3`, with no patched release at this review. After removal,
`bun why braces` resolves these remaining paths:

* Root development dependency `@lingual/i18n-check → @formatjs/cli-lib →
  fast-glob → micromatch → braces`: translation source scanning, development/CI only.
* `apps/web → @excalidraw/excalidraw → sass@1.51.0 → chokidar@3.6.0 → braces`:
  retained installation edge through a runtime-declared editor dependency, but
  Sass compilation/watch tooling rather than editor request processing.
* Next, Vite and Vite+ optional Sass peer edges converge on that same Sass/watch
  chain: development/build tooling. No first-party server-side Sass/watch or
  untrusted-pattern caller was found.

`bun audit` also reports `transactional → react-email → chokidar → braces` and
`apps → @tanstack/react-start → @tanstack/start-plugin-core →
@tanstack/router-plugin → chokidar → braces`. These are email preview and route
build tooling respectively; installed `react-email` declares Chokidar 4 and
router-plugin declares Chokidar 5, neither of which depends on braces. Treat
these audit paths as reported graph associations, not verified Chokidar 3 call
chains. Manifest dependency classification alone does not prove runtime exposure.

Infrastructure desktop certificate inspection parses PKCS#12 material and
X.509 metadata with `@blamejs/pki`; Node's `crypto` module matches private keys
to certificates and computes certificate fingerprints. PKCS#12 stores without
a MAC, or requiring more than about one million combined KDF rounds, are
refused. Password failures remain normalized to `certificate_invalid`; a parser
load failure is reported separately as `certificate_inspection_unavailable`.

#### `@blamejs/pki` supply-chain exception

The infrastructure app pins `@blamejs/pki` to exactly `0.9.7`. It is the only
maintained option found that handles legacy 3DES and RC2-40 PKCS#12 stores
without hand-rolled cryptography. This is an explicit supply-chain exception:
the package is young, has a single maintainer, and its `pkijs.com` homepage can
be confused with the separate PKI.js project at `pkijs.org`. The reviewed
release has zero dependencies and no install scripts; its registry lockfile
integrity and SLSA provenance were checked on 2026-10-24. Loading is lazy and
limited to the Node runtime, and parser load failures are logged and surfaced as
`certificate_inspection_unavailable`.

* Owner: dependencies
* Approved by the user: 2026-10-24
* Review date: 2027-01-24
* Re-vet required for any version bump

The moderate esbuild development-server advisory
([GHSA-67mh-4wv8-2f99](https://github.com/advisories/GHSA-67mh-4wv8-2f99)) came
from `apps/apps → void → drizzle-kit → @esbuild-kit/esm-loader →
@esbuild-kit/core-utils`, which pins esbuild `~0.18.20`; Drizzle Kit 0.31 no
longer loads that deprecated loader. The root `esbuild@0.18` override moves it to
`0.25.12`, and `scripts/security-dependency-compatibility.test.js` checks the
esbuild-kit TypeScript transform on the patched version.

The standalone `.opencode/package-lock.json` (OpenCode local plugin install, no
tracked manifest) resolves `toml` through `@opencode-ai/plugin → effect`, whose
unstable CLI file parser is the only `toml` caller. Regenerate that lockfile with
a temporary manifest that overrides `toml` to at least `5.0.1`
(GHSA-4qx8-w7c3-pj3p, GHSA-9j65-hcg3-gc64, GHSA-9qmh-m7c6-f92p); the
compatibility test fails if a local reinstall commits a downgrade.

Recheck with `bun why braces --depth 4` and `bun audit` after dependency changes.
Before introducing an actual bash/glob runtime consumer, validate untrusted
patterns before expansion, including length, nesting, alternatives and ranges;
cover that real boundary with regression tests.

## Calendar description parsing

Shared browser Calendar descriptions use `sanitizeHtml` to parse input inside
inert template content, then reconstruct only allowed tags, attributes and URLs.
Original input nodes are never attached or returned. This applies wherever the
shared sanitizer is called; permitted formatting and rejected-element text
fallback remain the default, with no event-source exception.

The custom-element regression in `html-sanitizer.test.ts` checks that parsing
cannot run a rejected element's constructor and includes a working positive
control. This is parser hardening, not proof of a reproduced stored-XSS exploit
or deployed browser policy. Browser resource/error-handler behavior still needs
its own contained verification.

## Plan-aware egress and abuse allowances

When `SECURITY_EGRESS_ENFORCEMENT_ENABLED=true`, live Next.js uses Postgres-backed
request and private-download budgets independently of Redis. Free/anonymous
traffic has separate shared ceilings; active paid personal subscriptions and
current paid workspace memberships provide bounded account uplifts. Team CMS
delivery uses the target workspace's subscription, while personal workspace
media inherits the owner's paid account memberships. Free/Plus/Pro/Enterprise
multipliers are 1/4/10/20, with a capped bonus for multiple paid workspaces.
Trials, unpaid/expired subscriptions and zero-cost products do not increase limits.
Paid plans do not bypass authentication, permissions, abuse challenges, or global
byte containment. Anonymous public consumers keep strict client limits. Existing
public Storage assets remain outside private relay budgets.

See [Storage egress protection](/build/devops/storage-egress-protection) for exact
base allowances, scope, cache/revocation timing, regression tests, and migration-first
activation. This behavior is implemented in live Next.js; Rust parity is pending
and protected paths must remain on Next.js before any future traffic cutover.

## 1. Consistent Security Enforcement at the API Boundary

### Architectural Choice

Rather than a literal standalone API gateway, Tuturuuu enforces security **consistently at the API route boundary** through a shared higher-order wrapper. Every public SDK route under `apps/web/src/app/api/v1/*` is wrapped with `withApiAuth`, which centralizes the security logic (API-key authentication, rate limiting, permission checks) in one tested implementation instead of re-deriving it per route.

> [!NOTE]
>
> **Conceptual vs. real.** "API gateway" describes the *pattern* — a single, uniform enforcement point — not a literal gateway process in front of microservices. In `apps/web` there is no separate gateway tier; security is enforced per route. The uniformity comes from sharing the `withApiAuth` wrapper (`apps/web/src/lib/api-middleware.ts`), Next.js `middleware.ts`, and Vercel's edge. In the [TanStack + Rust migration](/platform/architecture/tanstack-rust-migration), the Rust backend (`apps/backend`) becomes the primary boundary that validates Supabase sessions.

### Impact and Justification

By funneling authentication and authorization through one shared wrapper, we create a **single security control plane in code**: policies are defined once and applied consistently before any business logic runs. Routes do not re-implement token parsing, key validation, or rate-limiting individually, which removes the drift and duplication that cause inconsistent security postures.

**Conceptual enforcement flow (illustrative, not a literal gateway process):**

```typescript theme={null}
// The shared concerns withApiAuth applies before your handler runs:
// 1. IP-based pre-auth rate limiting (cheap flood rejection)
// 2. API-key authentication against the database
// 3. Adaptive, key- and workspace-scoped rate limiting
// 4. Declarative permission checks
// 5. Workspace-scoped data access via an admin Supabase client
```

**Real example from Tuturuuu's SDK API** (`apps/web/src/app/api/v1/storage/list/route.ts`):

```typescript theme={null}
export const GET = withApiAuth(
  async (request, { context }) => {
    // Security is already enforced by the withApiAuth wrapper:
    // - API key authenticated
    // - Rate limiting applied (IP pre-auth + key/workspace-scoped)
    // - 'manage_drive' permission verified for this workspace
    const { wsId } = context;

// Use the admin client for SDK routes (no user session cookies).
    // createDynamicAdminClient is async — await it.
    const supabase = await createDynamicAdminClient();

return supabase.storage.from('workspaces').list(wsId /* ... */);
  },
  {
    permissions: ['manage_drive'], // Declarative authorization
    // Custom limits are also supported, e.g.:
    // rateLimit: { windowMs: 60000, maxRequests: 20 }
  }
);
```

Note that `rateLimit` is optional: by default `withApiAuth` leaves `GET`/`HEAD` reads open and applies a per-key mutation limit (about 100 requests/minute), with workspace-specific overrides read from `workspace_secrets`. Pass a `rateLimit` object only to tighten or relax those defaults.

### Clarifying Additions

**Shared enforcement ensures uniform security behavior across routes.** Instead of each route implementing authentication differently, `withApiAuth` provides a single, tested implementation every endpoint benefits from.

**Policies update consistently without touching each route.** When a new requirement emerges (e.g., a stricter default rate limit), it is implemented once in the wrapper and immediately applies everywhere it is used.

**This strengthens protection by eliminating inconsistent security implementations.** Human error is reduced because developers do not re-implement the same security logic across many routes.

***

## 2. Zero Trust Principles Applied at the Architectural Level

### Architectural Choice

The architecture implements Zero Trust security principles, where no service or request is inherently trusted based on its network location or source. Every interaction, whether from external clients or between internal services, must be explicitly authenticated and authorized.

### Impact and Justification

Traditional "castle-and-moat" security assumes that anything inside the network perimeter is trusted. This is a dangerous assumption because once an attacker breaches the perimeter, they have unrestricted access to internal systems.

Zero Trust architecture **eliminates implicit trust**. Every request is re-validated for identity and permissions at the boundary it crosses, and the database independently enforces access rules regardless of which app issued the query.

> [!WARNING]
>
> **No inter-service token system exists.** Tuturuuu does **not** implement service-to-service token exchange (`generateServiceToken`, `X-Service-Id` headers, per-service token verification). The apps share a single Supabase Postgres database, and Zero Trust is realized through **(a) request authentication at each API boundary** and **(b) Row-Level Security in the database** — not a mesh of mutually authenticating services. The example below shows how the apps actually establish identity, not a fictional token broker.

**How identity is established in practice.** Every request that reaches data must carry a verifiable identity, and that identity is re-checked at the boundary:

* **User requests** carry a Supabase session (cookie or `Authorization: Bearer` access token). The Rust backend validates these in `apps/backend/src/supabase_auth.rs`, which extracts the access token from the `sb-*-auth-token` cookie (including base64-prefixed, chunked cookies) or a non-app Bearer token, then calls the Supabase Auth `/user` endpoint with the service-role key to resolve the user.
* **SDK / machine requests** carry a workspace-scoped API key, authenticated and rate-limited by `withApiAuth` in `apps/web` before any handler runs.

```rust theme={null}
// apps/backend/src/supabase_auth.rs — real backend auth (simplified)
// 1. Pull the access token from a Bearer header or the Supabase auth cookie.
// 2. Verify it against Supabase Auth's /user endpoint using the service-role key.
// 3. Only a verified user proceeds; nothing is trusted by network location.
let access_token = request_access_token(request)?;            // bearer or cookie
let user = fetch_supabase_auth_user(contact_data, &access_token, outbound).await?;
```

There is no per-service shared secret to leak: trust derives from a Supabase-issued token (validated against Supabase) or a workspace API key (validated against the database), and the database enforces the final word via RLS.

**Database-level Zero Trust (Row-Level Security):**

```sql theme={null}
-- RLS policy ensures data access is validated at database level
-- Even if application code is compromised, database enforces security

CREATE POLICY "workspace_members_select_policy"
ON workspace_members FOR SELECT
TO authenticated
USING (
  -- User can only see members of workspaces they belong to
  EXISTS (
    SELECT 1 FROM workspace_members wm
    WHERE wm.ws_id = workspace_members.ws_id
    AND wm.user_id = auth.uid()
  )
);
```

### Clarifying Additions

**Identity is established from verifiable tokens, not network location.** A request is trusted because it carries a valid Supabase session or workspace API key that is re-validated at the boundary — not because it originated inside the deployment.

**The database has the final say.** Even if an API layer were bypassed or compromised, RLS policies independently enforce that a user can only read or write rows for workspaces they belong to. Application bugs cannot silently defeat data-access rules.

**This reduces risks associated with implicit trust.** Because authorization is enforced both at the boundary and in the database, a single compromised layer does not grant unrestricted data access.

***

## 3. Security Boundaries Through RLS and Permission Scoping

### Architectural Choice

Isolation between domains (finance, AI chat, drive, tasks) is enforced primarily by **per-table Row-Level Security policies and scoped permissions**, not by giving each app its own Supabase project or key. The apps share one Supabase database; the boundary lives in the policies and in the permission set each API key or user role is granted.

> [!WARNING]
>
> **Per-app anon keys are not how this works.** Earlier revisions of this page implied distinct `WEB_ANON_KEY`, `FINANCE_ANON_KEY`, and `REWISE_ANON_KEY` values backing separate "services". That is **not accurate** — Tuturuuu's apps share a single Supabase project and the same anon/service-role keys. Domain isolation comes from RLS policies and permission scoping on shared tables, described below.

### Impact and Justification

In a single shared database, a vulnerability that bypasses one route must still defeat the per-table RLS policy to reach data. By scoping each domain's tables with **dedicated policies and permission requirements**, we contain the blast radius: a bug in a drive route cannot read finance rows, because the finance policy requires finance-specific roles and the request's identity does not satisfy them.

Concretely, SDK routes declare the permissions they need (`permissions: ['manage_drive']`), and the database enforces an orthogonal check at query time. An attacker who somehow reaches a query path is still bounded by both the granted permission scope and the row-level policy.

**Data isolation through RLS policy design:**

```sql theme={null}
-- Finance-specific tables with dedicated RLS policies
CREATE TABLE finance_transactions (
  id UUID PRIMARY KEY,
  workspace_id UUID NOT NULL,
  amount DECIMAL NOT NULL,
  -- ... other fields
);

-- RLS policy specific to finance module
CREATE POLICY "finance_transactions_policy"
ON finance_transactions
TO authenticated
USING (
  -- Only users with finance permissions in workspace
  EXISTS (
    SELECT 1 FROM workspace_members wm
    WHERE wm.ws_id = finance_transactions.workspace_id
    AND wm.user_id = auth.uid()
    AND wm.role IN ('owner', 'admin', 'finance_manager')
  )
);

-- AI chat tables completely separate
CREATE TABLE ai_chat_messages (
  id UUID PRIMARY KEY,
  workspace_id UUID NOT NULL,
  message TEXT NOT NULL,
  -- ... other fields
);

-- Different RLS policy for AI data
CREATE POLICY "ai_chat_messages_policy"
ON ai_chat_messages
TO authenticated
USING (
  EXISTS (
    SELECT 1 FROM workspace_members wm
    WHERE wm.ws_id = ai_chat_messages.workspace_id
    AND wm.user_id = auth.uid()
  )
);
```

### Clarifying Additions

**A bug in one domain's routes does not expose another domain's data.** RLS policies and permission scoping bound each domain independently, so reaching a finance table requires finance-grade identity even from an unrelated route.

**Policies act as an independent barrier alongside application checks.** Defense in depth is achieved because the database re-validates access regardless of what the application layer believed.

**This scoping limits the damage in security incidents.** Incident response is more manageable because the data an attacker could reach is bounded by the policies and permissions that gate each table.

***

## 4. Defense-in-Depth via Layered Architecture

### Architectural Choice

The architecture implements multiple layers of security controls, from the network edge through the API Gateway, into the application services, down to the database layer. Each layer provides independent security validation.

### Impact and Justification

Relying on a single security layer is fragile. If that layer is bypassed or fails, the entire system is exposed. The **defense-in-depth** approach ensures that even if an attacker successfully bypasses one security control, they encounter additional independent security barriers at deeper layers.

For example, even if an attacker bypassed the API boundary's authentication (highly unlikely but theoretically possible), they would still encounter:

1. **Route-level authorization** checks (declared permissions) in the application code
2. **Database Row-Level Security** policies that enforce data access rules
3. **Workspace scoping** that bounds every query to the caller's workspace

**In Tuturuuu - Multiple Security Layers:**

**Layer 1: Edge / Boundary Security**

```typescript theme={null}
// First line of defense — applied by withApiAuth + Next.js middleware + Vercel edge:
// - API-key / session authentication
// - IP-based and key/workspace-scoped rate limiting
// - Request validation (e.g. zod query schemas)
// Note: there is no separate gateway process; these run at the route boundary.
```

**Browser framing boundary.** Every Next.js app that uses
`createTuturuuuNextConfig` receives `Content-Security-Policy: frame-ancestors
'none'` and `X-Frame-Options: DENY` on its responses. This prevents an
attacker-controlled page from rendering Tuturuuu interfaces inside an iframe
for UI redressing. App-specific `headers()` entries are composed after the
shared security rule, so route-specific cache and indexing headers remain
intact.

The only shared exception is the CMS WebGL asset route
`/api/v1/workspaces/:wsId/external-projects/assets/:assetId/webgl/*`. The CMS
player intentionally renders that document in a sandboxed iframe without
`allow-same-origin`; the asset route keeps its own restrictive CSP sandbox
policy. New framing exceptions must be path-specific, justified by a documented
product requirement, and preserve an equivalent sandbox boundary.

**Layer 2: Application-Level Security**

```typescript theme={null}
// Second line of defense - Application logic
export async function handleFinanceRequest(request: Request) {
  const user = await getCurrentUser(); // Verify user session

// Application-level authorization
  const hasPermission = await userHasFinanceAccess(user.id, workspaceId);
  if (!hasPermission) {
    throw new ForbiddenError('No finance access');
  }

// Business logic with additional checks
  return processFinanceOperation();
}
```

**Layer 3: Database-Level Security**

```sql theme={null}
-- Third line of defense - Database RLS
CREATE POLICY "finance_access_policy"
ON finance_transactions
TO authenticated
USING (
  -- Even if application is compromised,
  -- database enforces access control
  workspace_id IN (
    SELECT ws_id FROM workspace_members
    WHERE user_id = auth.uid()
    AND role IN ('owner', 'admin', 'finance_manager')
  )
);
```

**Layer 4: Data Encryption**

```typescript theme={null}
// Fourth line of defense - Encryption at rest
// Supabase automatically encrypts data at rest
// Sensitive fields additionally encrypted in application

async function storeSensitiveData(data: SensitiveData) {
  const encrypted = await encrypt(data, ENCRYPTION_KEY);
  await database.insert({
    data: encrypted,
    // Even with database access, data is encrypted
  });
}
```

### Clarifying Additions

**Multiple layers ensure no single point of failure exposes sensitive logic.** An attacker must defeat multiple independent security controls to compromise the system, making successful attacks exponentially harder.

**Higher layers validate and protect the domain before requests reach it.** The most critical business logic (the domain core) is protected by multiple security barriers, ensuring it only processes validated, authorized requests.

**The system becomes safer by distributing security responsibility across layers.** Security is not the responsibility of a single component but is woven throughout the architecture, creating a more resilient security posture.

***

## 5. Auditability and Background Security Workflows

### Architectural Choice

Security-relevant actions should be traceable, and heavier security workflows (anomaly scans, notifications, periodic reviews) should run as durable background jobs. Tuturuuu uses **Trigger.dev v4 `task()`** for background work and native server console logs plus retained platform observability data for server-side diagnostics.

> [!WARNING]
>
> **Aspirational, not implemented as written.** A comprehensive, cryptographically signed, immutable, event-sourced audit log is a **target pattern**, not a shipped subsystem. Tuturuuu does not have an event store or event-sourcing layer, and there is no global `audit_events` table that captures every state change. Treat the audit-log code below as an illustration of the goal. What exists today: Supabase keeps row history where tables are designed for it, retained platform observability data records selected server-side events, Trigger.dev runs durable background tasks, and runtime diagnostics use the native console method matching severity.

### Impact and Justification

Security is not just about prevention; it's also about **detection and accountability**. A durable, append-only audit trail would provide:

1. **Forensic Analysis**: After an incident, history lets investigators reconstruct what happened, when, and by whom
2. **Compliance**: Regulations (GDPR, SOX, HIPAA) require audit trails of data access and modifications
3. **Anomaly Detection**: Patterns can be analyzed to detect suspicious behavior (e.g., unusual access patterns, privilege escalation)
4. **Non-Repudiation**: Append-only, tamper-evident records provide strong proof of actions

**Target audit-write pattern (aspirational — illustrates intent):**

```typescript theme={null}
// Illustrative: how a critical operation could record an audit entry.
// There is no global event store today; persist via your table's history
// mechanism and emit server-side logs through native console methods.
export async function updateWorkspaceSettings(
  workspaceId: string,
  settings: WorkspaceSettings,
  userId: string
) {
  const previousSettings = await getSettings(workspaceId);

// Apply the change.
  await updateSettings(workspaceId, settings);

// Record an audit entry (target: append-only audit table or log-drain).
  await recordAuditEntry({
    event: 'workspace.settings.updated',
    workspaceId,
    userId,
    previousSettings,
    newSettings: settings,
    occurredAt: new Date().toISOString(),
  });
}

// Security-sensitive event names worth auditing (illustrative set)
export const AUDIT_EVENTS = {
  'user.login': 'User authentication',
  'user.logout': 'User session end',
  'user.password.changed': 'Password modification',
  'user.mfa.enabled': 'MFA enabled',
  'user.mfa.disabled': 'MFA disabled',
  'workspace.member.added': 'Member added to workspace',
  'workspace.member.removed': 'Member removed from workspace',
  'workspace.role.changed': 'Member role modified',
  'finance.transaction.created': 'Financial transaction',
  'data.export.requested': 'Data export initiated',
  'api.key.created': 'API key generated',
  'api.key.revoked': 'API key revoked',
} as const;
```

**Audit Log Query Interface (target shape):**

```typescript theme={null}
// Illustrative: querying an append-only audit table once one exists.
export async function getAuditLog(filters: AuditFilters) {
  const supabase = await createDynamicAdminClient(); // async — await it
  return supabase
    .from('audit_events')
    .select('event_type, user_id, workspace_id, created_at, payload')
    .eq('workspace_id', filters.workspaceId)
    .gte('created_at', filters.startDate)
    .lte('created_at', filters.endDate)
    .in('event_type', filters.events)
    .order('created_at', { ascending: false });
}
```

**Background security workflow (real Trigger.dev v4 `task()` API):**

Trigger.dev v4 uses the `task()` builder (`@trigger.dev/sdk` `^4.4.5`). The v2 API (`client.defineJob`, `eventTrigger`, `io.*`) does **not** exist in this repo. A security-scan task looks like the calendar/schedule tasks under `packages/trigger/src`:

```typescript theme={null}
import { task } from '@trigger.dev/sdk/v3';

// A task you trigger (e.g. from an API route) when repeated auth failures
// are observed, to evaluate and respond to a possible brute-force attempt.
export const securityScanTask = task({
  id: 'security-scan',
  queue: { concurrencyLimit: 5 },
  run: async (payload: { userId: string; windowSeconds?: number }) => {
    const recentFailures = await countRecentLoginFailures(
      payload.userId,
      payload.windowSeconds ?? 300 // 5 minutes
    );

if (recentFailures > 5) {
      // Respond (e.g. temporary lock + notify) and return a structured result.
      await applyTemporaryLock(payload.userId);
      return { userId: payload.userId, action: 'account.lock.temporary' };
    }

return { userId: payload.userId, action: 'none' };
  },
});
```

Trigger it from server code with `securityScanTask.trigger({ userId })` (or `batchTrigger` for many). See the [Event-Driven Architecture](/platform/architecture/system-design/event-driven-architecture) page for how Tuturuuu actually uses Trigger.dev v4 and native server console logs.

### Clarifying Additions

**Durable background tasks keep heavy security work off the request path.** Anomaly scans and notifications run as Trigger.dev v4 tasks rather than blocking the user's request.

**An append-only audit trail would support accountability and forensics.** This is the target; today, rely on retained platform observability data, native server console logs, and table-level history for traceability.

**Compliance benefits from consistent logging.** Use the native console method matching severity and retain structured metadata where platform observability wrappers are wired.

***

## Security Architecture Summary

## Security Best Practices in Tuturuuu

### 1. Never Trust, Always Verify

* Every request validated at multiple layers
* No assumptions about request origin or authenticity
* All user input sanitized and validated

### 2. Principle of Least Privilege

* Services granted minimum permissions needed
* Users granted minimum roles required
* API keys scoped to specific operations

### 3. Fail Securely

* Default deny for authorization decisions
* Explicit permission grants required
* Errors don't leak sensitive information

### 4. Defense in Depth

* Multiple layers of security controls
* Redundant security checks
* No single point of failure

### 5. Audit Everything

* All security-relevant events logged
* Immutable audit trail
* Regular security audits and reviews

## Security Under the TanStack + Rust Migration

* **Boundary authentication** shifts into the Rust backend (`apps/backend/src/supabase_auth.rs`), which validates Supabase access tokens from cookies or Bearer headers against Supabase Auth using the service-role key.
* **TanStack web** must not call `/trpc` or raw app APIs directly (a guard, `check-tanstack-api-access`, enforces this); product data flows through `packages/internal-api` helpers and REST `/api/v1` routes.
* **RLS remains the durable backstop** across both stacks because both share the same Supabase project.

See [TanStack Start And Rust Migration](/platform/architecture/tanstack-rust-migration) for the full migration contract.

## Related Documentation

* [Authentication](/platform/architecture/authentication) - User authentication implementation
* [Authorization](/platform/architecture/authorization) - Permission system and role-based access
* [RLS Policies](/reference/database/rls-policies) - Database-level security
* [TanStack Start And Rust Migration](/platform/architecture/tanstack-rust-migration) - How the boundary moves into the Rust backend
* [Encapsulation Patterns](/platform/architecture/system-design/encapsulation-patterns) - Service boundary enforcement
* [Event-Driven Architecture](/platform/architecture/system-design/event-driven-architecture) - Trigger.dev v4 tasks and background workflows

## Authenticator and meeting coordination

Authenticator registry mutations use the `apps/coordination` Cloudflare Worker
and SQLite Durable Objects. One object per hashed user serializes changes to
server-owned Supabase app metadata. Meeting delivery uses a separate namespace
with payload fingerprints and completion records, so retries preserve their
original identity. Login approval challenges remain in Supabase; this service
never stores authenticator secrets, session tokens, email addresses, or meeting
contents. Upstash is not required for these operations.

Provision `COORDINATION_TOKEN` as a Worker secret. Store its value in the
Infrastructure root-workspace secret `cloudflare_coordination:v1` as an
envelope (`version`, `encryptedDataKey`, `encryptedSecret`) using the existing
mobile deployment encryption helpers, then provision the same value as the server-only
`CLOUDFLARE_COORDINATION_TOKEN` in the web, Calendar, and Infrastructure deployment environments.
Set `CLOUDFLARE_COORDINATION_URL` to the deployed Worker's HTTPS origin. Never
expose these credentials in Flutter defines, public environment variables, URLs,
or logs. Missing credentials and network failures fail closed. Deploy the Worker
and verify its authenticated endpoint before enabling the server callers.

Registry leases expire after five minutes. Meeting leases expire after ten
minutes, while request fingerprints and completion records remain for at least two hours
and never expire before an active lease.
An expired owner cannot complete or release a newer owner's operation. The
calling service must still enforce request age and provider idempotency: a lease
alone cannot prevent an external provider request from finishing after a timeout.
Alarms clean up expired state. Arbitrary payloads and unbounded TTLs are rejected.

Validate changes with:

```sh theme={null}
bun run --cwd apps/coordination type-check
node --test apps/coordination/src/worker.test.mjs
# CI checks the emitted Build Output after its build.
node scripts/ci/cf-worker-parity.mjs apps/coordination scripts/ci/fixtures/cf-worker-parity/coordination.json
```

`type-check` runs the pinned `cf workers types` before TypeScript; its generated
bindings are in `apps/coordination/.cloudflare/types/index.d.ts`. The source
runtime test uses the cf/Vite harness with disposable secret fixtures. Run local
checks through the shared resource queue. Builds and emitted-artifact checks run
in CI; use `bun run --cwd apps/coordination dev` for normal local development.

The [cf publication runbook](/build/development-tools/cf-cli-wrangler-parity)
records the retained Durable Object publication gap. Production keeps its applied
`v1` migration history until a separate disposable data-retention rehearsal clears
the publisher transition.

The Coordination Cloudflare workflow runs these checks and deploys only the
production branch. Pre-provision `COORDINATION_TOKEN` on the Worker and configure
`COORDINATION_CLOUDFLARE_API_TOKEN` in the GitHub `coordination-production`
environment (the existing account deployment credential is a bootstrap fallback).
Inspect secret names only during deployment checks. A successful `/health`
response proves routing; also verify an authenticated acquire/check/release cycle
and rejection of unauthenticated requests before declaring coordination ready.

## Internal account recovery

Infrastructure's internal account directory and mobile Settings → Internal
accounts share the same authorized API. Native requests use their Supabase Bearer
session; an explicit invalid credential never falls back to another browser
session. Operators need a currently confirmed `@tuturuuu.com` account, enabled
access, and `manage_internal_accounts` in the root workspace.

Profile, access, password, and authenticator actions apply only to exact internal
email accounts. Sensitive actions require typing the target email and cannot
reset the operator's own access or credentials. The mobile directory remains in
memory only; password input is never cached or logged.

Authenticator reset clears server-owned trusted-device proofs before deleting
Supabase MFA factors. It shares the Cloudflare authenticator lease with device
registration and fails closed if coordination is unavailable. A partial provider
failure returns an error; retry the reset to finish removing remaining factors.
The action preserves an existing account ban. Factor enrollment still requires
the account holder to prove possession; administrators cannot silently enroll an
authenticator for someone else. Resetting factors is a recovery operation, not a
policy that requires MFA for subsequent sign-ins.

Before releasing these controls, verify Infrastructure has the same server-only
coordination credentials as web and test both authorized and denied native
requests. Never distribute those credentials in mobile configuration.

# TanStack Start And Rust Migration
Source: https://docs.tuturuuu.com/platform/architecture/tanstack-rust-migration

Migration contract for replacing apps/web with apps/tanstack-web plus the Rust backend

> [!WARNING]
>
> Retained inactive reference. Docker setup, Rust, and TanStack Start are paused
> and not in use. The Docker cron runner is retired. Do not execute the retained
> build, test, migration, deployment, or dependency-update procedures until
> explicitly resumed. Docker-backed E2E jobs are also paused. Use the
> [active runtime map](/build/devops/active-runtime) for current operations.

`apps/tanstack-web` is the replacement frontend for the legacy Next.js
`apps/web` runtime. It uses TanStack Start, TanStack Router, TanStack Query,
Vite, React 19, Tailwind 4, and the existing Tuturuuu shared packages.

`apps/backend` is the planned Rust API runtime. Do not create another backend
service for this migration; extend `apps/backend` route groups and keep API
contracts documented in `apps/backend/api/openapi.yaml`.

> [!WARNING]
>
> Active development of `apps/tanstack-web` and `apps/backend` is paused. Their
> combined `rust-backend.yml` CI/Cloudflare workflow, route-manifest CI, and
> automatic TanStack Vercel production builds are disabled in `tuturuuu.ci.ts`.
> Direct TanStack preview/production dispatches also skip their build jobs.
> Shared type-check, unit-test, coverage, and Biome workflows exclude both
> migration source trees; Docker CI skips the TanStack/Rust image and dual-stack
> steps; and maintained Next.js E2E disables the Rust support service while the
> migration matrix remains skipped. `apps/backend` is not deployed and receives
> no production traffic; `apps/web` remains the live API runtime. A route marked
> `migrated` below records implemented source work, not a production cutover or
> a currently maintained migration target.

The pause is enforced by
`node --test scripts/ci/paused-migration-workflows.test.js`. Resume migration CI
only as an intentional policy change: re-enable the switchboard entries and
direct deploy jobs, restore the shared-workflow package/source coverage and
Docker/E2E runtime services together, then update this warning and its guard
test in the same pull request.

The crate can run as a native container and keeps a Cloudflare Workers Rust
entrypoint in `apps/backend/wrangler.jsonc` for future, explicitly approved
preview deployment.

For exact local run commands and deployment steps across native local, Docker,
Cloudflare Workers, Vercel, and VPS/Cloudflare Tunnel paths, use
[TanStack/Rust Local And Deployment](/build/devops/tanstack-rust-local-deploy).

## Runtime Shape

Use `bun dev:tanstack-web` for local TanStack work. Docker dev also exposes the
`tanstack-web` service on port `7824` and injects `BACKEND_PUBLIC_ORIGIN`,
`BACKEND_INTERNAL_URL`, and `BACKEND_INTERNAL_TOKEN` for Rust backend calls.
Cloudflare preview uses the `BACKEND` service binding first and keeps
`BACKEND_INTERNAL_URL` as an HTTP fallback for local, Docker, and emergency
non-binding runs.

## Rendering And Cache Policy

Every migrated TanStack route must declare its rendering/cache class before it
is marked terminal in `route-overrides.json`:

| Class | Use for | Required implementation |
| - | - | - |
| Static prerender | Public routes whose HTML is fully local/static at build time. | Add the localized path to the `pages` and `prerender` options in `apps/tanstack-web/vite.config.ts`; keep `crawlLinks: true` plus the static-route filter enabled. |
| ISR-style CDN revalidation | Public routes backed by slow-changing Rust/backend data, such as models and changelog. | Add route-level `headers()` with `Cache-Control` `s-maxage` plus `stale-while-revalidate`; add `CDN-Cache-Control` for Cloudflare. |
| Dynamic no-store | Authenticated, workspace-scoped, session-specific, or secret-backed routes. | Do not prerender; use server functions/internal API calls with forwarded auth and no shared-cache headers. |
| Redirect/static compatibility | Redirect-only compatibility routes such as QR and docs handoffs. | Keep redirect behavior exact; only cache when the target contract is public and invariant. |

This follows TanStack Start's current guidance: prerender public paths through
the Start Vite plugin, use standard HTTP cache headers for ISR-style pages, and
prefer CDN headers such as `CDN-Cache-Control` for Cloudflare-specific shared
cache control. Official references:
[Static Prerendering](https://tanstack.com/start/latest/docs/framework/react/guide/static-prerendering)
and
[Incremental Static Regeneration](https://tanstack.com/start/latest/docs/framework/react/guide/isr).

The initial prerender set intentionally includes only public, unauthenticated,
non-backend-backed pages. Backend-backed public pages are not prerendered at
build time because Docker, CI, and Cloudflare builds must not require a live
Rust backend just to emit static HTML. Instead, those pages use conservative
ISR-style CDN headers from `apps/tanstack-web/src/lib/platform/cache.ts`.

## Cloudflare Preview Deployment

Cloudflare preview deployments are supported before cutover so the team can
validate the Worker runtime, smoke endpoints, and benchmark numbers without
moving production traffic. The preview path uses:

* `apps/backend/wrangler.jsonc` for the Rust Worker bundle.
* `apps/tanstack-web/wrangler.jsonc` for the TanStack Start Worker.
* `@cloudflare/vite-plugin` in `apps/tanstack-web/vite.config.ts`, registered
  before `tanstackStart()`.
* root `wrangler` tooling plus `bun check:cloudflare` to validate both Worker
  configs without contacting Cloudflare.

Validate the checked Cloudflare contract locally:

```bash theme={null}
bun check:cloudflare
```

Current compatibility contract:

`apps/tanstack-web` deployment runs `bun run build` internally through the
app-local `deploy:cloudflare` script. Do not run it during docs-only or
inspection work unless the task explicitly allows build commands. For a
configuration-only preflight, use `bun check:cloudflare`.

Both Wrangler configs declare required secret names with the schema-supported
`secrets.required` property. The validator requires these names and rejects
secret-looking values under `vars`:

| Worker | Required preview secrets |
| - | - |
| `apps/backend/wrangler.jsonc` | `BACKEND_INTERNAL_TOKEN`, `TUTURUUU_APP_COORDINATION_SECRET`, `SUPABASE_URL`, `SUPABASE_SERVICE_ROLE_KEY`, `CRON_SECRET`, `DISCORD_APP_DEPLOYMENT_URL`, `AURORA_EXTERNAL_URL`, `AURORA_EXTERNAL_WSID` |
| `apps/tanstack-web/wrangler.jsonc` | `BACKEND_PUBLIC_ORIGIN`, `BACKEND_INTERNAL_TOKEN`; `BACKEND` service binding to `tuturuuu-backend` |

For local Worker previews, put secret values next to the owning Wrangler config
in ignored files:

* `apps/backend/.dev.vars`
* `apps/tanstack-web/.dev.vars`

Do not commit `.dev.vars*` or `.env.preview*` files. `bun check:cloudflare`
validates the ignore rules so preview tokens and account-specific Worker
origins do not enter Git.

The backend Worker uses `BACKEND_ENV=preview` in `wrangler.jsonc`. Do not set
Cloudflare preview traffic to `development`; development-only migration routes
remain limited to local development and the explicit local E2E bypass.

Use `wrangler secret put` for initial preview bootstrapping only: Cloudflare
creates and deploys a new active Worker version when that command changes a
secret. For rotations, canaries, or any deployed Worker that already receives
traffic, use `wrangler versions secret put`, then promote the resulting version
with `wrangler versions deploy`.

Deploy the Rust backend Worker first:

```bash theme={null}
rustup target add wasm32-unknown-unknown
cargo install worker-build --locked
bun wrangler secret put BACKEND_INTERNAL_TOKEN --config apps/backend/wrangler.jsonc
bun wrangler secret put TUTURUUU_APP_COORDINATION_SECRET --config apps/backend/wrangler.jsonc
bun wrangler secret put SUPABASE_URL --config apps/backend/wrangler.jsonc
bun wrangler secret put SUPABASE_SERVICE_ROLE_KEY --config apps/backend/wrangler.jsonc
bun wrangler secret put CRON_SECRET --config apps/backend/wrangler.jsonc
bun wrangler secret put DISCORD_APP_DEPLOYMENT_URL --config apps/backend/wrangler.jsonc
bun wrangler secret put AURORA_EXTERNAL_URL --config apps/backend/wrangler.jsonc
bun wrangler secret put AURORA_EXTERNAL_WSID --config apps/backend/wrangler.jsonc
bun wrangler deploy --config apps/backend/wrangler.jsonc
```

`BACKEND_INTERNAL_TOKEN` is required before backend preview deploys are useful:
`/readyz` reports not-ready when the token is missing.
`TUTURUUU_APP_COORDINATION_SECRET` is required before contact/profile preview
routes can verify Tuturuuu `ttr_app_` app-session tokens in production-like
Cloudflare environments. `CRON_SECRET` and `DISCORD_APP_DEPLOYMENT_URL` are
required before the Rust-owned Discord cron proxy routes can call the Discord
app. `AURORA_EXTERNAL_URL` is required before the Rust-owned Aurora health and
ingest routes can call the Aurora service, and `AURORA_EXTERNAL_WSID` is
required before Aurora ingest routes can write rows. Wrangler prompts for
values; do not place those values in `wrangler.jsonc`, `vars`, docs, or shell
history.

`SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY` are required backend Worker
secrets for the Rust-owned contact/profile APIs. They stay server-only: the
backend reads `users` and `user_private_details`, updates profile fields, and
inserts `support_inquiries` through Supabase REST with the service-role key.
`GET /api/migration/status` exposes only redacted readiness state and the
Supabase origin, never the credential.

Smoke-test the returned `workers.dev` URL before pointing the frontend at it:

```bash theme={null}
curl -fsS https://<backend-worker-origin>/healthz
curl -fsS https://<backend-worker-origin>/readyz
curl -fsS \
  -H "Authorization: Bearer ${BACKEND_INTERNAL_TOKEN:?set BACKEND_INTERNAL_TOKEN}" \
  https://<backend-worker-origin>/api/migration/status
```

Then configure the TanStack Worker. `apps/tanstack-web/wrangler.jsonc`
declares a `BACKEND` service binding to `tuturuuu-backend`, so the backend
Worker must be deployed first. Store only the browser-safe public backend
origin and the shared internal token as Cloudflare secrets for preview runs:

```bash theme={null}
bun wrangler secret put BACKEND_PUBLIC_ORIGIN --config apps/tanstack-web/wrangler.jsonc
bun wrangler secret put BACKEND_INTERNAL_TOKEN --config apps/tanstack-web/wrangler.jsonc
```

For gradual/canary secret rotation after the first preview deploy, use the
versions command family instead:

```bash theme={null}
bun wrangler versions secret put BACKEND_INTERNAL_TOKEN --config apps/backend/wrangler.jsonc
bun wrangler versions secret put TUTURUUU_APP_COORDINATION_SECRET --config apps/backend/wrangler.jsonc
bun wrangler versions secret put SUPABASE_URL --config apps/backend/wrangler.jsonc
bun wrangler versions secret put SUPABASE_SERVICE_ROLE_KEY --config apps/backend/wrangler.jsonc
bun wrangler versions secret put CRON_SECRET --config apps/backend/wrangler.jsonc
bun wrangler versions secret put DISCORD_APP_DEPLOYMENT_URL --config apps/backend/wrangler.jsonc
bun wrangler versions secret put AURORA_EXTERNAL_URL --config apps/backend/wrangler.jsonc
bun wrangler versions secret put AURORA_EXTERNAL_WSID --config apps/backend/wrangler.jsonc
bun wrangler versions deploy --config apps/backend/wrangler.jsonc

bun wrangler versions secret put BACKEND_PUBLIC_ORIGIN --config apps/tanstack-web/wrangler.jsonc
bun wrangler versions secret put BACKEND_INTERNAL_TOKEN --config apps/tanstack-web/wrangler.jsonc
bun wrangler versions deploy --config apps/tanstack-web/wrangler.jsonc
```

`BACKEND_PUBLIC_ORIGIN` should initially be the backend Worker origin, for
example the `https://<backend-worker>.<subdomain>.workers.dev` URL returned by
the backend deploy. It remains the browser-safe origin used for public probes
and non-protected traffic. Start server functions prefer the `BACKEND` service
binding for Worker-to-Worker backend calls and fall back to
`BACKEND_INTERNAL_URL` only outside Cloudflare or when the binding is absent.
Use `BACKEND_INTERNAL_URL` in local Docker, local Node preview, or emergency
HTTP fallback runs; do not make it a required TanStack Worker secret while the
service binding is declared. The TanStack Worker still needs the same
`BACKEND_INTERNAL_TOKEN` value so Start server functions can call protected Rust
migration inventory endpoints. Local `wrangler dev` can omit origin bindings
because `packages/internal-api` falls back to `http://localhost:7820`; local
migration dashboard calls will fall back to the checked manifest when the
backend token is not configured.

Deploy the TanStack Start Worker after the backend origin secrets are present:

```bash theme={null}
bun --cwd apps/tanstack-web run cf-typegen
bun --cwd apps/tanstack-web run deploy:cloudflare
```

For a local Worker-shape smoke before deployment, use Wrangler preview servers
in separate terminals and then point the smoke command at those origins:

```bash theme={null}
bun wrangler dev --config apps/backend/wrangler.jsonc
bun --cwd apps/tanstack-web run preview:cloudflare
```

The checked Wrangler configs reserve distinct local preview ports so both
Workers can run at the same time: `http://localhost:8780` for the Rust backend
and `http://localhost:8784` for TanStack Start. Keep those ports stable because
`bun check:cloudflare` validates them and the smoke examples below assume them.

Set the same env variable names that the deployed Workers use. Keep values in
the shell, local ignored env files, or Wrangler secret storage only:
`BACKEND_INTERNAL_TOKEN` and `BACKEND_PUBLIC_ORIGIN`. When the TanStack local
Worker cannot use the `BACKEND` service binding, set `BACKEND_INTERNAL_URL` to
the local backend Wrangler origin as an HTTP fallback.

Then run the preview smoke command against the returned Worker origins:

```bash theme={null}
BACKEND_INTERNAL_TOKEN="${BACKEND_INTERNAL_TOKEN:?set BACKEND_INTERNAL_TOKEN}" \
BACKEND_WORKER_ORIGIN=http://localhost:8780 \
TANSTACK_WEB_WORKER_ORIGIN=http://localhost:8784 \
bun smoke:cloudflare \
  --output tmp/benchmarks/web-migration/<timestamp>/cloudflare-smoke.json
```

For deployed previews, replace those local origins with the `workers.dev` or
custom preview origins returned by Wrangler. Set `BACKEND_INTERNAL_TOKEN` in the
shell before running the smoke command. The smoke command probes `/healthz`,
`/readyz`, authenticated `/api/migration/status`, missing/invalid-token
rejection for the protected migration status endpoint, and the TanStack root
shell. It fails on unexpected `4xx` and `5xx` responses, requires the TanStack
root shell to show `Backend reachable`, and redacts the bearer token from
output. That final check proves the deployed Start server function can reach
the Rust Worker through the service binding or configured HTTP fallback and
token, not just that the static shell rendered. Use `--output` to persist the
smoke report under
ignored `tmp/benchmarks/web-migration/<timestamp>/cloudflare-smoke.json` when
the run is part of a cutover rehearsal.
For deployed E2E smoke runs, set `TANSTACK_EXPECT_BACKEND_REACHABLE=1` and
`TANSTACK_EXPECT_BACKEND_TARGET=cloudflare-workers` so the migration shell must
prove the frontend can reach the Rust Worker.

For a non-terminal Cloudflare preview gate, attach that smoke report while
explicitly allowing the still-legacy route inventory:

```bash theme={null}
bun migration:tanstack:gates -- \
  --allow-legacy \
  --skip-benchmark \
  --skip-e2e \
  --cloudflare-smoke-report tmp/benchmarks/web-migration/<timestamp>/cloudflare-smoke.json
```

This command is only preview evidence. It proves the current Workers can talk
to each other, but it does not satisfy the final route parity, Docker E2E, or
benchmark cutover gates.

This is still a preview/canary path. Keep `apps/web` as the production source of
truth until the manifest, Docker E2E, benchmark, and cutover gates below pass.
Do not map production hostnames to the preview Worker while `workers_dev`
canary traffic and route parity are still in progress.

Rollback is currently DNS/routing only: remove or roll back any Cloudflare route
or custom-domain mapping that sends traffic to the preview Worker, and leave the
Docker blue/green `apps/web` production stack serving the canonical host. Do
not delete Wrangler secrets during rollback unless the secret itself is
compromised; keeping them bound makes redeploying the previous Worker version or
re-running smoke checks deterministic. Inspect and roll back preview Worker
deployments with Wrangler:

```bash theme={null}
bun wrangler deployments list --config apps/backend/wrangler.jsonc
bun wrangler deployments status --config apps/backend/wrangler.jsonc
bun wrangler rollback <VERSION_ID> --config apps/backend/wrangler.jsonc

bun wrangler deployments list --config apps/tanstack-web/wrangler.jsonc
bun wrangler deployments status --config apps/tanstack-web/wrangler.jsonc
bun wrangler rollback <VERSION_ID> --config apps/tanstack-web/wrangler.jsonc
```

Worker rollback does not revert external resources, bindings, routes, custom
domains, or secret values. If a preview deploy regresses, roll back the Worker
version or remove the preview route, then run `bun smoke:cloudflare` against the
remaining preview origins before resuming canary traffic.

Protected TanStack-to-backend traffic now has a Cloudflare service binding from
the TanStack Worker to the backend Worker: binding name `BACKEND`, service
`tuturuuu-backend`. The shared backend client prefers that binding in
server-only TanStack code and keeps `BACKEND_INTERNAL_URL` as a non-Cloudflare
HTTP fallback. Protected workspace and admin APIs still must not move to
production Worker traffic until each route has backend tests, OpenAPI coverage,
an internal-api facade, and migration gate evidence. Browser code must never
receive service tokens, and server-owned protected data must stay behind
server-owned calls.

Current Cloudflare limitations:

* Runtime service binding smoke is pending. The config and internal client use
  the `BACKEND` binding, but deployed smoke still needs to prove the binding
  path in Cloudflare preview before production host routing.
* Production host routing is pending full route manifest completion, Docker
  compare-mode E2E evidence, benchmark evidence, and
  `bun migration:tanstack:gates`.
* Preview Workers should not become the owner for private workspace/admin APIs
  until each route has backend tests, OpenAPI coverage, an internal-api facade,
  and migration gate evidence.

## Route Ownership Manifest

The current migration manifest is checked in at
`apps/tanstack-web/migration/route-manifest.json`. It records the current
`apps/web/src/app` route inventory, intended target owner for each route, and a
progress summary grouped by target owner and route kind. API and route-handler
entries also include a `methods` array derived from exported Next route methods;
`summary.methodCounts` tracks total exported `GET`, `POST`, `PUT`, `PATCH`,
`DELETE`, `HEAD`, and `OPTIONS` handlers. When only some methods on a legacy
`route.ts` are migrated, `route-overrides.json` can split that file into
method-level artifacts with `parentId` and `method`; the unmigrated paired
methods stay visible as `legacy-next`.

### Rust GET-handler migration wave

The backend port proceeds GET-first: a route's read path moves to a Rust handler
in `apps/backend/src/<module>.rs` while its mutation methods stay on the live
Next.js route. The Rust handler matches the legacy mount path exactly and returns
`None` (never `405`) for every method it does not own, so the worker falls through
to Next.js for `POST`/`PUT`/`PATCH`/`DELETE`. Because the route is still the source
of truth for writes, it correctly stays `legacy-next` in the manifest until the
remaining methods are ported and a cutover decision is recorded — GET-only ports
do not flip ownership status, so they add no manifest debt.

As of this wave the curated non-special fresh-GET surface is migrated: \~235 GET
routes now have Rust handlers. The only deliberately-skipped GET routes are
`/api/v1/workspaces/:wsId/mind/boards/:boardId` and
`/api/v1/workspaces/:wsId/whiteboards/:boardId`, whose CRDT/Yjs binary state lives
in a store the worker cannot reach; they stay on Next.js. Still pending as
separate phases: mutation methods for the GET-migrated routes, and special-auth
GET routes (`/api/cron/*` `CRON_SECRET`, `/api/trpc`, `/:locale` pages, OAuth
callbacks, and Hive routes backed by `HIVE_DATABASE_URL`).

Each batch is verified with `bun check:backend` (mirrors the CI Rust gate: `cargo
fmt --check`, `cargo clippy --locked --all-targets --features native -- -D
warnings`, `cargo test --locked`, and the `wasm32-unknown-unknown` worker check)
plus a runtime dual coverage probe that asserts every migrated `GET` is served by
the dispatcher (COVER) and every un-ported method still falls through (FRESH).

### Worker-incompatible routes (native-backend or Next.js only)

Some legacy routes cannot run on the **Cloudflare Worker** build of
`apps/backend` because the wasm sandbox has no arbitrary sockets, no filesystem,
and no Redis/Postgres drivers. They split into three buckets:

* **Native-backend portable (deferred, needs secrets wired):** the scheduler
  `/api/cron/*` jobs that just "call an external API + write Supabase" —
  `finance/exchange-rates`, `inventory/polar-product-sync`, `payment/{orders,products,subscriptions}`,
  `ai/sync-models`, `tasks/generate-embeddings`, `calendar/{provider-sync,smart-schedule}`,
  `process-{post-email-queue,topic-announcement-queue,notification-batches}`, and
  `hive/simulate`. These ARE portable to the **native Rust container** target
  (`--features native`, which can do outbound HTTP and reach external DBs) once
  each job's provider secret/connection is added to `BackendConfig` +
  `wrangler.jsonc` secrets. They are not portable to the wasm Worker build. Until
  the secrets are wired they stay on Next.js (`Bearer CRON_SECRET`).
* **Host/infra-coupled (stay where the runner lives):** the cron-runner
  *monitoring* surface — `monitoring/cron/{control,run,runner-recovery,executions}`,
  plus `cron/infrastructure/{docker-recovery-alerts,sample-resources}` — reads a
  filesystem archive / controls the deployment host (Docker control), and
  `cron/infrastructure/sync-trust-cache` needs Redis. These belong with whatever
  orchestrates the runner, not a stateless handler.
* **Transport that can't be a single handler:** `/api/trpc/[trpc]` is a catch-all
  that dispatches the entire tRPC procedure router (`appRouter`). The transport
  stays on Next.js; its data access migrates incrementally as individual
  procedures move behind `packages/internal-api` / the Rust backend.

Record the chosen disposition for each in
`apps/tanstack-web/migration/route-overrides.json` with an evidence note rather
than leaving them as untriaged `legacy-next` backlog.

Current inventory:

* `156` pages
* `68` layouts
* `643` route handler artifacts
* `10` cron handlers
* `871` total tracked route artifacts
* `216` migrated artifacts, `230` terminal artifacts, and `641` remaining
  legacy-owned artifacts in the checked manifest

Regenerate it after adding or removing legacy routes:

```bash theme={null}
bun migration:tanstack:manifest
```

Regenerate the TanStack Router route tree after adding or removing
`apps/tanstack-web/src/routes/**` files:

```bash theme={null}
bun migration:tanstack:routes
```

This command preserves the TanStack Start `Register` augmentation footer that
`bun check:cloudflare` validates for the Cloudflare-compatible Start runtime,
then formats the generated `routeTree.gen.ts` with the generator's isolated
Biome config so repeated route-tree generation does not leave persistent dirty
output. The Rust/TanStack Cloudflare workflow runs
`scripts/generate-tanstack-route-tree.test.js` whenever the generator changes.

Route ownership status is preserved through
`apps/tanstack-web/migration/route-overrides.json`. Add an override with a
non-empty evidence note when a route becomes `migrated` or receives an accepted
removal decision; do not edit the generated manifest by hand.

Check that the manifest still matches the legacy route tree while migration is
in progress:

```bash theme={null}
bun migration:tanstack:check
```

Cutover mode is intentionally stricter. It fails while any route remains marked
as `legacy-next`:

```bash theme={null}
bun migration:tanstack:cutover-check
```

The full cutover gate also requires explicit Docker E2E, benchmark, and
Cloudflare smoke evidence:

```bash theme={null}
bun migration:tanstack:gates -- \
  --e2e-report tmp/e2e/web-migration/compare-report.json \
  --benchmark-report tmp/benchmarks/web-migration/<timestamp>/report.json \
  --cloudflare-smoke-report tmp/benchmarks/web-migration/<timestamp>/cloudflare-smoke.json \
  --output tmp/benchmarks/web-migration/<timestamp>/cutover-gates.json
```

This command validates route parity, terminal migration statuses, backend-owned
route mapping, compare-mode Docker E2E evidence, and a full compare benchmark
report without committing generated artifacts. The output JSON is the
review/handoff artifact for cutover sign-off and stays under ignored `tmp/`
paths with the source reports. The benchmark report must be created with
`--setup compare --profile full` and include every required metric comparison;
smoke reports alone are useful for previews but are not sufficient cutover
evidence. The Cloudflare smoke report must come from
`bun smoke:cloudflare` against distinct live Rust backend and TanStack Worker
origins, and the cutover gate verifies that each required probe URL matches
that provenance.

The manifest also includes `progress.byOwner`, `progress.byKind`, and
`progress.topLegacyRoutes`. Use those fields when splitting the remaining port
work across frontend and backend owners. Use each route's `methods` list when
checking API parity so a `GET` port does not accidentally hide an unmigrated
`POST`, `OPTIONS`, or mutation handler on the same route artifact. The Rust
backend exposes the same derived progress at:

```text theme={null}
GET /api/migration/progress
```

`apps/tanstack-web` reads that endpoint through `packages/internal-api` and
falls back to the checked manifest when the backend is offline.

Method-level migration ownership is only valid when the deployment path can
route traffic by HTTP method or otherwise avoid sending still-legacy methods to
Rust. For example, the Rust backend can own `OPTIONS` preflight responses for an
auth route while the corresponding `POST` or `GET` artifact remains
`legacy-next`; a path-only proxy must keep that whole path on Next until the
auth method is migrated too.

First migrated ownership:

| Legacy route | New owner | Evidence |
| - | - | - |
| `GET /.well-known/*` / `HEAD /.well-known/*` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route handler `migrated`; Rust returns a cacheable empty `404` with `Cache-Control: public, max-age=300, must-revalidate`. |
| `GET /~recover-browser-state` / `POST /~recover-browser-state` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route handler `migrated`; Rust returns the no-store reset HTML, enforces same-origin POST confirmation, emits `Clear-Site-Data`, clears Supabase auth cookies, and redirects to `/login?browserStateReset=1`. |
| `GET /serwist/:path` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route handler `migrated`; Rust serves a no-store decommissioning worker at `/serwist/sw.js` that unregisters stale Next/Serwist service workers during Cloudflare cutover and returns deterministic source-map metadata at `/serwist/sw.js.map`. This is cutover ownership, not offline-cache feature parity. |
| `GET /api/health` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; `GET /api/health` returns the legacy ok status JSON with `Cache-Control: no-store` and JSON security headers. |
| `GET /api/time-tracking/export` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates the browser Supabase session or non-app-session Bearer token, requires a `@tuturuuu.com` root user and the root workspace, verifies workspace membership, preserves legacy query parsing and the 1000-row limit cap, forwards `get_grouped_sessions_paginated` through the caller Supabase token, and returns the legacy data/pagination envelope with an empty-result fallback when RPC and JS-style recovery cannot produce rows. |
| `GET /api/auth/me` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates the Supabase browser session cookie or non-app-session Bearer token with Supabase Auth, returns the raw legacy user payload, keeps no-store headers, and preserves the legacy Unauthorized message response for missing or invalid sessions. |
| `GET /api/auth/mfa/totp/assurance-level` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates the Supabase browser session cookie or non-app-session Bearer token with Supabase Auth, derives `currentLevel` from the JWT `aal` claim, derives `nextLevel` from verified Supabase Auth factors on the revalidated user JSON, returns `currentAuthenticationMethods` from the JWT `amr` claim, and keeps the legacy no-store/error response shape. |
| `GET` / `POST` `/api/auth/mfa/totp/factors` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates the Supabase browser session cookie or non-app-session Bearer token with Supabase Auth, mirrors Auth JS `listFactors()` from the revalidated user JSON, enrolls TOTP factors through Supabase Auth REST, normalizes TOTP QR codes, and preserves the legacy no-store/error response shape. |
| `GET` / `DELETE` `/api/auth/mfa/totp/factors/:factorId` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates the Supabase browser session cookie or non-app-session Bearer token with Supabase Auth, resolves factor detail from the verified TOTP subset returned by Auth JS-compatible `listFactors()`, unenrolls factors through Supabase Auth REST, and preserves the legacy `Factor not found` and success-wrapper responses. |
| `GET /api/:wsId/crawlers/domains` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves the legacy no-auth, workspace-agnostic behavior, reads `crawled_urls` and non-skipped `crawled_url_next_urls` through the server-owned Supabase REST adapter, extracts valid URL hostnames, deduplicates them, and returns the sorted domain list with `cached: false`. |
| `GET /api/:wsId/crawlers/list` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates the browser Supabase session, requires a `@tuturuuu.com` user email before server-owned admin reads, preserves the legacy raw `crawled_urls` row payload, domain/search filters, `created_at.desc` ordering, exact-count pagination, and data/count response shape. Unauthorized callers now receive an explicit `401` instead of the legacy catch-all `500`. |
| `GET /api/:wsId/crawlers/uncrawled` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves the legacy no-auth, workspace-agnostic behavior, reads non-skipped `crawled_url_next_urls`, applies legacy URL filters and pagination, removes URLs already present in `crawled_urls`, groups the remaining rows by `origin_id`, and returns the legacy `uncrawledUrls`, `groupedUrls`, and `pagination` payload. |
| `GET /api/v1/workspaces/:wsId/crawlers/status` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves the legacy workspace-agnostic URL status lookup, validates the required `url` query parameter, reads the exact `crawled_urls.url` row through the server-owned Supabase REST adapter, and returns raw `crawledUrl` plus raw `crawled_url_next_urls` rows ordered by `created_at.desc`; missing crawled URLs still return `crawledUrl: null` and `relatedUrls: []`. |
| `GET /api/v1/calendar/mock` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust returns the deterministic legacy mock calendar event payload with JSON security headers. |
| `GET /api/v1/devboxes/cache` and `POST /api/v1/devboxes/cache/prune` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks both devbox cache routes `migrated`; Rust accepts CLI app-session Bearer tokens for the platform target with `cli:access` or browser/non-app-session Supabase credentials, requires root workspace `MEMBER` access, preserves the legacy empty caches list body, and returns the legacy prune acknowledgement without private devbox table mutations. Other devbox mutation routes remain legacy-owned. |
| `GET /api/admin/tasks/embeddings/stats` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the admin statistics route `migrated`; Rust validates the browser Supabase auth cookie with Supabase Auth, requires a `tuturuuu.com` or `xwf.tuturuuu.com` user email, reads exact system-wide task counts through the server-owned Supabase REST adapter, and returns only the derived legacy embedding coverage payload. The SSE embedding generation route remains legacy-owned. |
| `GET /api/v1/ai/whitelist/me` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves the legacy app-session-first auth behavior for satellite app-session targets, falls back to browser Supabase auth cookies only when no app-session token is present, reads only the `enabled` flag for the authenticated email from `private.ai_whitelisted_emails`, and returns the derived legacy email/enabled payload. |
| `GET` / `POST` `/api/v1/infrastructure/ai/whitelist/domains` and `/emails`; `PUT` / `DELETE` `/api/v1/infrastructure/ai/whitelist/:email` / `/domain/:domain` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the list/create collection methods plus detail `PUT` and `DELETE` method artifacts `migrated`; Rust revalidates the normal Supabase browser session or non-app-session Bearer token, requires a `@tuturuuu.com` operator email, reads, inserts, patches, and deletes private whitelist rows through the service-role private-schema REST adapter, preserves list pagination and create validation/defaults, applies legacy `Boolean(enabled)` truthiness for detail updates, and keeps the legacy success, validation, 403, JSON failure, and plain-text failure bodies. |
| `GET /api/v1/users/me/hive-access` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves the legacy app-session-first auth behavior for current-user app-session targets, falls back to browser Supabase auth cookies only when no app-session token is present, reads only `hive_members.enabled` and `platform_user_roles.enabled`/`allow_role_management` for the authenticated user through the server-owned Supabase REST adapter, returns the derived legacy access/admin/member payload, and keeps the legacy private cache directive on successful responses. |
| `GET /api/v1/cms/workspaces` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves app-session and browser Supabase auth, loads the caller's admin-visible workspaces through service-role Supabase REST, applies root-admin and per-workspace external-project permission checks, resolves active external-project bindings, and returns the raw legacy workspace array with subscription tier metadata. |
| `GET /api/v1/notifications/unread-count` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves app-session and browser Supabase auth, validates the optional `wsId` query filter, verifies workspace membership before scoped counts, builds the legacy notification access filter, reads the exact unread count through the service-role Supabase REST adapter, and returns no-store JSON responses. |
| `GET /api/v1/mira/achievements` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates the browser Supabase session or non-app-session Bearer token, reads the private Mira achievement catalog through the service-role private-schema Supabase REST adapter, reads the caller's unlocked achievements through the caller-token Supabase REST adapter, and preserves the legacy unlocked-status merge, grouping, XP/stat calculation, and empty-unlocked fallback when the user-achievement read fails. |
| `GET /api/v1/storage/list` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust validates legacy `ttr_` workspace API keys, resolves role/default workspace permissions, requires `manage_drive` or `admin`, preserves query coercion and storage path sanitization, blocks mobile-deployment vault paths, lists Supabase Storage through the server-owned storage REST adapter, filters placeholder/reserved entries, recursively counts matching files, and returns the legacy data/pagination and error envelopes. |
| `GET /api/v1/hive/ai/models` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves Hive-only app-session auth and browser Supabase cookie fallback, requires Hive member or admin access before private reads, reads only UI-safe model columns from `private.ai_gateway_models` through the server-owned private-schema REST adapter, preserves the legacy `enabled`/`type` filters and provider/name ordering, and returns the derived models UI payload. |
| `GET /api/v1/nova/me/team` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves Nova-only app-session auth and browser Supabase cookie fallback, reads only `team_id` for the authenticated user from `private.nova_team_members` through the server-owned private-schema REST adapter, and returns the derived legacy team ID payload. |
| `GET /api/v1/task-board-status-templates` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves authenticated Supabase browser-cookie and non-app-session Bearer access, rejects Tuturuuu app-session tokens without falling back to stale cookies, reads the global `task_board_status_templates` catalog through the server-owned Supabase REST adapter, preserves legacy `is_default.desc,name.asc` ordering, and returns the raw legacy templates payload. |
| `GET` / `PUT` `/api/v1/infrastructure/mobile-versions` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks both method artifacts `migrated`; Rust revalidates the normal Supabase browser session or non-app-session Bearer token, requires root workspace `manage_workspace_roles` through the server-owned `has_workspace_permission` RPC, reads the fixed root workspace mobile policy config IDs for snapshots, validates and normalizes write payloads, upserts all nine root workspace policy config rows through the server-owned Supabase REST adapter, and preserves the legacy admin policy snapshot plus success/error write bodies. |
| `GET` / `POST` `/api/v1/infrastructure/timezones` and `PUT` / `DELETE` `/api/v1/infrastructure/timezones/:timezoneId` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the collection `GET`/`POST` and detail `PUT`/`DELETE` artifacts `migrated`; Rust revalidates the normal Supabase browser session or non-app-session Bearer token, requires root workspace `manage_workspace_roles`, reads and writes `private.timezones` through the server-owned private-schema Supabase REST adapter, preserves `value.asc` ordering for reads, normalizes legacy create/update payloads, omits missing/null create IDs so the database UUID default is used, and preserves the legacy success and method-specific failure bodies. |
| `GET /api/v1/infrastructure/user-status-changes` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust requires a normal Supabase browser session or non-app-session Bearer token, forwards that caller token to Supabase REST so `workspace_user_status_changes` RLS remains active, preserves the legacy `ws_id` requirement, parseInt-style `limit`/`offset` range behavior, exact-count pagination, raw row list response, and legacy Supabase error body. |
| `GET /api/v1/infrastructure/users` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust uses the shared caller-token paginated export helper for `workspace_users`, preserving Supabase RLS, the legacy `ws_id` requirement, parseInt-style `limit`/`offset` range behavior, exact-count pagination, raw row list response, and legacy Supabase error body. |
| `GET /api/v1/infrastructure/classes`, `/product-categories`, and `/score-names` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks these routes `migrated`; Rust uses the shared caller-token paginated export helper for `workspace_user_groups`, `product_categories`, and `user_group_metrics`, preserving Supabase RLS, the legacy `ws_id` requirement, parseInt-style `limit`/`offset` range behavior, exact-count pagination, raw row list responses, and legacy Supabase error bodies. |
| `GET /api/v1/infrastructure/lessons` and `/packages` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks these routes `migrated`; Rust preserves the legacy no-auth service-role private-schema export for `lessons`, while `packages` revalidates a normal Supabase browser session or non-app-session Bearer token, normalizes the workspace, requires `view_inventory`, reads `workspace_products` through the service-role Supabase REST adapter, and preserves the legacy `ws_id`, parseInt-style `limit`/`offset`, exact-count pagination, data/count body, and error responses. |
| `GET /api/v1/infrastructure/bills`, `/roles`, and `/transaction-categories` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks these routes `migrated`; Rust uses the shared caller-token paginated export helper for `finance_invoices`, `workspace_user_groups`, and `transaction_categories`, preserving Supabase RLS, the legacy `ws_id` requirement, parseInt-style `limit`/`offset` range behavior, exact-count pagination, raw row list responses, and legacy Supabase error bodies. |
| `GET /api/v1/infrastructure/abuse-intelligence` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks only the `GET` method artifact `migrated`; Rust revalidates the normal Supabase browser session or non-app-session Bearer token, requires root workspace `view_infrastructure` through the shared workspace permission helper, reads reputation subjects, activity signals, and step-up challenges with caller-token Supabase REST, reads active trust overrides with the service-role Supabase adapter, and preserves the legacy `limit`/`signalLimit` parsing, summary, `topRiskySubjects` sorting, and auth/error bodies. POST remains legacy-owned. |
| `GET /api/v1/infrastructure/abuse-events` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates the normal Supabase browser session or non-app-session Bearer token, preserves the root workspace membership gate through caller-token Supabase REST reads, queries `abuse_events` with the caller token, and preserves the legacy `ip`/`type`/`success` filters, `page`/`pageSize` parseInt-style range behavior, exact-count pagination, data/count/page/pageSize/totalPages body, and legacy auth/error responses. |
| `GET /api/v1/infrastructure/blocked-ips` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks only the `GET` method artifact `migrated`; Rust revalidates the normal Supabase browser session or non-app-session Bearer token, preserves the root workspace membership gate through caller-token Supabase REST reads, queries `blocked_ips` with the legacy `unblocked_by_user` embed, and preserves the legacy `status`/`ip` filters, `page`/`pageSize` parseInt-style range behavior, exact-count pagination, data/count/page/pageSize/totalPages body, and legacy auth/error responses. POST/DELETE remain legacy-owned. |
| `GET /api/v1/infrastructure/suspensions` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks only the `GET` method artifact `migrated`; Rust revalidates the normal Supabase browser session or non-app-session Bearer token, requires root workspace `manage_workspace_roles` through `has_workspace_permission` with the caller token, reads active `user_suspensions` rows through the service-role Supabase REST adapter ordered by `suspended_at.desc`, returns the legacy raw row array, and preserves the legacy `Unauthorized`, `Forbidden`, and `Failed to fetch suspensions` error bodies. POST and detail DELETE remain legacy-owned. |
| `GET` / `POST` `/api/v1/infrastructure/email-blacklist` and `GET` / `PUT` / `DELETE` `/api/v1/infrastructure/email-blacklist/:entryId` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks all email blacklist collection and detail method artifacts `migrated`; Rust revalidates the normal Supabase browser session or non-app-session Bearer token, preserves root workspace membership gates and the detail GET non-root `401` quirk, reads, inserts, updates, and deletes through caller-token Supabase REST so RLS remains active, preserves Zod-style write validation bodies, maps duplicate creates to `409`, maps detail misses to the legacy `404` bodies, and preserves update/delete prefetch behavior. |
| `GET /api/v1/infrastructure/bill-coupons`, `/bill-packages`, `/class-attendance`, `/class-members`, `/class-packages`, `/class-scores`, `/package-stock-changes`, and `/student-feedbacks` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks these routes `migrated`; Rust extends the shared caller-token paginated export helper with route-specific embedded select strings and related-table workspace filters, preserving Supabase RLS, the legacy `ws_id` requirement, parseInt-style `limit`/`offset` range behavior, exact-count pagination, raw row list responses, and legacy Supabase error bodies. |
| `GET /api/v1/infrastructure/coupons`, `/user-coupons`, `/user-monthly-reports`, and `/user-monthly-report-logs` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks these routes `migrated`; Rust revalidates the normal Supabase browser session or non-app-session Bearer token, normalizes the requested workspace, requires `manage_external_migrations` through the shared workspace permission resolver, reads `private.workspace_promotions`, `private.user_linked_promotions`, and the private monthly report views through the server-owned Supabase REST adapter with private-schema headers, preserves the user-coupons empty-promotion short-circuit and `workspace_promotions` relation object reconstruction, and preserves the legacy `ws_id` requirement, parseInt-style `limit`/`offset` range behavior, exact-count pagination, raw row list responses, and legacy auth/error bodies. |
| `GET /api/v1/infrastructure/payment-methods`, `/wallets`, and `/wallet-transactions` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks these routes `migrated`; Rust revalidates the normal Supabase browser session or non-app-session Bearer token, normalizes the requested workspace and requires `view_transactions` for wallet/payment method reads, reads `private.workspace_wallets` through the server-owned Supabase REST adapter with private-schema headers, forwards wallet transaction reads to `get_wallet_transactions_with_permissions` with the caller token, and preserves the legacy `ws_id` requirement, parseInt-style `limit`/`offset` behavior, pagination/count envelopes, raw row list responses, and legacy auth/error bodies. |
| `GET /api/v1/workspaces/limits` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust validates the browser Supabase auth cookie with Supabase Auth, treats `tuturuuu.com` and `xwf.tuturuuu.com` user emails as unlimited, otherwise reads only the exact count of non-deleted workspaces created by the authenticated user through the server-owned Supabase REST adapter, and returns the legacy `canCreate`, `currentCount`, `limit`, and `remaining` payload. |
| `GET /api/v1/workspaces/:wsId/posts/permissions` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates a normal Supabase session when present, calls the server-owned `has_workspace_permission` RPC for workspace `approve_posts` and root workspace `manage_workspace_roles`, and preserves the legacy quiet-failure behavior where missing auth, inaccessible workspaces, RPC failures, and missing permissions all return `200` with both permission flags `false`. |
| `GET /api/v1/workspaces/:wsId/Mention` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves the legacy path casing, revalidates a normal Supabase browser session or non-app-session Bearer token, rejects app-session tokens, requires exact `MEMBER` workspace membership, reads `workspace_users.email` with the caller token, and preserves the legacy email response, Unauthorized, Forbidden, membership lookup failure, and Supabase error bodies. |
| `GET /api/v1/workspaces/:wsId/habits/access` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates a normal Supabase browser session or non-app-session Bearer token, rejects app-session tokens, resolves `internal`, `personal`, UUID, and handle workspace identifiers, requires exact `MEMBER` membership through the service-role `workspace_members` read, reads `ENABLE_HABITS` from `workspace_secrets` with exact `value === "true"` matching, and returns the legacy enabled access payload. |
| `GET /api/v1/workspaces/:wsId/mobile/module-flags` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates a normal Supabase browser session or non-app-session Bearer token, rejects app-session tokens, resolves the legacy `internal` workspace slug, requires workspace membership through a caller-token `workspace_members` read, reads `MOBILE_HIDE_EXPERIMENTAL_MODULES` and `MOBILE_HIDDEN_MODULES` from `workspace_secrets` through the server-owned Supabase REST adapter, preserves JSON-array and comma-separated hidden-module parsing, and returns sorted `hiddenModuleIds` with the legacy private cache directive. |
| `GET /api/v1/workspaces/:wsId/education/access` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates a normal Supabase browser session or non-app-session Bearer token, mirrors getPermissions-style workspace permission resolution for `ai_lab`, reads `ENABLE_EDUCATION` from `workspace_secrets` through the server-owned Supabase REST adapter, and preserves the legacy access-probe behavior where workspace, feature-flag, permission, and lookup failures return `200` with `enabled: false`. |
| `GET /api/v1/workspaces/:wsId/finance/budgets/status` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust accepts finance/platform app-session tokens and CLI app-session tokens before falling back to a normal Supabase browser session or non-app-session Bearer token, normalizes internal, personal, handle, and UUID workspace identifiers, requires `manage_finance` through `has_workspace_permission`, calls `get_budget_status` with the service-role credential, returns the raw legacy RPC payload, and preserves the legacy Unauthorized, Insufficient permissions, and Error fetching budget status bodies. |
| `GET /api/workspaces/:wsId/finance/charts/balance` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust accepts finance/platform app-session tokens and CLI app-session tokens before normal Supabase fallback, normalizes workspace identifiers, requires `view_finance_stats`, preserves the legacy required `date` query plus `includeConfidential` parsing, calls `get_wallet_balance_at_date`, and returns the legacy balance/date payload, Unauthorized, Forbidden, invalid-query, and balance lookup error bodies. |
| `GET /api/v1/workspaces/:wsId/finance/debts/summary` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust accepts finance/platform app-session tokens and CLI app-session tokens before normal Supabase fallback, normalizes internal, personal, handle, and UUID workspace identifiers, requires `manage_finance`, calls private-schema `get_debt_loan_summary` with `_actor_id` and `_ws_id` using service-role auth, returns the first legacy RPC row or the zero summary, and preserves the legacy Unauthorized, Insufficient permissions, and Error fetching debt/loan summary bodies. |
| `GET /api/v1/workspaces/:wsId/finance/filter-users` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust accepts finance/platform app-session tokens and CLI app-session tokens before normal Supabase fallback, normalizes workspace identifiers, requires `view_transactions`, preserves the legacy `type` branches, reads transaction and invoice creator filters through service-role Supabase REST with explicit `ws_id` filters, reads workspace users with the caller token for normal Supabase sessions and service-role auth for app sessions, and preserves the legacy users payload, Unauthorized, and branch-specific failure bodies. |
| `GET /api/v1/workspaces/:wsId/finance/invoices/subscription/context` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust accepts finance/platform app-session tokens and CLI app-session tokens before normal Supabase fallback, normalizes workspace identifiers, requires `create_invoices`, preserves the legacy missing-query short-circuit, validates requested student groups inside the workspace, reads month-scoped attendance and completed invoice history through service-role Supabase REST, returns the legacy attendance and latest paid invoice context shape, and preserves the legacy Unauthorized and subscription-context error bodies. |
| `GET /api/v1/workspaces/:wsId/finance/recurring-transactions/upcoming` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks only the upcoming transactions route `migrated`; Rust accepts finance/platform app-session tokens and CLI app-session tokens before normal Supabase fallback, normalizes workspace identifiers, requires `view_transactions`, preserves JavaScript parseInt-style `daysAhead` parsing with a 30-day fallback, calls `get_upcoming_recurring_transactions` with caller-token auth for normal Supabase sessions and service-role auth for app sessions, and preserves the legacy upcomingTransactions payload, `403` Unauthorized, and fetch-failure bodies. Recurring transaction collection and detail routes remain legacy-owned. |
| `GET /api/v1/workspaces/:wsId/settings/permissions` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates a normal Supabase browser session or non-app-session Bearer token, rejects app-session tokens, resolves personal/workspace identifiers, mirrors `getPermissions` role/default/creator/admin behavior, and returns the legacy `manage_subscription`, `manage_workspace_settings`, and `manage_workspace_members` flags with the private 30-second success cache directive. |
| `GET /api/v1/workspaces/:wsId/settings/permissions/check` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates a normal Supabase browser session or non-app-session Bearer token, ignores app-session tokens and the legacy `userId` query, resolves personal/workspace identifiers, requires workspace access, and mirrors `getPermissions` role/default/creator/admin behavior before returning the hasPermission payload. |
| `GET /api/v1/workspaces/:wsId/course-modules` and `GET /api/v1/workspaces/:wsId/quiz-sets/:setId/linked-modules` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks both education read endpoints `migrated`; Rust revalidates a normal Supabase browser session or non-app-session Bearer token, resolves `ai_lab` workspace permission, requires the `ENABLE_EDUCATION` secret, reads course modules through service-role Supabase REST with exact-count page/pageSize/q behavior, and verifies linked quiz sets belong to the resolved workspace before listing linked modules. |
| `GET` / `PATCH` `/api/v1/user/onboarding-progress` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust validates the browser Supabase session with Supabase Auth, reads or upserts only the authenticated user's `onboarding_progress` row through the server-owned Supabase REST adapter, preserves the legacy allowed-field filter, null missing-row response, invalid/empty update errors, and method handling. |
| `PATCH /api/v1/user/profile` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust validates the browser Supabase session with Supabase Auth, validates `display_name`, `bio`, and `avatar_url` with the legacy limits, ignores unknown fields, updates only the authenticated user's `users` row through the server-owned Supabase REST adapter, and preserves the legacy success/error response messages. |
| `GET` / `PATCH` `/api/v1/users/me/default-workspace` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust accepts current-user app-session tokens or revalidated browser Supabase sessions for reads, preserves the legacy `null` fallback when workspace data cannot be resolved, falls back from an inaccessible saved default to the caller's personal workspace, and updates `user_private_details.default_workspace_id` only after validating the `workspaceId` field as a UUID or `null` and verifying workspace membership with the caller token. |
| `GET` / `PATCH` `/api/v1/users/calendar-settings` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust accepts calendar app-session tokens or revalidated browser Supabase sessions, reads and updates the authenticated user's `timezone`, `first_day_of_week`, and `time_format` from `user_private_details`, defaults missing values to `auto`, strips unknown patch fields, validates the legacy enum/string limits, and preserves private read cache plus no-store mutation responses. |
| `GET /api/v1/users/me/identities` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates a normal Supabase browser session or non-app-session Bearer token with Supabase Auth, rejects Tuturuuu app-session tokens, extracts the Auth JS-compatible `identities` array from the revalidated Supabase user JSON, returns the legacy identities/canUnlink payload, and keeps the legacy private cache directive plus auth, Supabase rejection, and internal error bodies. |
| `PATCH /api/v1/users/me/full-name` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust revalidates the browser Supabase session cookie or non-app-session Bearer token with Supabase Auth, validates `full_name` as a required JSON string with trimmed length `1..100`, and upserts `user_private_details` with `user_id` fixed to the authenticated user through Supabase REST using the caller token and `on_conflict=user_id`. |
| `POST /api/v1/aurora/health` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust validates the browser Supabase session with Supabase Auth, preserves the exact `@tuturuuu.com` email-domain gate, calls `AURORA_EXTERNAL_URL/health`, and returns the legacy success, auth, forbidden, and upstream-failure JSON bodies. |
| `GET` / `POST` `/api/v1/aurora/forecast`, `GET` / `POST` `/api/v1/aurora/ml-metrics`, `GET` / `POST` `/api/v1/aurora/statistical-metrics` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the Aurora forecast and metrics method artifacts `migrated`; Rust reads public Aurora forecast and metric tables through the server-owned Supabase REST adapter for GET. POST ingest routes preserve the legacy `AURORA_EXTERNAL_URL` and `AURORA_EXTERNAL_WSID` checks, Supabase session revalidation, exact `@tuturuuu.com` email-domain gate, external Aurora fetches, normalized Supabase inserts with the caller token, and legacy success/error JSON bodies. |
| `GET` / `POST` `/api/v1/infrastructure/changelog`, `GET` / `PUT` / `DELETE` `/api/v1/infrastructure/changelog/:id`, `POST /api/v1/infrastructure/changelog/:id/publish`, `GET /api/v1/infrastructure/changelog/slug/:slug` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the collection, detail, publish, and slug route artifacts `migrated`; Rust reads `changelog_entries` through the server-owned Supabase REST adapter, validates browser Supabase auth cookies with Supabase Auth before checking root workspace `manage_changelog`, falls back to published-only public reads for anonymous or unauthorized sessions, preserves exact-count list pagination, singular PostgREST detail/slug lookups, write authorization and validation, publish/unpublish timestamp behavior, and maps `PGRST116` to the legacy `404` body. Media upload remains legacy-owned. |
| `GET /api/v1/inventory/storefronts/:slug`, `GET /api/v1/inventory/orders/:publicToken` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks both public inventory read endpoints `migrated`; Rust keeps storefront/order data behind private inventory RPCs and service-role private-schema metadata reads, preserves public storefront CDN cache headers, private storefront/order app-session and browser-session membership checks, simulated HMAC order tokens, private no-store cache headers, and legacy `401`/`403`/`404`/`500` JSON bodies. Storefront checkout creation, analytics events, Polar webhooks, and workspace inventory management remain legacy-owned. |
| `GET /api/v1/topic-announcement-verifications/:token` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust decodes the token path segment, hashes it with SHA-256, reads and updates `private.topic_announcement_contact_verifications` through the server-owned Supabase REST adapter, and returns the legacy public HTML pages for verified, unavailable/already-used, expired, and failed links. Workspace Topic Announcements management APIs remain legacy-owned. |
| `POST` / `DELETE` `/api/v1/infrastructure/languages` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves the legacy locale validation bodies and `NEXT_LOCALE` set/delete cookie behavior. |
| `POST` / `DELETE` `/api/v1/infrastructure/sidebar` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves the legacy collapsed-sidebar validation body and `sidebar-collapsed` set/delete cookie behavior. |
| `POST` / `DELETE` `/api/v1/infrastructure/sidebar/sizes` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves the legacy size validation body, two-cookie write behavior, and DELETE behavior that clears only `sidebar-size`. |
| `GET /api/v1/infrastructure/users/fields/types` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust returns the deterministic ordered legacy field type payload without opening a Supabase admin client for static metadata. |
| `GET /api/v1/infrastructure/ai/models` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust reads `private.ai_gateway_models` through the server-owned Supabase REST adapter with private-schema headers, preserves the fixed public column list, default `type=language` filtering, provider/tag/enabled/search/ids filters, exact-count pagination, and caps ID filters at 100 so private model metadata stays behind the backend. |
| `OPTIONS /api/v1/auth/password-login`, `/otp/send`, and `/otp/verify`; `GET` / `OPTIONS` `/api/v1/auth/otp/settings` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the shared auth preflight method artifacts plus OTP settings `GET` migrated; Rust preserves wildcard CORS, public client/platform validation, `WEB_OTP_ENABLED` reads for web/tulearn, mobile OTP policy reads, non-mobile fail-open diagnostics, and mobile fail-closed errors while the paired OTP send/verify and password auth methods remain `legacy-next`. |
| `OPTIONS /api/v1/auth/mobile/password-login`, `/send-otp`, and `/verify-otp` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks only the `OPTIONS` method artifacts `migrated`; Rust preserves the shared legacy wildcard CORS `204` response while the `POST` auth methods remain `legacy-next`. |
| `GET` / `OPTIONS` `/api/v1/mobile/version-check` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks both method artifacts `migrated`; Rust preserves public strict query validation, root workspace mobile policy config reads through the server-owned Supabase REST adapter, legacy update-status evaluation, and the shared wildcard CORS response headers. |
| `OPTIONS /api/v1/auth/qr-login/challenges`, `/:challengeId`, `/:challengeId/approve` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks only the `OPTIONS` method artifacts `migrated`; Rust preserves the legacy bare empty `204` response while QR challenge creation, polling, and approval remain `legacy-next`. |
| `OPTIONS /api/v1/auth/mfa/mobile/challenges` and `/approvals` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks only the `OPTIONS` method artifacts `migrated`, including dynamic challenge polling and approval paths; Rust preserves the legacy bare empty `204` response while challenge creation, polling, approval, and approval listing remain `legacy-next`. |
| `OPTIONS /api/v1/workspaces/:wsId/external-projects/webgl-packages/upload` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks only the `OPTIONS` method artifact `migrated`; Rust preserves the legacy origin-dependent CMS upload CORS `204` response while the protected `PUT` upload remains `legacy-next`. |
| `POST /api/v1/workspaces/:wsId/user-groups/:groupId/group-checks/:postId/email` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves the legacy `410 Gone` response for removed direct post email sending. |
| `GET` / `POST` `/api/v1/workspaces/:wsId/slides` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves the current `501 Not implemented` placeholder contract without adding protected workspace slide data access. |
| `PUT` / `DELETE` `/api/v1/workspaces/:wsId/slides/:slideId` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves the current `501 Not implemented` placeholder contract without adding protected workspace slide data access. |
| `PUT /api/v1/infrastructure/migrate/grouped-score-names` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the route `migrated`; Rust preserves the legacy development-only guard and the disabled `410 MIGRATION_DISABLED` response for the removed `user_group_indicators` table. |
| `GET` / `PUT` / `PATCH` / `POST` `/api/v1/infrastructure/migrate/:migration` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks the legacy one-off batch migration helpers `accepted-removal`; Rust preserves the development/local-E2E guard and legacy method allow lists, but returns terminal `410 MIGRATION_DISABLED` instead of exposing broad admin batch reads or writes through the Cloudflare-compatible backend. |
| `PUT /api/workspaces/:wsId/products/categories/migrate`, `/products/units/migrate`, `/transactions/categories/migrate`, `/users/indicators/migrate`, and `/wallets/transactions/migrate` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks these obsolete workspace migration writes `accepted-removal`; Rust preserves the development-only guard and returns the terminal `410 MIGRATION_DISABLED` decommission body instead of preserving legacy Supabase data writes. |
| `GET` / `POST` `/api/v1/workspaces/:wsId/encryption/migrate`, `POST /api/v1/workspaces/:wsId/storage/migrate`, `GET /api/v2/workspaces/:wsId/migrate/:module` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks these production auth/API-key migration helpers `accepted-removal`; Rust preserves each legacy method allow list but returns terminal `410 MIGRATION_DISABLED` in every environment instead of preserving broad admin calendar encryption, storage migration, or migration export data paths. |
| `GET /api/share/course/:courseId`, `GET /api/sync-logs`, `GET /api/users/search`, `GET /api/v1/proxy/tuturuuu` | `apps/backend` Rust route dispatcher | `route-overrides.json` marks these retired legacy API aliases, broad maintenance/search routes, and the development-only Tuturuuu API proxy `accepted-removal`; Rust returns terminal `410 ENDPOINT_REMOVED` with legacy `Allow` headers while maintained replacements, workspace-scoped readers, phase-specific routes, or direct backend/internal API clients remain separate migration work. Payment paths are not claimed by this compatibility responder and therefore return the normal platform `404`. |

First TanStack Start migrated ownership:

| Legacy route | New owner | Evidence |
| - | - | - |
| `/:locale` | `apps/tanstack-web` TanStack Start static route | `route-overrides.json` marks the landing page, landing metadata layout, and shared marketing layout `migrated`; the Start route preserves the public English and Vietnamese landing content with local primitives and no framer-motion, Next.js APIs, auth, Supabase, or protected workspace data access. |
| `/:locale/docs` | `apps/tanstack-web` TanStack Start route loader | `route-overrides.json` marks the page `migrated`; `/:locale/docs` throws a TanStack Router `307` redirect to `https://docs.tuturuuu.com`. |
| `/:locale/calendar/meet-together/[[...slug]]` | `apps/tanstack-web` TanStack Start route loader | `route-overrides.json` marks the page `migrated`; `/:locale/calendar/meet-together` and nested slug paths redirect to `/meet-together` while preserving trailing slug segments. |
| `/:locale/pricing` | `apps/tanstack-web` TanStack Start route loader | `route-overrides.json` marks the page `migrated`; `/pricing` and `/:locale/pricing` throw a TanStack Router `307` redirect to `/?hash-nav=1#pricing`. |
| `/:locale/about` | `apps/tanstack-web` TanStack Start static route | `route-overrides.json` marks the about page and metadata-only layout `migrated`; the Start route preserves the legacy English and Vietnamese `about.*` message namespace through TanStack-local message files and renders without framer-motion, Next.js APIs, auth, Supabase, or protected workspace data access. |
| `/:locale/contact` | `apps/tanstack-web` TanStack Start route | `route-overrides.json` marks the page and metadata layout `migrated`; the Start route preserves the visible contact shell, hydrates the current-user contact profile through TanStack Query and Start server functions, and submits inquiries through `@tuturuuu/internal-api` Rust backend facades for `/api/v1/users/me/profile` and `/api/v1/inquiries`. |
| `/:locale/users/:handle` | `apps/tanstack-web` TanStack Start dynamic route | `route-overrides.json` marks the auth-gated marketing profile page `migrated`; the Start route preserves fail-closed current-user auth, locale-aware login redirects with `nextUrl`, private no-store headers, caller-scoped reads of the legacy public `users` profile fields through the internal-api `users-server` facade, the profile background/avatar shell, and explicit no-auth Playwright coverage. A Rust-owned public profile reader remains the follow-up before removing the temporary request-scoped Supabase helper. |
| `/:locale/contributors` | `apps/tanstack-web` TanStack Start route | `route-overrides.json` marks the page `migrated`; the Start route preserves the public contributors shell, GitHub repository/contributor data loading, loading and error states, stats, contributor list, CTA links, and analytics sections through TanStack Query. Dependency-free CSS/SVG equivalents are accepted for the legacy `framer-motion`, Recharts, and `react-confetti` visuals. |
| `/:locale/women-in-tech` | `apps/tanstack-web` TanStack Start route | `route-overrides.json` marks the page and metadata layout `migrated`; the Start route preserves the localized legacy title, Open Graph/Twitter/head metadata, public Vietnamese Women's Day content, copied media, local language switcher, and section structure. Dependency-free native image and CSS animation replacements are accepted for the legacy Next/framer-motion runtime. |
| `/:locale/acceptable-use`, `/community-guidelines`, `/privacy`, and `/terms` | `apps/tanstack-web` TanStack Start static routes | `route-overrides.json` marks each legal page and metadata-only layout `migrated`; the Start routes preserve the legacy static legal content, local legal primitives, and metadata without auth, Supabase, or protected workspace data access. |
| `/:locale/partners` | `apps/tanstack-web` TanStack Start static route | `route-overrides.json` marks the partners page and metadata-only layout `migrated`; the Start route preserves the legacy partner content, CTAs, outbound links, local partner primitives, and copied public logo assets without auth, Supabase, or protected workspace data access. |
| `/:locale/products/ai`, `/calendar`, `/crm`, `/documents`, `/drive`, `/finance`, `/inventory`, `/lms`, `/mail`, `/tasks`, and `/workflows` | `apps/tanstack-web` TanStack Start static routes | `route-overrides.json` marks each static product page and layout `migrated`; the Start routes preserve the legacy product copy, metadata, and shared page primitives without adding auth, Supabase, or protected workspace data access. |
| `/:locale/ai/chats/:chatId` | `apps/tanstack-web` TanStack Start route | `route-overrides.json` marks the public AI chat page and metadata layout `migrated`; the Start route fetches only `ai_chats.is_public=true` rows and their ordered public messages through a server function backed by Supabase REST, hydrates with TanStack Query, preserves not-found behavior for missing/private chats, and renders a read-only transcript instead of the dashboard streaming chat client. |
| `/:locale/documents/:documentId` | `apps/tanstack-web` TanStack Start route | `route-overrides.json` marks the public document page and layout `migrated`; the Start route fetches only public `workspace_documents` rows through a server function, hydrates with TanStack Query, preserves fail-closed not-found behavior, and keeps the current empty document body shell. The migrated layout uses stable localized generic head metadata instead of the legacy document-name Open Graph lookup to avoid a second metadata-time Supabase dependency. |
| `/:locale/products/meet-together` | `apps/tanstack-web` TanStack Start route loader | `route-overrides.json` marks the page `migrated`; `/products/meet-together` and `/:locale/products/meet-together` throw a TanStack Router `307` redirect to `/meet-together`. |
| `/:locale/qr-generator` | `apps/tanstack-web` TanStack Start route loader | `route-overrides.json` marks the page `migrated`; `/qr-generator` and `/:locale/qr-generator` redirect to the QR app origin and forward the raw query string so duplicate query keys are preserved. |
| `/:locale/changelog` | `apps/tanstack-web` TanStack Start route | `route-overrides.json` marks the changelog index page `migrated`; the Start route reads the Rust-owned public changelog `GET` API through a server function, hydrates the list with TanStack Query, applies ISR-style CDN headers, and falls back to an empty public state when the backend cannot return published entries. |
| `/:locale/changelog/:slug` | `apps/tanstack-web` TanStack Start route | `route-overrides.json` marks the changelog detail page `migrated`; the Start route reads the Rust-owned public changelog slug `GET` API through a server function, hydrates the entry with TanStack Query, reuses the public changelog list for adjacent navigation, applies ISR-style CDN headers, and throws the TanStack not-found response when the slug is missing. No-auth coverage uses a deterministic missing-slug 404 example so empty databases remain valid. |
| `/:locale/:wsId/changelog` | `apps/tanstack-web` TanStack Start dynamic route | `route-overrides.json` marks the dashboard changelog page artifact `migrated`; the Start route preserves fail-closed current-user auth, forwarded workspace resolution, dashboard card/list parity, public changelog links, and TanStack Query loading through the Rust-owned changelog list API instead of direct Supabase reads. |
| `/:locale/:wsId/infrastructure/changelog` | `apps/tanstack-web` TanStack Start dynamic route | `route-overrides.json` marks the infrastructure changelog admin list page artifact `migrated`; the Start route preserves fail-closed current-user auth, workspace resolution, `manage_changelog` settings redirect parity, URL search filters, TanStack Query hydration, legacy table columns/actions, and Rust-backed changelog list loading instead of direct service-role Supabase reads. New/edit pages and media upload remain separately tracked. |
| `/tools/random`, `/:locale/tools/random` | `apps/tanstack-web` TanStack Start route loaders | The Start routes preserve the current web proxy contract by redirecting to `apps/tools /random` and forwarding the raw query string. The generator UI is owned by the tools satellite, not the platform shell. |
| `/:locale/branding`, `/blog`, and `/careers` | `apps/tanstack-web` TanStack Start static routes | `route-overrides.json` marks the visible marketing pages and metadata-only layouts `migrated`; the Start routes preserve the static brand, blog placeholder, and careers content without auth, Supabase, or protected workspace data access. Branding Open Graph/Twitter image artifacts remain legacy-owned. |
| `/:locale/facebook-mockup` | `apps/tanstack-web` TanStack Start client route | `route-overrides.json` marks the page `migrated`; the Start route preserves the public Facebook mockup demo with local browser-safe components and no auth, Supabase, or protected workspace data access. |
| `/:locale/security` | `apps/tanstack-web` TanStack Start static route | `route-overrides.json` marks the security landing page and metadata-only layout `migrated`; the Start route preserves the legacy static security copy, vulnerability-reporting CTAs, trust sections, and local primitives without framer-motion, Next.js APIs, auth, Supabase, or protected workspace data access. |
| `/:locale/security/policy` and `/bug-bounty` | `apps/tanstack-web` TanStack Start static routes | `route-overrides.json` marks the security policy page, Security Hall of Fame page, and bug-bounty metadata-only layout `migrated`; the Start routes preserve the legacy responsible-disclosure and researcher-credit copy with local security primitives and no auth, Supabase, or protected workspace data access. |
| `/:locale/solutions/construction`, `/education`, `/healthcare`, `/hospitality`, `/manufacturing`, `/pharmacies`, `/realestate`, `/restaurants`, and `/retail` | `apps/tanstack-web` TanStack Start static routes | `route-overrides.json` marks every static solution page and layout `migrated`; the Start routes preserve legacy copy, metadata, FAQ content, CTAs, success metrics, and local solution primitives without framer-motion, Next.js APIs, auth, Supabase, or protected workspace data access. |
| `/:locale/ui`, `/:locale/ui/setup`, `/:locale/ui/contributing`, `/:locale/ui/components`, `/:locale/ui/components/:componentId` | `apps/tanstack-web` TanStack Start static routes | `route-overrides.json` marks the public UI showcase layout and pages `migrated`; the Start routes preserve the UI docs shell, setup/contribution pages, component index, and component detail views through local registry/docs data without auth, Supabase, or protected workspace data access. |
| `/:locale/visualizations/horse-racing` | `apps/tanstack-web` TanStack Start client route | `route-overrides.json` marks the page `migrated`; the Start route preserves the public horse-racing algorithm visualization with local TanStack-safe visualization components and no auth, Supabase, or protected workspace data access. |
| `/:locale/verify-token` | `apps/tanstack-web` TanStack Start route loader | `route-overrides.json` marks the page `migrated`; the Start route preserves the legacy `nextUrl` redirect sanitizer and `/onboarding` fallback without importing Next auth/session runtime into the Cloudflare-compatible frontend. |
| `/:locale/shared/user-profile/:code` | `apps/tanstack-web` TanStack Start route | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves the legacy noindex head, profile-link loader, fail-closed auth redirect for protected links, unavailable shell for expired/revoked links, localized fill form, and allowlist-scoped prefill behavior. Submit/avatar APIs still route through `packages/internal-api` and remain separate backend migration work. |
| `/:locale/shared/task/:shareCode` | `apps/tanstack-web` TanStack Start route | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves fail-closed current-user resolution before task data fetch, the legacy login redirect with `nextUrl`, noindex metadata, unavailable shell for revoked links, and shared task dialog rendering. `/api/v1/shared/tasks/:shareCode` remains legacy-owned backend work. |
| `/:locale/shared/task-boards/:code` | `apps/tanstack-web` TanStack Start dynamic route | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves noindex metadata, unavailable-shell behavior for missing or revoked public board links, no-store loading through the `packages/internal-api` public board facade, and read-only public `BoardViews` rendering through TanStack-local payload adapters. `/api/v1/shared/task-boards/:code` remains legacy-owned backend work. |
| `/:locale/:wsId/finance` route layout plus `/:locale/:wsId/finance` and `/:locale/:wsId/finance/{analytics,budgets,categories,debts,debts/:debtId,invoices,invoices/:invoiceId,invoices/new,recurring,tags,transactions,transactions/:transactionId,wallets,wallets/:walletId}` | `apps/tanstack-web` TanStack Start route loaders | `route-overrides.json` marks the Finance route-specific layout and page artifacts `migrated`; the Start routes preserve the accepted 307 redirects to the platform Finance paths and forward raw query strings so creation/search/pagination handoff parameters survive. Dynamic finance IDs are encoded before handoff. The legacy Finance layout's command/provider UI is not rendered in TanStack because these migrated leaves redirect; parent dashboard/session and Finance data ownership remain legacy-owned until workspace provider parity is complete. |
| `/:locale/:wsId/mail` route layout plus `/:locale/:wsId/mail` and `/:locale/:wsId/mail/sent` pages | `apps/tanstack-web` TanStack Start route loaders | `route-overrides.json` marks the Mail leaf pages `migrated` and the legacy route-specific Mail layout `accepted-removal`; the Start leaves preserve 307 handoff to the standalone Mail app through `buildMailRedirectHref`, while the Mail app centralized auth proxy and workspace-normalization boundary replace the legacy dashboard layout gate. Parent dashboard/session ownership remains legacy-owned until workspace provider parity is complete. |
| `/:locale/:wsId/workforce`, `/ai-chat/new`, `/meet`, `/qr-generator`, `/drive`, education library/builder pages, `/epm`, and `/external-projects` | `apps/tanstack-web` TanStack Start route loaders | `route-overrides.json` marks these page artifacts `migrated`; the Start routes preserve the legacy 307/308 redirects to workspace user database, chat, meet plans, QR app with query forwarding, Drive app handoff with workspace slug normalization, education library/builder, and CMS app destinations. Parent dashboard layout/session ownership remains legacy-owned until workspace provider parity is complete. |
| `/:locale/:wsId/education/quiz-sets/:setId` | `apps/tanstack-web` TanStack Start route loader | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves fail-closed current-user auth, workspace resolution, quiz table search/pagination with the legacy 10-row default, forwarded-auth internal-api quiz reads, and TanStack Query-backed create/update/delete plus AI explanation actions. The quiz-set detail layout and quiz APIs remain separately tracked. |
| `/:locale/:wsId/education/quiz-sets/:setId/linked-modules` | `apps/tanstack-web` TanStack Start route loader | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves fail-closed current-user auth, workspace resolution, linked course module table parity, and link/unlink workflow through forwarded-auth internal-api facades backed by Rust-owned education read endpoints. Parent dashboard/session ownership remains legacy-owned. |
| `/:locale/:wsId/education/courses/:courseId/modules/:moduleId/content` | `apps/tanstack-web` TanStack Start route loader | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves fail-closed current-user auth, workspace resolution, forwarded internal-api module reads, localized module content summary, and TanStack Query/internal-api-backed debounced content saves. The parent module layout and module API ownership remain separately tracked. |
| `/:locale/:wsId/education/courses/:courseId/modules/:moduleId/quizzes` | `apps/tanstack-web` TanStack Start route loader | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves fail-closed current-user auth, workspace resolution, the legacy `update_user_groups` not-found gate before data loading, URL-backed quiz search/pagination, and forwarded-auth internal-api quiz reads plus shared quiz table edit/delete actions. Quiz API and AI quiz-generation backend ownership remain separately tracked. |
| `/:locale/:wsId/education/courses/:courseId/modules/:moduleId/quizzes/new` | `apps/tanstack-web` TanStack Start route loader | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves fail-closed current-user auth, workspace resolution, localized manual quiz creation shell, and TanStack Query-backed submission through the internal-api quiz facade. Quiz create/update API ownership and the module quiz list page remain separately tracked. |
| `/:locale/:wsId/hive` route layout | `apps/tanstack-web` TanStack Start route loaders | `route-overrides.json` marks the route-specific layout artifact `migrated`; the migrated Hive leaves redirect to the standalone Hive app, while the legacy layout only imported `@xyflow/react` styles and returned children. Hive APIs and parent dashboard/session ownership remain legacy-owned. |
| `/:locale/:wsId/mind/boards/:boardId` route layout | `apps/tanstack-web` TanStack Start route loader | `route-overrides.json` marks the route-specific layout artifact `migrated`; the migrated Mind board page redirects to the standalone Mind board route with query forwarding, while the legacy layout only imported `@xyflow/react` styles and returned children. Mind APIs and parent dashboard/session ownership remain legacy-owned. |
| `/:locale/:wsId/documents/:documentId` route layout | `apps/tanstack-web` TanStack Start metadata | `route-overrides.json` marks the static Document Details metadata layout artifact `migrated`; the legacy layout only exported title/description metadata and returned children. The document detail page, workspace dashboard/session ownership, and document data/API routes remain legacy-owned. |
| `/:locale/:wsId/infrastructure` and `/:locale/:wsId/platform` parent layouts | `apps/tanstack-web` TanStack Start parent loaders | `route-overrides.json` marks both layout artifacts `migrated`; the Start parent routes preserve fail-closed current-user auth, workspace resolution, root `view_infrastructure` permission gating, and `Outlet` rendering for migrated children. The exact infrastructure analytics page, platform billing, platform roles, and remaining settings children stay separately tracked as legacy-next artifacts. |
| `/:locale/:wsId/epm/collections/:collectionId`, `/epm/entries/:entryId`, `/platform/external-projects`, and `/users/topic-announcements` | `apps/tanstack-web` TanStack Start route loaders | `route-overrides.json` marks these page artifacts `migrated`; the Start routes preserve the legacy 307 redirects to CMS collection/entry/admin destinations and legacy dashboard aliases. Infrastructure settings/app-coordination routes now live in `apps/infrastructure` and the old TanStack/web route is recorded as an accepted removal. Parent dashboard layout/session ownership remains legacy-owned until workspace provider parity is complete. |
| `/:locale/:wsId/ai-chat/chatbots` | `apps/tanstack-web` TanStack Start route loader | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves fail-closed current-user auth, workspace resolution, `ai_chat` permission gating, route metadata, and localized `FeatureSummary` content. The create action intentionally targets the canonical `/:locale/:wsId/ai-chat/my-chatbots/new` Start route instead of the legacy `/:wsId/chat` alias. Parent dashboard and AI chat session/provider ownership remains legacy-owned. |
| `/:locale/:wsId/ai-chat/my-chatbots` | `apps/tanstack-web` TanStack Start route loader | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves fail-closed current-user auth, workspace resolution, the legacy `ai_chat` layout permission gate, URL-backed table search/pagination, forwarded-auth group-tag reads, internal-api-backed row deletion, and localized `FeatureSummary`/`CustomDataTable` UI. Parent dashboard and AI chat session/provider ownership remains legacy-owned. |
| `/:locale/:wsId/ai-chat/my-chatbots/new` | `apps/tanstack-web` TanStack Start client route | `route-overrides.json` marks the static metadata layout and client-only form page `migrated`; the Start route preserves the local validation, localized summary strings, and submit toast behavior without adding protected API, Supabase, or server-action access. Parent dashboard and AI chat session/provider ownership remains legacy-owned. |
| `/:locale/:wsId/users/group-tags` | `apps/tanstack-web` TanStack Start route loader | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves fail-closed current-user auth, workspace resolution, URL-backed table search/pagination, forwarded-auth group-tag reads, internal-api-backed group-tag mutations/row actions, localized `FeatureSummary`/`CustomDataTable` UI, and locale-prefixed detail hrefs. Group-tag API ownership remains separately tracked for the backend Rust wave. |
| `/:locale/:wsId/users/group-tags/:tagId` | `apps/tanstack-web` TanStack Start route loader | `route-overrides.json` marks the page artifact `migrated`; the dynamic no-store Start route preserves fail-closed current-user auth, workspace resolution, URL-backed linked-group search/pagination, forwarded-auth tag detail and linked-group reads, TanStack Query-backed add/remove linked-group actions, localized `FeatureSummary`/`CustomDataTable` UI, and locale-prefixed group detail hrefs. Group-tag API ownership remains separately tracked for the backend Rust wave. |
| `/:locale/:wsId/settings/reports` | `apps/tanstack-web` TanStack Start route loader | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves fail-closed current-user auth, workspace resolution, `manage_user_report_templates` gating, URL-backed `q` search state, report and lead-generation template tables, preview panels, and edit/reset actions through TanStack Query server functions plus `packages/internal-api` workspace-config facades. |
| `/:locale/:wsId/settings/notifications` | `apps/tanstack-web` TanStack Start route loader | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves fail-closed current-user auth, workspace resolution, account notification status, workspace-wide enable/disable, browser permission controls, and editable event/channel preferences through TanStack Query server functions plus `packages/internal-api` notification preference facades. Notification preference API artifacts remain separately tracked Rust backend work. |
| `/:locale/:wsId/billing/success` | `apps/pay` satellite app via TanStack redirect | `route-overrides.json` marks the legacy success page as a `satellite-app` accepted replacement; the Start route issues a `307` to Pay and preserves the complete query string, including `checkoutId`. Checkout result rendering and payment reads remain Pay-owned. |
| `/:locale/:wsId/inventory` | `apps/tanstack-web` TanStack Start route loader | `route-overrides.json` marks the root inventory dashboard page artifact `migrated`; the Start route preserves fail-closed current-user auth, forwarded-auth workspace resolution, `view_inventory` permission handling, localized access-denied state, statistic-card loading/error states, and inventory statistics loaded through the internal-api facade. `/api/v1/workspaces/:wsId/inventory/statistics` and deeper inventory pages remain separately tracked. |
| `/:locale/:wsId/inventory/batches` | `apps/tanstack-web` TanStack Start dynamic route | `route-overrides.json` marks the inventory batches page artifact `migrated`; the Start route preserves fail-closed current-user auth, forwarded-auth workspace resolution, `view_inventory` permission handling, localized access-denied state, URL-backed `q`/`page`/`pageSize` search state, and TanStack Query table loading through the internal-api inventory facade. `/api/v1/workspaces/:wsId/inventory/batches` remains separately tracked backend work. |
| `/:locale/:wsId/inventory/categories`, `/manufacturers`, `/suppliers`, `/units`, and `/warehouses` | `apps/tanstack-web` TanStack Start dynamic routes | `route-overrides.json` marks these inventory resource page artifacts `migrated`; the Start routes preserve fail-closed current-user auth, forwarded-auth workspace resolution, inventory view/create/update/delete or catalog/setup permission booleans, localized access-denied states, URL-backed `q`/`page`/`pageSize` table state, and TanStack Query table loading plus create/update/delete actions through the internal-api inventory facades. The matching workspace inventory and product compatibility APIs remain separately tracked backend work. |
| `/:locale/:wsId/inventory/products` and `/:productId` | `apps/tanstack-web` TanStack Start dynamic routes | `route-overrides.json` marks the inventory product list and product detail/new form page artifacts `migrated`; the Start routes preserve fail-closed auth, workspace resolution, inventory and stock permission parity, route metadata, localized access-denied state, and TanStack Query product list/form loading plus mutations through internal-api inventory facades. Workspace inventory product APIs remain separately tracked backend work. |
| `/:locale/:wsId/inventory/promotions` | `apps/tanstack-web` TanStack Start dynamic route | `route-overrides.json` marks the inventory promotions page artifact `migrated`; the Start route preserves fail-closed auth, workspace resolution, inventory view/create/update/delete permission context, route metadata, and TanStack Query CRUD through internal-api promotion facades. Workspace promotion API routes remain separately tracked backend work. |
| `/:locale/:wsId/inventory/storefronts` | `apps/tanstack-web` TanStack Start dynamic route | `route-overrides.json` marks the inventory storefronts page artifact `migrated`; the Start route preserves fail-closed auth, workspace resolution, inventory catalog permission parity, route metadata, localized access-denied state, and TanStack Query reads/mutations through internal-api inventory storefront facades. Workspace storefront, listing, option-template, product, and public storefront APIs remain separately tracked backend work. |
| `/:locale/:wsId/members` | `apps/tanstack-web` TanStack Start route loader | `route-overrides.json` marks the workspace members page artifact `migrated`; the Start route preserves fail-closed auth, workspace resolution, personal-workspace/settings redirect, `manage_workspace_members` and `manage_workspace_roles` context, tab search validation, metadata, and the shared workspace-access client. `disableInvite` currently defaults to false until a Rust/internal-api workspace secret reader lands for `DISABLE_INVITE`; invite-link creation remains protected by the existing server API check. |
| `/:locale/:wsId/tasks` plus task cycles, estimates, initiatives, labels, logs, notes, projects, templates, and template marketplace pages | `apps/tanstack-web` TanStack Start route loaders | `route-overrides.json` marks these page artifacts `migrated`; the Start routes preserve authenticated workspace resolution, route metadata, and shared task UI clients. Project/cycle/initiative/log/template/estimate/label routes keep the legacy `manage_projects` permission gate through the forwarded-auth internal permission check, while the project/template detail routes load their initial data through forwarded-auth internal-api facades. Parent dashboard/session and remaining task data APIs remain separately owned. |
| `/:locale/:wsId/tasks/boards` and `/:locale/:wsId/tasks/boards/:boardId` | `apps/tanstack-web` TanStack Start route loaders | `route-overrides.json` marks both page artifacts `migrated`; the Start routes preserve authenticated board index/detail shells through shared task-board UI, the `next/navigation` runtime shim, forwarded-auth board authorization, legacy not-found mapping, and member/guest board access handling. The detail page omits the legacy Mira idle chat island until its local Next.js API/UI dependencies move behind shared TanStack/Rust facades. |
| `/:locale/:wsId/calendar`, `/chat`, `/cron`, and `/memories` | `apps/tanstack-web` TanStack Start route loaders | `route-overrides.json` marks these page artifacts `migrated`; the Start routes preserve authenticated workspace shells, route metadata, and legacy permission gates (`manage_calendar`, `view_chat`, or `ai_lab`) through forwarded-auth internal permission checks. Calendar/chat clients self-load through existing facades, while cron and memories keep data-free shared headers until app-local data clients move behind shared internal-api/Rust facades. |
| `/:locale/:wsId/users/tutoring` | `apps/tanstack-web` TanStack Start route loader | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves fail-closed current-user auth, forwarded-auth full workspace resolution, personal-workspace and `view_user_groups` not-found handling, `update_user_groups_scores` management context, route metadata, and the shared tutoring client. Tutoring backing APIs remain separately tracked Rust migration work. |
| `/:locale/:wsId/polls` | `apps/tanstack-web` TanStack Start static route | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves the legacy mock polls dashboard with local English/Vietnamese message bundles and shared UI primitives, without adding auth, Supabase, protected API, or server-action access. Parent dashboard layout/session ownership remains legacy-owned. |
| `/:locale/:wsId/users/structure` | `apps/tanstack-web` TanStack Start static route | `route-overrides.json` marks the page artifact `migrated`; the Start route ports the legacy local-state organizational-structure mock page, metadata, message bundle keys, canvas interactions, profile/details panel, and management dialogs without adding Supabase, protected API, or server-action access. Parent dashboard layout/session ownership remains legacy-owned. |
| `/:locale/:wsId/users/feedbacks` | `apps/tanstack-web` TanStack Start route loader | `route-overrides.json` marks the page artifact `migrated`; the Start route preserves fail-closed current-user auth, full workspace resolution, personal-workspace and `view_user_groups` not-found handling, `update_user_groups_scores` management context, route metadata, and the shared feedbacks client through internal-api user facades. Feedback data APIs remain separately tracked backend/internal-api work. |
| `/:locale` error and not-found shells | `apps/tanstack-web` root route | `route-overrides.json` marks both artifacts `migrated`; the Start root route owns the legacy reset button, localized `404` copy, and onboarding link through route error/not-found components. |
| `/~offline` page | `apps/tanstack-web` TanStack Start route | `route-overrides.json` marks the page `migrated`; the Start route renders the shared `OfflinePage` with the legacy title, message, and foreground/background classes. |
| `/~offline` layout | `apps/tanstack-web` root document | `route-overrides.json` marks the layout `migrated`; the Start root document imports shared UI globals and applies the legacy scroll/background body classes without relying on Next.js font helpers. |

Accepted removals:

| Legacy artifact | Decision | Evidence |
| - | - | - |
| `apps/web/src/app/api/auth/me/session/route.ts` | `accepted-removal` | The debug-style route returns raw `sb-*` auth cookie values plus the full Supabase session payload. No in-repo caller references `/api/auth/me/session`, and the TanStack/Rust cutover must not preserve raw session export behavior. |
| `apps/web/src/app/api/workspaces/[wsId]/categories/route.ts` | `accepted-removal` | The file is zero bytes and exports no HTTP methods, so there is no runtime behavior to port. The override keeps the artifact visible and terminal instead of silently dropping it from the inventory. |
| `apps/web/src/app/api/v1/workspaces/[wsId]/encryption/migrate/route.ts` | `accepted-removal` | The legacy route performs admin calendar-event encryption status reads and E2EE data writes. Rust owns a terminal `410 MIGRATION_DISABLED` response with the original `GET, POST` allow list so cutover does not preserve broad migration writes. |
| `apps/web/src/app/api/v1/workspaces/[wsId]/storage/migrate/route.ts` | `accepted-removal` | The legacy route mutates workspace storage providers after privileged permission checks. Rust owns a terminal `410 MIGRATION_DISABLED` response with the original `POST` allow list; storage moves must use maintained runbooks or local backfills. |
| `apps/web/src/app/api/v2/workspaces/[wsId]/migrate/[module]/route.ts` | `accepted-removal` | The legacy route exposes broad API-key migration exports backed by admin Supabase reads, private schemas, and RPCs. Rust owns a terminal `410 MIGRATION_DISABLED` response with the original `GET` allow list instead of preserving this export surface. |

Recently migrated backend runtime candidates:

| Legacy route | Decision | Evidence |
| - | - | - |
| `GET /api/auth/me` | `migrated` | Rust `handle_backend_request` revalidates the Supabase browser cookie or non-app-session Bearer token with Supabase Auth, preserves the raw legacy user payload, no-store headers, and unauthorized response. |
| `GET /api/auth/mfa/totp/assurance-level` | `migrated` | Rust `handle_backend_request` revalidates the Supabase browser cookie or non-app-session Bearer token with Supabase Auth, then derives the no-argument Supabase MFA AAL payload from JWT claims and verified factors. |
| `GET` / `POST` `/api/auth/mfa/totp/factors` | `migrated` | Rust `handle_backend_request` mirrors Auth JS factor listing from the revalidated Supabase user JSON and enrolls TOTP factors through Supabase Auth REST with QR-code normalization. |
| `GET` / `DELETE` `/api/auth/mfa/totp/factors/:factorId` | `migrated` | Rust `handle_backend_request` resolves verified TOTP factor detail from the Auth JS-compatible list and unenrolls factors through Supabase Auth REST with the legacy success wrapper. |
| `GET /api/v1/workspaces/:wsId/posts/permissions` | `migrated` | Rust `handle_backend_request` returns the legacy post approval/force-send flags through `has_workspace_permission` RPC checks, with missing auth or permission failures collapsed to false flags. |
| `GET /api/v1/workspaces/:wsId/Mention` | `migrated` | Rust `handle_backend_request` returns the legacy singular email array after Supabase auth revalidation and exact `MEMBER` workspace membership, with caller-token `workspace_users.email` reads and legacy error bodies. |
| `GET /api/v1/workspaces/:wsId/habits/access` | `migrated` | Rust `handle_backend_request` returns the legacy enabled habits access probe after Supabase auth revalidation, workspace normalization, service-role `MEMBER` validation, and exact `ENABLE_HABITS=true` secret matching. |
| `GET /api/v1/workspaces/:wsId/mobile/module-flags` | `migrated` | Rust `handle_backend_request` returns the legacy sorted hiddenModuleIds payload after Supabase auth revalidation, caller-token workspace membership, and server-owned `workspace_secrets` mobile module flag reads. |
| `GET /api/v1/workspaces/:wsId/education/access` | `migrated` | Rust `handle_backend_request` returns the legacy enabled education access probe after Supabase auth, getPermissions-compatible `ai_lab` checks, and server-owned `workspace_secrets` feature-flag reads, with workspace/secret/permission lookup failures collapsed to `enabled: false`. |
| `GET /api/v1/workspaces/:wsId/finance/budgets/status` | `migrated` | Rust `handle_backend_request` accepts finance/platform app-session and CLI credentials before Supabase fallback, normalizes the workspace, checks `manage_finance`, calls `get_budget_status` with service-role auth, and returns the raw legacy payload/error bodies. |
| `GET /api/workspaces/:wsId/finance/charts/balance` | `migrated` | Rust `handle_backend_request` accepts finance app-session, CLI, or Supabase credentials, normalizes the workspace, checks `view_finance_stats`, calls `get_wallet_balance_at_date`, and returns the legacy balance/date payload. |
| `GET /api/v1/workspaces/:wsId/finance/debts/summary` | `migrated` | Rust `handle_backend_request` accepts finance app-session, CLI, or Supabase credentials, normalizes the workspace, checks `manage_finance`, calls private `get_debt_loan_summary` with `_actor_id`, and returns the first row or legacy zero summary. |
| `GET /api/v1/workspaces/:wsId/finance/filter-users` | `migrated` | Rust `handle_backend_request` accepts finance app-session, CLI, or Supabase credentials, normalizes the workspace, checks `view_transactions`, returns legacy users filter rows, and preserves caller-token workspace user reads for normal sessions. |
| `GET /api/v1/workspaces/:wsId/finance/invoices/subscription/context` | `migrated` | Rust `handle_backend_request` accepts finance app-session, CLI, or Supabase credentials, normalizes the workspace, checks `create_invoices`, validates requested student groups, and returns the legacy attendance plus latest paid invoice context. |
| `GET /api/v1/workspaces/:wsId/finance/recurring-transactions/upcoming` | `migrated` | Rust `handle_backend_request` accepts finance app-session, CLI, or Supabase credentials, normalizes the workspace, checks `view_transactions`, preserves `daysAhead` parseInt behavior, and returns the legacy upcomingTransactions envelope. |
| `GET /api/v1/workspaces/:wsId/settings/permissions` | `migrated` | Rust `handle_backend_request` mirrors the legacy `getPermissions` result for settings permission flags after Supabase auth revalidation and workspace membership/default/role permission resolution. |
| `GET /api/v1/workspaces/:wsId/settings/permissions/check` | `migrated` | Rust `handle_backend_request` mirrors the legacy `getPermissions(...).containsPermission(...)` result after Supabase auth revalidation and workspace membership/default/role permission resolution. |
| `GET` / `PUT` `/api/v1/infrastructure/mobile-versions` | `migrated` | Rust `handle_backend_request` revalidates the browser cookie or non-app-session Bearer token, requires root `manage_workspace_roles`, returns the legacy mobile policy snapshot, and upserts normalized mobile policy writes through the server-owned Supabase REST adapter. |
| `GET` / `POST` `/api/v1/infrastructure/timezones` and `PUT` / `DELETE` `/api/v1/infrastructure/timezones/:timezoneId` | `migrated` | Rust `handle_backend_request` revalidates the browser cookie or non-app-session Bearer token, requires root `manage_workspace_roles`, reads and writes `private.timezones` with private-schema headers, normalizes legacy create/update payloads, omits missing/null create IDs for database UUID defaults, and preserves legacy success/error bodies. |
| `GET /api/v1/infrastructure/user-status-changes` | `migrated` | Rust `handle_backend_request` forwards the caller's Supabase token to PostgREST for `workspace_user_status_changes`, preserving RLS, required `ws_id`, parseInt-style range headers, exact count, and the legacy data/count body. |
| `GET /api/v1/infrastructure/users` | `migrated` | Rust `handle_backend_request` forwards the caller's Supabase token to PostgREST for `workspace_users`, preserving RLS, required `ws_id`, parseInt-style range headers, exact count, and the legacy data/count body. |
| `GET /api/v1/infrastructure/classes`, `/product-categories`, and `/score-names` | `migrated` | Rust `handle_backend_request` uses the shared caller-token paginated export helper for `workspace_user_groups`, `product_categories`, and `user_group_metrics`, preserving RLS, exact count, and the legacy data/count bodies. |
| `GET /api/v1/infrastructure/lessons` and `/packages` | `migrated` | Rust `handle_backend_request` preserves the no-auth private-schema lesson export and revalidates package callers before requiring `view_inventory`, while keeping exact-count pagination and the legacy data/count bodies. |
| `GET /api/v1/infrastructure/product-prices`, `/product-units`, and `/warehouses` | `migrated` | Rust `handle_backend_request` accepts inventory app-session credentials or normal Supabase browser/Bearer credentials, requires inventory catalog/setup read permissions, and reads private inventory setup rows through the service-role Supabase REST adapter with exact-count pagination. Product prices scope through the `workspace_products` inner workspace filter. |
| `GET` / `POST` `/api/v1/infrastructure/ai/whitelist/domains` and `/emails` | `migrated` | Rust `handle_backend_request` revalidates the Supabase browser session or non-app-session Bearer token, requires a `@tuturuuu.com` operator email, reads and inserts private whitelist rows through the service-role private-schema REST adapter, and preserves `page`/`pageSize`/`q`, `created_at.desc` ordering, exact-count pagination, Zod-style create validation messages, `enabled` defaults, 201 create wrappers, 403 denial bodies, and plain-text 500 bodies. |
| `PUT` / `DELETE` `/api/v1/infrastructure/ai/whitelist/:email` and `/domain/:domain` | `migrated` | Rust `handle_backend_request` revalidates the same operator boundary as the list routes, decodes the path segment, patches/deletes matching private whitelist rows through the service-role private-schema REST adapter, applies legacy `Boolean(enabled)` update truthiness, and preserves the legacy success/error bodies. |
| `GET /api/v1/infrastructure/post-email-queue` | `migrated` | Rust `handle_backend_request` revalidates the Supabase browser session or non-app-session Bearer token, requires root workspace membership, reads `post_email_queue` through the service-role Supabase REST adapter, preserves the legacy summary/workspace/recent-batch aggregation payload, and keeps workspace/batch breakdown failures non-fatal. |
| `GET /api/v1/infrastructure/bills`, `/roles`, and `/transaction-categories` | `migrated` | Rust `handle_backend_request` uses the shared caller-token paginated export helper for `finance_invoices`, `workspace_user_groups`, and `transaction_categories`, preserving RLS, exact count, and the legacy data/count bodies. |
| `GET /api/v1/infrastructure/wallet-transactions` | `migrated` | Rust `handle_backend_request` forwards the caller's Supabase token to `get_wallet_transactions_with_permissions`, preserving the legacy RPC payload, raw rows, and first-row `total_count` envelope. |
| `GET /api/v1/infrastructure/abuse-intelligence` | `migrated` | Rust `handle_backend_request` validates the Supabase browser session or Bearer token, requires root `view_infrastructure`, reads caller-scoped abuse reputation subjects, activity signals, and challenges, reads active overrides with service-role auth, and returns the legacy summary plus `topRiskySubjects` payload while leaving POST legacy-owned. |
| `GET /api/v1/infrastructure/abuse-events` | `migrated` | Rust `handle_backend_request` validates the Supabase browser session or Bearer token, checks root workspace membership with the caller token, reads `abuse_events` with legacy filters and page/pageSize pagination, and returns the legacy pagination envelope. |
| `GET /api/v1/infrastructure/blocked-ips` | `migrated` | Rust `handle_backend_request` validates the Supabase browser session or Bearer token, checks root workspace membership with the caller token, reads `blocked_ips` with legacy filters and page/pageSize pagination, and leaves POST/DELETE legacy-owned. |
| `GET /api/v1/infrastructure/suspensions` | `migrated` | Rust `handle_backend_request` validates the Supabase browser session or Bearer token, requires root `manage_workspace_roles`, reads active `user_suspensions` rows through the service-role Supabase REST adapter, and leaves POST/detail DELETE legacy-owned. |
| `GET` / `POST` `/api/v1/infrastructure/email-blacklist` and `GET` / `PUT` / `DELETE` `/api/v1/infrastructure/email-blacklist/:entryId` | `migrated` | Rust `handle_backend_request` validates the Supabase browser session or Bearer token, checks root workspace membership with the caller token, returns the legacy ordered collection/detail rows, writes with caller-token Supabase REST, preserves POST/PUT Zod-style validation bodies, maps duplicate creates to `409`, and preserves detail update/delete prefetch/not-found behavior. |
| `GET /api/v1/infrastructure/bill-coupons`, `/bill-packages`, `/class-attendance`, `/class-members`, `/class-packages`, `/class-scores`, `/package-stock-changes`, and `/student-feedbacks` | `migrated` | Rust `handle_backend_request` uses the shared caller-token paginated export helper with route-specific embedded select strings and related-table workspace filters while preserving exact count and the legacy data/count bodies. |
| `GET /api/v1/infrastructure/user-monthly-reports` and `/user-monthly-report-logs` | `migrated` | Rust `handle_backend_request` requires `manage_external_migrations`, resolves workspace aliases through the shared permission helper, and reads the private monthly report views through private-schema Supabase REST with exact-count pagination. |
| `GET /api/v1/workspaces/:wsId/crawlers/status` | `migrated` | Rust `handle_backend_request` preserves the legacy exact-URL crawler status lookup, raw Supabase row payloads, missing-URL validation, and `crawledUrl: null` fallback when no row exists. |
| `GET /api/v1/workspaces/:wsId/course-modules` and `GET /api/v1/workspaces/:wsId/quiz-sets/:setId/linked-modules` | `migrated` | Rust `handle_backend_request` resolves education workspace access, requires `ENABLE_EDUCATION`, reads service-role course-module rows with exact-count pagination, and verifies linked quiz sets belong to the resolved workspace before listing linked modules. |
| `PATCH /api/v1/user/profile` | `migrated` | Rust `handle_backend_request` validates browser Supabase auth, validates legacy profile fields, and updates only the authenticated user's `users` row through the server-owned Supabase REST adapter. |
| `GET` / `PATCH` `/api/v1/users/me/default-workspace` | `migrated` | Rust `handle_backend_request` resolves the authenticated user's default workspace with the legacy personal-workspace/null fallback and updates `default_workspace_id` after caller-token membership validation. |
| `GET` / `PATCH` `/api/v1/users/calendar-settings` | `migrated` | Rust `handle_backend_request` accepts calendar app-session tokens or revalidated browser Supabase sessions, reads and updates the authenticated user's calendar settings in `user_private_details`, defaults missing values to `auto`, and preserves legacy patch validation/cache behavior. |
| `GET /api/v1/users/me/identities` | `migrated` | Rust `handle_backend_request` revalidates browser Supabase auth, reads the raw Supabase Auth user JSON, returns the legacy linked identities list plus `canUnlink`, and preserves the private cache directive. |
| `PATCH /api/v1/users/me/full-name` | `migrated` | Rust `handle_backend_request` validates browser Supabase auth, validates the required trimmed `full_name`, and upserts `user_private_details` for the authenticated user with the caller token. |
| `GET /api/cron/discord/daily-report` | `migrated` | Rust `handle_backend_request` proxies to `DISCORD_APP_DEPLOYMENT_URL/daily-report` with cron bearer auth, upstream status/body passthrough, invalid-JSON fallback, OpenAPI coverage, and native/Worker outbound support. |
| `GET /api/cron/discord/wol/daily/remind` | `migrated` | Rust `handle_backend_request` reuses the same proxy contract for `DISCORD_APP_DEPLOYMENT_URL/wol-reminder` with route tests and Cloudflare Worker config requirements for the cron secret and Discord app deployment URL. |

Frontend pages now terminal:

| Legacy route | Status | Evidence |
| - | - | - |
| `/:locale/add-account` | `migrated` | Dynamic no-store TanStack Start route `/$locale/add-account` is registered in `routeTree.gen.ts`, preserves the legacy account-switcher add-account handoff, carries `returnUrl` through TanStack Router search validation, renders localized loading/success/error states, and persists the current session through a TanStack Query mutation backed by `@tuturuuu/internal-api` auth helpers instead of Next navigation or raw protected API calls. |
| `/:locale/:wsId/habits` | `migrated` | TanStack Start route `/$locale/$wsId/habits` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, checks the Rust-owned `/api/v1/workspaces/:wsId/habits/access` feature probe, and renders the shared `HabitsClientPage`. |
| `/:locale/:wsId/posts` | `migrated` | TanStack Start route `/$locale/$wsId/posts` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves pass-through URL search state for the shared posts client, and uses internal-api facades including the Rust-owned posts permission probe. |
| `/:locale/:wsId/crawlers` | `migrated` | TanStack Start route `/$locale/$wsId/crawlers` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves legacy `ai_lab` gating, carries URL page/pageSize/domain/search state through TanStack Router, and renders a read-only crawled URL table plus uncrawled/domain stats through Rust-owned crawler backend facades. |
| `/:locale/:wsId/crawlers/uncrawled` | `migrated` | TanStack Start route `/$locale/$wsId/crawlers/uncrawled` is registered in `routeTree.gen.ts`, uses the same authenticated workspace and `ai_lab` gate, carries URL filters through TanStack Router, and renders grouped read-only uncrawled URLs through the Rust-owned crawler backend facades while leaving crawl-trigger mutations out of scope. |
| `/:locale/:wsId/pipelines` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/pipelines` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves legacy `ai_lab` gating, carries URL page/pageSize/domain/search state through TanStack Router, and renders the crawler-backed read-only list through Rust-owned crawler backend facades. Legacy crawler create/update actions remain separately tracked. |
| `/:locale/:wsId/queues` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/queues` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves legacy `ai_lab` gating, carries URL page/pageSize/domain/search state through TanStack Router, and renders the crawler-backed read-only list through Rust-owned crawler backend facades. Legacy crawler create/update actions remain separately tracked. |
| `/:locale/:wsId/cron` layout | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/cron` preserves the legacy cron route-specific layout gate by requiring current-user auth, resolving the workspace, enforcing `ai_lab`, and rendering exact-match Overview, Cron jobs, and Executions tabs. Child cron pages stay separately tracked until their tables and mutations move behind internal-api or Rust facades. |
| `/:locale/:wsId/cron/jobs` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/cron/jobs` is registered in `routeTree.gen.ts`, duplicates fail-closed current-user/workspace/`ai_lab` gates before loading protected data, carries `q`, `page`, and `pageSize` through TanStack Router search state, and renders the cron job list through a typed internal-api facade instead of direct Supabase reads or raw browser `/api` fetches. Create, edit, delete, next-run calculation, and job detail navigation remain separately tracked until dataset readers, mutation flows, and `/:locale/:wsId/cron/jobs/:jobId` move behind internal-api or Rust facades. |
| `/:locale/:wsId/documents` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/documents` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the legacy `manage_documents` permission gate, and renders the workspace document list/create/delete flow through TanStack Query plus the typed documents internal-api facade. Document editor mutations and workspace document APIs remain separately tracked. |
| `/:locale/:wsId/documents/:documentId` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/documents/$documentId` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the legacy `manage_documents` permission gate, loads the protected document row through the typed documents internal-api facade with forwarded request auth, and renders document metadata plus a read-only rich-text preview. Document edit/share/delete/autosave behavior and workspace document APIs remain separately tracked. |
| `/:locale/:wsId/infrastructure/abuse-events` | `migrated` | TanStack Start route `/$locale/$wsId/infrastructure/abuse-events` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves `view_infrastructure` not-found gating, carries URL search filters through TanStack Router, and loads rows through the Rust-owned abuse-events backend facade. |
| `/:locale/:wsId/infrastructure/abuse-intelligence` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/abuse-intelligence` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the legacy root-workspace redirect boundary, requires root `view_infrastructure`, and renders shared TanStack Query/internal-api-backed reputation subject, signal, and trust override controls. Abuse Intelligence mutation APIs remain separately tracked. |
| `/:locale/:wsId/infrastructure/app-coordination` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/app-coordination` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the legacy root-workspace redirect boundary, accepts root `manage_workspace_secrets` or `manage_workspace_roles`, and renders shared TanStack Query/internal-api-backed app-session policy controls. App Coordination APIs remain separately tracked. |
| `/:locale/:wsId/infrastructure/blocked-ips` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/blocked-ips` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves root and workspace `view_infrastructure` not-found gating, carries URL search/status/pagination filters through TanStack Router, and renders localized block/unblock controls through typed internal-api facades instead of direct Supabase reads or raw client `/api` fetches. Blocked IP APIs remain separately tracked. |
| `/:locale/:wsId/infrastructure/realtime` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/realtime` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace alias, preserves root and workspace `view_infrastructure` not-found gating, and renders the realtime analytics TanStack Query surface through createServerFn wrappers plus typed internal-api facades instead of raw protected `/api` fetches. Realtime analytics API artifacts remain separately tracked backend migration work. |
| `/:locale/:wsId/infrastructure/external-apps` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/external-apps` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the legacy root-workspace redirect boundary, accepts root `manage_workspace_secrets` or `manage_workspace_roles`, and renders shared TanStack Query/internal-api-backed external app registration and secret rotation controls. External Apps APIs remain separately tracked. |
| `/:locale/:wsId/infrastructure/github-bot` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/github-bot` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the legacy root-workspace redirect boundary, requires root `manage_workspace_secrets`, loads the initial GitHub Bot state through forwarded internal-api auth, and renders localized TanStack Query/internal-api-backed configuration, validation, watcher client, and audit controls. GitHub Bot APIs remain separately tracked. |
| `/:locale/:wsId/infrastructure/ai/whitelist/{domains,emails}` | `migrated` | TanStack Start routes `/$locale/$wsId/infrastructure/ai/whitelist/domains` and `/emails` are registered in `routeTree.gen.ts`, gate anonymous users through `requireCurrentUser`, preserve the `@tuturuuu.com` operator not-found boundary plus root `view_infrastructure` gating, carry URL pagination/search through TanStack Router, and load/mutate rows through the Rust-owned AI whitelist internal-api facade. |
| `/:locale/:wsId/infrastructure/mobile-versions` | `migrated` | TanStack Start route `/$locale/$wsId/infrastructure/mobile-versions` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, preserves the legacy root-workspace redirect boundary, requires root `manage_workspace_roles`, loads policies through the Rust-owned mobile-versions internal-api facade, and saves updates through TanStack Query mutations. |
| `/:locale/:wsId/infrastructure/mobile-deployment` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/mobile-deployment` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the legacy root-workspace redirect boundary, requires root `manage_mobile_deployment_vault`, loads the initial vault state through forwarded internal-api auth, and renders localized secret, file, activation, rollback, and CI token controls through TanStack Query/internal-api facades. Mobile Deployment APIs remain separately tracked. |
| `/:locale/:wsId/infrastructure/monitoring/stress-tests` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/monitoring/stress-tests` is registered under the TanStack monitoring layout in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the legacy root-workspace redirect boundary and root `view_infrastructure` not-found gate, renders the localized monitoring hero/section navigation, and uses TanStack Query/internal-api facades for stress-test snapshots, queue, abort, run detail polling, metrics, and history. Stress-test APIs remain separately tracked. |
| `/:locale/:wsId/infrastructure/monitoring/cron` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/monitoring/cron` is registered under the TanStack monitoring layout in `routeTree.gen.ts`, relies on the parent current-user, root-workspace redirect, and root `view_infrastructure` gates, and uses TanStack Query/internal-api facades for cron snapshots, execution archives, manual run queueing, control toggles, and console-log detail. Cron APIs remain separately tracked. |
| `/:locale/:wsId/infrastructure/monitoring/requests` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/monitoring/requests` is registered under the TanStack monitoring layout in `routeTree.gen.ts`, relies on the parent current-user, root-workspace redirect, and root `view_infrastructure` gates, and uses TanStack Query/internal-api facades for retained request archives, status/route/render/traffic filters, pagination, deployment context, and request inspection. Request archive APIs remain separately tracked. |
| `/:locale/:wsId/infrastructure/monitoring/watcher-logs` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/monitoring/watcher-logs` is registered under the TanStack monitoring layout in `routeTree.gen.ts`, relies on the parent current-user, root-workspace redirect, and root `view_infrastructure` gates, and uses TanStack Query/internal-api facades for watcher snapshots, deployment scope/level/rollout status filters, pagination, commit context, and log detail inspection. Watcher-log APIs remain separately tracked. |
| `/:locale/:wsId/infrastructure/monitoring/rollouts` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/monitoring/rollouts` is registered under the TanStack monitoring layout in `routeTree.gen.ts`, relies on the parent current-user, root-workspace redirect, and root `view_infrastructure` gates, and uses TanStack Query/internal-api facades for rollout summaries, deployment stage panels, standby sync controls, deployment pin controls, watcher event streams, and deployment history. Rollout mutation APIs remain separately tracked. |
| `/:locale/:wsId/infrastructure/monitoring{,/analytics,/deployments,/logs,/observability,/projects,/resources}` | `migrated` | Dynamic no-store TanStack Start routes are registered under the TanStack monitoring layout in `routeTree.gen.ts`, rely on the parent current-user, root-workspace redirect, and root `view_infrastructure` gates, and render the observability overview, analytics, deployment history, grouped logs, health signals, project controls, and resource inventory through TanStack Query/internal-api facades. Project deletion and deeper observability API ownership remain separately tracked follow-ups. |
| `/:locale/:wsId/infrastructure/timezones` | `migrated` | TanStack Start route `/$locale/$wsId/infrastructure/timezones` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, preserves the legacy root-workspace redirect boundary, requires root `manage_workspace_roles`, overlays Rust-owned persisted timezone rows onto the bundled timezone catalog, and performs create/update/delete sync mutations through the backend timezones facade. |
| `/:locale/:wsId/infrastructure/holidays` | `migrated` | TanStack Start route `/$locale/$wsId/infrastructure/holidays` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, preserves the legacy root-workspace redirect boundary, requires root `manage_workspace_roles`, carries the year filter through TanStack Router search state, and performs list/create/update/delete/bulk-import work through the Rust-owned holidays backend facade. |
| `/:locale/:wsId/infrastructure/email-blacklist` | `migrated` | TanStack Start route `/$locale/$wsId/infrastructure/email-blacklist` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves `view_infrastructure` not-found gating, carries URL search/type/pagination filters through TanStack Router, and loads/mutates rows through the Rust-owned email blacklist backend facade. |
| `/:locale/:wsId/infrastructure/email-templates` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/email-templates` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves root and workspace `view_infrastructure` not-found gating, and renders the localized React Email template selector, property editor, server-function preview renderer, dark-mode simulation, and iframe HTML preview without raw `/api` fetches or Supabase reads. |
| `/:locale/:wsId/infrastructure/rate-limits` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/rate-limits` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the legacy root-workspace redirect boundary, requires root `view_infrastructure`, forwards `manage_workspace_roles` as can-manage state, and renders the shared TanStack Query/internal-api-backed protection toggles, rate-limit rule, live-usage, and workspace-secret controls. Rate-limit APIs remain separately tracked. |
| `/:locale/:wsId/infrastructure/post-email-queue` | `migrated` | TanStack Start route `/$locale/$wsId/infrastructure/post-email-queue` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves `view_infrastructure` not-found gating, and renders the read-only queue summary, workspace breakdown, and recent batches through the Rust-owned post-email-queue backend facade while leaving the legacy cron trigger out of scope. |
| `/:locale/:wsId/education` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/education` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, and renders the legacy education overview shell with forwarded-auth internal-api counts for courses, flashcards, and quizzes. Education list APIs remain separately tracked. |
| `/:locale/:wsId/education/library/flashcards` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/education/library/flashcards` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, carries `q`/`page`/`pageSize` search state through TanStack Router, and renders the legacy flashcard library table through forwarded internal-api auth plus shared TanStack Query-backed create/update/delete components. Flashcard API ownership remains separately tracked. |
| `/:locale/:wsId/education/library/quizzes` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/education/library/quizzes` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, carries `q`/`page`/`pageSize` search state through TanStack Router with the legacy 10-row default, and renders the legacy quiz library table through forwarded internal-api auth plus shared TanStack Query-backed create/update/delete components and AI explanation generation. Quiz API ownership remains separately tracked. |
| `/:locale/:wsId/education/library/quiz-sets` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/education/library/quiz-sets` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, carries `q`/`page`/`pageSize` search state through TanStack Router with the legacy 10-row default, and renders the legacy quiz-set library table through forwarded internal-api auth plus linked course/module label hydration and shared TanStack Query-backed create/update/delete components. Quiz-set and linked-module API ownership remains separately tracked. |
| `/:locale/:wsId/education/attempts` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/education/attempts` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the legacy `view_user_groups_reports` not-found gate, carries filter/sort/page/pageSize search state through TanStack Router, and renders the legacy attempts review table through forwarded internal-api auth with learner and quiz-set metadata. Attempts APIs remain separately tracked. |
| `/:locale/:wsId/education/attempts/:attemptId` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/education/attempts/$attemptId` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the `view_user_groups_reports` not-found gate used by the list/API, and renders the legacy attempt detail header, learner card, KPI strip, and per-question answer correctness cards through forwarded internal-api auth. Attempts APIs remain separately tracked. |
| `/:locale/:wsId/education/courses` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/education/courses` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, carries `q`/`page`/`pageSize`/`view` search state through TanStack Router, and renders the legacy course card/table page through forwarded internal-api auth plus shared CourseCardView, CoursePagination, CustomDataTable, and internal-api-backed create/edit/delete actions. Course API ownership and course builder remain separately tracked. |
| `/:locale/:wsId/education/quiz-sets/:setId` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/education/quiz-sets/$setId` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, carries `q`/`page`/`pageSize` search state through TanStack Router with the legacy 10-row default, and renders the legacy quiz-set quiz table through forwarded internal-api auth plus shared TanStack Query-backed create/update/delete components and AI explanation generation. The exact `/education/quiz-sets` redirect is an index route so detail children are reachable; the quiz-set detail layout and quiz APIs remain separately tracked. |
| `/:locale/:wsId/ai-chat` layout | `migrated` | Dynamic no-store TanStack Start parent route `/$locale/$wsId/ai-chat` wraps migrated AI chat child routes with fail-closed current-user auth, workspace resolution, the legacy `ai_chat` permission redirect, and localized New Chat, Chatbots, and My Chatbots tabs. The exact `/ai-chat` leaf deliberately remains not-found in TanStack until the legacy chat page is migrated; parent dashboard/session ownership also remains separately tracked. |
| `/:locale/:wsId/ai-chat/my-chatbots` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/ai-chat/my-chatbots` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the legacy `ai_chat` permission gate, carries `q`/`page`/`pageSize` search state through TanStack Router, and renders the legacy My Chatbots table through forwarded internal-api auth plus internal-api-backed row deletion. Group-tag API ownership remains separately tracked. |
| `/:locale/:wsId/users/approvals` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/users/approvals` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the personal-workspace notice and approve reports/posts not-found gating, carries `status`/`page`/`limit`/`groupId`/`userId`/`creatorId` filter state through TanStack Router, and renders the shared approvals tabs through TanStack Query-backed reads and internal-api-backed approve/reject/unapprove mutations. Approval APIs remain separately tracked. |
| `/:locale/:wsId/users/group-tags` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/users/group-tags` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, carries `q`/`page`/`pageSize` search state through TanStack Router, and renders the legacy group-tag table through forwarded internal-api auth plus shared create/update/delete components and locale-prefixed detail hrefs. Group-tag API ownership remains separately tracked. |
| `/:locale/:wsId/users/group-tags/:tagId` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/users/group-tags/$tagId` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, carries `q`/`page`/`pageSize` search state through TanStack Router, and renders the legacy linked user-group table through forwarded internal-api auth plus TanStack Query-backed linked-group add/remove components. Group-tag API ownership remains separately tracked. |
| `/:locale/:wsId/users/topic-announcements/announcements` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/users/topic-announcements/announcements` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves personal-workspace not-found parity, enforces `ENABLE_TOPIC_ANNOUNCEMENTS` and `manage_users`, carries `status`/`q`/`page` search state through TanStack Router, and renders the legacy announcements composer/table with send-permission-aware create/send/schedule flows, attachment upload, live email preview, save-as-template, and typed topic-announcement internal-api contracts. |
| `/:locale/:wsId/users/topic-announcements/templates` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/users/topic-announcements/templates` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves personal-workspace not-found parity, enforces `ENABLE_TOPIC_ANNOUNCEMENTS` and `manage_users`, and renders the legacy templates CRUD page through TanStack Query plus typed topic-announcement and user-group internal-api facades. The exact parent redirect now only fires on `/topic-announcements`, so migrated child tabs can render. |
| `/:locale/:wsId/users/topic-announcements/contacts` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/users/topic-announcements/contacts` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves personal-workspace not-found parity, enforces `ENABLE_TOPIC_ANNOUNCEMENTS` and `manage_users`, and renders the legacy contacts table, create dialog, linked workspace-user selector, delete confirmation, and verification request action through TanStack Query plus typed topic-announcement and workspace-user internal-api facades. Verification controls stay hidden unless the caller has `send_user_group_post_emails`. |
| `/:locale/:wsId/users/topic-announcements/delivery` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/users/topic-announcements/delivery` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves personal-workspace not-found parity, enforces `ENABLE_TOPIC_ANNOUNCEMENTS` and `manage_users`, and renders the legacy read-only delivery history with forwarded-auth `listTopicAnnouncements({ status: "sent" })` loader hydration, calendar timezone normalization, TanStack Query refreshes, sent-only defensive filtering, recipient summary chips, sent-at formatting, and empty-state compose handoff. Delivery does not require `send_user_group_post_emails`. |
| `/:locale/:wsId/users/topic-announcements/import` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/users/topic-announcements/import` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves personal-workspace not-found parity, enforces `ENABLE_TOPIC_ANNOUNCEMENTS` and `manage_users`, derives `send_user_group_post_emails` for create-and-send availability, and renders the legacy bulk import flow with client-only XLSX template download/first-sheet parsing, custom CSV/header alias parsing, editable spreadsheet grid, row validation/result summaries, and TanStack Query mutations through `importTopicAnnouncements` plus `sendTopicAnnouncementsBulk`. Rust backend ownership of the import and send-bulk API routes remains separately tracked. |
| `/:locale/:wsId/settings/reports` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/settings/reports` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves `manage_user_report_templates` permission gating, carries `q` search state through TanStack Router, and renders the legacy reports and lead-generation template tables plus previews through TanStack Query server functions and the shared workspace-config internal-api facade. |
| `/:locale/:wsId/users/groups/calendar` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/users/groups/calendar` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves manage-users/view-user-groups not-found gating, forwards update-user-groups schedule permission state, and renders the shared user-group session calendar through internal-api-backed session reads and mutations. User-group session APIs remain separately tracked. |
| `/:locale/:wsId/users/groups/:groupId/attendance` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/users/groups/$groupId/attendance` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves `check_user_attendance` not-found gating and `update_user_attendance` save gating, hydrates group/session/member/config/attendance data through forwarded internal-api auth, and renders the attendance calendar/session/member cards with TanStack Query-backed reads and saves. User-group attendance/member/config/session APIs remain separately tracked for the backend Rust wave. |
| `/:locale/:wsId/users/groups/:groupId/requests` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/users/groups/$groupId/requests` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves approve reports/posts not-found gating, and renders the shared group requests tabs through TanStack Query and internal-api-backed approval mutations. Parent group detail page and approval APIs remain separately tracked. |
| `/:locale/:wsId/users/groups/:groupId/schedule` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/users/groups/$groupId/schedule` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, loads the target group through forwarded internal-api auth, preserves update-user-groups schedule permission state, and renders the shared end-date dialog and user-group session calendar. Parent group detail page and schedule APIs remain separately tracked. |
| `/:locale/:wsId/education/courses/:courseId/modules/:moduleId/content` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/education/courses/$courseId/modules/$moduleId/content` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, loads the requested module through forwarded internal-api auth, and renders the legacy rich-text module content editor with TanStack Query/internal-api-backed debounced saves. Parent module layout and module API ownership remain separately tracked. |
| `/:locale/:wsId/education/courses/:courseId/modules/:moduleId/youtube-links` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/education/courses/$courseId/modules/$moduleId/youtube-links` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, loads the requested module through forwarded internal-api auth, and renders the legacy Youtube Links management page with shared form/delete/embed UI backed by strict internal-api mutations. Parent module layout and module API ownership remain separately tracked. |
| `/:locale/:wsId/education/courses/:courseId/modules/:moduleId/quiz-sets` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/education/courses/$courseId/modules/$moduleId/quiz-sets` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, carries list search state through TanStack Router, and renders the legacy module quiz-set table through forwarded internal-api auth plus shared TanStack Query-backed create/update/delete components. Course-module quiz-set API ownership remains separately tracked. |
| `/:locale/:wsId/education/courses/:courseId/modules/:moduleId/quizzes` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/education/courses/$courseId/modules/$moduleId/quizzes` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the legacy `update_user_groups` not-found gate before quiz reads, carries search state through TanStack Router, and renders the shared quiz table through forwarded internal-api auth. Quiz API and AI quiz-generation backend ownership remain separately tracked. |
| `/:locale/:wsId/education/courses/:courseId/modules/:moduleId/quizzes/new` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/education/courses/$courseId/modules/$moduleId/quizzes/new` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, renders the legacy manual quiz creation shell, and submits through the shared TanStack Query/internal-api quiz form before returning to the locale-prefixed module quizzes route. Quiz API ownership and the module quiz list page remain separately tracked. |
| `/:locale/logout` | `migrated` | Dynamic TanStack Start route `/$locale/logout` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, renders the legacy localized confirmation card with `from` copy, and logs out through the typed internal-api browser-session facade without raw protected app API or Supabase access in TanStack source. The underlying `POST /api/auth/logout` route remains legacy-owned until the auth backend wave. |
| `/:locale/:wsId/infrastructure/ai-agents` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/infrastructure/ai-agents` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, preserves the root-workspace and `manage_workspace_secrets` redirect gates, and renders the legacy AI Agents controls through forwarded internal-api auth plus shared TanStack Query-backed agent, channel, identity, secret, and external-thread actions. AI Agents APIs remain separately tracked for Rust backend ownership. |
| `/:locale/:wsId/notifications` | `migrated` | Dynamic no-store TanStack Start route `/$locale/$wsId/notifications` is registered in `routeTree.gen.ts`, gates anonymous users through `requireCurrentUser`, resolves the workspace, carries tab/type/scope/priority/page/pageSize search state through TanStack Router, and renders the legacy read-only notifications inbox through forwarded internal-api auth. Mark read/unread, mark all read, delete, invite actions, metadata updates, realtime subscription behavior, and entity action links remain separately tracked follow-ups. |

Frontend migration candidates blocked on auth/data ownership:

| Legacy route | Blocker | Required design |
| - | - | - |
| `/:locale/meet` and `/:locale/meet-together` | Public TanStack preview shells are available, but the legacy routes also load authenticated meeting plans and create plans through Next-only Supabase/server-action paths. | Add Rust-owned or TanStack server-function-backed plan list/create APIs, route them through `packages/internal-api`, preserve unauthenticated empty/login-required behavior, and add E2E evidence before adding the `page:/:locale/meet` or `page:/:locale/meet-together` overrides. |
| `/:locale/:wsId/usage` | The wrapper is small, but the content fans out into many server-side workspace stats backed by Supabase RPCs, admin reads, storage provider helpers, and per-feature permission checks. | Create a Rust-owned workspace usage summary endpoint or a small set of typed server functions that return the same permission-masked stats, then render the dashboard through TanStack Query without direct Supabase reads. |
| `/:locale/:wsId/ai/spark`, `/:locale/:wsId/mira`, and the canonical `/:locale/:wsId` Mira dashboard | These look compact at the page file level, but their clients call AI object generation, Mira focus/task/calendar/pet APIs, live voice/audio helpers, or assistant multimodal providers that are still Next/API coupled. The standalone `/:locale/:wsId/assistant` route was removed when text and rich live voice were consolidated into the workspace root. | Move each AI surface as a dedicated product lane with typed AI/Mira/assistant facades and focused browser evidence; avoid shell-only migrations that would expose incomplete AI behavior. |
| `/:locale/games/farm` | The visible game page is client-only, but the legacy layout gates access through Supabase auth and `isValidTuturuuuEmail(user?.email)` before rendering. | Add a TanStack server gate that validates the session and email domain through server-owned auth helpers, then port the game UI without exposing it publicly. |
| `/:locale` app-shell providers | The root route now centralizes locale validation, legacy root head metadata, `html lang`, theme bootstrapping, Query, and tooltip providers, but full legacy layout parity still includes `next-intl`, `NuqsAdapter`, theme-aware toasts, auth-backed version/DB badges, and service-worker runtime behavior. | Finish the provider/runtime contract in TanStack Start, decide which legacy badges and service-worker behaviors are accepted removals versus ports, then add route-level E2E or screenshot evidence before marking remaining localized layout artifacts terminal. |
| `/:locale/login` | Login owns OAuth callback forwarding, Supabase session redirects, app-token confirmation, OTP/password/passkey/MFA flows, account switching, Turnstile state, and session hydration. | Complete the auth/session contract for TanStack Start and Rust, then port login as a dedicated auth milestone with focused E2E coverage. |

## Frontend Runtime Adapters

TanStack route ports should use the adapter modules under
`apps/tanstack-web/src/lib/platform/` instead of rebuilding Next.js behavior in
each route:

| Adapter | Owns |
| - | - |
| `locale.ts` | `en` / `vi` locale detection, `NEXT_LOCALE`, as-needed prefixes, and `Accept-Language` fallback. |
| `head.ts` | TanStack-compatible metadata, canonical links, alternates, and stylesheet descriptors. |
| `theme.ts` | The class-based `system` / `light` / `dark` theme boot script used by the root shell. |
| `navigation.ts` | Typed redirect and not-found errors that can be converted to `Response` objects in loaders or server functions. |
| `session.ts` | Sanitized auth/session hydration snapshots from request cookies without exposing token values to the browser. |
| `query.ts` | Shared TanStack Query defaults and dehydration behavior for loader-prefetched data. |
| `app-shell.ts` | Root locale validation, localized document language derivation, and legacy-compatible head descriptors. |
| `redirects.ts` | Legacy-compatible redirect destinations for public, auth, dashboard alias, QR, Mail, CMS, CMS deep-link, and education routes. |

The root TanStack shell already uses the head, locale, theme, and Query
adapters. New route ports should add route-specific metadata through
`createPageHead`, prefetch loader data through the shared QueryClient, and pass
only sanitized session state to client components.

## Data And API Rules

* TanStack loaders and server functions may act as a BFF layer for SSR,
  cookies, headers, and query hydration.
* Product data reads/writes move to Rust-owned endpoints in `apps/backend`.
* Browser/shared UI code calls `packages/internal-api` helpers, not scattered
  raw API paths.
* Protected data stays behind server-owned private/admin access. Do not expose
  private Supabase or protected workspace reads directly to browser code.
* Use TanStack Query for client fetching and mutation. Do not fetch data in
  `useEffect`.
* `bun validate` runs `node scripts/check-tanstack-api-access.js` to enforce that
  `apps/tanstack-web/src` does not call relative protected `/api`, `/internal`,
  or `/trpc` paths directly and does not import or create Supabase clients. Run
  the focused command when reviewing a frontend port before the full repo check.

## Backend Crate Structure And The 700-LOC Ceiling

Every source file in the repo — Rust included — must stay well-maintained and
under a hard **700-LOC ceiling** whenever possible (start splitting around
\~400 LOC). The `apps/backend` crate root was decomposed to honor this:

* `src/lib.rs` (\~680 LOC) is now just the module registry (`mod <handler>;`),
  the public types, and `pub(crate) use` re-exports.
* `src/dispatch/` holds `handle_backend_request` plus one
  `dispatch_chunk_NN.rs` per route-table chunk. **New route arms append to a
  `dispatch_chunk_NN.rs`**; when a chunk approaches 700 LOC, add a fresh
  `chunk_NN.rs` and wire it into `dispatch/mod.rs`. Each chunk does
  `use crate::*;` to reach crate-root helpers/types.
* Cohesive helper families live in named submodules, each under 700 LOC:
  `types.rs`, `response.rs`, `runtime.rs`, `migration.rs`, `legacy_routes.rs`,
  `static_routes.rs`, `route_predicates.rs`, `config_env.rs`, `constants.rs`,
  `native.rs`, `worker_runtime.rs`. Each is re-exported from `lib.rs` with
  `pub(crate) use <mod>::*;` so existing call sites resolve unchanged.
* The unit-test suite lives in `src/tests.rs` (`mod tests;`), split by area so
  no test file crosses the ceiling.

To extract a new family: move the items into `src/<mod>.rs`, header it with
`use crate::*;` (plus any external `use serde…`), give moved items `pub(crate)`
visibility, then add `mod <mod>; pub(crate) use <mod>::*;` to `lib.rs`. Keep a
struct and the functions that read its private fields in the same module so
fields only need `pub(crate)` where a cross-module reader (e.g. `tests.rs`)
requires it. Do not bulk-restructure `lib.rs`/`dispatch/` while batches are
appending without a `tmp/agent-coordination/` claim. See `apps/backend/AGENTS.md`
for the full rules.

## No New Debt While The Switch Is Pending

Treat `apps/web`, `apps/backend`, and `apps/tanstack-web` as **one system**. The
migration runs in parallel with normal feature work, so any change that touches
only `apps/web` silently grows the backlog the cutover must clear. All future
work must keep the three surfaces consistent where applicable:

* **New or changed `apps/web` API route (any method).** If `apps/backend` already
  owns that path, port the same behavior change into the Rust handler in the same
  PR (match status codes, body shape, cache headers; migrate GET first and return
  `None` for un-ported methods so they fall through). If it is not owned yet,
  register/refresh the route in
  `apps/tanstack-web/migration/route-overrides.json` and regenerate with
  `bun migration:tanstack:manifest`, so the new surface is tracked as backlog
  instead of invisible debt. Verify ownership with the runtime coverage probe in
  `apps/backend/AGENTS.md` (migrated method = COVER, un-ported = FRESH).
* **New or changed dashboard page/route.** Mirror the manifest registration so
  `apps/tanstack-web` tracking stays accurate, and route shared data access
  through `packages/internal-api` (consumed by both frontends) rather than
  app-local fetchers, so the eventual TanStack port is a move, not a rewrite.
* **Shared data access.** Prefer adding a `packages/internal-api` facade over a
  one-off `apps/web` fetcher; the facade is the seam both the Next.js and
  TanStack frontends call, and it forwards to the Rust backend server-side.
* **Tracking, not blocking.** You do not have to finish the Rust/TanStack port in
  every PR, but you must leave the manifest accurate. A route that is added to
  `apps/web` and not reflected in the manifest is the debt this migration exists
  to avoid. `bun migration:tanstack:check` and the backend coverage probe are the
  guards.

## Security And Test Requirements

Every migrated Rust endpoint needs the same ownership evidence before its
manifest entry can move out of `legacy-next`:

* a `route-overrides.json` entry with a non-empty evidence note that marks the
  legacy artifact as `migrated` or `accepted-removal`
* an OpenAPI path or schema update in `apps/backend/api/openapi.yaml`
* a Rust route dispatcher test covering the success case; full-route ownership
  also needs unsupported method behavior, while method-level ownership needs an
  assertion that still-legacy sibling methods are not claimed by Rust
* a `packages/internal-api` facade when the TanStack app or shared UI needs to
  call the endpoint

Contact/profile backend routes now meet that terminal bar for the app-session
contract used by TanStack contact: `GET /api/v1/users/me/profile`,
`PATCH /api/v1/users/me/profile`, and `POST /api/v1/inquiries` verify
`ttr_app_` app-session JWTs, enforce same-origin mutation checks for cookie
auth, validate request bodies, call Supabase REST through the server-owned Rust
outbound adapter, and have mocked native/Worker persistence tests.
`PATCH /api/v1/users/me/full-name` separately revalidates the browser Supabase
session, validates the required trimmed `full_name`, and upserts the
authenticated user's `user_private_details` row with the caller token.
`GET` / `PATCH` `/api/v1/users/me/default-workspace` separately preserves the
legacy default-workspace read fallback to `null`, supports current-user
app-session reads, and updates the authenticated user's saved default workspace
only after caller-token workspace membership validation.
`PATCH /api/v1/inquiries/:id` separately revalidates the browser Supabase
session, requires a Tuturuuu/XWF email domain, and updates the inquiry admin
flags through the same Rust Supabase REST adapter. Broader Supabase session
revalidation remains part of the dedicated auth migration milestone, so route
notes must stay explicit about the app-session versus browser-session boundary.

`scripts/backend-openapi-migration-contract.test.js` compares the migrated
Rust-owned route artifacts in `apps/tanstack-web/migration/route-manifest.json`
with `apps/backend/api/openapi.yaml`. Add or update the OpenAPI operation in the
same commit that marks a Rust route artifact `migrated`; otherwise `bun validate`
fails.

For method-level overrides, the same evidence applies to each migrated method,
and the route override must leave every unmigrated sibling method as a generated
`legacy-next` artifact. Do not mark a full route migrated only because a safe
preflight or placeholder method is implemented in Rust.

The manifest check compares both aggregate method counts and each route's method
list against the current `apps/web/src/app` tree, including generated export
patterns such as `createOfflineRoute(...)` exports. Regenerate
the manifest after adding, removing, or changing exported methods in a legacy
`route.ts`. Non-terminal routes with `methods: []` are still artifacts in the
ownership inventory; port, restore an exported method, or mark them
`accepted-removal` with an explicit reason before cutover.

Rust JSON responses must keep the shared response security defaults:
`Content-Type: application/json`, `Content-Security-Policy: default-src 'none';
frame-ancestors 'none'; base-uri 'none'`, `Referrer-Policy: no-referrer`,
`X-Content-Type-Options: nosniff`, and `X-Frame-Options: DENY`. Route ports that
replace legacy public probes or API handlers must preserve explicit cache
behavior, including `Cache-Control: no-store` for `/api/health` and
`Cache-Control: public, max-age=300, must-revalidate` for `/.well-known/*`.
Non-JSON routes should use the empty-response path instead of serializing JSON
`null` when the legacy handler returned no body.

Protected workspace, cron, job, and admin endpoints stay server-owned. Browser
code cannot call protected Rust routes directly, cannot receive service tokens,
and cannot bypass `packages/internal-api` / TanStack server functions for
session-aware data access. Worker-bound secrets belong in Cloudflare secret
bindings; keep local, Docker, and Wrangler configuration to environment
variable names only.

For Cloudflare specifically:

* Bind `BACKEND_INTERNAL_TOKEN`, `BACKEND_PUBLIC_ORIGIN`, `SUPABASE_URL`,
  `SUPABASE_SERVICE_ROLE_KEY`, `CRON_SECRET`, and
  `DISCORD_APP_DEPLOYMENT_URL`, plus `AURORA_EXTERNAL_URL` and
  `AURORA_EXTERNAL_WSID`, with `wrangler secret put`,
  `wrangler versions secret put`, or Cloudflare dashboard secret bindings.
  The TanStack Worker reaches the backend Worker through the `BACKEND` service
  binding; configure `BACKEND_INTERNAL_URL` only for non-binding HTTP fallback
  runs. Use `secret put` for first preview bootstrap only because it deploys a
  new active version immediately; use the versions command family for
  rotations and canaries.
* Bind `TUTURUUU_APP_COORDINATION_SECRET` on the backend Worker before testing
  contact/profile routes. The Rust verifier also accepts existing
  app-coordination fallback secret names for compatibility, but the dedicated
  secret name is the preferred Cloudflare binding.
* Keep local Worker secret values in ignored `apps/backend/.dev.vars` and
  `apps/tanstack-web/.dev.vars` files. Do not commit literal origins that are
  account-specific private targets, tokens, API keys, cookies, or session
  material.
* `CMS_APP_URL` and `NEXT_PUBLIC_CMS_APP_URL` are public origin allowlist inputs
  for the WebGL upload preflight. They may be supplied through Wrangler vars or
  local `.dev.vars`, but they are not backend tokens and must not be listed as
  required secrets.
* Keep private/admin data ownership server-side. If a migrated endpoint needs a
  Supabase service role or private schema access, the Rust backend owns that
  call path; the browser receives only the authorized response shape.
* Review CORS, cookie domain, `SameSite`, secure-cookie, and session-origin
  behavior before mapping a custom hostname. Preview `workers.dev` origins are
  different sites from `tuturuuu.localhost` and production `tuturuuu.com`, so
  cookie/session behavior must be proven with smoke or E2E evidence rather than
  assumed from Docker.
* Keep `BACKEND_ENV=preview` for Cloudflare preview. Development-only
  migration routes and local E2E bypasses must not be enabled by Worker deploys.
* Do not bypass the migration gate because a Worker smoke passed. Worker smoke
  proves deploy compatibility; cutover still requires manifest, Docker E2E, and
  benchmark evidence.

Migration inventory endpoints are also protected because they expose checked
legacy route source paths and route ownership state. `GET /api/migration/status`,
`GET /api/migration/manifest`, `GET /api/migration/progress`, and
`GET /api/migration/cutover-gates` require
`Authorization: Bearer <BACKEND_INTERNAL_TOKEN>`. The TanStack migration
dashboard calls them from a Start server function through
`packages/internal-api`, which adds the bearer token only on the server.

The first Rust-owned migration contracts are exposed from `apps/backend` and
consumed by the TanStack shell through a Start server function:

| Endpoint | Purpose |
| - | - |
| `GET /.well-known/*` / `HEAD /.well-known/*` | Legacy-compatible cacheable empty `404` for unsupported well-known probes. |
| `GET /~recover-browser-state` / `POST /~recover-browser-state` | Legacy-compatible browser recovery route with no-store HTML, same-origin POST protection, Clear-Site-Data, auth cookie clearing, and login redirect. |
| `GET /api/health` | Legacy-compatible health route migrated from `apps/web` to Rust. |
| `GET /api/auth/me` | Legacy-compatible current Supabase user route backed by browser Supabase cookie or non-app-session Bearer revalidation through Supabase Auth, returning the raw user payload with no-store headers. |
| `GET /api/auth/mfa/totp/assurance-level` | Legacy-compatible Supabase MFA assurance-level route backed by browser Supabase cookie or non-app-session Bearer revalidation, JWT `aal`/`amr` claims, and verified factors from the revalidated user JSON. |
| `GET` / `POST` `/api/auth/mfa/totp/factors` | Legacy-compatible Supabase TOTP factor list/enrollment routes backed by browser Supabase cookie or non-app-session Bearer revalidation and Supabase Auth REST for enrollment. |
| `GET` / `DELETE` `/api/auth/mfa/totp/factors/:factorId` | Legacy-compatible Supabase TOTP factor detail/unenrollment routes backed by Auth JS-compatible factor listing and Supabase Auth REST unenrollment. |
| `GET /api/v1/calendar/mock` | Legacy-compatible deterministic mock calendar events migrated from `apps/web` to Rust. |
| `GET /api/v1/devboxes/cache` and `POST /api/v1/devboxes/cache/prune` | Legacy-compatible devbox cache routes accepting platform CLI app-session access tokens or browser Supabase sessions, requiring root workspace `MEMBER` access, returning the current empty cache list body, and acknowledging prune requests without private devbox table mutations. |
| `GET` / `POST` `/api/v1/aurora/forecast`, `/ml-metrics`, and `/statistical-metrics` | Legacy-compatible Aurora forecast and metric readers plus protected ingest routes backed by Supabase Auth, the legacy Tuturuuu email-domain gate, external Aurora fetches, and caller-token Supabase inserts. |
| `POST` / `DELETE` `/api/v1/infrastructure/languages` | Legacy-compatible locale preference cookie route for `NEXT_LOCALE`. |
| `POST` / `DELETE` `/api/v1/infrastructure/sidebar` | Legacy-compatible sidebar collapsed preference cookie route for `sidebar-collapsed`. |
| `POST` / `DELETE` `/api/v1/infrastructure/sidebar/sizes` | Legacy-compatible sidebar sizing preference cookie route for `sidebar-size` and `main-content-size`. |
| `GET /api/v1/infrastructure/users/fields/types` | Legacy-compatible static user field type metadata route returning `TEXT`, `NUMBER`, `BOOLEAN`, `DATE`, and `DATETIME` in the original order. |
| `GET /api/v1/infrastructure/ai/models` | Legacy-compatible public AI model catalog backed by private-schema Supabase REST reads with a fixed public column list, filters, sanitized search, capped ID filters, and exact-count pagination. |
| `GET /api/admin/tasks/embeddings/stats` | Legacy-compatible Tuturuuu-admin task embedding coverage stats backed by Supabase Auth cookie validation and server-owned exact task counts. The SSE embedding generator remains legacy-owned. |
| `GET /api/:wsId/crawlers/list` | Legacy-compatible authenticated crawled URL listing backed by Supabase Auth cookie validation, server-owned raw `crawled_urls` reads, exact-count pagination, and an explicit 401 for non-Tuturuuu callers. |
| `GET /api/v1/workspaces/:wsId/crawlers/status` | Legacy-compatible workspace-agnostic crawler status lookup backed by server-owned exact `crawled_urls.url` reads and raw related `crawled_url_next_urls` rows ordered by `created_at.desc`. |
| `GET /api/v1/ai/whitelist/me` | Legacy-compatible authenticated current-user AI whitelist status backed by satellite app-session auth or browser Supabase cookie auth and a server-owned private-schema enabled-flag lookup. |
| `GET /api/v1/cms/workspaces` | Legacy-compatible CMS workspace list backed by app-session or browser Supabase auth, service-role workspace reads, root-admin/per-workspace external-project permission checks, active binding resolution, and subscription tier metadata. |
| `GET /api/v1/mira/achievements` | Legacy-compatible Mira achievement catalog backed by browser Supabase auth, private-schema service-role catalog reads, caller-token unlocked-achievement reads, and derived unlock/grouping/stat payloads. |
| `GET /api/v1/storage/list` | Legacy-compatible workspace Drive object list backed by `ttr_` workspace API-key validation, `manage_drive` permission checks, path sanitization, reserved mobile-deployment vault blocking, server-owned Supabase Storage list calls, placeholder/reserved-entry filtering, and recursive file-count pagination. |
| `GET /api/time-tracking/export` | Legacy-compatible root-only grouped time-tracking export backed by browser Supabase auth, Tuturuuu email-domain gating, root workspace membership checks, caller-token `get_grouped_sessions_paginated` RPC calls, parseInt-style query defaults, a 1000-row limit cap, and the legacy empty-result fallback. |
| `GET /api/v1/hive/ai/models` | Legacy-compatible Hive AI model catalog backed by Hive app-session or browser Supabase auth, Hive member/admin access, and server-owned private-schema model reads mapped to the shared UI model shape. |
| `GET /api/v1/users/me/hive-access` | Legacy-compatible authenticated current-user Hive access status backed by current-user app-session auth or browser Supabase cookie auth and server-owned membership/admin flag lookups. |
| `GET /api/v1/nova/me/team` | Legacy-compatible authenticated current-user Nova team lookup backed by Nova app-session auth or browser Supabase cookie auth and a server-owned private-schema team membership lookup. |
| `GET /api/v1/task-board-status-templates` | Legacy-compatible authenticated global task-board status template catalog backed by Supabase cookie or Bearer auth and server-owned ordered catalog reads. |
| `GET /api/v1/workspaces/limits` | Legacy-compatible authenticated workspace creation limit check backed by Supabase Auth cookie validation and server-owned exact counts of non-deleted workspaces created by the caller. |
| `GET /api/v1/workspaces/:wsId/posts/permissions` | Legacy-compatible post permission flag reader backed by Supabase Auth revalidation and server-owned `has_workspace_permission` RPC checks, preserving quiet false flags for missing auth or unresolved permissions. |
| `GET /api/v1/workspaces/:wsId/Mention` | Legacy-compatible mention email endpoint backed by Supabase Auth revalidation, exact `MEMBER` workspace membership, and caller-token `workspace_users.email` reads. |
| `GET /api/v1/workspaces/:wsId/habits/access` | Legacy-compatible habits feature access probe backed by Supabase Auth revalidation, workspace normalization, service-role membership validation, and exact `ENABLE_HABITS=true` workspace secret matching. |
| `GET /api/v1/workspaces/:wsId/mobile/module-flags` | Legacy-compatible mobile module flag endpoint backed by Supabase Auth revalidation, caller-token workspace membership, and server-owned `workspace_secrets` reads for hidden module policy. |
| `GET /api/v1/workspaces/:wsId/education/access` | Legacy-compatible education feature access probe backed by Supabase Auth revalidation, getPermissions-compatible `ai_lab` checks, and server-owned `workspace_secrets` `ENABLE_EDUCATION` reads. |
| `GET /api/v1/workspaces/:wsId/finance/budgets/status` | Legacy-compatible budget status probe backed by finance/platform app-session or Supabase Auth revalidation, workspace normalization, `manage_finance` permission checks, and server-owned `get_budget_status` RPC reads. |
| `GET /api/workspaces/:wsId/finance/charts/balance` | Legacy-compatible balance chart point backed by finance/platform app-session or Supabase Auth revalidation, workspace normalization, `view_finance_stats` checks, and `get_wallet_balance_at_date` RPC reads. |
| `GET /api/v1/workspaces/:wsId/finance/debts/summary` | Legacy-compatible debt and loan summary probe backed by finance/platform app-session or Supabase Auth revalidation, workspace normalization, `manage_finance` checks, and private `get_debt_loan_summary` RPC reads. |
| `GET /api/v1/workspaces/:wsId/finance/filter-users` | Legacy-compatible finance filter user endpoint backed by finance/platform app-session or Supabase Auth revalidation, workspace normalization, `view_transactions` checks, service-role creator reads, and caller-token workspace user reads. |
| `GET /api/v1/workspaces/:wsId/finance/invoices/subscription/context` | Legacy-compatible subscription invoice context endpoint backed by finance/platform app-session or Supabase Auth revalidation, workspace normalization, `create_invoices` checks, student group validation, and service-role attendance/invoice reads. |
| `GET /api/v1/workspaces/:wsId/finance/recurring-transactions/upcoming` | Legacy-compatible upcoming recurring transaction probe backed by finance/platform app-session or Supabase Auth revalidation, workspace normalization, `view_transactions` checks, and `get_upcoming_recurring_transactions` RPC reads. |
| `GET /api/v1/workspaces/:wsId/settings/permissions` | Legacy-compatible workspace settings permission flags backed by Supabase Auth revalidation, personal/workspace identifier resolution, membership validation, server-owned role/default permission reads, and the private 30-second success cache directive. |
| `GET /api/v1/workspaces/:wsId/settings/permissions/check` | Legacy-compatible workspace permission checker backed by Supabase Auth revalidation, personal/workspace identifier resolution, membership validation, and server-owned role/default permission reads. |
| `GET /api/v1/workspaces/:wsId/course-modules` and `GET /api/v1/workspaces/:wsId/quiz-sets/:setId/linked-modules` | Legacy-compatible education module readers backing the TanStack linked-modules page, with browser Supabase auth, `ai_lab` permission resolution, `ENABLE_EDUCATION` gating, exact-count pagination, and quiz-set workspace binding. |
| `GET` / `PATCH` `/api/v1/user/onboarding-progress` | Legacy-compatible authenticated onboarding progress reader/updater backed by Supabase Auth cookie validation, server-owned `onboarding_progress` reads/upserts, and the legacy allowed-field update contract. |
| `PATCH /api/v1/user/profile` | Legacy-compatible browser-session profile update backed by Supabase Auth cookie validation, legacy profile field validation, and server-owned `users` row updates scoped to the authenticated user. |
| `GET` / `PATCH` `/api/v1/users/me/default-workspace` | Legacy-compatible default-workspace reader/updater backed by current-user app-session or browser Supabase auth for reads, caller-token membership validation for writes, and the legacy personal-workspace/null fallback. |
| `GET` / `PATCH` `/api/v1/users/calendar-settings` | Legacy-compatible current-user calendar settings reader/updater backed by calendar app-session or browser Supabase auth, `user_private_details` reads/writes, `auto` defaults, and legacy enum/string patch validation. |
| `GET /api/v1/users/me/identities` | Legacy-compatible browser-session linked identity reader backed by Supabase Auth revalidation, raw user JSON identity extraction, derived `canUnlink`, and the private success cache directive. |
| `PATCH /api/v1/users/me/full-name` | Legacy-compatible browser-session full-name update backed by Supabase Auth cookie validation, required trimmed `full_name` validation, and caller-token `user_private_details` upsert scoped to the authenticated user. |
| `POST /api/v1/aurora/health` | Legacy-compatible protected Aurora health probe backed by Supabase Auth cookie validation, the legacy Tuturuuu email-domain gate, and an outbound `AURORA_EXTERNAL_URL/health` check. |
| `GET` / `POST` `/api/v1/internal/holidays`, `POST` `/api/v1/internal/holidays/bulk`, and `PUT` / `DELETE` `/api/v1/internal/holidays/:holidayId` | Rust counterparts for the Infrastructure-owned Vietnamese holiday list/create/bulk-import/update/delete routes. GET uses the Rust server-owned Supabase REST adapter with optional parseInt-style year filtering. Mutations revalidate Supabase auth, require root workspace `MEMBER` access, and write with the caller token so holiday RLS stays active. Bulk import preserves the replace-existing year delete plus date-conflict upsert behavior. |
| `GET /api/v1/topic-announcement-verifications/:token` | Legacy-compatible public Topic Announcements email verification route backed by server-owned private-schema Supabase REST reads and updates. Workspace Topic Announcements management APIs remain legacy-owned. |
| `GET /api/v1/users/me/profile` | App-session current-user profile route. It verifies `ttr_app_` JWTs, reads `users` and `user_private_details` through the server-owned Supabase REST adapter, and returns the legacy profile shape with no-store headers. |
| `PATCH /api/v1/users/me/profile` | App-session profile mutation route. It enforces same-origin confirmation for cookie auth, validates `display_name`, `bio`, and `avatar_url`, and persists the allowed fields to the `users` row through Supabase REST. |
| `POST /api/v1/inquiries` | App-session support-inquiry route. It enforces same-origin confirmation for cookie auth, validates the legacy payload and field limits, and inserts `support_inquiries` with `creator_id` from the resolved app-session user. |
| `PATCH /api/v1/inquiries/:id` | Browser-session inquiry admin update route. It validates the legacy `is_read` and `is_resolved` flags, requires a Tuturuuu/XWF email domain, and patches `support_inquiries` through the server-owned Supabase REST adapter. |
| `OPTIONS /api/v1/auth/password-login`, `/otp/send`, and `/otp/verify`; `GET` / `OPTIONS` `/api/v1/auth/otp/settings` | Legacy-compatible shared wildcard CORS preflights plus public OTP availability lookup backed by the root workspace OTP config reads. Paired OTP send/verify and password auth methods remain legacy-owned. |
| `OPTIONS /api/v1/auth/mobile/password-login`, `/send-otp`, and `/verify-otp` | Method-level legacy-compatible shared wildcard CORS `204` preflights; paired mobile auth methods remain legacy-owned. |
| `GET` / `PUT` `/api/v1/infrastructure/mobile-versions` | Legacy-compatible protected mobile policy snapshot and write route requiring a revalidated Supabase browser session or Bearer token plus root `manage_workspace_roles`; writes normalize the policy payload and upsert all nine root config rows. |
| `GET` / `POST` `/api/v1/infrastructure/timezones` and `PUT` / `DELETE` `/api/v1/infrastructure/timezones/:timezoneId` | Legacy-compatible protected timezone collection plus detail update/delete routes requiring a revalidated Supabase browser session or Bearer token plus root `manage_workspace_roles`, backed by server-owned private-schema `timezones` reads/writes. |
| `GET /api/v1/infrastructure/user-status-changes` | Legacy-compatible workspace user status change list backed by caller-token Supabase REST reads so `workspace_user_status_changes` RLS, exact count, required `ws_id`, and legacy `limit`/`offset` range behavior stay intact. |
| `GET /api/v1/infrastructure/users` | Legacy-compatible workspace user export list backed by caller-token Supabase REST reads so `workspace_users` RLS, exact count, required `ws_id`, and legacy `limit`/`offset` range behavior stay intact. |
| `GET /api/v1/infrastructure/classes`, `/product-categories`, and `/score-names` | Legacy-compatible catalog export lists backed by caller-token Supabase REST reads so `workspace_user_groups`, `product_categories`, and `user_group_metrics` RLS and exact-count pagination stay intact. |
| `GET /api/v1/infrastructure/lessons` and `/packages` | Legacy-compatible content export lists for private `user_group_posts` and `workspace_products`, preserving exact-count pagination, legacy auth shape for packages, and the no-auth lesson export behavior. |
| `GET /api/v1/infrastructure/product-prices`, `/product-units`, and `/warehouses` | Legacy-compatible inventory setup exports for private `inventory_products`, `inventory_units`, and `inventory_warehouses`, preserving inventory app-session auth, catalog/setup permission checks, exact-count pagination, and error bodies. |
| `GET` / `POST` `/api/v1/infrastructure/ai/whitelist/domains` and `/emails` | Legacy-compatible protected AI whitelist collection routes backed by service-role private-schema reads/inserts after Supabase auth and `@tuturuuu.com` operator email validation. |
| `PUT` / `DELETE` `/api/v1/infrastructure/ai/whitelist/:email` and `/domain/:domain` | Legacy-compatible protected AI whitelist detail update/delete backed by service-role private-schema writes after Supabase auth and `@tuturuuu.com` operator email validation. |
| `GET /api/v1/infrastructure/post-email-queue` | Legacy-compatible protected post email queue infrastructure summary backed by service-role `post_email_queue` reads after root workspace membership validation, preserving summary, workspace, and batch aggregation behavior. |
| `GET /api/v1/infrastructure/bills`, `/roles`, and `/transaction-categories` | Legacy-compatible workspace export lists backed by caller-token Supabase REST reads so `finance_invoices`, `workspace_user_groups`, and `transaction_categories` RLS and exact-count pagination stay intact. |
| `GET /api/v1/infrastructure/wallet-transactions` | Legacy-compatible protected wallet transaction export backed by the caller-token `get_wallet_transactions_with_permissions` RPC with legacy ordering, limit/offset, raw rows, and first-row `total_count` extraction. |
| `GET /api/v1/infrastructure/abuse-intelligence` | Legacy-compatible protected abuse intelligence snapshot backed by caller-token reputation subject, signal, and challenge reads plus service-role active trust override reads after root `view_infrastructure` permission validation. |
| `GET /api/v1/infrastructure/abuse-events` | Legacy-compatible root-workspace abuse event list backed by caller-token Supabase REST reads with legacy `ip`/`type`/`success` filters, page/pageSize pagination, exact counts, and auth/error bodies. |
| `GET /api/v1/infrastructure/blocked-ips` | Legacy-compatible root-workspace blocked IP list backed by caller-token Supabase REST reads with the legacy `unblocked_by_user` embed, status/ip filters, page/pageSize pagination, exact counts, and auth/error bodies. |
| `GET /api/v1/infrastructure/suspensions` | Legacy-compatible active user suspension list backed by service-role `user_suspensions` reads after root `manage_workspace_roles`; POST and detail DELETE remain legacy-owned mutation methods. |
| `GET` / `POST` `/api/v1/infrastructure/email-blacklist` and `GET` / `PUT` / `DELETE` `/api/v1/infrastructure/email-blacklist/:entryId` | Legacy-compatible root-workspace email blacklist reads, creation, detail update, and detail deletion backed by caller-token Supabase REST with Zod-style write validation parity. |
| `GET /api/v1/infrastructure/bill-coupons`, `/bill-packages`, `/class-attendance`, `/class-members`, `/class-packages`, `/class-scores`, `/package-stock-changes`, and `/student-feedbacks` | Legacy-compatible related-filter export lists backed by caller-token Supabase REST reads with embedded workspace relationships and exact-count pagination. |
| `GET /api/v1/infrastructure/user-monthly-reports` and `/user-monthly-report-logs` | Legacy-compatible protected monthly report export lists backed by shared workspace permission resolution and private-schema Supabase REST exact-count pagination. |
| `GET` / `OPTIONS` `/api/v1/mobile/version-check` | Legacy-compatible public mobile version policy evaluation and shared wildcard CORS preflight backed by fixed root workspace policy config IDs read through the Rust backend Supabase REST adapter. |
| `OPTIONS /api/v1/auth/qr-login/challenges[...]` | Method-level legacy-compatible bare empty `204` preflights for QR login challenge create, poll, and approve routes. |
| `OPTIONS /api/v1/auth/mfa/mobile/challenges[...]` and `/approvals[...]` | Method-level legacy-compatible bare empty `204` preflights for MFA mobile challenge create, poll, approve, and approval listing routes. |
| `OPTIONS /api/v1/workspaces/:wsId/external-projects/webgl-packages/upload` | Method-level legacy-compatible WebGL upload preflight with credentialed CMS CORS headers only for allowed CMS origins. |
| `POST /api/v1/workspaces/:wsId/user-groups/:groupId/group-checks/:postId/email` | Legacy-compatible removed direct post email route returning `410 Gone`; queue-based sending owns approved emails. |
| `GET` / `POST` `/api/v1/workspaces/:wsId/slides` | Legacy-compatible workspace slides collection placeholder returning `501 Not implemented`. |
| `PUT` / `DELETE` `/api/v1/workspaces/:wsId/slides/:slideId` | Legacy-compatible workspace slide item placeholder returning `501 Not implemented`. |
| `PUT /api/v1/infrastructure/migrate/grouped-score-names` | Disabled infrastructure migration route migrated from `apps/web` to Rust with the same development-only guard and `410 MIGRATION_DISABLED` body. |
| `GET` / `PUT` / `PATCH` / `POST` `/api/v1/infrastructure/migrate/:migration` | Accepted-removal terminal decommission for legacy batch migration helpers; Rust preserves the development/local-E2E guard and per-slug legacy method allow lists while returning `410 MIGRATION_DISABLED`. |
| `PUT /api/workspaces/:wsId/products/categories/migrate`, `/products/units/migrate`, `/transactions/categories/migrate`, `/users/indicators/migrate`, and `/wallets/transactions/migrate` | Obsolete workspace migration writes accepted for removal; Rust keeps the development-only guard and returns a terminal `410 MIGRATION_DISABLED` response. |
| `GET` / `POST` `/api/v1/workspaces/:wsId/encryption/migrate`, `POST /api/v1/workspaces/:wsId/storage/migrate`, `GET /api/v2/workspaces/:wsId/migrate/:module` | Production auth/API-key migration helpers accepted for removal; Rust keeps the legacy method allow lists and returns terminal `410 MIGRATION_DISABLED` in all environments. |
| `GET /api/migration/status` | Runtime, environment, deployment target, and manifest pointer. |
| `GET /api/migration/manifest` | The checked route manifest JSON. |
| `GET /api/migration/progress` | Owner/kind progress buckets and representative remaining legacy route artifacts. |
| `GET /api/migration/cutover-gates` | Backend-derived manifest gates plus required E2E and benchmark evidence placeholders. |

`/api/migration/cutover-gates` is the dashboard authority for cutover state. It
must stay blocked while any manifest route remains `legacy-next`, any backend
route artifact is not mapped to `rust-backend`, or required Docker E2E and
benchmark evidence is missing.

## Docker And E2E

The production compose stack defines `tanstack-web`, `tanstack-web-blue`, and
`tanstack-web-green` services. The Docker Bake file includes matching
`blue-green-tanstack-web*` targets so benchmark and cutover work can build
candidate TanStack images beside the legacy web images.

`apps/backend/Dockerfile` copies
`apps/tanstack-web/migration/route-manifest.json` into the Rust build context
because the backend includes the manifest at compile time for the migration
contract endpoints. Run `bun check:docker` after manifest path or Dockerfile
changes.

Legacy E2E remains the default:

```bash theme={null}
bun test:e2e:web:docker -- --frontend next
```

TanStack E2E uses the same Playwright suite and points at the TanStack route:

```bash theme={null}
bun test:e2e:web:docker -- --frontend tanstack
```

Run both modes sequentially before cutover:

```bash theme={null}
bun test:e2e:web:docker -- --frontend compare
```

Compare mode writes `tmp/e2e/web-migration/compare-report.json` after running
both frontends. Each frontend result includes normalized origin evidence,
`passRate`, `wallMs`, and Playwright JSON reporter test counts so
`bun migration:tanstack:gates` can evaluate same-origin mistakes, E2E
regressions, and zero-test false positives from the same evidence file. The gate
rejects missing, credentialed, invalid, or identical Next/TanStack origins, and
it rejects compare reports that do not prove nonzero Playwright execution for
both frontends. Set `E2E_COMPARE_REPORT_PATH` when a run needs to write the file
elsewhere under `tmp/`.

`apps/web/e2e/public-marketing-routes.noauth.spec.ts` is the first shared
public-route parity suite for this migration. It runs under the existing
`apps/web` Playwright project so `--frontend tanstack` and `--frontend compare`
reuse the same assertions for migrated landing, product, legal, redirect,
offline, branding, blog, careers, demo, security, partners, UI docs,
visualization, and static solution routes.

`scripts/public-marketing-e2e-coverage.test.js` compares the migrated public
page entries in `apps/tanstack-web/migration/route-manifest.json` with that
no-auth Playwright spec. When a public marketing, UI docs, redirect, or offline
page is marked `migrated`, the route needs a concrete default-locale E2E
example in the shared spec before `bun validate` can pass.

## Benchmarks

Use the benchmark harness to compare reachable Next and TanStack frontend
routes, plus independent Rust backend smoke routes. It does not yet compare
legacy Next.js API route timing against equivalent Rust endpoints. Reports are
written under ignored
`tmp/benchmarks/web-migration/<timestamp>/report.json`.

```bash theme={null}
bun benchmark:web-setups -- --setup compare --profile smoke
```

Backend benchmark samples include protected migration endpoints. Set
`BACKEND_INTERNAL_TOKEN` when running the benchmark against local Docker,
preview Workers, or any backend that requires internal authorization; otherwise
the protected samples correctly fail as unreachable `4xx` responses.

To compare the legacy production/staging origin against Cloudflare preview
Workers, pass all origins explicitly:

```bash theme={null}
BACKEND_INTERNAL_TOKEN="${BACKEND_INTERNAL_TOKEN:?set BACKEND_INTERNAL_TOKEN}" \
bun benchmark:web-setups -- \
  --setup compare \
  --profile smoke \
  --next-origin https://<legacy-next-origin> \
  --tanstack-origin https://<tanstack-worker-origin> \
  --backend-origin https://<backend-worker-origin>
```

Compare reports must prove that the legacy Next.js and TanStack Start samples
came from distinct normalized frontend origins. `bun benchmark:web-setups`
rejects same-origin compare runs before writing a report, and
`bun migration:tanstack:gates` rejects benchmark evidence with missing origins,
credentialed origins, identical Next/TanStack origins, route/sample URLs that do
not match the recorded setup origin, or matched frontend routes without their
own `frontend-route-p95` comparison. Docker E2E compare evidence uses the same
distinct-origin rule for the browser-facing Next and TanStack frontend runs.

Use full mode when both frontends are running with representative seeded data:

```bash theme={null}
bun benchmark:web-setups -- --setup compare --profile full --require-all
```

In compare mode, `--require-all` fails the benchmark command when any required
metric evidence is missing. That keeps local benchmark rehearsals aligned with
`bun migration:tanstack:gates` instead of deferring missing dev-ready, build,
image-size, RSS/CPU, JS-output, E2E, or API latency evidence until cutover.

Pass reviewer-approved non-HTTP metrics and accepted regression notes through
`--evidence` when the harness cannot measure them directly:

```json theme={null}
{
  "metrics": {
    "backend": {
      "apiLatencyP50Ms": 80,
      "apiLatencyP95Ms": 120,
      "apiLatencyP99Ms": 180
    },
    "next": {
      "apiLatencyP50Ms": 75,
      "apiLatencyP95Ms": 110,
      "apiLatencyP99Ms": 170,
      "devReadyMs": 2200,
      "dockerBuildMs": 240000,
      "e2ePassRate": 1,
      "e2eWallMs": 90000,
      "firstRouteColdMs": 650,
      "imageSizeBytes": 1200000000,
      "jsOutputBytes": 850000,
      "productionCpuPercent": 4,
      "productionRssBytes": 640000000,
      "warmNavigationMs": 180
    },
    "tanstack": {
      "devReadyMs": 1800,
      "dockerBuildMs": 180000,
      "e2ePassRate": 1,
      "e2eWallMs": 84000,
      "firstRouteColdMs": 520,
      "imageSizeBytes": 760000000,
      "jsOutputBytes": 620000,
      "productionCpuPercent": 3,
      "productionRssBytes": 420000000,
      "warmNavigationMs": 140
    }
  },
  "acceptedRegressions": [
    {
      "metric": "first-route-cold-time",
      "note": "Approved while Cloudflare preview cache is cold."
    }
  ]
}
```

```bash theme={null}
bun benchmark:web-setups -- \
  --setup compare \
  --profile full \
  --require-all \
  --evidence tmp/benchmarks/web-migration/evidence.json
```

After the full benchmark writes a report, pass that report to
`bun migration:tanstack:gates` with the Docker E2E compare report and
Cloudflare smoke report. Generated benchmark, smoke, and E2E reports stay under
ignored `tmp/` paths. Cutover gates reject evidence older than 24 hours by
default; use `--evidence-max-age-ms <milliseconds>` only when a rehearsal
explicitly accepts a longer freshness window.

Default gates:

* frontend route p95 must not regress more than `25%`
* Cloudflare smoke evidence must include passing `backend-health`,
  `backend-ready`, `backend-migration-status`,
  `backend-migration-status-missing-token`,
  `backend-migration-status-invalid-token`, and `tanstack-root` probes
* cutover reports must include the full metric comparison contract:
  API p50/p95/p99, dev ready time, first-route cold time, warm navigation time,
  Docker build time, image size, JS output size, production RSS/CPU baseline,
  E2E wall time, and E2E pass rate, with numeric baseline, candidate, ratio,
  and threshold values for each required comparison
* full compare evidence must include complete matching frontend route coverage;
  unmatched Next-only or TanStack-only routes fail `--require-all` and cutover
  gate validation
* representative backend smoke routes must stay below the smoke ceiling
* strict runs fail when any required route is unreachable

Route samples include aggregate `p50Ms`, `p95Ms`, and `p99Ms`, plus `coldMs`
for the first successful request and `warmP50Ms` / `warmP95Ms` / `warmP99Ms`
for later samples. Use those fields for first-route cold time, warm navigation
time, and representative API latency notes. Add Docker build time, image size,
process RSS/CPU, JS output size, and E2E wall-time evidence to the same
benchmark directory when running full cutover rehearsals.

Record approved exceptions in the migration PR. Do not silently widen thresholds
to make a run pass.

## Cutover Checklist

1. Every manifest route is `migrated` or `accepted-removal`.
2. `bun migration:tanstack:cutover-check` passes.
3. `bun test:e2e:web:docker -- --frontend compare` passes and has a compare
   evidence report.
4. `bun benchmark:web-setups -- --setup compare --profile full --require-all` passes or has approved exceptions. HTTPS origins must present a certificate trusted by the host; use the local development CA or `NODE_EXTRA_CA_CERTS` instead of disabling certificate verification.
5. `bun smoke:cloudflare --output <path>` passes against the preview Workers.
6. `bun migration:tanstack:gates -- --e2e-report <path> --benchmark-report <path> --cloudflare-smoke-report <path>` passes.
7. `bun check:docker` and `bun validate` pass.
8. Legacy `apps/web` remains available as the rollback fixture until production
   monitoring shows the TanStack/Rust path is stable.

# TanStack/Rust Migration Plan
Source: https://docs.tuturuuu.com/platform/architecture/tanstack-rust-migration-plan

Phased plan for replacing apps/web with apps/tanstack-web and apps/backend.

This page is the discoverable docs copy of the root migration plan for replacing
the legacy Next.js platform app with a dedicated TanStack Start frontend and a
Rust backend.

Use the architecture contract at
`platform/architecture/tanstack-rust-migration` for route ownership rules and
implementation patterns. Use the operational runbook at
`build/devops/tanstack-rust-cutover-runbook` for dual-stack bring-up and final
cutover evidence. Use this page for sequencing, verification gates, and
agent-lane planning.

## Current Snapshot

The route manifest at `apps/tanstack-web/migration/route-manifest.json` is the
source of truth. The latest local snapshot on 2026-10-04 is:

| Status | Count |
| - | -: |
| `legacy-next` | 641 |
| `migrated` | 216 |
| `accepted-removal` | 14 |
| Total tracked artifacts | 871 |

Remaining legacy artifacts are concentrated in API/backend ownership:

| Kind | Remaining legacy artifacts |
| - | -: |
| API | 553 |
| Cron | 8 |
| Error boundary | 1 |
| Loading boundary | 1 |
| tRPC | 1 |
| Route handler | 1 |
| Page | 55 |
| Layout | 21 |

The production target is:

* `apps/tanstack-web` as the user-facing frontend.
* `apps/backend` as the Rust-owned API/backend runtime.
* `apps/web` kept only as a rollback fallback until terminal cutover gates are
  green.

## First Verification Gap Closure

Before accelerating route waves, keep the verification layer green and visible:

* Expose the dual-stack Docker E2E runner through the root package scripts.
* Keep `scripts/run-tanstack-e2e-docker.test.js` inside `test:scripts`.
* Run actual CI coverage for the minimal TanStack/Rust dual-stack compose stack.
* Run CI compare-mode coverage against a focused public no-auth Playwright
  smoke before broader cutover rehearsals.
* Keep the migration plan and cutover runbook discoverable from `apps/docs`.

The root commands are:

```bash theme={null}
bun test:e2e:tanstack:docker -- -- --project=chromium
bun test:e2e:web:docker:compare -- public-marketing-routes.noauth.spec.ts --project=chromium-no-auth
```

The double separator in the first command is intentional when invoking through
Bun: the first `--` separates Bun args, and the second is forwarded to the
TanStack runner so Playwright receives the project flag.

## Backend Waves

Backend migration is the primary bottleneck. Batch Rust routes by domain and
keep each batch independently revertible:

1. Auth, session, account identity, and current-user profile.
2. Workspace core, membership, limits, and permissions/navigation prerequisites.
3. High-density `/api/v1/workspaces/*` domains that unblock authenticated pages.
4. Cron, tRPC, and remaining low-frequency API compatibility routes.

Each backend wave must update focused Rust tests, route helper abstractions when
patterns harden, `apps/backend/README.md` when runtime behavior changes, and the
OpenAPI contract through the coordinator-owned `apps/backend/api/openapi.yaml`.

## Frontend Waves

Frontend work should follow backend readiness rather than reintroduce protected
raw API calls:

1. Dashboard shell, providers, navigation, auth gate, and workspace permission
   parity.
2. Authenticated dashboard pages whose data APIs are Rust-owned.
3. Module and settings pages in domain batches.
4. Public/static pages that still have legacy route artifacts.
5. Decommission-only accepted removals.

Use TanStack Router loaders, `createServerFn`, TanStack Query, and the existing
`auth-gate`, `workspace`, and `workspace-permission` helpers. Shared UI and the
TanStack app must call typed internal-api/backend facades, not protected raw
Supabase reads or raw `/api/*` endpoints.

Every terminal route must be classified as one of:

* static prerender
* ISR/CDN cache
* dynamic no-store
* redirect
* accepted removal

### 2026-06-25 Frontend Scout Handoff

The first frontend-only scout wave deliberately rejected several compact-looking
routes because they would otherwise become shell-only migrations. Keep these
handoffs visible so parallel workers do not repeat the same audit:

| Candidate lane | Current finding | Next unblock |
| - | - | - |
| `/:locale/meet` and `/:locale/meet-together` | TanStack public preview shells exist, but legacy also shows authenticated meeting plans and creates plans through Supabase/server-action paths. | Add typed plan list/create APIs through Rust or TanStack server functions, then prove unauthenticated and authenticated parity with focused E2E. |
| `/:locale/:wsId/users/topic-announcements/import` | Migrated in the TanStack frontend as a dynamic no-store page with fail-closed auth, workspace and feature gates, `manage_users`, send-permission-aware create-and-send controls, client-only XLSX/CSV parsing, editable row validation, and typed internal-api import/send-bulk mutations. | Backend agents still need Rust ownership for `/api/v1/workspaces/:wsId/topic-announcements/import` and `/send-bulk` before full backend cutover. |
| `/:locale/:wsId/users/groups/:groupId/attendance` | Migrated in the TanStack frontend as a dynamic no-store page with fail-closed auth, workspace and group checks, `check_user_attendance`, `update_user_attendance` save gating, session/date URL state, and typed internal-api attendance/member/config/session facades. | Backend agents still need Rust ownership for the user-group attendance, members, workspace config, and session APIs before full backend cutover. |
| `/:locale/:wsId/billing` | `apps/pay` owns detailed billing, checkout, invoices, credits, subscriptions, webhooks, and payment mutations. `apps/web` retains only a read-only summary loaded from Pay through `packages/internal-api`; all actions link to Pay. | Treat the remaining web summary as an intentional satellite-app handoff. Do not restore payment mutations or detailed billing UI to either platform frontend. |
| `/:locale/:wsId/usage` | The page wrapper is small, but the content is a broad Supabase/RPC workspace usage dashboard. | Create a usage-summary backend contract or server-function bundle that returns permission-masked stats without direct Supabase reads in TanStack. |
| `/:locale/:wsId/ai/spark`, `/:locale/:wsId/mira`, and the canonical `/:locale/:wsId` Mira dashboard | Page files are compact, but the behavior is coupled to AI object APIs, Mira API routes, voice/live API helpers, or assistant providers. The standalone `/:locale/:wsId/assistant` route has been removed in favor of the unified workspace-root chat and rich voice experience. | Treat these as dedicated product lanes with typed AI/Mira/assistant facades and focused browser evidence. |

## Coordinator-Owned Artifacts

Only the migration coordinator should edit generated or contract artifacts:

* `apps/tanstack-web/src/routeTree.gen.ts`
* `apps/tanstack-web/migration/route-manifest.json`
* `apps/tanstack-web/migration/route-overrides.json`
* `apps/backend/api/openapi.yaml`
* `apps/docs/platform/architecture/tanstack-rust-migration.mdx`

Workers should own disjoint route/API/domain lanes and leave coordinator-owned
files for integration.

## Required Gates

Per backend wave:

* `cargo fmt --check`
* focused `cargo test --locked <module>`
* `cargo clippy --locked --all-targets --features native -- -D warnings`
* OpenAPI contract tests
* `bun migration:tanstack:check`

Per frontend wave:

* `bun --filter @tuturuuu/tanstack-web type-check`
* `bun --filter @tuturuuu/tanstack-web test`
* route-tree generator tests when route files change
* `bun migration:tanstack:check`
* TanStack API access checks
* focused Playwright when route behavior changes

Final cutover requires:

* `bun migration:tanstack:cutover-check`
* `bun migration:tanstack:gates`
* dual-stack Docker E2E evidence
* compare-mode Docker E2E evidence
* benchmark evidence
* Cloudflare smoke evidence
* final `bun validate`

## Commit Cadence

Commit after each independently revertible lane or small batch. In a shared
checkout, claim the commit window immediately before exact-path staging, inspect
the staged files, commit with a Conventional Commit subject, then release the
window. Do not run `bun git-sync` or push unless explicitly requested.

# tRPC Scaffold
Source: https://docs.tuturuuu.com/platform/architecture/trpc

What the tRPC layer in apps/web actually is today: a minimal, intentional stub kept alive during the TanStack/Rust migration

> [!WARNING]
>
> tRPC in this monorepo is an **intentional stub**, not the product API. The
> router in `apps/web/src/trpc/routers/_app.ts` exposes a single `healthCheck`
> procedure. There are **no** workspace, user, AI, or tasks routers, and there is
> **no** auth middleware. Product authentication and data flow through
> [`@tuturuuu/internal-api`](/platform/architecture/api-routes) helpers and REST
> routes under `/api/v1`, not tRPC. This page documents the real scaffold so you
> do not build on procedures that do not exist.

## Why a stub?

Rather than build out a tRPC API surface that would be thrown away, the team
keeps a minimal tRPC scaffold wired end-to-end so the type system and client
plumbing stay valid and ready, while all real reads and writes go through the
internal API client and REST routes. New product features should **not** add
tRPC routers — use the patterns in
[Data Fetching](/platform/architecture/data-fetching) and
[API Routes](/platform/architecture/api-routes).

> [!NOTE]
>
> A repository guard (`scripts/check-tanstack-api-access.js`, run as part of
> `bun validate`) forbids calls to `/trpc` from `apps/tanstack-web/src`. The
> TanStack app talks to the Rust backend and REST API, never to this stub.

## What actually exists today

```
apps/web/src/trpc/
├── init.ts                       # initTRPC + context + exported helpers
├── query.ts                      # makeQueryClient (superjson + rate-limit retry)
├── client.tsx                    # TRPCProvider + createTRPCReact client
├── server.ts                     # RSC caller + HydrateClient hydration helpers
└── routers/
    └── _app.ts                   # appRouter: a single healthCheck procedure

apps/web/src/app/api/trpc/[trpc]/route.ts   # fetch adapter (GET + POST)
```

Relevant versions in `apps/web/package.json`: `@trpc/server`, `@trpc/client`,
and `@trpc/react-query` are all on `^11.x`, paired with
`@tanstack/react-query` `^5.x` and `superjson` `^2.x`. (Check the manifest for
exact pinned versions; do not hard-code them in code.)

## Initialization (`init.ts`)

`init.ts` creates the tRPC instance with the superjson transformer and exports
helper factories. Note the **real** export names — there is no `router`,
`publicProcedure`, or `protectedProcedure`.

```typescript theme={null}
// apps/web/src/trpc/init.ts
import { initTRPC } from '@trpc/server';
import { cache } from 'react';
import superjson from 'superjson';

export const createTRPCContext = cache(async () => {
  // @see: https://trpc.io/docs/server/context
  // This is a placeholder context. There is no Supabase auth here —
  // login authentication uses API routes via @tuturuuu/internal-api.
  return { userId: 'user_123' };
});

const t = initTRPC.create({
  // superjson preserves Dates, Maps, Sets, etc. across the wire.
  transformer: superjson,
});

// Base router and procedure helpers
export const createTRPCRouter = t.router;
export const createCallerFactory = t.createCallerFactory;
export const baseProcedure = t.procedure;
```

Exported helpers:

| Export | What it is | Used by |
| - | - | - |
| `createTRPCContext` | Async cached context factory. Returns a hardcoded `{ userId: 'user_123' }` placeholder — **no real auth**. | `route.ts`, `server.ts` |
| `createTRPCRouter` | `t.router` — builds routers. | `routers/_app.ts` |
| `createCallerFactory` | `t.createCallerFactory` — builds RSC server callers. | `server.ts` |
| `baseProcedure` | `t.procedure` — the only procedure builder. | `routers/_app.ts` |

> [!WARNING]
>
> The context is a hardcoded stub, not an authenticated user. Do not read
> `ctx.userId` expecting a real identity, and do not invent a
> `protectedProcedure` / `isAuthed` middleware — none exists. If you need the
> signed-in user, use the auth helpers and `@tuturuuu/internal-api`, not tRPC.

## The root router (`routers/_app.ts`)

The entire API surface is one health-check query that keeps the tRPC type system
compiling:

```typescript theme={null}
// apps/web/src/trpc/routers/_app.ts
import { baseProcedure, createTRPCRouter } from '../init';

// tRPC router for the web app
// Login authentication uses API routes via @tuturuuu/internal-api.
export const appRouter = createTRPCRouter({
  // Health check procedure to maintain tRPC type system compatibility
  healthCheck: baseProcedure.query(() => {
    return { status: 'ok', timestamp: Date.now() };
  }),
});

// export type definition of API
export type AppRouter = typeof appRouter;
```

That is the complete router. The only callable procedure is
`appRouter.healthCheck`.

## The route handler (`app/api/trpc/[trpc]/route.ts`)

A standard tRPC fetch adapter exposes the router over HTTP for both `GET` and
`POST`:

```typescript theme={null}
// apps/web/src/app/api/trpc/[trpc]/route.ts
import { fetchRequestHandler } from '@trpc/server/adapters/fetch';
import type { NextRequest } from 'next/server';
import { createTRPCContext } from '@/trpc/init';
import { appRouter } from '@/trpc/routers/_app';

const handler = (req: NextRequest) =>
  fetchRequestHandler({
    endpoint: '/api/trpc',
    req,
    router: appRouter,
    createContext: createTRPCContext,
  });

export { handler as GET, handler as POST };
```

## Query client (`query.ts`)

`makeQueryClient` builds a TanStack Query v5 `QueryClient` with superjson
de/serialization and rate-limit-aware retries. This is shared by both the client
provider and the RSC caller.

```typescript theme={null}
// apps/web/src/trpc/query.ts (abridged)
import { defaultShouldDehydrateQuery, QueryClient } from '@tanstack/react-query';
import { deserialize, serialize } from 'superjson';
import { HttpError, isRateLimitError } from '@/lib/api-fetch';

export function makeQueryClient(options?: MakeQueryClientOptions) {
  return new QueryClient({
    queryCache: options?.queryCache,
    mutationCache: options?.mutationCache,
    defaultOptions: {
      queries: {
        staleTime: 30 * 1000,
        // Retry only rate-limited requests, up to 3 times.
        retry: (failureCount, error) =>
          isRateLimitError(error) ? failureCount < 3 : false,
        retryDelay: (_attemptIndex, error) =>
          error instanceof HttpError && error.retryAfter
            ? error.retryAfter * 1000
            : 1000,
      },
      // mutations use the same rate-limit retry policy
      dehydrate: {
        serializeData: serialize,
        shouldDehydrateQuery: (query) =>
          defaultShouldDehydrateQuery(query) ||
          query.state.status === 'pending',
      },
      hydrate: { deserializeData: deserialize },
    },
  });
}
```

> [!NOTE]
>
> On TanStack Query v5, the cache-retention option is `gcTime`, not the v4
> `cacheTime`. The factory above relies on the v5 default `gcTime`; if you set it
> explicitly anywhere, use `gcTime`.

## Client provider (`client.tsx`)

`client.tsx` creates the typed React client with `createTRPCReact<AppRouter>()`
and wires a `TRPCProvider` over `@tanstack/react-query`. The HTTP batch link
points at `/api/trpc` and uses the superjson transformer.

```tsx theme={null}
// apps/web/src/trpc/client.tsx (abridged)
'use client';

import { QueryClientProvider } from '@tanstack/react-query';
import { httpBatchLink } from '@trpc/client';
import { createTRPCReact } from '@trpc/react-query';
import { useState } from 'react';
import superjson from 'superjson';
import { makeQueryClient } from './query';
import type { AppRouter } from './routers/_app';

export const trpc = createTRPCReact<AppRouter>();

export function TRPCProvider({ children }: { children: React.ReactNode }) {
  const queryClient = getQueryClient(); // singleton in browser, fresh on server
  const [trpcClient] = useState(() =>
    trpc.createClient({
      links: [httpBatchLink({ transformer: superjson, url: getUrl() })],
    })
  );

return (
    <trpc.Provider client={trpcClient} queryClient={queryClient}>
      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
    </trpc.Provider>
  );
}
```

The only hook you can actually call through this client today is:

```tsx theme={null}
'use client';

import { trpc } from '@/trpc/client';

export function HealthBadge() {
  const { data } = trpc.healthCheck.useQuery();
  return <span>{data?.status ?? 'checking…'}</span>;
}
```

## Server caller and hydration (`server.ts`)

`server.ts` builds an RSC-side caller from the root router plus the same query
client, and exposes `trpc` and `HydrateClient` via tRPC's
`createHydrationHelpers`. It is marked `server-only`.

```typescript theme={null}
// apps/web/src/trpc/server.ts
import { createCallerFactory, createTRPCContext } from './init';
import { makeQueryClient } from './query';
import { appRouter } from './routers/_app';
import { createHydrationHelpers } from '@trpc/react-query/rsc';
import { cache } from 'react';
import 'server-only';

export const getQueryClient = cache(makeQueryClient);
const caller = createCallerFactory(appRouter)(createTRPCContext);
export const { trpc, HydrateClient } = createHydrationHelpers<typeof appRouter>(
  caller,
  getQueryClient
);
```

In a Server Component you can prefetch and hydrate the single health-check
procedure:

```tsx theme={null}
import { trpc, HydrateClient } from '@/trpc/server';

export default async function Page() {
  // The only available procedure today
  await trpc.healthCheck();
  return (
    <HydrateClient>
      {/* client components can read the hydrated cache */}
    </HydrateClient>
  );
}
```

## How to actually fetch product data

Because tRPC is a stub, real data access uses the platform's standard stack:

* **Server Components** read data directly (via Supabase server clients and
  `@tuturuuu/internal-api` helpers) and pass it down as props.
* **Client components** use **TanStack Query v5** hooks wrapping
  `@tuturuuu/internal-api` helpers / REST `/api/v1` routes. Never fetch in
  `useEffect`, and never call raw app APIs from the client directly.
* **Realtime** updates are wired into the TanStack Query cache, not into
  `useEffect`.

When using the Supabase server clients from `@tuturuuu/supabase/next/server`,
remember:

```typescript theme={null}
import {
  createClient,
  createDynamicClient,
  createAdminClient,
} from '@tuturuuu/supabase/next/server';

const supabase = await createClient();         // ASYNC — await it
const dynamic = await createDynamicClient();    // ASYNC — await it
const admin = createAdminClient();              // SYNC  — do NOT await
```

See [Data Fetching](/platform/architecture/data-fetching) for the canonical
patterns and decision table.

## Extending the stub (rarely needed)

If you genuinely need to add a procedure to the stub (for example, another
lightweight diagnostic), follow the real helper names:

```typescript theme={null}
// apps/web/src/trpc/routers/_app.ts
import { baseProcedure, createTRPCRouter } from '../init';

export const appRouter = createTRPCRouter({
  healthCheck: baseProcedure.query(() => ({ status: 'ok', timestamp: Date.now() })),
  // example diagnostic addition
  ping: baseProcedure.query(() => ({ pong: true })),
});

export type AppRouter = typeof appRouter;
```

Procedures here run with the placeholder context only — there is no auth
middleware to attach. For anything user-facing, authenticated, or
product-related, prefer `@tuturuuu/internal-api` + REST routes instead of
growing this scaffold during the migration.

## Related Documentation

* [Data Fetching](/platform/architecture/data-fetching) — the real client/server
  fetching stack (Server Components + internal-api + TanStack Query)
* [API Routes](/platform/architecture/api-routes) — REST `/api/v1` patterns and
  `@tuturuuu/internal-api`
* [TanStack + Rust migration](/platform/architecture/tanstack-rust-migration) —
  why this layer is a stub
* [Authentication](/platform/architecture/authentication)
* [Authorization](/platform/architecture/authorization)

## External Resources

* [tRPC Official Docs](https://trpc.io/)
* [TanStack Query Docs](https://tanstack.com/query/latest)
* [superjson](https://github.com/flightcontrol/superjson)

# Workspaces & Permissions
Source: https://docs.tuturuuu.com/platform/architecture/workspaces-permissions

Complete reference for workspace identity, membership, routing, and effective permissions in apps/web

This page documents the actual workspace and permission model used by `apps/web` today.

It focuses on the implementation that page components, route handlers, and the internal API helpers actually consume:

* `packages/utils/src/workspace-helper.ts`
* `packages/ui/src/components/ui/custom/workspace-wrapper.tsx`
* `apps/web/src/proxy.ts`
* `packages/utils/src/permissions.tsx`
* `apps/web/src/lib/api-middleware.ts`

## Mental Model

There are four layers, and most bugs come from mixing them together:

1. **Workspace identity**
   `personal`, `internal`, and UUIDs all describe the same underlying `workspaces.id` shape, but only UUIDs are stored in the database.
2. **Membership**
   `workspace_members` answers "is this signed-in user allowed inside this workspace at all?"
3. **Effective permissions**
   `workspace_role_members`, `workspace_role_permissions`, `workspace_default_permissions`, and creator fallback answer "what may this member do?"
4. **Surface enforcement**
   Pages, navigation, and API routes decide whether to hide, redirect, 403, or allow the action.

```mermaid theme={null}
flowchart LR
  URL["Incoming URL or API param"] --> Proxy["apps/web/src/proxy.ts"]
  Proxy --> Slug["Canonical slug handling<br/>personal / internal / UUID"]
  Slug --> Page["WorkspaceWrapper / getWorkspace()"]
  Slug --> Route["normalizeWorkspaceId()"]
  Page --> Member["workspace_members membership check"]
  Route --> Auth["createClient(request)"]
  Auth --> Perms["getPermissions()"]
  Perms --> UI["navigation.tsx / server pages"]
  Perms --> API["privileged route handlers"]
```

## Workspace Vocabulary

## Membership Is Not The Same Thing As A Workspace User Record

`apps/web` uses two different "user-ish" concepts:

* `workspace_members`
  This is the access-control boundary. Most auth checks read this table.
* `workspace_users`
  This is domain data used by product features such as user management, attendance, reports, and directory-style views.

Do not treat `workspace_users` as evidence that a signed-in platform user has workspace access. In the web app, access checks consistently use `workspace_members`.

## Canonical Workspace Identifiers

The web app accepts three route forms:

* a raw workspace UUID
* `personal`
* `internal`

The database only stores UUID workspace IDs. The slugs are convenience identifiers used at the edge and in page params.

### Resolution Rules

* `personal` resolves to the signed-in user's personal workspace UUID.
* `internal` resolves to `ROOT_WORKSPACE_ID`.
* a personal workspace UUID in the URL is redirected back to `/personal/...`.
* the root workspace UUID in the URL is redirected back to `/internal/...`.

This canonicalization happens before most page rendering so the browser settles on stable, human-friendly URLs.

## How Proxy Routing Works

`apps/web/src/proxy.ts` is the entry point for workspace-aware URL normalization.

The proxy is responsible for:

* locale-aware path parsing
* redirecting root visits to the user's default workspace
* rewriting raw root UUIDs to `internal`
* rewriting personal workspace UUIDs to `personal`
* preserving auth cookies while issuing those redirects

It also uses `getUserDefaultWorkspace()` from `packages/utils/src/user-helper.ts` to decide where an authenticated user lands when they hit `/`.

### Default Workspace Behavior

The default workspace is stored in `user_private_details.default_workspace_id`.

When the stored default workspace is missing or no longer accessible, the helper falls back to the user's personal workspace.

That fallback is used both for root-path redirect behavior and for other flows that need a stable "start workspace" concept.

## Server-Page Workspace Resolution

For server-rendered pages under `apps/web/src/app/[locale]/(dashboard)/[wsId]/...`, the normal entry point is `WorkspaceWrapper`.

`WorkspaceWrapper` delegates to `getWorkspace(wsId)`, which:

1. validates that the incoming identifier is a supported direct lookup form
2. authenticates the current user
3. resolves `personal` / `internal` into a concrete workspace ID
4. queries `workspaces` joined through `workspace_members!inner(user_id)`
5. returns the workspace plus:
   * `joined`
   * `tier`
   * normalized `workspace.id`

If that lookup fails, the wrapper calls `notFound()`.

### Important Consequence

Page components that use `WorkspaceWrapper` already know:

* the user is authenticated
* the user has a `workspace_members` row for the workspace
* the child callback receives the canonical UUID as `wsId`

That does **not** mean the user has feature-level permissions. Fine-grained authorization still needs `getPermissions()`.

It also does not mean the user is a full member. Guests can have `workspace_members.type = 'GUEST'`, so non-guest-capable pages and APIs must explicitly require `MEMBER`.

## Route-Handler Workspace Resolution

API routes cannot depend on `WorkspaceWrapper`, so they use `normalizeWorkspaceId()`.

`normalizeWorkspaceId()`:

* accepts the route param
* optionally accepts a request-scoped Supabase client
* preserves mobile/Bearer-token auth by using `createClient(request)` when needed
* returns the canonical workspace UUID
* throws when `personal` is requested but no authenticated personal workspace exists

App-session and CLI routes that call `normalizeWorkspaceId()` with an admin
Supabase client should first attach the verified actor with
`attachSupabaseAuthUser()` from `@tuturuuu/auth/app-session`. Do not duplicate
manual `personal` workspace fallback lookups inside each route.

Use it whenever a route param may contain `personal` or `internal` but the query must operate on concrete workspace IDs.

## Effective Permission Evaluation

The main evaluator is `getPermissions({ wsId, request? })` in `packages/utils/src/workspace-helper.ts`.

Its behavior is the key thing to understand.

### Inputs

* authenticated current user
* workspace identifier from the page or route

### Data sources

* `workspace_role_members`
* `workspace_roles`
* `workspace_role_permissions`
* `workspace_default_permissions.member_type`
* `workspaces.creator_id`

### Evaluation algorithm

1. Authenticate the current user.
2. Normalize the workspace ID.
3. Verify whether the caller is a `MEMBER` or `GUEST`.
4. For `MEMBER`, load role-derived permissions for the current user in that workspace.
5. Load workspace-wide default permissions where `member_type` matches the caller.
6. Load the workspace creator ID.
7. If the user is the creator and a `MEMBER`, return the full permission catalog from `packages/utils/src/permissions.tsx`.
8. Otherwise return the deduplicated union of role-derived and default permissions.
9. If the user is not the creator and the union is empty, return `null`.

`MEMBER` defaults are the backward-compatible default. Existing rows became `member_type = 'MEMBER'`, and `/api/v1/workspaces/[wsId]/roles/default` still defaults to `memberType=MEMBER` when the query parameter is omitted.

`GUEST` defaults use the same full permission catalog as members, but the default is deny: a missing guest row means no permission. The dashboard proxy applies this as a route guard for guests: members keep existing behavior, while guests may open only routes that map to an enabled guest default permission. Routes without a permission mapping are denied for guests even when the guest has `admin`.

### Why creator fallback matters

A newly created workspace may exist before any roles or defaults are configured.

The creator fallback prevents the creator from locking themselves out. The dashboard permission-setup banner exists because everyone else would otherwise have no effective permissions until defaults or roles are configured.

## `workspace_members.role` Is Not The Current Permission Source

This is the most important corrective note for anyone reading older docs or legacy schema assumptions.

`apps/web` permission checks do **not** currently derive access from `workspace_members.role`.

Modern member permission evaluation reads:

* role memberships from `workspace_role_members`
* permission definitions from `workspace_role_permissions`
* workspace-wide defaults from `workspace_default_permissions.member_type = 'MEMBER'`

Guest permission evaluation reads `workspace_default_permissions.member_type = 'GUEST'` for dashboard route defaults and keeps `workspace_guest_permissions` for resource-specific grants such as `course:view`.

If you document or implement new authorization behavior against `workspace_members.role`, you will diverge from the real app behavior.

## Permission Catalog

The permission catalog is defined in `packages/utils/src/permissions.tsx`.

The catalog is grouped for UI presentation and creator fallback. The main groups currently cover:

* workspace administration
* AI
* calendar
* projects
* documents
* time tracking
* drive
* users
* user groups
* leads
* inventory
* finance
* workforce
* transactions
* invoices

When the current workspace is the root workspace, an additional infrastructure group is available.

### `admin` semantics

`admin` is just another permission ID in the catalog, but `containsPermission()` treats it as a full bypass:

* creator => all permissions
* `admin` => all permissions
* explicit permission match => specific permission granted

That means `admin` is a permission bit, not a separate role engine.

## Where Permissions Affect The UI

### Navigation

`apps/web/src/app/[locale]/(dashboard)/[wsId]/navigation.tsx` is the broadest consumer of `getPermissions()`.

It uses `withoutPermission(...)` to:

* disable whole sidebar sections
* disable specific children under a section
* expose root-only capabilities only when the current user also has root-workspace permissions
* combine permissions with workspace secrets and product-tier checks

This is why a missing permission often appears first as a disabled nav item, not as a late 403 from the clicked page.

### Mobile module flags

The mobile app can hide experimental app modules per workspace through
workspace secrets exposed by
`/api/v1/workspaces/[wsId]/mobile/module-flags`. The route authenticates the
mobile session, verifies workspace membership with the request-scoped client,
then reads only the mobile module flag secrets with an admin client.

Supported secrets:

* `MOBILE_HIDE_EXPERIMENTAL_MODULES`: truthy values (`1`, `true`, `yes`, `on`)
  hide the default experimental modules.
* `MOBILE_HIDDEN_MODULES`: JSON array or comma-separated module IDs for explicit
  hidden modules.

Keep these flags as display controls. API routes that expose protected module
data must still perform their own workspace membership and permission checks.

### Settings pages

Workspace settings pages usually follow this pattern:

1. resolve the workspace with `WorkspaceWrapper`
2. call `getPermissions({ wsId })`
3. redirect away or `notFound()` if the required permission is missing

Examples:

* members page requires `manage_workspace_members`
* roles page requires `manage_workspace_roles`
* settings page checks `manage_workspace_settings` and `manage_workspace_security`

### Members UI

The members settings surfaces use `workspace_members_and_invites` so joined members and pending invites can be shown together.

The enhanced members route also merges:

* role memberships
* enabled role permissions
* default permissions
* creator flag
* privacy-related workspace secrets like `HIDE_MEMBER_EMAIL` and `HIDE_MEMBER_NAME`

That is why the members page can show a permission breakdown per person without recomputing everything in the browser.

## Where Permissions Affect API Routes

There are two broad families in `apps/web`.

### Session-authenticated browser/mobile routes

These routes use:

* `createClient(request)` or `withSessionAuth(...)` for authentication
* `normalizeWorkspaceId()` for canonical workspace lookup
* `getPermissions()` when a privileged capability is involved

Examples:

* `apps/web/src/app/api/workspaces/[wsId]/route.ts`
* `apps/web/src/app/api/workspaces/[wsId]/members/route.ts`
* many `apps/web/src/app/api/.../workspaces/[wsId]/...` handlers

### Workspace API key routes

SDK-facing routes use `withApiAuth(...)` from `apps/web/src/lib/api-middleware.ts`.

The middleware:

1. extracts the API key from `Authorization`
2. validates it against `workspace_api_keys`
3. loads role-derived and default permissions for that key
4. enforces rate limits and IP bans
5. rejects requests whose `[wsId]` does not match the API key's bound workspace

That keeps the permission vocabulary identical between browser/session access and API-key access.

## Split Between Session Client And Admin Client

A recurring pattern in the helpers is:

* authenticate with the request-scoped or cookie-scoped Supabase client
* then read supporting tables with an admin client when richer joins or privileged reads are needed

Examples:

* `getPermissions()` authenticates with a normal client but reads role/default data through an admin client.
* `getWorkspace()` authenticates first, then may use an admin client for the workspace fetch when requested.

This is intentional. It preserves the caller identity while still allowing the app to assemble permission state that would be awkward to fetch purely through RLS-limited joins.

Name every `createAdminClient()` local `sbAdmin`, not `supabase`, so reviewers can immediately distinguish service-role access from request-scoped clients.

## Special Workspace Rules

### Personal workspaces

Personal workspaces are special in several places:

* canonical URL slug is always `personal`
* roles management is effectively bypassed in the UI
* invitations are blocked
* manual deletion is blocked
* many workspace settings pages simplify or redirect for personal mode

### Root/internal workspace

The root workspace is the internal control plane.

Common patterns:

* canonical URL slug is `internal`
* extra infrastructure permissions exist only here
* some features compare target-workspace permissions with root-workspace permissions
* root membership is often treated as the gate for platform-wide admin tooling

### Account security administration

Infrastructure exposes **Platform Admin → Account Security** only when the
operator has the root-only `manage_internal_accounts` permission. The server
rechecks that permission against the root workspace on every request and
requires the actor to use an exact `@tuturuuu.com` email address.

Use **Platform account recovery** to force-set a temporary password for any
Tuturuuu platform account by its exact email address. The internal directory
limits profile, Drive, and per-account password/MFA controls to exact
`@tuturuuu.com` accounts. Disable-access and enable-access are an explicit
exception: they also accept strictly validated managed subdomains such as
`@xwf.tuturuuu.com`, with matching email confirmation and the same target UUID.
External addresses and suffix lookalikes remain ineligible; actors still require
an exact-root address and `manage_internal_accounts`. Self-service access and password mutations
are rejected to reduce accidental lockouts. Passwords must never be copied into
logs, tickets, or coordination notes; share a temporary password only through
an approved secure channel.

Disabling access applies an Auth ban and does not implicitly revoke every
already-issued session. If an incident also requires session revocation, handle
that as a separate authenticated operation and verify the target carefully.

## Current Enforcement Patterns In The Codebase

Today the codebase uses a mix of patterns:

* newer surfaces centralize on `WorkspaceWrapper`, `normalizeWorkspaceId()`, and `getPermissions()`
* internal API client helpers call web routes instead of letting client components query arbitrary tables directly
* some older routes still hand-query role/default permission tables instead of calling `getPermissions()`
* some routes still rely mostly on membership + RLS and do not add a second explicit permission layer

That means the architecture is clear, but the implementation is still partly transitional. When adding new routes, prefer the shared helpers instead of reimplementing the joins manually.

## Recommended Developer Pattern

For a new workspace-scoped server page:

1. Use `WorkspaceWrapper`.
2. Use the normalized `wsId` from the wrapper callback for all DB reads.
3. Call `getPermissions({ wsId })` before rendering privileged content.
4. Gate or redirect from `containsPermission(...)` / `withoutPermission(...)`.

For a new workspace-scoped API route:

1. Authenticate with `createClient(request)` or `withSessionAuth(...)`.
2. Normalize the route param with `normalizeWorkspaceId(...)`.
3. Verify membership when needed.
4. Call `getPermissions({ wsId, request })` for privileged behavior.
5. Use `packages/internal-api` on the client instead of ad hoc browser `fetch()` contracts when the route is meant to be reused.

For a new SDK/API-key route:

1. Wrap the handler with `withApiAuth(...)`.
2. Require specific permission IDs in the middleware options when possible.
3. Reject workspace mismatches instead of trying to remap the requested workspace.

## Quick Reference

## Practical Rules To Keep In Mind

* A member can exist without any effective permissions.
* The creator always has the full catalog, even if no roles/defaults exist yet.
* `admin` is a permission bit that grants universal access through the helper.
* `workspace_users` is not the access-control table.
* Browser URLs prefer `personal` and `internal`, but DB queries should use canonical UUIDs.
* New privileged routes should reuse the shared helpers instead of reimplementing role/default joins.

## Employee creation preparation

Infrastructure uses the registered satellite session id `infra`. Employee creation
requires a fresh root-workspace `MEMBER`, `manage_internal_accounts`, and a current
confirmed, unbanned administrator with an exact `@tuturuuu.com` identity. Directory
subdomains do not grant staff mutation privileges.

The first-class web `/api/v1/infrastructure/internal-accounts/employees` boundary
currently reports `available: false` and refuses authenticated creation with503.
The UI exposes a disabled preparation form. No journal, provider or SQL connector
is installed by this source change. The shared client strictly validates the
request and acknowledgement, binds an operation key, and never retries creation.

A durable journal is a separate prerequisite: atomically bind the administrator,
operation key and canonical payload fingerprint to one server-allocated target
UUID; preserve that UUID and exact email/name tuple across re-entry. A conflicting
payload or known pending/unknown result requires inspection. A caller header,
in-memory map or the existing per-invocation UUID orchestration is not this journal.
Temporary passwords must remain transient and must not enter journal payloads,
logs, browser storage or receipts.

Actual172-assertion disposable-schema qualification is distinct from current-main
schema composition, correct-project applied ledger/catalog/ACL proofs, real
provider ownership and runtime qualification. Keep creation unavailable until the
durable journal and bounded transport satisfy those gates. No blind provider
create retry, compensation deletion, mailbox change or named-account creation is
authorized by the preparation form.

# Components
Source: https://docs.tuturuuu.com/platform/components/overview

Reusable UI components and utilities for the Tuturuuu platform

This section contains documentation for reusable components and utilities used across the Tuturuuu platform.

## Available Components

### WorkspaceWrapper

A standardized component for handling workspace ID resolution and validation across the application.

The canonical implementation is shared from `packages/ui` at
`packages/ui/src/components/ui/custom/workspace-wrapper.tsx` and is imported as
`@tuturuuu/ui/custom/workspace-wrapper`. `apps/web/src/components/workspace-wrapper.tsx`
is a thin re-export kept for backward compatibility with existing imports.

* [WorkspaceWrapper Guide](./workspace-wrapper) - Complete documentation with examples
* [Quick Reference](./workspace-wrapper-quick-reference) - Quick reference guide

## Component Guidelines

### When to Create a Component

Create a new component when:

1. **Reusability**: The code is used in 2+ places
2. **Complexity**: The logic is complex enough to warrant separation
3. **Testing**: The component needs isolated testing
4. **Maintenance**: The component has specific maintenance requirements

### Where Components Live

Components belong in the narrowest home that fits their reuse:

* **Shared / reusable components** (used across apps) live in `packages/ui` under
  `packages/ui/src/components/ui/custom/`. For example, `WorkspaceWrapper` lives at
  `packages/ui/src/components/ui/custom/workspace-wrapper.tsx` and is imported via
  `@tuturuuu/ui/custom/workspace-wrapper`.
* **App-specific components** live in that app's `components/` directory
  (for example `apps/web/src/components/`).
* When a shared component is promoted to `packages/ui`, keep the old app path stable
  with a thin re-export so existing imports keep working — as
  `apps/web/src/components/workspace-wrapper.tsx` does for `WorkspaceWrapper`.

There is no enforced per-component folder scaffold. Most components are a single file
(co-located types and small hooks are fine inline); split into multiple files only when
size or complexity warrants it. Per the repo guidelines, split files over \~400 LOC and
components/widgets over \~200 LOC, and keep import paths stable with thin re-exports when
callers depend on them. Colocated tests live in `__tests__/` directories next to the code.

### Documentation Requirements

Each component must include:

1. **Purpose**: What the component does
2. **Props**: Complete API reference
3. **Examples**: Real-world usage examples
4. **Migration Guide**: If replacing existing patterns
5. **Best Practices**: Usage guidelines

### Naming Conventions

* **Components**: PascalCase (`WorkspaceWrapper`)
* **Files**: kebab-case (`workspace-wrapper.mdx`)
* **Props**: camelCase (`params`)
* **Types**: PascalCase with descriptive suffixes (`WorkspaceWrapperProps`)

## Contributing

When adding new components:

1. Create the component in the narrowest home that fits its reuse — `packages/ui` for
   shared/reusable components, or the app's `components/` directory for app-specific ones
2. Add comprehensive documentation
3. Include TypeScript types
4. Add tests
5. Update this overview page
6. Follow the established patterns

## Examples

See the [Examples Library](/learn/examples/overview) for practical implementation examples of all components.

# Accordion
Source: https://docs.tuturuuu.com/platform/components/ui/accordion

Preview Accordion, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/accordion.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/accordion](https://tuturuuu.com/ui/components/accordion).

**Category:** Layout · **Import:** `@tuturuuu/ui/accordion` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from '@tuturuuu/ui/accordion';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from '@tuturuuu/ui/accordion';

<Accordion type="single" collapsible>
  <AccordionItem value="overview">
    <AccordionTrigger>Overview</AccordionTrigger>
    <AccordionContent>Composable disclosure content.</AccordionContent>
  </AccordionItem>
</Accordion>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from '@tuturuuu/ui/accordion';

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Accordion,
  AccordionItem,
  AccordionTrigger,
  AccordionContent,
} from '@tuturuuu/ui/accordion';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Accordion } from '@tuturuuu/ui/accordion';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Type
* Collapsible
* Content density

## Related components

* [Aspect Ratio](./aspect-ratio)
* [Card](./card)
* [Carousel](./carousel)

# Alert
Source: https://docs.tuturuuu.com/platform/components/ui/alert

Preview Alert, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/alert.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/alert](https://tuturuuu.com/ui/components/alert).

**Category:** Feedback · **Import:** `@tuturuuu/ui/alert` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Alert, AlertTitle, AlertDescription } from '@tuturuuu/ui/alert';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Alert, AlertDescription, AlertTitle } from '@tuturuuu/ui/alert';

<Alert>
  <AlertTitle>Deployment ready</AlertTitle>
  <AlertDescription>All required checks have passed.</AlertDescription>
</Alert>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Alert, AlertDescription, AlertTitle } from '@tuturuuu/ui/alert';

<Alert>
  <AlertTitle>Deployment ready</AlertTitle>
  <AlertDescription>All required checks have passed.</AlertDescription>
</Alert>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Alert,
  AlertTitle,
  AlertDescription,
} from '@tuturuuu/ui/alert';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Alert } from '@tuturuuu/ui/alert';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Variant
* Icon
* Tone

## Related components

* [Avatar](./avatar)
* [Badge](./badge)
* [Progress](./progress)

# Alert Dialog
Source: https://docs.tuturuuu.com/platform/components/ui/alert-dialog

Preview Alert Dialog, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/alert-dialog.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/alert-dialog](https://tuturuuu.com/ui/components/alert-dialog).

**Category:** Overlays · **Import:** `@tuturuuu/ui/alert-dialog` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { AlertDialog, AlertDialogTrigger, AlertDialogContent } from '@tuturuuu/ui/alert-dialog';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { AlertDialog, AlertDialogContent, AlertDialogTrigger } from '@tuturuuu/ui/alert-dialog';

<AlertDialog>
  <AlertDialogTrigger>Open confirmation</AlertDialogTrigger>
  <AlertDialogContent>Confirm the irreversible action.</AlertDialogContent>
</AlertDialog>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { AlertDialog, AlertDialogContent, AlertDialogTrigger } from '@tuturuuu/ui/alert-dialog';

<AlertDialog>
  <AlertDialogTrigger>Open confirmation</AlertDialogTrigger>
  <AlertDialogContent>Confirm the irreversible action.</AlertDialogContent>
</AlertDialog>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  AlertDialog,
  AlertDialogTrigger,
  AlertDialogContent,
} from '@tuturuuu/ui/alert-dialog';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { AlertDialog } from '@tuturuuu/ui/alert-dialog';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Trigger
* Destructive action
* Copy

## Related components

* [Context Menu](./context-menu)
* [Dialog](./dialog)
* [Drawer](./drawer)

# Aspect Ratio
Source: https://docs.tuturuuu.com/platform/components/ui/aspect-ratio

Preview Aspect Ratio, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/aspect-ratio.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/aspect-ratio](https://tuturuuu.com/ui/components/aspect-ratio).

**Category:** Layout · **Import:** `@tuturuuu/ui/aspect-ratio` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { AspectRatio } from '@tuturuuu/ui/aspect-ratio';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { AspectRatio } from '@tuturuuu/ui/aspect-ratio';

<AspectRatio ratio={16 / 9}>
  <img src="/preview.png" alt="" className="h-full w-full object-cover" />
</AspectRatio>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { AspectRatio } from '@tuturuuu/ui/aspect-ratio';

<AspectRatio ratio={16 / 9}>
  <img src="/preview.png" alt="" className="h-full w-full object-cover" />
</AspectRatio>
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { AspectRatio } from '@tuturuuu/ui/aspect-ratio';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Ratio
* Media
* Radius

## Related components

* [Accordion](./accordion)
* [Card](./card)
* [Carousel](./carousel)

# Avatar
Source: https://docs.tuturuuu.com/platform/components/ui/avatar

Preview Avatar, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/avatar.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/avatar](https://tuturuuu.com/ui/components/avatar).

**Category:** Feedback · **Import:** `@tuturuuu/ui/avatar` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Avatar, AvatarImage, AvatarFallback } from '@tuturuuu/ui/avatar';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Avatar, AvatarFallback, AvatarImage } from '@tuturuuu/ui/avatar';

<Avatar>
  <AvatarImage src="/avatar.png" alt="User" />
  <AvatarFallback>TT</AvatarFallback>
</Avatar>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Avatar, AvatarFallback, AvatarImage } from '@tuturuuu/ui/avatar';

<Avatar>
  <AvatarImage src="/avatar.png" alt="User" />
  <AvatarFallback>TT</AvatarFallback>
</Avatar>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Avatar,
  AvatarImage,
  AvatarFallback,
} from '@tuturuuu/ui/avatar';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Avatar } from '@tuturuuu/ui/avatar';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Size
* Fallback
* Stacking

## Related components

* [Alert](./alert)
* [Badge](./badge)
* [Progress](./progress)

# Badge
Source: https://docs.tuturuuu.com/platform/components/ui/badge

Preview Badge, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/badge.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/badge](https://tuturuuu.com/ui/components/badge).

**Category:** Feedback · **Import:** `@tuturuuu/ui/badge` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Badge } from '@tuturuuu/ui/badge';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Badge } from '@tuturuuu/ui/badge';

<Badge variant="secondary">Beta</Badge>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Badge } from '@tuturuuu/ui/badge';

<Badge variant="secondary">Beta</Badge>
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Badge } from '@tuturuuu/ui/badge';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Variant
* Tone
* Icon

## Related components

* [Alert](./alert)
* [Avatar](./avatar)
* [Progress](./progress)

# Breadcrumb
Source: https://docs.tuturuuu.com/platform/components/ui/breadcrumb

Preview Breadcrumb, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/breadcrumb.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/breadcrumb](https://tuturuuu.com/ui/components/breadcrumb).

**Category:** Navigation · **Import:** `@tuturuuu/ui/breadcrumb` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Breadcrumb, BreadcrumbList, BreadcrumbItem, BreadcrumbLink } from '@tuturuuu/ui/breadcrumb';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList } from '@tuturuuu/ui/breadcrumb';

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem><BreadcrumbLink href="/">Home</BreadcrumbLink></BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList } from '@tuturuuu/ui/breadcrumb';

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem><BreadcrumbLink href="/">Home</BreadcrumbLink></BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Breadcrumb,
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbLink,
} from '@tuturuuu/ui/breadcrumb';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Breadcrumb } from '@tuturuuu/ui/breadcrumb';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Separator
* Current item
* Overflow

## Related components

* [Command](./command)
* [Quick Command Center](./quick-command-center)
* [Menubar](./menubar)

# Button
Source: https://docs.tuturuuu.com/platform/components/ui/button

Preview Button, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/button.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/button](https://tuturuuu.com/ui/components/button).

**Category:** Actions · **Import:** `@tuturuuu/ui/button` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Button, buttonVariants } from '@tuturuuu/ui/button';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Button } from '@tuturuuu/ui/button';

<Button variant="default" size="sm">Create workspace</Button>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Button } from '@tuturuuu/ui/button';

<Button variant="default" size="sm">Create workspace</Button>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Button,
  buttonVariants,
} from '@tuturuuu/ui/button';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Button } from '@tuturuuu/ui/button';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Variant
* Size
* Icon

## Related components

* [Toggle](./toggle)
* [Toggle Group](./toggle-group)
* [Accordion](./accordion)

# Calendar
Source: https://docs.tuturuuu.com/platform/components/ui/calendar

Preview Calendar, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/calendar.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/calendar](https://tuturuuu.com/ui/components/calendar).

**Category:** Inputs · **Import:** `@tuturuuu/ui/calendar` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Calendar } from '@tuturuuu/ui/calendar';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Calendar } from '@tuturuuu/ui/calendar';

<Calendar mode="single" selected={date} onSelect={setDate} />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Calendar } from '@tuturuuu/ui/calendar';

<Calendar mode="single" selected={date} onSelect={setDate} />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Calendar } from '@tuturuuu/ui/calendar';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Mode
* Timezone
* Week start

## Related components

* [Checkbox](./checkbox)
* [Color Picker](./color-picker)
* [Currency Input](./currency-input)

# Card
Source: https://docs.tuturuuu.com/platform/components/ui/card

Preview Card, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/card.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/card](https://tuturuuu.com/ui/components/card).

**Category:** Layout · **Import:** `@tuturuuu/ui/card` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@tuturuuu/ui/card';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Card, CardContent, CardHeader, CardTitle } from '@tuturuuu/ui/card';

<Card>
  <CardHeader><CardTitle>Workspace</CardTitle></CardHeader>
  <CardContent>Summary content</CardContent>
</Card>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Card, CardContent, CardHeader, CardTitle } from '@tuturuuu/ui/card';

<Card>
  <CardHeader><CardTitle>Workspace</CardTitle></CardHeader>
  <CardContent>Summary content</CardContent>
</Card>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Card,
  CardHeader,
  CardTitle,
  CardDescription,
  CardContent,
  CardFooter,
} from '@tuturuuu/ui/card';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Card } from '@tuturuuu/ui/card';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Header
* Content
* Footer

## Related components

* [Accordion](./accordion)
* [Aspect Ratio](./aspect-ratio)
* [Carousel](./carousel)

# Carousel
Source: https://docs.tuturuuu.com/platform/components/ui/carousel

Preview Carousel, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/carousel.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/carousel](https://tuturuuu.com/ui/components/carousel).

**Category:** Layout · **Import:** `@tuturuuu/ui/carousel` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious } from '@tuturuuu/ui/carousel';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Carousel, CarouselContent, CarouselItem } from '@tuturuuu/ui/carousel';

<Carousel opts={{ align: 'start' }}>
  <CarouselContent>
    <CarouselItem>Slide content</CarouselItem>
  </CarouselContent>
</Carousel>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Carousel, CarouselContent, CarouselItem } from '@tuturuuu/ui/carousel';

<Carousel opts={{ align: 'start' }}>
  <CarouselContent>
    <CarouselItem>Slide content</CarouselItem>
  </CarouselContent>
</Carousel>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
} from '@tuturuuu/ui/carousel';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Carousel } from '@tuturuuu/ui/carousel';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Orientation
* Slides
* Controls

## Related components

* [Accordion](./accordion)
* [Aspect Ratio](./aspect-ratio)
* [Card](./card)

# Chart
Source: https://docs.tuturuuu.com/platform/components/ui/chart

Preview Chart, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/chart.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/chart](https://tuturuuu.com/ui/components/chart).

**Category:** Data · **Import:** `@tuturuuu/ui/chart` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { ChartContainer, ChartTooltip, ChartTooltipContent } from '@tuturuuu/ui/chart';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { ChartContainer, ChartTooltip, ChartTooltipContent } from '@tuturuuu/ui/chart';

<ChartContainer config={{ work: { label: 'Work', color: 'hsl(var(--primary))' } }}>
  <BarChart data={data}>
    <ChartTooltip content={<ChartTooltipContent />} />
  </BarChart>
</ChartContainer>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { ChartContainer, ChartTooltip, ChartTooltipContent } from '@tuturuuu/ui/chart';

<ChartContainer config={{ work: { label: 'Work', color: 'hsl(var(--primary))' } }}>
  <BarChart data={data}>
    <ChartTooltip content={<ChartTooltipContent />} />
  </BarChart>
</ChartContainer>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  ChartContainer,
  ChartTooltip,
  ChartTooltipContent,
} from '@tuturuuu/ui/chart';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { ChartContainer } from '@tuturuuu/ui/chart';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Series
* Theme
* Tooltip

## Related components

* [Diff Viewer](./diff-viewer)
* [Table](./table)
* [Accordion](./accordion)

# Checkbox
Source: https://docs.tuturuuu.com/platform/components/ui/checkbox

Preview Checkbox, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/checkbox.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/checkbox](https://tuturuuu.com/ui/components/checkbox).

**Category:** Inputs · **Import:** `@tuturuuu/ui/checkbox` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Checkbox } from '@tuturuuu/ui/checkbox';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Checkbox } from '@tuturuuu/ui/checkbox';

<Checkbox id="terms" defaultChecked />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Checkbox } from '@tuturuuu/ui/checkbox';

<Checkbox id="terms" defaultChecked />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Checkbox } from '@tuturuuu/ui/checkbox';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Checked state
* Disabled state
* Label

## Related components

* [Calendar](./calendar)
* [Color Picker](./color-picker)
* [Currency Input](./currency-input)

# Code Block
Source: https://docs.tuturuuu.com/platform/components/ui/codeblock

Preview Code Block, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/codeblock.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/codeblock](https://tuturuuu.com/ui/components/codeblock).

**Category:** Typography · **Import:** `@tuturuuu/ui/codeblock` · **Status:** Pattern preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { CodeBlock } from '@tuturuuu/ui/codeblock';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { CodeBlock } from '@tuturuuu/ui/codeblock';

<CodeBlock language="tsx" value={"<Button>Save</Button>"} />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { CodeBlock } from '@tuturuuu/ui/codeblock';

<CodeBlock language="tsx" value={"<Button>Save</Button>"} />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { CodeBlock } from '@tuturuuu/ui/codeblock';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Language
* Theme
* Line numbers

## Related components

* [Kbd](./kbd)
* [Markdown](./markdown)
* [Accordion](./accordion)

# Collapsible
Source: https://docs.tuturuuu.com/platform/components/ui/collapsible

Preview Collapsible, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/collapsible.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/collapsible](https://tuturuuu.com/ui/components/collapsible).

**Category:** Layout · **Import:** `@tuturuuu/ui/collapsible` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Collapsible, CollapsibleTrigger, CollapsibleContent } from '@tuturuuu/ui/collapsible';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@tuturuuu/ui/collapsible';

<Collapsible>
  <CollapsibleTrigger>Toggle details</CollapsibleTrigger>
  <CollapsibleContent>Hidden content</CollapsibleContent>
</Collapsible>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@tuturuuu/ui/collapsible';

<Collapsible>
  <CollapsibleTrigger>Toggle details</CollapsibleTrigger>
  <CollapsibleContent>Hidden content</CollapsibleContent>
</Collapsible>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Collapsible,
  CollapsibleTrigger,
  CollapsibleContent,
} from '@tuturuuu/ui/collapsible';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Collapsible } from '@tuturuuu/ui/collapsible';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Open state
* Trigger
* Content density

## Related components

* [Accordion](./accordion)
* [Aspect Ratio](./aspect-ratio)
* [Card](./card)

# Color Picker
Source: https://docs.tuturuuu.com/platform/components/ui/color-picker

Preview Color Picker, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/color-picker.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/color-picker](https://tuturuuu.com/ui/components/color-picker).

**Category:** Inputs · **Import:** `@tuturuuu/ui/color-picker` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { ColorPicker, ensureVisibleColor } from '@tuturuuu/ui/color-picker';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { ColorPicker } from '@tuturuuu/ui/color-picker';

<ColorPicker value={color} onChange={setColor} />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { ColorPicker } from '@tuturuuu/ui/color-picker';

<ColorPicker value={color} onChange={setColor} />
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  ColorPicker,
  ensureVisibleColor,
} from '@tuturuuu/ui/color-picker';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { ColorPicker } from '@tuturuuu/ui/color-picker';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Value
* Contrast
* Disabled state

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Currency Input](./currency-input)

# Command
Source: https://docs.tuturuuu.com/platform/components/ui/command

Preview Command, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/command.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/command](https://tuturuuu.com/ui/components/command).

**Category:** Navigation · **Import:** `@tuturuuu/ui/command` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Command, CommandInput, CommandItem, CommandList } from '@tuturuuu/ui/command';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Command, CommandInput, CommandItem, CommandList } from '@tuturuuu/ui/command';

<Command>
  <CommandInput placeholder="Search..." />
  <CommandList><CommandItem>Open dashboard</CommandItem></CommandList>
</Command>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Command, CommandInput, CommandItem, CommandList } from '@tuturuuu/ui/command';

<Command>
  <CommandInput placeholder="Search..." />
  <CommandList><CommandItem>Open dashboard</CommandItem></CommandList>
</Command>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Command,
  CommandInput,
  CommandItem,
  CommandList,
} from '@tuturuuu/ui/command';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Command } from '@tuturuuu/ui/command';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Groups
* Empty state
* Shortcuts

## Related components

* [Breadcrumb](./breadcrumb)
* [Quick Command Center](./quick-command-center)
* [Menubar](./menubar)

# Context Menu
Source: https://docs.tuturuuu.com/platform/components/ui/context-menu

Preview Context Menu, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/context-menu.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/context-menu](https://tuturuuu.com/ui/components/context-menu).

**Category:** Overlays · **Import:** `@tuturuuu/ui/context-menu` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { ContextMenu, ContextMenuTrigger, ContextMenuContent } from '@tuturuuu/ui/context-menu';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { ContextMenu, ContextMenuContent, ContextMenuItem, ContextMenuTrigger } from '@tuturuuu/ui/context-menu';

<ContextMenu>
  <ContextMenuTrigger>Right click area</ContextMenuTrigger>
  <ContextMenuContent><ContextMenuItem>Duplicate</ContextMenuItem></ContextMenuContent>
</ContextMenu>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { ContextMenu, ContextMenuContent, ContextMenuItem, ContextMenuTrigger } from '@tuturuuu/ui/context-menu';

<ContextMenu>
  <ContextMenuTrigger>Right click area</ContextMenuTrigger>
  <ContextMenuContent><ContextMenuItem>Duplicate</ContextMenuItem></ContextMenuContent>
</ContextMenu>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  ContextMenu,
  ContextMenuTrigger,
  ContextMenuContent,
} from '@tuturuuu/ui/context-menu';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { ContextMenu } from '@tuturuuu/ui/context-menu';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Items
* Shortcuts
* Danger zone

## Related components

* [Alert Dialog](./alert-dialog)
* [Dialog](./dialog)
* [Drawer](./drawer)

# Currency Input
Source: https://docs.tuturuuu.com/platform/components/ui/currency-input

Preview Currency Input, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/currency-input.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/currency-input](https://tuturuuu.com/ui/components/currency-input).

**Category:** Inputs · **Import:** `@tuturuuu/ui/currency-input` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { CurrencyInput } from '@tuturuuu/ui/currency-input';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { CurrencyInput } from '@tuturuuu/ui/currency-input';

<CurrencyInput value={amount} onChange={setAmount} currencySymbol="$" />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { CurrencyInput } from '@tuturuuu/ui/currency-input';

<CurrencyInput value={amount} onChange={setAmount} currencySymbol="$" />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { CurrencyInput } from '@tuturuuu/ui/currency-input';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Locale
* Symbol
* Helpers

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)

# Date Time Picker
Source: https://docs.tuturuuu.com/platform/components/ui/date-time-picker

Preview Date Time Picker, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/date-time-picker.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/date-time-picker](https://tuturuuu.com/ui/components/date-time-picker).

**Category:** Inputs · **Import:** `@tuturuuu/ui/date-time-picker` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { DateTimePicker } from '@tuturuuu/ui/date-time-picker';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { DateTimePicker } from '@tuturuuu/ui/date-time-picker';

<DateTimePicker date={date} setDate={setDate} showTimeSelect />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { DateTimePicker } from '@tuturuuu/ui/date-time-picker';

<DateTimePicker date={date} setDate={setDate} showTimeSelect />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { DateTimePicker } from '@tuturuuu/ui/date-time-picker';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Timezone
* Time format
* Inline mode

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)

# Dialog
Source: https://docs.tuturuuu.com/platform/components/ui/dialog

Preview Dialog, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/dialog.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/dialog](https://tuturuuu.com/ui/components/dialog).

**Category:** Overlays · **Import:** `@tuturuuu/ui/dialog` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Dialog, DialogTrigger, DialogContent, DialogHeader } from '@tuturuuu/ui/dialog';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Dialog, DialogContent, DialogTrigger } from '@tuturuuu/ui/dialog';

<Dialog>
  <DialogTrigger>Open</DialogTrigger>
  <DialogContent>Dialog content</DialogContent>
</Dialog>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Dialog, DialogContent, DialogTrigger } from '@tuturuuu/ui/dialog';

<Dialog>
  <DialogTrigger>Open</DialogTrigger>
  <DialogContent>Dialog content</DialogContent>
</Dialog>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Dialog,
  DialogTrigger,
  DialogContent,
  DialogHeader,
} from '@tuturuuu/ui/dialog';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Dialog } from '@tuturuuu/ui/dialog';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Size
* Trigger
* Footer

## Related components

* [Alert Dialog](./alert-dialog)
* [Context Menu](./context-menu)
* [Drawer](./drawer)

# Diff Viewer
Source: https://docs.tuturuuu.com/platform/components/ui/diff-viewer

Preview Diff Viewer, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/diff-viewer.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/diff-viewer](https://tuturuuu.com/ui/components/diff-viewer).

**Category:** Data · **Import:** `@tuturuuu/ui/diff-viewer` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { DiffViewer } from '@tuturuuu/ui/diff-viewer';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { DiffViewer } from '@tuturuuu/ui/diff-viewer';

<DiffViewer oldValue={oldText} newValue={newText} wrapper="inline" />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { DiffViewer } from '@tuturuuu/ui/diff-viewer';

<DiffViewer oldValue={oldText} newValue={newText} wrapper="inline" />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { DiffViewer } from '@tuturuuu/ui/diff-viewer';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* View mode
* Granularity
* Line numbers

## Related components

* [Chart](./chart)
* [Table](./table)
* [Accordion](./accordion)

# Drawer
Source: https://docs.tuturuuu.com/platform/components/ui/drawer

Preview Drawer, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/drawer.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/drawer](https://tuturuuu.com/ui/components/drawer).

**Category:** Overlays · **Import:** `@tuturuuu/ui/drawer` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Drawer, DrawerTrigger, DrawerContent } from '@tuturuuu/ui/drawer';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Drawer, DrawerContent, DrawerTrigger } from '@tuturuuu/ui/drawer';

<Drawer>
  <DrawerTrigger>Open drawer</DrawerTrigger>
  <DrawerContent>Drawer content</DrawerContent>
</Drawer>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Drawer, DrawerContent, DrawerTrigger } from '@tuturuuu/ui/drawer';

<Drawer>
  <DrawerTrigger>Open drawer</DrawerTrigger>
  <DrawerContent>Drawer content</DrawerContent>
</Drawer>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Drawer,
  DrawerTrigger,
  DrawerContent,
} from '@tuturuuu/ui/drawer';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Drawer } from '@tuturuuu/ui/drawer';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Direction
* Snap points
* Handle

## Related components

* [Alert Dialog](./alert-dialog)
* [Context Menu](./context-menu)
* [Dialog](./dialog)

# Dropdown Menu
Source: https://docs.tuturuuu.com/platform/components/ui/dropdown-menu

Preview Dropdown Menu, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/dropdown-menu.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/dropdown-menu](https://tuturuuu.com/ui/components/dropdown-menu).

**Category:** Overlays · **Import:** `@tuturuuu/ui/dropdown-menu` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent } from '@tuturuuu/ui/dropdown-menu';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger } from '@tuturuuu/ui/dropdown-menu';

<DropdownMenu>
  <DropdownMenuTrigger>Open menu</DropdownMenuTrigger>
  <DropdownMenuContent><DropdownMenuItem>Settings</DropdownMenuItem></DropdownMenuContent>
</DropdownMenu>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger } from '@tuturuuu/ui/dropdown-menu';

<DropdownMenu>
  <DropdownMenuTrigger>Open menu</DropdownMenuTrigger>
  <DropdownMenuContent><DropdownMenuItem>Settings</DropdownMenuItem></DropdownMenuContent>
</DropdownMenu>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
} from '@tuturuuu/ui/dropdown-menu';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { DropdownMenu } from '@tuturuuu/ui/dropdown-menu';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Items
* Checkbox items
* Shortcuts

## Related components

* [Alert Dialog](./alert-dialog)
* [Context Menu](./context-menu)
* [Dialog](./dialog)

# Form
Source: https://docs.tuturuuu.com/platform/components/ui/form

Preview Form, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/form.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/form](https://tuturuuu.com/ui/components/form).

**Category:** Inputs · **Import:** `@tuturuuu/ui/form` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from '@tuturuuu/ui/form';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Form, FormControl, FormField, FormItem, FormLabel } from '@tuturuuu/ui/form';

<Form {...form}>
  <FormField name="name" render={({ field }) => (
    <FormItem><FormLabel>Name</FormLabel><FormControl><Input {...field} /></FormControl></FormItem>
  )} />
</Form>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Form, FormControl, FormField, FormItem, FormLabel } from '@tuturuuu/ui/form';

<Form {...form}>
  <FormField name="name" render={({ field }) => (
    <FormItem><FormLabel>Name</FormLabel><FormControl><Input {...field} /></FormControl></FormItem>
  )} />
</Form>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Form,
  FormField,
  FormItem,
  FormLabel,
  FormControl,
  FormMessage,
} from '@tuturuuu/ui/form';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Form } from '@tuturuuu/ui/form';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Validation
* Required
* Description

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)

# Form Required Indicator
Source: https://docs.tuturuuu.com/platform/components/ui/form-required-indicator

Preview Form Required Indicator, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/form-required-indicator.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/form-required-indicator](https://tuturuuu.com/ui/components/form-required-indicator).

**Category:** Inputs · **Import:** `@tuturuuu/ui/form-required-indicator` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { FormRequiredIndicator } from '@tuturuuu/ui/form-required-indicator';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { FormRequiredIndicator } from '@tuturuuu/ui/form-required-indicator';

<Label>Name <FormRequiredIndicator /></Label>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { FormRequiredIndicator } from '@tuturuuu/ui/form-required-indicator';

<Label>Name <FormRequiredIndicator /></Label>
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { FormRequiredIndicator } from '@tuturuuu/ui/form-required-indicator';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Label
* Required
* Accessibility

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)

# Hover Card
Source: https://docs.tuturuuu.com/platform/components/ui/hover-card

Preview Hover Card, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/hover-card.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/hover-card](https://tuturuuu.com/ui/components/hover-card).

**Category:** Overlays · **Import:** `@tuturuuu/ui/hover-card` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { HoverCard, HoverCardTrigger, HoverCardContent } from '@tuturuuu/ui/hover-card';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { HoverCard, HoverCardContent, HoverCardTrigger } from '@tuturuuu/ui/hover-card';

<HoverCard>
  <HoverCardTrigger>Hover profile</HoverCardTrigger>
  <HoverCardContent>Profile summary</HoverCardContent>
</HoverCard>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { HoverCard, HoverCardContent, HoverCardTrigger } from '@tuturuuu/ui/hover-card';

<HoverCard>
  <HoverCardTrigger>Hover profile</HoverCardTrigger>
  <HoverCardContent>Profile summary</HoverCardContent>
</HoverCard>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  HoverCard,
  HoverCardTrigger,
  HoverCardContent,
} from '@tuturuuu/ui/hover-card';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { HoverCard } from '@tuturuuu/ui/hover-card';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Delay
* Side
* Content

## Related components

* [Alert Dialog](./alert-dialog)
* [Context Menu](./context-menu)
* [Dialog](./dialog)

# Input
Source: https://docs.tuturuuu.com/platform/components/ui/input

Preview Input, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/input.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/input](https://tuturuuu.com/ui/components/input).

**Category:** Inputs · **Import:** `@tuturuuu/ui/input` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Input } from '@tuturuuu/ui/input';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Input } from '@tuturuuu/ui/input';

<Input placeholder="Workspace name" />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Input } from '@tuturuuu/ui/input';

<Input placeholder="Workspace name" />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Input } from '@tuturuuu/ui/input';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Type
* Placeholder
* Disabled state

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)

# Input OTP
Source: https://docs.tuturuuu.com/platform/components/ui/input-otp

Preview Input OTP, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/input-otp.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/input-otp](https://tuturuuu.com/ui/components/input-otp).

**Category:** Inputs · **Import:** `@tuturuuu/ui/input-otp` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { InputOTP, InputOTPGroup, InputOTPSlot } from '@tuturuuu/ui/input-otp';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { InputOTP, InputOTPGroup, InputOTPSlot } from '@tuturuuu/ui/input-otp';

<InputOTP maxLength={6}>
  <InputOTPGroup>{[0, 1, 2].map((index) => <InputOTPSlot key={index} index={index} />)}</InputOTPGroup>
</InputOTP>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { InputOTP, InputOTPGroup, InputOTPSlot } from '@tuturuuu/ui/input-otp';

<InputOTP maxLength={6}>
  <InputOTPGroup>{[0, 1, 2].map((index) => <InputOTPSlot key={index} index={index} />)}</InputOTPGroup>
</InputOTP>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  InputOTP,
  InputOTPGroup,
  InputOTPSlot,
} from '@tuturuuu/ui/input-otp';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { InputOTP } from '@tuturuuu/ui/input-otp';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Length
* Separator
* Masking

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)

# Kbd
Source: https://docs.tuturuuu.com/platform/components/ui/kbd

Preview Kbd, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/kbd.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/kbd](https://tuturuuu.com/ui/components/kbd).

**Category:** Typography · **Import:** `@tuturuuu/ui/kbd` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Kbd } from '@tuturuuu/ui/kbd';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Kbd } from '@tuturuuu/ui/kbd';

<Kbd>Cmd K</Kbd>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Kbd } from '@tuturuuu/ui/kbd';

<Kbd>Cmd K</Kbd>
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Kbd } from '@tuturuuu/ui/kbd';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

| Export | Kind |
| - | - |
| `Kbd` | component |

## Customization

Common props, states, and composition points to review before using this component.

* Keys
* Size
* Sequence

## Related components

* [Code Block](./codeblock)
* [Markdown](./markdown)
* [Accordion](./accordion)

# Label
Source: https://docs.tuturuuu.com/platform/components/ui/label

Preview Label, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/label.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/label](https://tuturuuu.com/ui/components/label).

**Category:** Inputs · **Import:** `@tuturuuu/ui/label` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Label } from '@tuturuuu/ui/label';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Label } from '@tuturuuu/ui/label';

<Label htmlFor="workspace">Workspace</Label>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Label } from '@tuturuuu/ui/label';

<Label htmlFor="workspace">Workspace</Label>
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Label } from '@tuturuuu/ui/label';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Label target
* Required
* Disabled state

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)

# Markdown
Source: https://docs.tuturuuu.com/platform/components/ui/markdown

Preview Markdown, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/markdown.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/markdown](https://tuturuuu.com/ui/components/markdown).

**Category:** Typography · **Import:** `@tuturuuu/ui/markdown` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { MemoizedReactMarkdown } from '@tuturuuu/ui/markdown';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { MemoizedReactMarkdown } from '@tuturuuu/ui/markdown';

<MemoizedReactMarkdown>{markdown}</MemoizedReactMarkdown>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { MemoizedReactMarkdown } from '@tuturuuu/ui/markdown';

<MemoizedReactMarkdown>{markdown}</MemoizedReactMarkdown>
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { MemoizedReactMarkdown } from '@tuturuuu/ui/markdown';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Components
* Content
* Memoization

## Related components

* [Code Block](./codeblock)
* [Kbd](./kbd)
* [Accordion](./accordion)

# Menubar
Source: https://docs.tuturuuu.com/platform/components/ui/menubar

Preview Menubar, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/menubar.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/menubar](https://tuturuuu.com/ui/components/menubar).

**Category:** Navigation · **Import:** `@tuturuuu/ui/menubar` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Menubar, MenubarMenu, MenubarTrigger, MenubarContent } from '@tuturuuu/ui/menubar';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Menubar, MenubarContent, MenubarMenu, MenubarTrigger } from '@tuturuuu/ui/menubar';

<Menubar>
  <MenubarMenu><MenubarTrigger>File</MenubarTrigger><MenubarContent /></MenubarMenu>
</Menubar>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Menubar, MenubarContent, MenubarMenu, MenubarTrigger } from '@tuturuuu/ui/menubar';

<Menubar>
  <MenubarMenu><MenubarTrigger>File</MenubarTrigger><MenubarContent /></MenubarMenu>
</Menubar>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Menubar,
  MenubarMenu,
  MenubarTrigger,
  MenubarContent,
} from '@tuturuuu/ui/menubar';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Menubar } from '@tuturuuu/ui/menubar';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Menus
* Shortcuts
* Radio items

## Related components

* [Breadcrumb](./breadcrumb)
* [Command](./command)
* [Quick Command Center](./quick-command-center)

# Navbar
Source: https://docs.tuturuuu.com/platform/components/ui/navbar

Preview Navbar, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/navbar.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/navbar](https://tuturuuu.com/ui/components/navbar).

**Category:** Navigation · **Import:** `@tuturuuu/ui/navbar` · **Status:** Pattern preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Navbar } from '@tuturuuu/ui/navbar';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Navbar } from '@tuturuuu/ui/navbar';

<Navbar title="Tuturuuu" navigationMenu={<MainNavigation />} actions={<UserActions />} />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Navbar } from '@tuturuuu/ui/navbar';

<Navbar title="Tuturuuu" navigationMenu={<MainNavigation />} actions={<UserActions />} />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Navbar } from '@tuturuuu/ui/navbar';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Logo
* Actions
* Navigation

## Related components

* [Breadcrumb](./breadcrumb)
* [Command](./command)
* [Quick Command Center](./quick-command-center)

# Navigation Menu
Source: https://docs.tuturuuu.com/platform/components/ui/navigation-menu

Preview Navigation Menu, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/navigation-menu.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/navigation-menu](https://tuturuuu.com/ui/components/navigation-menu).

**Category:** Navigation · **Import:** `@tuturuuu/ui/navigation-menu` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { NavigationMenu, NavigationMenuList, NavigationMenuItem } from '@tuturuuu/ui/navigation-menu';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { NavigationMenu, NavigationMenuItem, NavigationMenuList } from '@tuturuuu/ui/navigation-menu';

<NavigationMenu><NavigationMenuList><NavigationMenuItem /></NavigationMenuList></NavigationMenu>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { NavigationMenu, NavigationMenuItem, NavigationMenuList } from '@tuturuuu/ui/navigation-menu';

<NavigationMenu><NavigationMenuList><NavigationMenuItem /></NavigationMenuList></NavigationMenu>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  NavigationMenu,
  NavigationMenuList,
  NavigationMenuItem,
} from '@tuturuuu/ui/navigation-menu';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { NavigationMenu } from '@tuturuuu/ui/navigation-menu';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Items
* Content
* Viewport

## Related components

* [Breadcrumb](./breadcrumb)
* [Command](./command)
* [Quick Command Center](./quick-command-center)

# Optional Time Picker
Source: https://docs.tuturuuu.com/platform/components/ui/optional-time-picker

Preview Optional Time Picker, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/optional-time-picker.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/optional-time-picker](https://tuturuuu.com/ui/components/optional-time-picker).

**Category:** Inputs · **Import:** `@tuturuuu/ui/optional-time-picker` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { OptionalTimePicker } from '@tuturuuu/ui/optional-time-picker';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { OptionalTimePicker } from '@tuturuuu/ui/optional-time-picker';

const [includeTime, setIncludeTime] = useState(true);

<OptionalTimePicker
  date={date}
  setDate={setDate}
  includeTime={includeTime}
  setIncludeTime={setIncludeTime}
  includeTimeLabel="Include time"
/>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { OptionalTimePicker } from '@tuturuuu/ui/optional-time-picker';

const [includeTime, setIncludeTime] = useState(true);

<OptionalTimePicker
  date={date}
  setDate={setDate}
  includeTime={includeTime}
  setIncludeTime={setIncludeTime}
  includeTimeLabel="Include time"
/>
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { OptionalTimePicker } from '@tuturuuu/ui/optional-time-picker';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Include time
* Timezone
* Time format
* Disabled state

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)

# UI Components
Source: https://docs.tuturuuu.com/platform/components/ui/overview

Reference for every component in the @tuturuuu/ui registry, mirrored from the live UI explorer.

> [!NOTE]
>
> Browse the live, interactive explorer at [tuturuuu.com/ui](https://tuturuuu.com/ui).

## Actions

* [Button](./button)
* [Toggle](./toggle)
* [Toggle Group](./toggle-group)

## Inputs

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)
* [Currency Input](./currency-input)
* [Date Time Picker](./date-time-picker)
* [Optional Time Picker](./optional-time-picker)
* [Form](./form)
* [Form Required Indicator](./form-required-indicator)
* [Input](./input)
* [Input OTP](./input-otp)
* [Label](./label)
* [Radio Group](./radio-group)
* [Select](./select)
* [Slider](./slider)
* [Switch](./switch)
* [Textarea](./textarea)
* [Time Picker Input](./time-picker-input)

## Overlays

* [Alert Dialog](./alert-dialog)
* [Context Menu](./context-menu)
* [Dialog](./dialog)
* [Drawer](./drawer)
* [Dropdown Menu](./dropdown-menu)
* [Hover Card](./hover-card)
* [Popover](./popover)
* [Sheet](./sheet)
* [Tooltip](./tooltip)

## Navigation

* [Breadcrumb](./breadcrumb)
* [Command](./command)
* [Quick Command Center](./quick-command-center)
* [Menubar](./menubar)
* [Navbar](./navbar)
* [Navigation Menu](./navigation-menu)
* [Pagination](./pagination)
* [Sidebar](./sidebar)
* [Tabs](./tabs)

## Feedback

* [Alert](./alert)
* [Avatar](./avatar)
* [Badge](./badge)
* [Progress](./progress)
* [Skeleton](./skeleton)
* [Sonner](./sonner)
* [Sticky Bottom Bar](./sticky-bottom-bar)
* [Toast](./toast)
* [Toaster](./toaster)

## Data

* [Chart](./chart)
* [Diff Viewer](./diff-viewer)
* [Table](./table)

## Layout

* [Accordion](./accordion)
* [Aspect Ratio](./aspect-ratio)
* [Card](./card)
* [Carousel](./carousel)
* [Collapsible](./collapsible)
* [Resizable](./resizable)
* [Scroll Area](./scroll-area)
* [Separator](./separator)

## Typography

* [Code Block](./codeblock)
* [Kbd](./kbd)
* [Markdown](./markdown)

## Advanced

* [Report Problem Dialog](./report-problem-dialog)

# Pagination
Source: https://docs.tuturuuu.com/platform/components/ui/pagination

Preview Pagination, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/pagination.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/pagination](https://tuturuuu.com/ui/components/pagination).

**Category:** Navigation · **Import:** `@tuturuuu/ui/pagination` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Pagination, PaginationContent, PaginationItem, PaginationLink } from '@tuturuuu/ui/pagination';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Pagination, PaginationContent, PaginationItem, PaginationLink } from '@tuturuuu/ui/pagination';

<Pagination><PaginationContent><PaginationItem><PaginationLink href="#">1</PaginationLink></PaginationItem></PaginationContent></Pagination>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Pagination, PaginationContent, PaginationItem, PaginationLink } from '@tuturuuu/ui/pagination';

<Pagination><PaginationContent><PaginationItem><PaginationLink href="#">1</PaginationLink></PaginationItem></PaginationContent></Pagination>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Pagination,
  PaginationContent,
  PaginationItem,
  PaginationLink,
} from '@tuturuuu/ui/pagination';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Pagination } from '@tuturuuu/ui/pagination';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Page
* Siblings
* Disabled state

## Related components

* [Breadcrumb](./breadcrumb)
* [Command](./command)
* [Quick Command Center](./quick-command-center)

# Popover
Source: https://docs.tuturuuu.com/platform/components/ui/popover

Preview Popover, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/popover.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/popover](https://tuturuuu.com/ui/components/popover).

**Category:** Overlays · **Import:** `@tuturuuu/ui/popover` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Popover, PopoverTrigger, PopoverContent } from '@tuturuuu/ui/popover';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Popover, PopoverContent, PopoverTrigger } from '@tuturuuu/ui/popover';

<Popover><PopoverTrigger>Open</PopoverTrigger><PopoverContent>Popover content</PopoverContent></Popover>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Popover, PopoverContent, PopoverTrigger } from '@tuturuuu/ui/popover';

<Popover><PopoverTrigger>Open</PopoverTrigger><PopoverContent>Popover content</PopoverContent></Popover>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Popover,
  PopoverTrigger,
  PopoverContent,
} from '@tuturuuu/ui/popover';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Popover } from '@tuturuuu/ui/popover';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Side
* Align
* Content

## Related components

* [Alert Dialog](./alert-dialog)
* [Context Menu](./context-menu)
* [Dialog](./dialog)

# Progress
Source: https://docs.tuturuuu.com/platform/components/ui/progress

Preview Progress, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/progress.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/progress](https://tuturuuu.com/ui/components/progress).

**Category:** Feedback · **Import:** `@tuturuuu/ui/progress` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Progress } from '@tuturuuu/ui/progress';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Progress } from '@tuturuuu/ui/progress';

<Progress value={72} />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Progress } from '@tuturuuu/ui/progress';

<Progress value={72} />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Progress } from '@tuturuuu/ui/progress';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Value
* Indicator
* Label

## Related components

* [Alert](./alert)
* [Avatar](./avatar)
* [Badge](./badge)

# Quick Command Center
Source: https://docs.tuturuuu.com/platform/components/ui/quick-command-center

Preview Quick Command Center, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/quick-command-center.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/quick-command-center](https://tuturuuu.com/ui/components/quick-command-center).

**Category:** Navigation · **Import:** `@tuturuuu/ui/quick-command-center` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { QuickCommandCenter } from '@tuturuuu/ui/quick-command-center';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { QuickCommandCenter } from '@tuturuuu/ui/quick-command-center';

<QuickCommandCenter
  open={open}
  onOpenChange={setOpen}
  title="Quick actions"
  placeholder="Search..."
  emptyLabel="No commands found"
  digitShortcuts
  groups={groups}
/>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { QuickCommandCenter } from '@tuturuuu/ui/quick-command-center';

<QuickCommandCenter
  open={open}
  onOpenChange={setOpen}
  title="Quick actions"
  placeholder="Search..."
  emptyLabel="No commands found"
  digitShortcuts
  groups={groups}
/>
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { QuickCommandCenter } from '@tuturuuu/ui/quick-command-center';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Groups
* Digit shortcuts
* Search value

## Related components

* [Breadcrumb](./breadcrumb)
* [Command](./command)
* [Menubar](./menubar)

# Radio Group
Source: https://docs.tuturuuu.com/platform/components/ui/radio-group

Preview Radio Group, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/radio-group.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/radio-group](https://tuturuuu.com/ui/components/radio-group).

**Category:** Inputs · **Import:** `@tuturuuu/ui/radio-group` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { RadioGroup, RadioGroupItem } from '@tuturuuu/ui/radio-group';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { RadioGroup, RadioGroupItem } from '@tuturuuu/ui/radio-group';

<RadioGroup defaultValue="compact"><RadioGroupItem value="compact" /></RadioGroup>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { RadioGroup, RadioGroupItem } from '@tuturuuu/ui/radio-group';

<RadioGroup defaultValue="compact"><RadioGroupItem value="compact" /></RadioGroup>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  RadioGroup,
  RadioGroupItem,
} from '@tuturuuu/ui/radio-group';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { RadioGroup } from '@tuturuuu/ui/radio-group';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Orientation
* Default value
* Labels

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)

# Report Problem Dialog
Source: https://docs.tuturuuu.com/platform/components/ui/report-problem-dialog

Preview Report Problem Dialog, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/report-problem-dialog.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/report-problem-dialog](https://tuturuuu.com/ui/components/report-problem-dialog).

**Category:** Advanced · **Import:** `@tuturuuu/ui/report-problem-dialog` · **Status:** Pattern preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { ReportProblemDialog } from '@tuturuuu/ui/report-problem-dialog';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { ReportProblemDialog } from '@tuturuuu/ui/report-problem-dialog';

<ReportProblemDialog />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { ReportProblemDialog } from '@tuturuuu/ui/report-problem-dialog';

<ReportProblemDialog />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { ReportProblemDialog } from '@tuturuuu/ui/report-problem-dialog';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Products
* Trigger
* Show trigger

## Related components

* [Accordion](./accordion)
* [Alert](./alert)
* [Alert Dialog](./alert-dialog)

# Resizable
Source: https://docs.tuturuuu.com/platform/components/ui/resizable

Preview Resizable, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/resizable.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/resizable](https://tuturuuu.com/ui/components/resizable).

**Category:** Layout · **Import:** `@tuturuuu/ui/resizable` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { ResizablePanelGroup, ResizablePanel, ResizableHandle } from '@tuturuuu/ui/resizable';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from '@tuturuuu/ui/resizable';

<ResizablePanelGroup direction="horizontal">
  <ResizablePanel>Primary</ResizablePanel><ResizableHandle withHandle /><ResizablePanel>Secondary</ResizablePanel>
</ResizablePanelGroup>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from '@tuturuuu/ui/resizable';

<ResizablePanelGroup direction="horizontal">
  <ResizablePanel>Primary</ResizablePanel><ResizableHandle withHandle /><ResizablePanel>Secondary</ResizablePanel>
</ResizablePanelGroup>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  ResizablePanelGroup,
  ResizablePanel,
  ResizableHandle,
} from '@tuturuuu/ui/resizable';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { ResizablePanelGroup } from '@tuturuuu/ui/resizable';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Direction
* Default size
* Handle

## Related components

* [Accordion](./accordion)
* [Aspect Ratio](./aspect-ratio)
* [Card](./card)

# Scroll Area
Source: https://docs.tuturuuu.com/platform/components/ui/scroll-area

Preview Scroll Area, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/scroll-area.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/scroll-area](https://tuturuuu.com/ui/components/scroll-area).

**Category:** Layout · **Import:** `@tuturuuu/ui/scroll-area` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { ScrollArea, ScrollBar } from '@tuturuuu/ui/scroll-area';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { ScrollArea } from '@tuturuuu/ui/scroll-area';

<ScrollArea className="h-48">Scrollable content</ScrollArea>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { ScrollArea } from '@tuturuuu/ui/scroll-area';

<ScrollArea className="h-48">Scrollable content</ScrollArea>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  ScrollArea,
  ScrollBar,
} from '@tuturuuu/ui/scroll-area';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { ScrollArea } from '@tuturuuu/ui/scroll-area';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Height
* Scrollbar
* Content

## Related components

* [Accordion](./accordion)
* [Aspect Ratio](./aspect-ratio)
* [Card](./card)

# Select
Source: https://docs.tuturuuu.com/platform/components/ui/select

Preview Select, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/select.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/select](https://tuturuuu.com/ui/components/select).

**Category:** Inputs · **Import:** `@tuturuuu/ui/select` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Select, SelectTrigger, SelectContent, SelectItem } from '@tuturuuu/ui/select';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@tuturuuu/ui/select';

<Select><SelectTrigger><SelectValue placeholder="Choose" /></SelectTrigger><SelectContent><SelectItem value="one">One</SelectItem></SelectContent></Select>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@tuturuuu/ui/select';

<Select><SelectTrigger><SelectValue placeholder="Choose" /></SelectTrigger><SelectContent><SelectItem value="one">One</SelectItem></SelectContent></Select>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Select,
  SelectTrigger,
  SelectContent,
  SelectItem,
} from '@tuturuuu/ui/select';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Select } from '@tuturuuu/ui/select';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Options
* Placeholder
* Disabled state

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)

# Separator
Source: https://docs.tuturuuu.com/platform/components/ui/separator

Preview Separator, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/separator.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/separator](https://tuturuuu.com/ui/components/separator).

**Category:** Layout · **Import:** `@tuturuuu/ui/separator` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Separator } from '@tuturuuu/ui/separator';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Separator } from '@tuturuuu/ui/separator';

<Separator orientation="horizontal" />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Separator } from '@tuturuuu/ui/separator';

<Separator orientation="horizontal" />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Separator } from '@tuturuuu/ui/separator';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Orientation
* Spacing
* Decorative

## Related components

* [Accordion](./accordion)
* [Aspect Ratio](./aspect-ratio)
* [Card](./card)

# Sheet
Source: https://docs.tuturuuu.com/platform/components/ui/sheet

Preview Sheet, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/sheet.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/sheet](https://tuturuuu.com/ui/components/sheet).

**Category:** Overlays · **Import:** `@tuturuuu/ui/sheet` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Sheet, SheetTrigger, SheetContent } from '@tuturuuu/ui/sheet';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Sheet, SheetContent, SheetTrigger } from '@tuturuuu/ui/sheet';

<Sheet><SheetTrigger>Open panel</SheetTrigger><SheetContent side="right">Panel content</SheetContent></Sheet>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Sheet, SheetContent, SheetTrigger } from '@tuturuuu/ui/sheet';

<Sheet><SheetTrigger>Open panel</SheetTrigger><SheetContent side="right">Panel content</SheetContent></Sheet>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Sheet,
  SheetTrigger,
  SheetContent,
} from '@tuturuuu/ui/sheet';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Sheet } from '@tuturuuu/ui/sheet';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Side
* Size
* Footer

## Related components

* [Alert Dialog](./alert-dialog)
* [Context Menu](./context-menu)
* [Dialog](./dialog)

# Sidebar
Source: https://docs.tuturuuu.com/platform/components/ui/sidebar

Preview Sidebar, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/sidebar.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/sidebar](https://tuturuuu.com/ui/components/sidebar).

**Category:** Navigation · **Import:** `@tuturuuu/ui/sidebar` · **Status:** Pattern preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { SidebarProvider, Sidebar, SidebarMenu, SidebarTrigger } from '@tuturuuu/ui/sidebar';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Sidebar, SidebarProvider, SidebarTrigger } from '@tuturuuu/ui/sidebar';

<SidebarProvider><Sidebar /><SidebarTrigger /></SidebarProvider>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Sidebar, SidebarProvider, SidebarTrigger } from '@tuturuuu/ui/sidebar';

<SidebarProvider><Sidebar /><SidebarTrigger /></SidebarProvider>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  SidebarProvider,
  Sidebar,
  SidebarMenu,
  SidebarTrigger,
} from '@tuturuuu/ui/sidebar';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { SidebarProvider } from '@tuturuuu/ui/sidebar';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Collapsible
* Variant
* Groups

## Related components

* [Breadcrumb](./breadcrumb)
* [Command](./command)
* [Quick Command Center](./quick-command-center)

# Skeleton
Source: https://docs.tuturuuu.com/platform/components/ui/skeleton

Preview Skeleton, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/skeleton.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/skeleton](https://tuturuuu.com/ui/components/skeleton).

**Category:** Feedback · **Import:** `@tuturuuu/ui/skeleton` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Skeleton } from '@tuturuuu/ui/skeleton';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Skeleton } from '@tuturuuu/ui/skeleton';

<Skeleton className="h-6 w-32" />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Skeleton } from '@tuturuuu/ui/skeleton';

<Skeleton className="h-6 w-32" />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Skeleton } from '@tuturuuu/ui/skeleton';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Shape
* Size
* Layout

## Related components

* [Alert](./alert)
* [Avatar](./avatar)
* [Badge](./badge)

# Slider
Source: https://docs.tuturuuu.com/platform/components/ui/slider

Preview Slider, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/slider.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/slider](https://tuturuuu.com/ui/components/slider).

**Category:** Inputs · **Import:** `@tuturuuu/ui/slider` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Slider } from '@tuturuuu/ui/slider';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Slider } from '@tuturuuu/ui/slider';

<Slider defaultValue={[64]} max={100} step={1} />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Slider } from '@tuturuuu/ui/slider';

<Slider defaultValue={[64]} max={100} step={1} />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Slider } from '@tuturuuu/ui/slider';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Min and max
* Step
* Value

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)

# Sonner
Source: https://docs.tuturuuu.com/platform/components/ui/sonner

Preview Sonner, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/sonner.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/sonner](https://tuturuuu.com/ui/components/sonner).

**Category:** Feedback · **Import:** `@tuturuuu/ui/sonner` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Toaster, toast } from '@tuturuuu/ui/sonner';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Toaster, toast } from '@tuturuuu/ui/sonner';

toast.success('Saved changes');

<Toaster />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Toaster, toast } from '@tuturuuu/ui/sonner';

toast.success('Saved changes');

<Toaster />
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Toaster,
  toast,
} from '@tuturuuu/ui/sonner';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Toaster } from '@tuturuuu/ui/sonner';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Theme
* Position
* Action

## Related components

* [Alert](./alert)
* [Avatar](./avatar)
* [Badge](./badge)

# Sticky Bottom Bar
Source: https://docs.tuturuuu.com/platform/components/ui/sticky-bottom-bar

Preview Sticky Bottom Bar, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/sticky-bottom-bar.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/sticky-bottom-bar](https://tuturuuu.com/ui/components/sticky-bottom-bar).

**Category:** Feedback · **Import:** `@tuturuuu/ui/sticky-bottom-bar` · **Status:** Pattern preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { StickyBottomBar } from '@tuturuuu/ui/sticky-bottom-bar';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { StickyBottomBar } from '@tuturuuu/ui/sticky-bottom-bar';

<StickyBottomBar show message="Unsaved changes" actions={<Button>Save</Button>} />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { StickyBottomBar } from '@tuturuuu/ui/sticky-bottom-bar';

<StickyBottomBar show message="Unsaved changes" actions={<Button>Save</Button>} />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { StickyBottomBar } from '@tuturuuu/ui/sticky-bottom-bar';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Visibility
* Message
* Actions

## Related components

* [Alert](./alert)
* [Avatar](./avatar)
* [Badge](./badge)

# Switch
Source: https://docs.tuturuuu.com/platform/components/ui/switch

Preview Switch, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/switch.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/switch](https://tuturuuu.com/ui/components/switch).

**Category:** Inputs · **Import:** `@tuturuuu/ui/switch` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Switch } from '@tuturuuu/ui/switch';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Switch } from '@tuturuuu/ui/switch';

<Switch defaultChecked />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Switch } from '@tuturuuu/ui/switch';

<Switch defaultChecked />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Switch } from '@tuturuuu/ui/switch';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Checked state
* Disabled state
* Label

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)

# Table
Source: https://docs.tuturuuu.com/platform/components/ui/table

Preview Table, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/table.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/table](https://tuturuuu.com/ui/components/table).

**Category:** Data · **Import:** `@tuturuuu/ui/table` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Table, TableHeader, TableRow, TableHead, TableBody, TableCell } from '@tuturuuu/ui/table';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@tuturuuu/ui/table';

<Table><TableHeader><TableRow><TableHead>Name</TableHead></TableRow></TableHeader><TableBody><TableRow><TableCell>Mira</TableCell></TableRow></TableBody></Table>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@tuturuuu/ui/table';

<Table><TableHeader><TableRow><TableHead>Name</TableHead></TableRow></TableHeader><TableBody><TableRow><TableCell>Mira</TableCell></TableRow></TableBody></Table>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Table,
  TableHeader,
  TableRow,
  TableHead,
  TableBody,
  TableCell,
} from '@tuturuuu/ui/table';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Table } from '@tuturuuu/ui/table';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Columns
* Density
* Empty state

## Related components

* [Chart](./chart)
* [Diff Viewer](./diff-viewer)
* [Accordion](./accordion)

# Tabs
Source: https://docs.tuturuuu.com/platform/components/ui/tabs

Preview Tabs, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/tabs.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/tabs](https://tuturuuu.com/ui/components/tabs).

**Category:** Navigation · **Import:** `@tuturuuu/ui/tabs` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Tabs, TabsList, TabsTrigger, TabsContent } from '@tuturuuu/ui/tabs';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Tabs, TabsContent, TabsList, TabsTrigger } from '@tuturuuu/ui/tabs';

<Tabs defaultValue="preview"><TabsList><TabsTrigger value="preview">Preview</TabsTrigger></TabsList><TabsContent value="preview">Content</TabsContent></Tabs>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Tabs, TabsContent, TabsList, TabsTrigger } from '@tuturuuu/ui/tabs';

<Tabs defaultValue="preview"><TabsList><TabsTrigger value="preview">Preview</TabsTrigger></TabsList><TabsContent value="preview">Content</TabsContent></Tabs>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Tabs,
  TabsList,
  TabsTrigger,
  TabsContent,
} from '@tuturuuu/ui/tabs';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Tabs } from '@tuturuuu/ui/tabs';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Default value
* Orientation
* Content

## Related components

* [Breadcrumb](./breadcrumb)
* [Command](./command)
* [Quick Command Center](./quick-command-center)

# Textarea
Source: https://docs.tuturuuu.com/platform/components/ui/textarea

Preview Textarea, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/textarea.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/textarea](https://tuturuuu.com/ui/components/textarea).

**Category:** Inputs · **Import:** `@tuturuuu/ui/textarea` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Textarea } from '@tuturuuu/ui/textarea';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Textarea } from '@tuturuuu/ui/textarea';

<Textarea placeholder="Write an update..." />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Textarea } from '@tuturuuu/ui/textarea';

<Textarea placeholder="Write an update..." />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Textarea } from '@tuturuuu/ui/textarea';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Rows
* Placeholder
* Resize

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)

# Time Picker Input
Source: https://docs.tuturuuu.com/platform/components/ui/time-picker-input

Preview Time Picker Input, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/time-picker-input.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/time-picker-input](https://tuturuuu.com/ui/components/time-picker-input).

**Category:** Inputs · **Import:** `@tuturuuu/ui/time-picker-input` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { TimePickerInput } from '@tuturuuu/ui/time-picker-input';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { TimePickerInput } from '@tuturuuu/ui/time-picker-input';

<TimePickerInput picker="hours" date={date} setDate={setDate} />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { TimePickerInput } from '@tuturuuu/ui/time-picker-input';

<TimePickerInput picker="hours" date={date} setDate={setDate} />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { TimePickerInput } from '@tuturuuu/ui/time-picker-input';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Picker
* Date
* Keyboard

## Related components

* [Calendar](./calendar)
* [Checkbox](./checkbox)
* [Color Picker](./color-picker)

# Toast
Source: https://docs.tuturuuu.com/platform/components/ui/toast

Preview Toast, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/toast.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/toast](https://tuturuuu.com/ui/components/toast).

**Category:** Feedback · **Import:** `@tuturuuu/ui/toast` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Toast, ToastTitle, ToastDescription, ToastProvider } from '@tuturuuu/ui/toast';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Toast, ToastDescription, ToastTitle } from '@tuturuuu/ui/toast';

<Toast><ToastTitle>Saved</ToastTitle><ToastDescription>Your changes are live.</ToastDescription></Toast>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Toast, ToastDescription, ToastTitle } from '@tuturuuu/ui/toast';

<Toast><ToastTitle>Saved</ToastTitle><ToastDescription>Your changes are live.</ToastDescription></Toast>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Toast,
  ToastTitle,
  ToastDescription,
  ToastProvider,
} from '@tuturuuu/ui/toast';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Toast } from '@tuturuuu/ui/toast';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Variant
* Action
* Viewport

## Related components

* [Alert](./alert)
* [Avatar](./avatar)
* [Badge](./badge)

# Toaster
Source: https://docs.tuturuuu.com/platform/components/ui/toaster

Preview Toaster, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/toaster.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/toaster](https://tuturuuu.com/ui/components/toaster).

**Category:** Feedback · **Import:** `@tuturuuu/ui/toaster` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Toaster } from '@tuturuuu/ui/toaster';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Toaster } from '@tuturuuu/ui/toaster';

<Toaster />
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Toaster } from '@tuturuuu/ui/toaster';

<Toaster />
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Toaster } from '@tuturuuu/ui/toaster';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Provider
* Viewport
* Hooks

## Related components

* [Alert](./alert)
* [Avatar](./avatar)
* [Badge](./badge)

# Toggle
Source: https://docs.tuturuuu.com/platform/components/ui/toggle

Preview Toggle, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/toggle.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/toggle](https://tuturuuu.com/ui/components/toggle).

**Category:** Actions · **Import:** `@tuturuuu/ui/toggle` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Toggle, toggleVariants } from '@tuturuuu/ui/toggle';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Toggle } from '@tuturuuu/ui/toggle';

<Toggle aria-label="Toggle bold">B</Toggle>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Toggle } from '@tuturuuu/ui/toggle';

<Toggle aria-label="Toggle bold">B</Toggle>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Toggle,
  toggleVariants,
} from '@tuturuuu/ui/toggle';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Toggle } from '@tuturuuu/ui/toggle';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Pressed state
* Variant
* Size

## Related components

* [Button](./button)
* [Toggle Group](./toggle-group)
* [Accordion](./accordion)

# Toggle Group
Source: https://docs.tuturuuu.com/platform/components/ui/toggle-group

Preview Toggle Group, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/toggle-group.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/toggle-group](https://tuturuuu.com/ui/components/toggle-group).

**Category:** Actions · **Import:** `@tuturuuu/ui/toggle-group` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { ToggleGroup, ToggleGroupItem } from '@tuturuuu/ui/toggle-group';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { ToggleGroup, ToggleGroupItem } from '@tuturuuu/ui/toggle-group';

<ToggleGroup type="single" defaultValue="list"><ToggleGroupItem value="list">List</ToggleGroupItem></ToggleGroup>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { ToggleGroup, ToggleGroupItem } from '@tuturuuu/ui/toggle-group';

<ToggleGroup type="single" defaultValue="list"><ToggleGroupItem value="list">List</ToggleGroupItem></ToggleGroup>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  ToggleGroup,
  ToggleGroupItem,
} from '@tuturuuu/ui/toggle-group';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { ToggleGroup } from '@tuturuuu/ui/toggle-group';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Type
* Selection
* Size

## Related components

* [Button](./button)
* [Toggle](./toggle)
* [Accordion](./accordion)

# Tooltip
Source: https://docs.tuturuuu.com/platform/components/ui/tooltip

Preview Tooltip, copy setup snippets, review examples, and inspect API exports for @tuturuuu/ui/tooltip.

> [!NOTE]
>
> Explore the live, interactive preview at [tuturuuu.com/ui/components/tooltip](https://tuturuuu.com/ui/components/tooltip).

**Category:** Overlays · **Import:** `@tuturuuu/ui/tooltip` · **Status:** Live preview

## Installation

Install the shared UI package, import global styles once, then import the component from its public subpath.

```bash theme={null}
bun add @tuturuuu/ui
```

```tsx theme={null}
import '@tuturuuu/ui/globals.css';
import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from '@tuturuuu/ui/tooltip';
```

## Usage

Copy the default usage snippet and adapt labels, state, and event handlers to the product surface.

```tsx theme={null}
import { Tooltip, TooltipContent, TooltipTrigger } from '@tuturuuu/ui/tooltip';

<Tooltip><TooltipTrigger>Hover</TooltipTrigger><TooltipContent>Helpful context</TooltipContent></Tooltip>
```

## Examples

Examples reuse the registry snippets so the docs stay aligned with the component catalog.

### Default

A minimal implementation using the current registry snippet.

```tsx theme={null}
import { Tooltip, TooltipContent, TooltipTrigger } from '@tuturuuu/ui/tooltip';

<Tooltip><TooltipTrigger>Hover</TooltipTrigger><TooltipContent>Helpful context</TooltipContent></Tooltip>
```

### Composition

Use the grouped exports when the primitive has slots, triggers, content regions, or providers.

```tsx theme={null}
import {
  Tooltip,
  TooltipTrigger,
  TooltipContent,
  TooltipProvider,
} from '@tuturuuu/ui/tooltip';
```

### Package import

Import through the public package path so workspace and external apps share the same contract.

```tsx theme={null}
// Public package import
import { Tooltip } from '@tuturuuu/ui/tooltip';

// Workspace apps should keep importing through the package boundary.
```

## API reference

The public exports currently available from this component entry.

## Customization

Common props, states, and composition points to review before using this component.

* Delay
* Side
* Content

## Related components

* [Alert Dialog](./alert-dialog)
* [Context Menu](./context-menu)
* [Dialog](./dialog)

# WorkspaceWrapper Component
Source: https://docs.tuturuuu.com/platform/components/workspace-wrapper

A standardized component for handling workspace ID resolution and validation across the application

The `WorkspaceWrapper` component provides a centralized way to handle workspace ID resolution and validation across the application. It automatically converts legacy workspace identifiers to validated UUIDs and provides the full workspace object to child components.

## Problem Solved

Currently, workspace ID resolution is handled inconsistently across components:

* `'personal'` → resolves to the user's personal workspace UUID
* `'internal'` → resolves to `ROOT_WORKSPACE_ID`
* UUID strings → validates and uses as-is

The `WorkspaceWrapper` centralizes this logic and ensures that child components always receive a validated workspace UUID. After resolution, the `isPersonal` flag is derived from the resolved `workspace.personal` field (not from the original `'personal'` URL string), and `isRoot` is derived by comparing `workspace.id` to `ROOT_WORKSPACE_ID`.

> [!NOTE]
>
> This component is specific to the **Next.js App Router** server-component model in `apps/web` (port `7803`). It relies on async `params`, React Suspense, and server-side `getWorkspace`. The platform is actively migrating `apps/web` to `apps/tanstack-web` (TanStack Start) plus `apps/backend` (Rust); see [/platform/architecture/tanstack-rust-migration](/platform/architecture/tanstack-rust-migration). This wrapper pattern does not carry over verbatim to the TanStack Start app, but the `apps/web` documentation below remains valid for the current platform.

## URL Context

The `WorkspaceWrapper` is designed for use in Next.js App Router pages with dynamic segments:

### Basic Pattern

* **File structure**: `apps/web/src/app/[locale]/(dashboard)/[wsId]/page.tsx`
* **User-facing URL**: `/[wsId]/...` (locale handled transparently by middleware)
* **Route params**: `{ wsId: string }`

### Advanced Pattern with Additional Params

* **File structure**: `apps/web/src/app/[locale]/(dashboard)/[wsId]/[datasetId]/page.tsx`
* **User-facing URL**: `/[wsId]/[datasetId]/...`
* **Route params**: `{ wsId: string, datasetId: string }`

The component automatically passes through any additional parameters beyond `wsId` to the children function.

## Installation

The canonical source lives in the shared UI package at `@tuturuuu/ui/custom/workspace-wrapper` (file: `packages/ui/src/components/ui/custom/workspace-wrapper.tsx`).

```tsx theme={null}
// Canonical import (shared package — works in any consumer)
import WorkspaceWrapper, {
  withWorkspace,
  type BaseParams,
  type WorkspaceWrapperProps,
} from '@tuturuuu/ui/custom/workspace-wrapper';
```

Within `apps/web` you may also see the legacy path `@/components/workspace-wrapper`. That module is a thin backward-compatible re-export of the canonical package and exposes the same `default`, `withWorkspace`, `BaseParams`, and `WorkspaceWrapperProps` symbols:

```tsx theme={null}
// Backward-compatible re-export inside apps/web
import WorkspaceWrapper from '@/components/workspace-wrapper';
```

Prefer the `@tuturuuu/ui/custom/workspace-wrapper` import for new code, especially in shared packages and other apps.

## Basic Usage

### Function Children Pattern

```tsx theme={null}
export default async function MyPage({ 
  params 
}: { 
  params: Promise<{ wsId: string }> 
}) {
  return (
    <WorkspaceWrapper params={params}>
      {({ workspace, wsId, isPersonal, isRoot }) => (
        <div>
          <h1>{workspace.name}</h1>
          <p>Workspace UUID: {wsId}</p>
          <p>Is Personal: {isPersonal ? 'Yes' : 'No'}</p>
          <p>Is Root: {isRoot ? 'Yes' : 'No'}</p>
        </div>
      )}
    </WorkspaceWrapper>
  );
}
```

### With Loading Fallback

```tsx theme={null}
import LoadingSpinner from '@/components/loading-spinner';

export default async function MyPage({ 
  params 
}: { 
  params: Promise<{ wsId: string }> 
}) {
  return (
    <WorkspaceWrapper 
      params={params}
      fallback={<LoadingSpinner />}
    >
      {({ workspace, wsId, isPersonal, isRoot }) => (
        <MyWorkspaceContent workspace={workspace} wsId={wsId} />
      )}
    </WorkspaceWrapper>
  );
}
```

## Advanced Usage

### With Additional Route Parameters

For pages with additional dynamic segments beyond `wsId`:

```tsx theme={null}
// File: apps/web/src/app/[locale]/(dashboard)/[wsId]/[datasetId]/page.tsx
// URL: /personal/datasets/123, /550e8400-e29b-41d4-a716-446655440000/datasets/456
export default async function DatasetPage({
  params
}: {
  params: Promise<{ wsId: string; datasetId: string }>
}) {
  return (
    <WorkspaceWrapper params={params}>
      {({ workspace, wsId, isPersonal, isRoot, datasetId }) => (
        <div>
          <h1>{workspace.name} - Dataset {datasetId}</h1>
          <p>Workspace UUID: {wsId}</p>
          <p>Dataset ID: {datasetId}</p>
          <p>Is Personal: {isPersonal ? 'Yes' : 'No'}</p>
        </div>
      )}
    </WorkspaceWrapper>
  );
}
```

The `WorkspaceWrapper` automatically passes through `datasetId` (and any other additional params) to the children function.

### Using withWorkspace Helper

For client components that need workspace context, use the `withWorkspace` helper:

```tsx theme={null}
import { withWorkspace } from '@tuturuuu/ui/custom/workspace-wrapper';
import MyClientComponent from './my-client-component';

export default async function MyPage({
  params
}: {
  params: Promise<{ wsId: string }>
}) {
  const { wsId } = await params;

return withWorkspace(
    wsId,
    MyClientComponent,
    {
      someProp: 'value',
      anotherProp: 42
    },
    <div>Loading workspace...</div>
  );
}
```

### Client Component Receiving Workspace Props

```tsx theme={null}
'use client';

import type { Workspace, WorkspaceProductTier } from '@tuturuuu/types';

interface MyClientComponentProps {
  workspace: Workspace & {
    joined: boolean;
    tier: WorkspaceProductTier | null;
  };
  wsId: string; // Validated UUID
  isPersonal: boolean;
  isRoot: boolean;
  someProp: string;
  anotherProp: number;
}

export function MyClientComponent({ 
  workspace, 
  wsId, 
  isPersonal,
  isRoot,
  someProp, 
  anotherProp 
}: MyClientComponentProps) {
  // Use workspace and wsId safely - they're guaranteed to be valid
  return (
    <div>
      <h1>{workspace.name}</h1>
      <p>Workspace ID: {wsId}</p>
      <p>Personal: {isPersonal ? 'Yes' : 'No'}</p>
      <p>Root: {isRoot ? 'Yes' : 'No'}</p>
    </div>
  );
}
```

## API Reference

### WorkspaceWrapper Props

| Prop | Type | Required | Description |
| - | - | - | - |
| `params` | `Promise<TParams>` where `TParams extends BaseParams` | Yes | The route params containing `wsId` and any additional params |
| `children` | `Function` | Yes | Function that receives `{ workspace, wsId, isPersonal, isRoot, ...additionalParams }` |
| `fallback` | `ReactNode` | No | Loading fallback component |

**Note**: The `params` type is generic and supports additional route parameters beyond the base `locale` and `wsId`.

### withWorkspace Parameters

### Children Function Parameters

| Parameter | Type | Description |
| - | - | - |
| `workspace` | `Workspace & { joined: boolean; tier: WorkspaceProductTier \| null }` | Full workspace object, including `joined` status and the resolved product `tier` (`null` when the workspace has no active tier) |
| `wsId` | `string` | Validated UUID from `workspace.id` |
| `isPersonal` | `boolean` | Whether the workspace is a personal workspace |
| `isRoot` | `boolean` | Whether the workspace is the root/internal workspace |
| `...additionalParams` | `TParams extends BaseParams` | Any additional route parameters beyond `wsId` (e.g., `datasetId`, `taskId`) |

**Note**: Additional parameters are automatically passed through from the route params object.

## Migration Guide

### Before (Manual Resolution)

```tsx theme={null}
export default async function MyPage({
  params
}: {
  params: Promise<{ wsId: string }>;
}) {
  const { wsId: id } = await params;

const workspace = await getWorkspace(id);
  if (!workspace) notFound();

const wsId = workspace.id; // Manual extraction

return <MyComponent workspace={workspace} wsId={wsId} />;
}
```

### After (With WorkspaceWrapper)

## Real-World Example

Here's how the dashboard page uses the WorkspaceWrapper:

```tsx theme={null}
// Example 1: Basic Dashboard Page
// File: apps/web/src/app/[locale]/(dashboard)/[wsId]/dashboard/page.tsx
// URL: /personal/dashboard, /550e8400-e29b-41d4-a716-446655440000/dashboard
export default async function DashboardPage({
  params
}: {
  params: Promise<{ wsId: string }>
}) {
  return (
    <WorkspaceWrapper params={params}>
      {({ workspace, wsId, isPersonal, isRoot }) => (
        <div className="p-6">
          <h1 className="text-2xl font-bold mb-4">
            {workspace.name || 'Unnamed Workspace'}
          </h1>
          <div className="grid gap-4">
            <div className="p-4 bg-gray-100 rounded">
              <h2 className="font-semibold">Workspace Details</h2>
              <p>ID: {wsId}</p>
              <p>Type: {isPersonal ? 'Personal' : 'Team'}</p>
              <p>Role: {workspace.role}</p>
              <p>Joined: {workspace.joined ? 'Yes' : 'No'}</p>
              <p>Root: {isRoot ? 'Yes' : 'No'}</p>
            </div>
          </div>
        </div>
      )}
    </WorkspaceWrapper>
  );
}
```

```tsx theme={null}
// Example 2: Settings Page with Loading State
// File: apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/settings/page.tsx
// URL: /personal/settings, /550e8400-e29b-41d4-a716-446655440000/settings
export default async function SettingsPage({
  params
}: {
  params: Promise<{ wsId: string }>
}) {
  return (
    <WorkspaceWrapper
      params={params}
      fallback={<div className="p-6">Loading workspace settings...</div>}
    >
      {async ({ workspace, wsId }) => {
        const currentUser = await getCurrentUser();
        const { withoutPermission } = await getPermissions({ wsId });

return (
          <div className="p-6">
            <h1 className="text-2xl font-bold mb-4">Workspace Settings</h1>

{withoutPermission('manage_workspace') ? (
              <div className="text-red-600">
                You don't have permission to manage this workspace.
              </div>
            ) : (
              <div className="space-y-4">
                <div>
                  <label className="block text-sm font-medium mb-2">
                    Workspace Name
                  </label>
                  <input
                    type="text"
                    defaultValue={workspace.name || ''}
                    className="w-full p-2 border rounded"
                  />
                </div>

<div>
                  <label className="block text-sm font-medium mb-2">
                    Workspace ID (Read-only)
                  </label>
                  <input
                    type="text"
                    value={wsId}
                    readOnly
                    className="w-full p-2 border rounded bg-gray-100"
                  />
                </div>
              </div>
            )}
          </div>
        );
      }}
    </WorkspaceWrapper>
  );
}
```

## Benefits

1. **Centralized Logic**: All workspace ID resolution logic is centralized
2. **Type Safety**: TypeScript ensures proper workspace object structure
3. **Error Handling**: Automatic `notFound()` when workspace doesn't exist
4. **Loading States**: Built-in Suspense support with custom fallbacks
5. **Cleaner Code**: Reduces boilerplate in page components
6. **Future-Proof**: Easy to modify workspace resolution logic in one place

## Error Handling

The `WorkspaceWrapper` automatically handles common error cases:

* Invalid workspace ID → `notFound()`
* User not authenticated → Redirects to login (via `getWorkspace`)
* Workspace not found → `notFound()`
* User not a member → `notFound()`

## Performance Considerations

* The wrapper uses React Suspense for loading states
* Workspace data is fetched once and passed down to children
* Consider using `fallback` prop for better UX during loading
* The component is optimized for server-side rendering

## Best Practices

1. **Always use the validated `wsId`** from the wrapper, not the original parameter
2. **Provide meaningful fallbacks** for better user experience
3. **Use the `withWorkspace` helper** for client components that need workspace context
4. **Keep workspace logic centralized** - don't duplicate workspace resolution elsewhere
5. **Handle loading states gracefully** with appropriate fallback components

## Troubleshooting

### Common Issues

**Issue**: `notFound()` is called unexpectedly
**Solution**: Ensure the user has access to the workspace and the workspace ID is valid

**Issue**: TypeScript errors with workspace object
**Solution**: Make sure you're using the workspace object provided by the wrapper, not importing it separately

**Issue**: Loading state never resolves
**Solution**: Check that the `getWorkspace` function is working correctly and not throwing errors

### Debug Tips

1. Check the browser's Network tab for failed workspace requests
2. Verify the workspace ID in the URL is correct
3. Ensure the user is authenticated and has workspace access
4. Check the console for any error messages from `getWorkspace`

# WorkspaceWrapper Quick Reference
Source: https://docs.tuturuuu.com/platform/components/workspace-wrapper-quick-reference

Quick reference guide for the WorkspaceWrapper component

## Quick Start

```tsx theme={null}
// Canonical shared-package import
import WorkspaceWrapper from '@tuturuuu/ui/custom/workspace-wrapper';
// (`@/components/workspace-wrapper` in apps/web is a thin re-export of the above)

// Basic usage - for pages like /personal/dashboard, /550e8400-e29b-41d4-a716-446655440000/tasks
<WorkspaceWrapper params={params}>
  {({ workspace, wsId, isPersonal, isRoot }) => (
    <div>{workspace.name} - {wsId}</div>
  )}
</WorkspaceWrapper>

// With loading fallback
<WorkspaceWrapper
  params={params}
  fallback={<LoadingSpinner />}
>
  {({ workspace, wsId, isPersonal, isRoot }) => <MyComponent />}
</WorkspaceWrapper>

// With additional params - for pages like /personal/datasets/123
<WorkspaceWrapper params={params}>
  {({ workspace, wsId, isPersonal, isRoot, datasetId }) => (
    <div>{workspace.name} - Dataset {datasetId}</div>
  )}
</WorkspaceWrapper>
```

## withWorkspace Helper

```tsx theme={null}
import { withWorkspace } from '@tuturuuu/ui/custom/workspace-wrapper';

// For client components
return withWorkspace(
  (await params).wsId,
  MyClientComponent,
  { prop1: 'value' },
  <LoadingSpinner />
);
```

## Props Reference

| Prop | Type | Description |
| - | - | - |
| `params` | `Promise<{ wsId: string }>` | Route params containing `wsId` |
| `children` | `Function` | Receives `{ workspace, wsId, isPersonal, isRoot }` |
| `fallback` | `ReactNode` | Loading fallback component |

## Children Function

```tsx theme={null}
{({ workspace, wsId, isPersonal, isRoot }) => {
  // workspace: Workspace & { joined: boolean; tier: WorkspaceProductTier | null }
  // wsId: string (validated UUID)
  // isPersonal: boolean
  // isRoot: boolean
}}
```

## Common Patterns

### Dashboard Page

```tsx theme={null}
// File: apps/web/src/app/[locale]/(dashboard)/[wsId]/dashboard/page.tsx
// URL: /personal/dashboard, /550e8400-e29b-41d4-a716-446655440000/dashboard
export default async function Dashboard({ params }) {
  return (
    <WorkspaceWrapper params={params}>
      {({ workspace, wsId, isPersonal, isRoot }) => (
        <DashboardContent workspace={workspace} wsId={wsId} />
      )}
    </WorkspaceWrapper>
  );
}
```

### Settings Page

```tsx theme={null}
// File: apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/settings/page.tsx
// URL: /personal/settings, /550e8400-e29b-41d4-a716-446655440000/settings
export default async function Settings({ params }) {
  return (
    <WorkspaceWrapper params={params}>
      {({ workspace, wsId, isPersonal, isRoot }) => (
        <SettingsForm
          workspace={workspace}
          wsId={wsId}
          onSave={handleSave}
        />
      )}
    </WorkspaceWrapper>
  );
}
```

### Dataset Page (with additional params)

```tsx theme={null}
// File: apps/web/src/app/[locale]/(dashboard)/[wsId]/[datasetId]/page.tsx
// URL: /personal/datasets/123, /550e8400-e29b-41d4-a716-446655440000/datasets/456
export default async function DatasetPage({ params }) {
  return (
    <WorkspaceWrapper params={params}>
      {({ workspace, wsId, isPersonal, isRoot, datasetId }) => (
        <DatasetView
          workspace={workspace}
          wsId={wsId}
          datasetId={datasetId}
        />
      )}
    </WorkspaceWrapper>
  );
}
```

### Client Component Integration

```tsx theme={null}
// Server component - apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/settings/page.tsx
export default async function Page({ params }) {
  return withWorkspace(
    (await params).wsId,
    WorkspaceSettings,
    { theme: 'dark' },
    <div>Loading...</div>
  );
}

// Client component
'use client';
export function WorkspaceSettings({
  workspace,
  wsId,
  isPersonal,
  isRoot,
  theme
}: {
  workspace: Workspace & { joined: boolean; tier: WorkspaceProductTier | null };
  wsId: string;
  isPersonal: boolean;
  isRoot: boolean;
  theme: string;
}) {
  return <div>{workspace.name}</div>;
}
```

## Error Handling

The wrapper automatically handles:

* Invalid workspace ID → `notFound()`
* User not authenticated → Redirects to login
* Workspace not found → `notFound()`
* User not a member → `notFound()`

## Migration Checklist

* [ ] Replace manual `getWorkspace()` calls
* [ ] Pass the route `params` Promise (not `searchParams`) into `WorkspaceWrapper`
* [ ] Use validated `wsId` from wrapper
* [ ] Add appropriate loading fallbacks
* [ ] Update TypeScript types
* [ ] Test error scenarios

## Troubleshooting

# Account benefits
Source: https://docs.tuturuuu.com/platform/features/account-benefits

Central audited grants for features, early access and bonus AI credits.

Infrastructure owns the Account benefits dashboard. Operators require root
workspace membership plus both `manage_workspace_roles` and
`manage_workspace_secrets`. Grants record their issuer, target account, reason,
time and stable request UUID. A retry with the same UUID and payload returns the
same grant; changed payloads conflict.

Feature keys use `feature.*`; early access uses `early_access.*`. Both are
boolean flags with optional expiration and explicit revocation. Services consume
specific keys on the server. Creating an arbitrary key does not enable unrelated
product features. `feature.learn.playgrounds` is the first hosted-programming
consumer.

`ai_credits` allocates a one-time bonus to the account's personal-workspace credit
balance and records a credit transaction in the same database transaction. Credit
grants have no feature expiry and cannot be revoked as an access flag after
delivery. Repeated grant requests never allocate twice. Existing credit accounting
and billing-period rules continue to govern the resulting balance.

The default is no benefits. Normal playground access also accepts a paid personal
subscription. Meet's verified internal-admin room exception is evaluated in that
room and never added to this ledger. Team-workspace benefits, global staff roles
and permanent workspace access are outside this grant model.

Test active, expired and revoked flags, duplicate grant IDs, changed replay
payloads, failed credit transactions and unauthorized operators before changing
benefit consumers. Never use profile metadata or client-provided email domains
as entitlement evidence.

# Assistant Live
Source: https://docs.tuturuuu.com/platform/features/assistant-live

Gemini voice, screen context, workspace tools, and session recovery in the dashboard assistant.

The dashboard assistant's Live mode connects directly to Gemini using the Google
Gen AI SDK. The server supplies a single-use, constrained ephemeral token;
`GOOGLE_GENERATIVE_AI_API_KEY` must remain server-side. The model is selected by
`/api/v1/live/token` and passed to the client. Google documents the protocol in the
[Live API guide](https://ai.google.dev/gemini-api/docs/live-api).

## Native local text models

See [Assistant local models](/platform/features/assistant-local-models) for mobile
installation, compatibility, preparation recovery, and the separate inference gate.

## Experience

On mobile, Live keeps mic, camera, keyboard and exit in four fixed slots in the shell's floating navbar.
Chat and Live retain its bounds, material and navigation action. Idle mic starts; setup and reconnect keep visible media controls with truthful disabled states and Cancel.
Active capture remains stoppable. Each start gets one microphone attempt; late permission, token or connection results cannot unmute or replace a newer attempt.
Camera needs a connection. Keyboard returns to Chat and disconnects by default, with opt-in browsing retention; Exit cancels startup, hangs up or returns to Chat after ending.

One scrollable blob, status and transcript stage stays mounted through reconnect and ending. Speaking uses admitted assistant audio and spectrum; reduced motion keeps it static.
Recovery detail and retry remain inline. `assistant_live_dock_lifecycle_test.dart`, `assistant_live_state_presentation_test.dart` and `assistant_live_microphone_restart_test.dart` cover these rules.

![Mira Live in the shared shell navbar](https://mintcdn.com/tuturuuu/yQH4sTI32XMawFda/images/mira-live-shell-light-390x844.png?fit=max\&auto=format\&n=yQH4sTI32XMawFda\&q=85\&s=fa810cd513e9c4a22d7dd4393e045384)

Text chat grows to at most five lines in the dock, then scrolls inside the input.
The Assistant has no fullscreen/expand draft action. Its single 52dp side action
remains Send, recording control, or navigation as appropriate. Attachment previews,
text selection, multiline input and keyboard/dock clearance remain inline.
`assistant_composer_draft_test.dart`, `assistant_composer_multiline_test.dart` and `assistant_composer_geometry_test.dart` cover these mobile rules.

Empty and single-line drafts share field, icon slots and side-action bounds.
Typing hides the microphone but reserves its space, removing its interaction and accessibility target.
The placeholder stays on one visual line at enlarged text sizes; accessibility retains the full prompt.
Attachment and side-action controls stay bottom-aligned as the draft grows. Matching keyboard/safe-area
geometry preserves empty/typed bounds. `assistant_composer_stability_test.dart` covers narrow phones,
enlarged text, keyboard insets, multiline growth and retained dock material.

![Stable mobile Assistant composer while typing in light mode](https://mintcdn.com/tuturuuu/8YlgQWXU4S8dSHyq/images/assistant-composer-light-typed.png?fit=max\&auto=format\&n=8YlgQWXU4S8dSHyq\&q=85\&s=a04a28d692e636d4f0b136b3008bba83)

Compare empty drafts in [light](/images/assistant-composer-light-empty.png) and [dark](/images/assistant-composer-dark-empty.png) mode,
and multiline drafts in [light](/images/assistant-composer-light-multiline.png) and [dark](/images/assistant-composer-dark-multiline.png) mode.

Live capture requests PCM16 mono, gain control, echo cancellation and noise suppression.
Android uses the communication source/mode and speaker route; the pinned iOS recorder enables native voice processing, and playback preserves its category/options.
Disconnect stops owned capture and releases playback without immediately initializing it again; this does not claim global iOS audio-session deactivation.
Permission-only cancellation avoids native capture queries serialized behind an unanswered OS dialog. Generation fences discard late grants and obsolete setup/frame work.
A pending native capture start still retains cleanup ownership. Old results cannot connect or clear a replacement attempt; microphone restart remains explicit.
Device verification still covers speaker, headset and Bluetooth routes and echo reduction.
Regression coverage includes `assistant_live_dock_lifecycle_test.dart`, `assistant_live_calling_view_test.dart`, `assistant_live_recorder_test.dart`,
`assistant_live_recorder_lifecycle_test.dart`, `assistant_live_disconnect_audio_test.dart` and `assistant_live_microphone_restart_test.dart`.

Mobile chat uses the shell's existing dock for its composer and primary action.
An empty draft keeps the navigation menu; a nonempty draft or attachment changes
that action to Send. During inline recording it becomes Pause, then Send while
paused. Cancel discards only the recording and returns to the retained text draft.
An untouched actor/workspace scope with no envelope, legacy selection/context,
creation marker or in-process hold receives one serialized, acknowledged fresh
envelope. Its first Send creates the chat without a reset dialog and retains the
draft until the user-message acknowledgement. Missing envelopes with legacy
state, a vanished inspected envelope, pending creation and held state still
require informed recovery. If a
text-only send has no selected conversation and local creation authority needs
recovery, Send opens the existing informed New Chat confirmation. Cancel
retains the draft without creating or sending anything. Confirmation resets the
held selection, retains the unchanged draft, and sends it once; only a persisted
user-message acknowledgement clears it. Unknown writes still require informed
recovery and are never silently replayed. Remote-model preference hydration does
not show a temporary local-model status in the navbar; a resolved local choice or
preparation failure still shows its status. These mobile-only rules are covered
by `assistant_send_recovery_test.dart` and `assistant_fresh_scope_test.dart`.

![Mobile Assistant creation recovery with a retained draft](https://mintcdn.com/tuturuuu/vNzQ3z9L2i4-AR7D/images/assistant-send-recovery.png?fit=max\&auto=format\&n=vNzQ3z9L2i4-AR7D\&q=85\&s=2313783a7a4451a4f202ba9c34e358a6)

The input row has no second Send button. Each assistant turn has one initially
collapsed transparent thinking accordion, showing the latest heading from reasoning
text already supplied by the API. Expanding it reveals those existing sections in
source order. Only the current streaming turn animates its thinking icon; stopped,
completed, and failed turns use a static icon. Consecutive tool calls share one
collapsed transparent accordion displaying the latest tool name, while response
text and generated images keep their relative positions. No additional hidden
reasoning is requested or inferred. These rules apply to mobile Mira's timeline;
other clients retain their own presentation. Accordion regressions are in
`assistant_activity_accordion_test.dart`. The transcript's scroll-to-bottom
action clears the dock using the shell viewport's inherited clearance; the outer
shell consumes the keyboard inset once. Regressions cover controller and capture
transitions, retained dock identity, transparent tool inspection, and actual shell
geometry in `apps/mobile/test/features/assistant/widgets/`.

### Mobile message actions and appearance

Long-press a message for Copy. Saved messages in native Assistant conversations
also offer Reply and reactions. The reply preview stays inside the existing
floating composer and can be cancelled before sending. Native replies retain the
original target through retries; reactions reuse `private.chat_message_reactions`
and the authenticated Chat API, so native web Chat and mobile see the same data.
The server derives the actor from authentication and validates conversation access;
one actor can remove only their own reaction. Optimistic rows, Live drafts and
local-only model messages cannot receive persisted reactions or reply references.
Legacy `ai-chat-*` and `legacy-ai-*` conversations keep Copy, but cannot use private
Chat message IDs. Legacy dashboard Mira reaction/reply parity requires its own
adapter work; IDs must never be stripped or guessed to enable it.

Retained Live text cannot carry replies. A selected reply blocks sending and keeps its draft and
target; end the call or cancel the reply first. The reply reference is never silently discarded.

Changing or cancelling a reply during timezone resolution keeps the unsent draft and current target available for review, with a notice in the same composer scope.
An admitted native turn consumes its acknowledgement even if a later draft selects another reply.

![Reply change keeps the unsent draft in light mode](https://mintcdn.com/tuturuuu/w0Wr_Xglf5ytijJn/images/assistant-reply-feedback-light.png?fit=max\&auto=format\&n=w0Wr_Xglf5ytijJn\&q=85\&s=6c083a7b599af7a1bb9b538383bf9616)

Live completion clears unchanged submitted text regardless of cursor or IME ranges, and removes only matching attachments. New replies and later text edits remain. Local socket admission proves neither provider acknowledgement nor durable saving.
Aborted typed preparation disconnects only its owned request; newer preparation remains active. Current-chat connection loss reports refusal, and same-chat reselection after possible dispatch reports uncertainty while retaining the draft.
Refused or uncertain delivery is not automatically replayed. Mobile reply-guard and Live dispatch tests cover setup retirement, recovery, scoped notices and snapshot cleanup.

Reactions follow the native idempotent contract below. **Refresh reactions** reconciles an unknown
intent before updating its exact message. Reply previews jump to loaded originals without resuming
bottom-following; acknowledgement ID relocation preserves expanded message state.

Choose **Chat appearance** in Assistant More. Classic is the default; light/dark-aware presets offer
solid, gradient and ombre backgrounds. Advanced starts collapsed and separates message palette,
text accent, background palette/style and intensity. Preferences are device-local and actor-scoped
across Assistant conversations and workspaces, for both remote and on-device conversations.
They do not change the shell, web UI or another actor's preferences, or synchronize across devices.
Preview updates immediately; storage debounces and slider release flushes the latest change.
Closing flushes the last authorized edit; logout or session replacement retires delayed edits.
Contrast, round trips, actor/session fences and collapsed-editor tests: `apps/mobile/test/features/assistant/theme/`.

### Native mobile reaction operations

Mobile persists reactions only for acknowledged messages in native Assistant
conversations. It uses the actor-scoped private Chat model and **PUT** on the
conversation reactions endpoint with a stable `opId`, `emoji` and desired
`present` value. The reaction and operation receipt commit atomically; repeating
an operation acknowledges it without applying it again, including after a newer
operation. Existing web Chat **POST** callers retain toggle behavior. Old servers
without PUT reject the new request before any reaction write; mobile never falls
back to a toggle. Apply the operation migration before enabling this client.

Before dispatch, an independent Hive journal must acknowledge and flush the
intent. Failed storage adds no uncertainty. Scope retirement before dispatch
removes the matching unsent marker. A valid terminal receipt cleans its exact
operation even after navigation or a client timeout; it cannot erase a successor.
Unknown outcomes retain the original operation. **Refresh reactions** retries
that same idempotent intent and reads the exact message, so older messages do not
depend on the latest history page. Reads alone never prove a mutation terminal.

Sign-out retires dispatch admission synchronously, including auth-event logout,
and removes actor/message/workspace/emoji journal metadata. Only hashed actor
keys and unresolved operation IDs remain as a minimal retirement fence. Before
that actor can submit another reaction, bounded authenticated retirement batches
mark those IDs terminal on the server; delayed original requests cannot restore
an old reaction after a later choice. Failed retirement retains the fence for an
explicit retry. No reaction operation enters the offline queue.

Coverage: `chat-reaction-operations.sql`, the reactions/retire route tests,
`assistant_reaction_lifecycle_review_test.dart`,
`api_client_operation_review_test.dart`, and the journal/flush regression suites.

Age-based cleanup is disabled. The [retention proposal](/platform/features/assistant-reaction-retention)
requires server-enforced expiry before bounded Cloudflare cleanup can remove operation or retirement records.

### Web dashboard Live

On the web dashboard, start or stop Live with the waveform icon in the chat
composer. Live keeps the
same message timeline visible, with a compact gradient visualization and media
controls above it. Spoken turns, typed prompts, tool calls, and search sources
appear in that timeline and share the workspace artifacts. Close Live or press
Escape to stop media capture and continue typing.

Finalized Live turns are saved to the same chat through the owner-checked
`/api/ai/chat/live-messages` endpoint. Stable message IDs make retries idempotent;
ordered parts keep text and tools interleaved after refresh. Complete transcript
text lives in canonical parts metadata; the separate search/fallback content field
is capped at 10,000 Unicode characters to satisfy its database limits of
10,000 characters and 40,000 bytes. Pending saves finish
before a subsequent typed request. Failed saves show a retry action; keep the page
open until they succeed. In-progress speech remains provisional until the turn
finishes or the session closes. Audio and video are not stored as chat attachments.
Live starts with up to 64,000 characters of conversation context: bounded earlier
excerpts preserve original roles alongside recent turns and compact tool results.
This is deterministic compaction, not a generated summary. This bound does not remove older saved messages. Temporary session notes
remain separate from workspace documents.

Chat and Live share a persistent composer panel in the page layout. Switching
modes swaps the toolset and preserves the text draft. Chat shows its model and
credit controls without a redundant mode label. Screen/camera sharing uses a
compact thumbnail that expands on demand; the composer does not cover messages.
Transitions respect reduced-motion preferences.

The assistant opens tasks, calendar, finance, and meetings next to the conversation
through tool calls. The chat toolbar has no product, sidebar, or layout controls. One artifact splits the available space in half; multiple
artifacts automatically use a four-cell grid with chat in one cell. Side-by-side,
stacked, and grid controls override the arrangement. Narrow containers stack
panels so sidebar width is included in the responsive decision. Up to three
artifacts remain open; opening a fourth replaces the oldest. Artifacts are scoped
to the workspace selected when opened and can be refreshed or closed individually.
Task previews use the Tasks app’s personal feed, showing 12 rows at a time with
Show more. Calendar previews cover the next seven days, and wallet balances retain
their own currencies. APIs remain the
permission boundary and panels expose loading, empty, and retry states.

The assistant can call `show_workspace_artifact`, `set_sidebar` (expanded,
collapsed, hover, hidden), and `set_theme` (light, dark, system) in chat and Live.
Chat applies UI commands when the streamed tool output arrives, independently of
whether the result card is visible. Restoring history does not replay old UI
commands. Sidebar changes use the existing preference provider and respect its
local/account synchronization settings. Ask the assistant to restore navigation
when it is hidden.

Meeting panels provide a creation form to eligible `@tuturuuu.com` accounts using
`createWorkspaceMeeting`. The existing meeting API authenticates the account,
checks workspace membership, and enforces the domain policy. Opening the panel is
not meeting creation; success is shown only after the creation request succeeds.
No meeting API or database policy changes are part of this interface update.

Live mode displays both speakers' streamed transcripts, task visualizations,
Google Search sources, tool activity, and temporary session notes. Typed prompts
and voice share one session. Camera and screen sharing require an explicit media
control action; a preview indicates what is shared. Microphone mute sends
`audioStreamEnd`, and interruption stops queued assistant playback.

Workspace artifacts remain beside the shared conversation. Tool results and Google
Search sources stay in the message timeline. Temporary notes are not workspace
documents. The existing five-minute credit authorization limit remains in force;
expiration ends media capture and keeps the saved conversation available.

## Mobile audio capture

On mobile, Chat and Live use the same top header mode switch and page background.
Live keeps the floating bottom navigation visible. Its idle start action is the
icon-only **Call Mira** button beside that navigation; the top header opens Live
settings in a sheet with the Keep Live while browsing switch. The idle screen
does not show an availability badge or a second start button. During a session,
connected call controls replace navigation inside the same dock and provide
camera, microphone, typing, and end actions. A connecting call retains navigation
and offers cancel. Connection problems show retry without changing the page
background.

Starting mobile Live with the microphone enabled requests permission and captures
speech while the connection initializes. A memory-only FIFO holds at most 30
seconds of 16 kHz mono PCM. Once ready, chunks drain in order; cancelling capture
or leaving the session discards unsent audio. Connection errors do not persist
this buffer to disk.

The normal mobile chat microphone replaces the text field with a real microphone
waveform inside the same persistent floating dock. It opens no recording sheet.
Pause reveals restart, attach, send, and resume; the two-minute limit pauses
capture rather than discarding it. Restart erases only the current unsent local
recording. Attach keeps the text draft and uploads through the existing attachment
flow; send explicitly attaches and submits it. Backgrounding pauses capture.
Leaving the Assistant, switching actors or workspaces, and disposal cancel the
unsent recording. Async completion cannot attach or send into a different scope.

Mobile assistant Markdown renders directly against the app background. Text,
reasoning, and separate tool activity follow canonical persisted part order after
history restoration. User messages keep their own bubble. Chat and Live both
expose the shared quick-settings action. Regression coverage lives in the voice
capture, composer dock, and transcript bubble tests under
`apps/mobile/test/features/assistant/`.

## Flash and Pro

Flash uses `gemini-3.8-live`; Pro uses `gemini-3.8-live-extended-thinking`
with high background reasoning. The chat response labels are now Flash/Pro;
existing saved Fast/Thinking preferences remain compatible. Live starts with that
preference and offers its own Flash/Pro control. Switching restarts authorization
and media capture, preserves the shared conversation, and uses a separate
resumption scope for each model.

Both models declare tools as `NON_BLOCKING`. Each incoming tool batch runs up to
four calls concurrently, so pending approval does not hold up independent reads.
Speech interruptions stop audio without falsely cancelling background tools;
provider cancellation IDs or disconnects end those calls. Flash omits `thinkingConfig`;
Pro never uses `MINIMAL` or function-response scheduling. Pro's `turnComplete`
ends an utterance, while `interactionStatus: IDLE` finalizes the interaction.
The UI shows background work until that signal, allowing further speech and tools.
Both modes compress context at 100,000 tokens toward a 64,000-token window,
using more of the new models’ 131,072-token input capacity.
Proactive audio stays enabled by the provider. Camera and screen frames remain
opt-in, and mutation approval/cancellation checks still apply.

Before deploying this upgrade, apply
`20260916100000_mira_live_38_models.sql` through the database release process.
It registers model pricing and extends existing Live model allowlists. Without
these rows new sessions fail closed; they do not silently bill another model.
Production migration application is user-operated. Existing sessions keep their
original pricing snapshot. The installed `@google/genai` 2.22 SDK already supports
interaction status and asynchronous tool declarations.

Google's [migration guide](https://ai.google.dev/gemini-api/docs/models/gemini-3.8-live)
and [Thinking guide](https://ai.google.dev/gemini-api/docs/live-api/thinking)
define the session contract. Rates come from the
[pricing table](https://ai.google.dev/gemini-api/docs/pricing).

## First-party tools

Calendar reads require an explicit ISO date range of at most 31 days and return
at most 50 events to Gemini. Event creation validates timestamps and text lengths.
Model arguments cannot select a different workspace or calendar provider. Existing
calendar APIs enforce authentication and workspace permissions. Calendar tools
themselves require no additional schema changes.

The dashboard token has its own expanded tool declarations and instructions.
Legacy assistant voice clients retain their original tool catalog.

Task mutations and calendar creation wait for approval of an on-screen argument
preview. This is a user-interaction gate; server-side authorization remains the
security boundary. Calls are deduplicated by provider ID, cancellation includes
queued calls, and late cancelled results are not sent back or displayed. Stopping
a request cannot roll back a mutation already accepted by the server. Failed
mutations are not retried automatically; verify their result before retrying.

## Recovery and billing

The client forwards `sessionResumption.handle` even with ephemeral authorization,
without supplying replacements for server-constrained tools or instructions.
`GoAway` schedules reconnection, and unexpected closure attempts recovery at most
three times. Explicit disconnect and unmount invalidate pending connections and
retries. Manual restart obtains fresh authorization. Paid dashboard sessions retain recovery handles in memory for the current billing
reservation only, so a fresh authorization cannot replay cumulative usage from a
previous reservation. Legacy unmetered consumers retain workspace/conversation
scoping through the existing session API.

Credit reservation and cumulative usage settlement remain on the live Next.js
backend. Rust is a future migration target, not the deployed API. The token route
is tracked in `apps/tanstack-web/migration/route-overrides.json`.

## Verification

From `apps/web`, run focused Vitest tests under the dashboard `assistant` directory,
`src/__tests__/assistant-live-token-routes.test.ts`, and
`src/__tests__/live/token-builder.test.ts`. Run internal API live-tool tests from
`packages/internal-api`, followed by `bun validate` at the root and `bun run build`
in `apps/web`.

Authenticated runtime acceptance requires a configured Gemini key, available AI
credits, and microphone permissions. Verify spoken input/output, interruption,
mute, camera/screen stop, task and calendar permission failures, approval/decline,
provider cancellation, reconnect, expiration, Flash/Pro switching, Pro background
status after an utterance, and export at desktop and mobile
sizes. Component or mocked protocol checks do not prove provider audio quality,
credit settlement, or authenticated production delivery.

Artifact panels replace the dashboard’s former server-loaded task and calendar insight slots. Full-view links preserve the active language; meeting links open the Meet app. Meeting creation checks the authenticated account’s verified email and provides a retry if account lookup fails. The live panel follows measured header and composer sizes as attachments, text, and narrow layouts change.

Platform forwards `/api/v1/workspaces/:wsId/calendar/events` and its event-detail path to the Calendar app. Calendar remains responsible for membership, `manage_calendar`, and event encryption. Keep these forwarding rules when changing dashboard artifacts or Live calendar tools; a missing rule returns a Platform HTML 404 before Calendar authorization runs. The empty chat reserves space for the composer, allowing welcome actions to scroll independently in compact panels.

### Compact product panels

The Tasks artifact uses the same personal task feed as the Tasks app. A Personal context includes tasks across workspaces and applies personal overrides; a team context stays scoped to that workspace. Compact cards reuse Tasks label colors, priority icons, estimation mappings, and assignee avatars. Due-date filters and board links keep the task feed actionable. Search filters the loaded panel, and Show more reveals additional tasks without discarding the rest of the feed.

Calendar shows a seven-day strip and an agenda, including events spanning multiple days. Finance keeps currencies separate and compares absolute wallet balances, marking negative values; totals reflect the displayed wallets. Meetings separates upcoming and past entries from the latest 30 records and keeps creation in an expandable form for eligible accounts. Each panel retains refresh, error recovery, and full-app navigation.

### Assistant-managed workspace

Use `show_workspace_artifact` to open or update a panel. Its optional `presentation` carries a concise title plus search, taskStatus, currency, date, or itemIds filters. Scope captions and assistant explanation blocks are omitted so product cards have the space. Legacy descriptions and highlights remain accepted for compatibility but are not rendered. Calendar dates start a seven-day local range. Keep explanations in chat, grounded in tool data, and only use IDs already returned by data tools. Artifacts fetch their own authorized data; presentation text never grants access or changes source records.

Use `manage_workspace` with `close_artifact`, `focus_artifact`, `close_all`, or `set_layout` to manage screen space as the task changes. Opening a new panel automatically collapses expanded navigation; collapsed, hover, and hidden modes are preserved. Updating an existing panel leaves navigation alone. Opening or updating a panel without a layout preserves the current arrangement. Focusing retains that panel's presentation and closes the others; closing all restores full-width chat. The user can still search, filter, refresh, open the full product, and close each artifact directly. Distinct theme-aware product accents distinguish task urgency, calendar days, wallet balances, and meetings.

For artifact orchestration, a successful UI command is complete: issue only the remaining requested actions and then answer. Replacing one panel uses `close_artifact` and `show_workspace_artifact`; `focus_artifact` deliberately closes the others. Opening a panel does not return its data to the model. Use a title-only presentation until a relevant data-read tool supplies facts; the panel itself displays authoritative counts and balances.

### Chat capability discovery and reliable actions

Chat starts with a small discovery set. `search_tools` returns at most eight authorized matches plus focused domain guidance and activates them for the next step. `select_tools` supports a working set of at most twelve known operations. Add tool definitions, directory metadata, permission mapping, and an executor together; discovery indexes the directory automatically. This is progressive tool loading, not arbitrary code execution or automatic access to external MCP servers.

Workspace verification fails closed before context reads. Mutation permissions are resolved for the selected workspace, and operations retain that authorized workspace if another concurrent call changes context. The per-turn runtime ends repeated identical read/discovery/UI cycles and repeated failures. Gemini native search reports `server:GOOGLE_SEARCH_WEB`; recognize it alongside `google_search` before forcing another search, and do not retry a wrapper that already returned grounded sources. Identical task creations share their first result within a turn, including concurrent calls. This is not cross-request idempotency. Task creation saves creator, start/due dates, and estimates, then reads the saved task location. Assignment or readback failures return an incomplete result with the created ID; recover that task rather than inserting another. `get_task` and paginated `search_tasks` locate saved tasks in the current workspace. Existing label, project, assignee, and task mutation tools remain available.

Chat Calendar automation and event writes forward the authenticated request through the existing Calendar API, including selected Google/Microsoft destinations. It can inspect connection health, provide Google OAuth authorization, sync connected calendars, lock/unlock events, read schedulable tasks, and preview/apply scheduling. Apply requires a successful same-workspace/window preview in the current turn and uses safe apply; the Calendar service recomputes availability and rejects unresolved warnings. Provider authorization and locked commitments remain enforced by Calendar. These new automation tools are not exposed in legacy Live/Meet sessions without the corresponding authenticated execution path.

When debugging a reported false completion, inspect the stored tool result and returned task ID first, then read that ID in its recorded workspace. A chat confirmation or artifact opening alone is not evidence of a product write. Runtime verification of provider sync or scheduling requires an authorized test account; mocked tests only verify dispatch and failure handling.

### Native search completion

Mira keeps `google_search` as an executable function tool. Do not override it
with a provider-native tool in the main mixed tool set: Gemini maps required
tool choice to `ANY`, which can issue many server-side searches inside one
provider step without answering. The outer step guard cannot interrupt that
provider-step loop.

Explicit search requests require the search executor before proceeding. The
executor uses native Google search through the direct Google provider used by chat, with
automatic tool choice, a 30-second deadline, one provider step, and at most one
grounding retry. It requires grounding evidence and a nonempty final answer.
Other required workspace and task tools keep their required-tool policy.
Verify a real grounded answer and visible sources after orchestration changes;
mocked tool events alone are insufficient.

The search executor must use the configured direct Google connection, like the
chat route. Routing only search through AI Gateway adds a separate credit and
authentication dependency; a gateway 403 does not mean Google search is down.

### Conversation chronology and native presentation

On mobile, Assistant chat inherits the shell background, branded top title and
single floating navigation dock. Back stays in that dock. The prompt retains its
height on focus, grows with its content up to five lines, and Enter inserts a
newline; the side primary action sends. The transcript jump action uses measured
composer height and shell dock/safe-area clearance, including the resized keyboard
viewport. Streaming output follows only while the reader is near the bottom;
reading earlier messages preserves the scroll position.

User receipts show semibold **Delivered** only after the existing saved-user
acknowledgement replaces an optimistic request ID. **Read** means a subsequent
Assistant response has begun processing that turn, not that a person read it.
A newly observed Read transition holds Delivered for 700 milliseconds before
showing Read. Timestamps use light `HH:mm`; assistant replies and live drafts have
no delivery timestamp. History without acknowledgement provenance and optimistic
or failed sends remain timestamp-only. These presentation rules do not establish
backend persistence; messages whose saved and request IDs match also remain
unlabelled until explicit receipt state is available.

`assistant_composer_multiline_test.dart`, `assistant_composer_geometry_test.dart`,
`assistant_scroll_overlay_test.dart`, and `assistant_message_receipt_test.dart`
cover editing, dock/keyboard clearance and receipt states. Settings retain the
single branded header labelled Assistant Settings, compact content spacing and a
bottom Back control; `assistant_settings_layout_test.dart` covers safe areas and
enlarged text. Widget rasters do not replace installed-device acceptance.

Assistant history stores the ordered provider content for every generation step in
`metadata.ai.parts`. Tool results update their original call slot, including failed
and unfinished calls; they do not move to completion order. The message content
column contains text segments in order, up to its database limit of 10,000 Unicode
characters and 40,000 bytes. Longer completed replies retain their full text in
`metadata.ai.parts`, with `metadata.ai.contentTruncated=true` marking the bounded
column as a preview. This applies to Web Mira and native mobile Assistant text
conversations. Native Chat copies retain the same full parts and preview marker.
History loading prefers canonical parts over legacy text/tool arrays, and only
adjacent tool activity is grouped. Follow-ups restore the full assistant text;
model preparation splits long assistant text into bounded parts without raising
the user prompt limit. User message content never comes from this preview marker.

When metadata must be compacted, text spans reference the content column only if
that column contains the complete reply. Overflow text stays inline. Tool payload
previews shrink while later timeline entries remain present; the fallback omits
the detailed context breakdown. The current schema allows 10 MiB of AI message
metadata. Persistence errors still fail the send; an emitted terminal event alone
is not evidence of a saved reply. Old records that already lost text or
interleaving cannot have their original content reconstructed.

Regression evidence: `stream-finish-reopen.test.ts` enforces the content limits;
`assistant-followup-context.test.ts` retains full generated context and rejects an
oversized user prompt. `native-ai-reopen.test.ts` exercises save, history GET,
follow-up, and history GET with the real finish saver and model preparation.
Mobile `assistant_history_ai_parts_test.dart` covers canonical parts and compact
offsets; `assistant_chat_persistence_contract_test.dart` covers creation, two sends,
fresh-repository reloads, saved replies, attachment ownership, and request identity.
Native Chat treats an upstream SSE error as inconclusive until the bounded
readback of that request's saved reply finishes. A saved reply is copied through
the actor/workspace-authorized idempotent batch; no receipt means the turn still
fails. Leaving the stream does not revoke an accepted save. Mobile reconciles all
rows of the terminal batch from canonical parts, including long split replies.
On entry, a cached Assistant snapshot renders immediately and authorized history
revalidation updates that same selection unless navigation, a settings change, or a new local turn
has superseded it. Live audio keeps its separate turn-save contract.

Regression coverage: `native-ai-stream-persistence.test.ts` covers upstream errors,
missing saves, disconnects and replay. `assistant_chat_saved_batch_test.dart` and
`assistant_chat_revalidation_test.dart` cover batch reconciliation and visible
cache refresh with navigation fences.

These use database/provider fixtures. Authenticated Web and installed Android/iOS
verification with real attachments and a provider remains a release check.

Explicit requests to show tasks, calendar, finance, or meetings activate the native
artifact opener directly. Follow-ups such as "show it in an artifact" use recent
conversation context. Product panels fetch their own data; a task-data read or
Markdown table must never be described as an opened artifact. Workspace resolution
still precedes presentation when a named workspace needs to be selected.

### Reading retried tool chains

The collapsed action summary counts unresolved failed attempts, rather than all
calls in a chain. A later successful call with the same tool name and normalized
input changes the summary to "Completed after retry". The original failed attempt
remains expandable, labeled as recovered. Different inputs and missing inputs do not establish recovery. A logical failure
output is not a successful retry; a later verified success can recover either
a transport error or a logical failure. This outcome is derived from
ordered message parts, so restoring a conversation produces the same summary;
assistant prose is never used as proof of success.

Presentation destinations such as "in the task panel" are not workspace names.
An explicitly requested artifact can still open after repeated discovery calls,
subject to the existing three-attempt artifact limit.

## Composer and session timeline

Mira keeps Live controls in the chat composer. Voice starts with text entry collapsed; opening text entry adds the prompt below the Live controls without hiding them. The shared conversation stays visible at every artifact layout size. Session start/end notices are canonical `data-live-session` parts and are restored alongside text and tool results. They describe session state, not a guarantee that an outstanding save has completed; save failures retain the existing retry notification.

Context bounds are described under [Experience](#experience); media verification remains covered under [Verification](#verification).

### Shared Chat and Live personalization

Chat and both Live token endpoints use `packages/ai/src/chat/mira-prompt.ts` for the same Mira identity, behavior, workspace context and scoped memory prompt. Live loads the authenticated user's saved name, personality, tone, boundaries and memories on session creation; saved language, accent and speaking-pace preferences are passed to the model as instructions. These are behavioral preferences, not a separate selectable provider voice ID.

`apps/web/src/lib/live/mira-prompt.ts` adds only spoken-delivery and actual Live tool constraints. Do not restore a static “You are Mira” prompt or duplicate the Chat context loader. Live's smaller tool catalog does not support Chat's memory/settings writes: it must not claim to persist changes using session notes. Dashboard personalization is resolved before reserving credits, and a prompt-loading failure prevents an unpersonalized token from being minted. End and restart Live after changing saved preferences; an ongoing connection retains its session instructions.

## Mira chat tool discovery

Mira chat uses AI SDK `toolSearch()` with deferred tool definitions (AI SDK
7.0.107 or later). The first step exposes only the selected control tools.
Search results make matching capabilities available on the next model step;
searching does not perform the operation or approve a mutation. Explicit tool
selection remains supported for clients that already know the tool names.

The per-generation discovery adapter rechecks workspace permissions before each
step, while the existing executors authorize writes independently. A workspace
change during permission resolution fails closed. Forced artifact/workspace
steps and terminal loop guards retain their restricted tool sets. Definitions
are never mutated in the shared registry. This change applies to streamed Mira
chat; live voice retains its separate tool protocol.

Run the SDK-backed tests in `packages/ai/src/tools/mira-sdk-tool-search.test.ts`
when changing discovery. They exercise real SDK model steps with a mock provider,
including deferred loading, denied permissions, workspace changes, explicit
selection, and approval-gated writes. These tests do not replace authenticated
provider or meeting-invitation round trips.

### Mobile text dock modes

Normal mobile Assistant text chat uses one floating bottom dock. Navigation mode
shows the existing section icons with a chat-bubble primary action. Composing
replaces that same slot with a single-row plus menu, prompt, microphone/send and
hamburger primary action. The hamburger returns to navigation; it does not place
navigation above the prompt. The draft and selection survive a toggle. Opening
chat focuses the prompt; returning to navigation, opening the menu or microphone,
leaving the page, and tapping outside release prompt focus and dismiss the IME.

Both modes use the same default 52 logical pixel rail, theme-derived glass and
outline; prompt height grows for accessible text. Reduced-motion settings remove
mode animation. The anchored plus popover uses one matching glass surface and
consistent icon/title rows for attachments, model, credit source
and closing the prompt; existing per-attachment previews/removal remain available.
Live mode keeps its explicit entry and transport behavior. This rule applies to
normal native mobile text chat, not web chat or Live stage controls. Regression
coverage is in `assistant_morphing_dock_test.dart` and
`assistant_composer_dock_test.dart`; installed-device appearance/keyboard checks
remain part of release verification.

Native mobile text sends and regeneration always use Thinking, including chats
restored from older Fast preferences and the legacy transport fallback. The mode
selector is intentionally absent; web and Live behavior are unchanged. Model
selection defaults to hiding locked or disabled models; users can reveal them
for inspection but cannot select them. Model and attachment sheets use the dock
glass material. Add attachments offers Files, Photos & Videos Library, and
Capture & Record. Camera photo/video capture appears on Android and iOS only;
recorded audio uses the existing microphone permission/recording flow. Cancelling
a system picker adds nothing. Regression coverage includes the native request
payload, stored preference migration, model default filter and source availability.

Root mobile destinations and Assistant share 12px horizontal insets, an 8px
bottom gap, and fixed 52px primary-action columns. A second column is reserved
on viewports at least 400px wide, regardless of whether an action is present.
Narrow phones keep secondary dock actions in the top navbar so five root
navigation targets retain at least 44px. Apps and Assistant use the same rail;
chat/navigation toggling changes content without moving the primary action.

The fixed empty action columns apply to the five root destinations (Home, Apps,
Assistant, Notifications, and Profile). Mini-app navigation intentionally keeps
its available width when it has no actions, including six-item docks on narrow
phones. Registered mini-app actions consume space only when present; secondary
actions remain reachable from the top navbar on narrow screens. The six-item
320px no-action regression checks that touch targets stay at least 44px; this
does not claim every possible mini-app/action combination has that width.

Native attachment requests retain the workspace version captured before opening
a picker or recording. They reject a workspace switch, including a switch back,
before decoding, adding a pending attachment, creating a chat, or starting an
upload. An upload already in flight retains its original workspace and does not
update a replacement composer. Voice send-now also checks the original scope.
Delayed file decoding and stale pre-timezone scope are covered by
`assistant_chat_restore_test.dart`.

### Mobile Live calling surface

Mira Live inherits the app background and follows the [shared calling behavior](#experience). It reflects connection and speaking state without a second control rail, provider-latency claims or on-device model execution.

Regression coverage: `assistant_live_mode_view_test.dart` and `assistant_live_call_controls_test.dart` cover narrow/landscape and enlarged-text layouts, real connection-state action availability, and the absence of a body-owned control rail. `shared_navbar_large_text_test.dart` exercises the actual shell at enlarged text size and verifies the same dock Material element survives Chat, Live, global-navigation and full-screen transitions.

#### Full-screen call

Starting a call (not unmuting) opens a full-screen call surface on the root navigator, above the app shell, as a system-like flow. It keeps the gradient and blob appearance backdrops, and it adds no navbar or second shell.

* **Identity and status.** The surface shows the assistant's voice-reactive orb, name and one status line: Connecting…, the elapsed time, Reconnecting…, "Call ended · mm:ss", or "Couldn't connect".
* **Elapsed time.** Shown as mm:ss, then h:mm:ss from one hour. Only the timer redraws each second, and screen readers get it as "Call duration". The call clock starts on the first connection, keeps running through reconnects and transient errors, records the duration on disconnect, and resets when a new call starts.
* **Controls.** 64 dp circular controls: Mute, Camera, Keyboard, Captions, a 72 dp red End, and Minimize. In-call controls stay in place, disabled, while connecting; End stays available and cancels a connecting call. Mute appears toggled only while connected.
* **Captions.** An optional drawer shows the latest turns and live drafts.
* **After a call.** Ended and failed calls offer Close plus Call again or Retry.
* **Minimizing.** Minimize or system Back keeps the call running and returns to the in-shell Live view, whose Return to call control reopens the surface. The dock call controls stay the in-shell control set.
* **Lifecycle.** The surface opens before its session starts and reads as Connecting… until then; if the start attempt settles without a session (for example, a refused microphone permission), the surface closes. After the session starts, any disconnect ends the call on the surface, including page-initiated disconnects without a final turn such as backgrounding the app: on return it shows "Call ended" with Call again and Close, never a stuck Connecting… with live controls. Nothing reconnects such a call automatically.
* **Teardown.** A workspace switch or a signed-in account change dismisses the surface, because its actions belong to the previous workspace. A start that is still waiting for its token checks the selected workspace directly, so a token answered during the switch never opens a call for the previous workspace. The provider handshake times out after 10 seconds, so a disconnect (and the next connect, which waits for that close) cannot hang on an unanswered socket. Disposing the page closes the session, which also dismisses the surface.
* **Speaker routing.** Live keeps its existing speaker and Bluetooth routing. A speaker/earpiece toggle, CallKit/ConnectionService, an Android microphone foreground service and proximity dimming are follow-ups that need native work and device verification.

Regression coverage: `live_call/assistant_live_call_model_test.dart` (duration format, call clock, phases, captions), `live_call/assistant_live_call_view_test.dart` (timer ticks without rebuilding peers, labels and tap targets, connecting/muted/ended states, and the 390×844 and 820×1180 light/dark/blob render matrix written to `MIRA_LIVE_CALL_RENDER_DIR`), `live_call/assistant_live_call_route_test.dart` (opens above the host, Minimize keeps the call, Return to call, dismissal on session close, a disconnect without a final turn shows the ended summary, and an unstarted start attempt closes the surface), and `assistant_live_keyboard_startup_test.dart` (backgrounding a presented call shows it ended on resume; a workspace switch dismisses it and leaves Live disconnected). The view test also checks that landscape and 2x text with captions open scroll without overflow.

### Mobile draft editing and previews

The mobile prompt grows inline through five lines and preserves text selection.
Enter inserts a newline; the side action sends through the guarded submission
path. Attachment previews sit above the prompt. Images and videos open
media previews; audio opens playback controls without automatic playback.
Uploading and failed attachments remain identified and removable. Previews are
bounded and scrollable on narrow screens and at enlarged text sizes.

Assistant settings and its field editors reuse the existing custom floating
navigation for Back. Other settings frames retain their current navigation.
Live-browsing, local-model and workspace-memory explanations open from labeled
information buttons. Hardware, upload/download progress, errors and recovery
controls remain visible; all original explanatory copy stays in the dialogs.
Personality values use two-line previews with the full value retained for
accessibility and field editing. The central Assistant tile waits for completed
authentication; this presentation does not grant new permissions.

Regression coverage: `assistant_composer_draft_test.dart` observes focused input
height, control order, draft/selection/focus return, preview state updates and
blocked submission. `assistant_settings_ux_test.dart` covers authentication
readiness; existing routed settings tests cover Back and safe-area clearance.
Widget evidence uses synthetic data and does not establish installed-device
performance, chat persistence, or provider operation.

### Central mobile Mira settings

On mobile, Settings → Apps → Assistant opens the same live-browsing preference used by Mira quick settings. The shared shell supplies the title and back dock; the editor adds no second navbar. The preference defaults to off and remains scoped to the signed-in actor and workspace. Switching either scope invalidates the open editor and prevents late reads or writes from publishing into the replacement scope. An unreadable preference shows retry without an editable guessed value; a failed save retains the last confirmed value. This surface configures the existing live-browsing setting only, not local-model installation or provider credentials.

Regression coverage: `assistant_settings_cubit_test.dart`, `assistant_settings_hub_test.dart`, and `assistant_preferences_test.dart` cover persisted values, shared shell publication, failed reads/writes, and async scope invalidation.

## Mobile tool ordering and session ownership

Mobile Live runs the currently declared workspace tools on the authenticated
server API; only screen context is resolved locally. Tool batches execute in
provider receipt order. Finalizing a turn waits for its pending tool results,
including errors, before saving ordered text/tool parts. Both canonical Chat
history and legacy Assistant history restore those parts without replaying tools.
Provider text and output transcription are alternate streams: text takes priority
when both are present, preventing duplicated replies.

Each batch belongs to the actor, workspace, and connection generation captured
when received. Disconnecting, replacing the session, or changing actor discards
late output and prevents remaining calls from executing or reaching a new socket.
An already dispatched server mutation cannot be undone by client cancellation.
Starting a new typed turn keeps the completed previous turn's original text and
attachment metadata; its pending output cannot overwrite the new draft.

Regression evidence lives in `assistant_live_persistence_test.dart` and
`assistant_live_turn_parts_test.dart`. These are lifecycle and metadata checks;
provider latency and live device connectivity require separate runtime evidence.

## Mobile startup measurements

After the authenticated token arrives, mobile starts binding the visible
conversation and, in parallel, initializes its native audio player and then
opens the provider socket. The token envelope already carries seed history and
the server owns the chat, so binding never gates the provider handshake: the
call connects (and buffered startup speech drains) while the transcript is still
restoring. A binding failure stays in the chat view and never fails the call; an
audio failure still prevents connection. `prepareSession` still returns only
after binding settles, so a typed send captured from the visible conversation
dispatches only once that conversation is bound: a namespace switch can still
retire it. A retired preparation may already have opened a provider connection;
it is closed without sending user content. Cancellation or an actor/workspace
epoch change prevents later connection and timing publication. Native playback
initialization and disposal retain their existing serial queue.

Live state records monotonic millisecond durations for token minting, history
binding, audio initialization, socket connection, provider readiness, and the
whole attempt. These measurements contain no tokens, account identifiers, message
content, or error payloads and are not uploaded automatically. Concurrent stage
durations must not be added to estimate total latency. Failed attempts retain
only completed phase timings; obsolete attempts publish none.

`assistant_live_startup_phases_test.dart` verifies that binding overlaps the
handshake, that binding failures keep the call, that audio failures do not
connect, cancelled scope fencing, and immutable measurements. The total phase is
the time to a connected call; a slower binding publishes its duration after it
settles.
The Live information action in the shared shell opens the existing info sheet.
It shows the most recent attempt’s recorded phase durations in milliseconds,
including partial failed attempts, in a fixed phase order. Missing phases are
omitted. Measurements stay in memory on the current device: no account IDs,
request IDs, credentials, message content, persistence, or automatic uploads.
History overlaps the other phases, so phase durations do not sum to total time.
The sheet scrolls on small screens and with enlarged text. Widget regression
coverage is in `assistant_live_startup_diagnostics_test.dart`.

This removes serial client-side waiting; actual device/provider speed remains a
runtime measurement rather than a promised fixed latency reduction.

## Canonical mobile Live capabilities

New mobile clients request the `canonical-v1` tool protocol. The token response
selects the protocol; an absent or unsupported response value keeps the legacy
execution route. Existing clients keep legacy declarations and execution. A
canonical session discovers authorized operations through `search_workspace_tools`
and executes their validated input through `execute_workspace_tool`. Schemas come
from the same Mira registry used by Chat, so registered capabilities do not need
a second manually maintained mobile tool declaration list.

Every canonical request authenticates the actor, verifies workspace membership
and the voice tier, and executes through the canonical permission-aware factory.
This transport stays in the session workspace; workspace switching, interactive
rendered UI, and approval-gated tools are unavailable. Screen metadata remains a
local, opt-in capability. Discovery does not authorize a later request: execution
rechecks access. A tool error is retained as an error rather than represented as
a completed action. Provider call identifiers are preserved; this does not claim
network-wide mutation deduplication or cancellation of dispatched writes.

Resumption handles use protocol-specific, UUID-validated chat scopes so a
canonical connection cannot restore legacy tool declarations, or vice versa.
Both scopes still require ownership of the same conversation. The Rust GET
session port follows the same validation; web remains the production runtime.

`canonical-tool-bridge.test.ts`, the canonical execution route tests,
`session-scope.test.ts`, and `assistant_live_repository_test.dart` cover schema
validation, permissions, unavailable tools, scope separation, and compatibility.
Provider calls and latency still require authenticated runtime verification.

### Mobile remote reply lifecycle

An admitted mobile Chat reply keeps streaming while the app is temporarily
backgrounded and can complete or report its error before the user returns.
Foreground admission still applies to new prompts, attachments, history actions,
and Live controls. Account and workspace changes, including leaving and returning
to the same identity, and an explicit local/remote mode change invalidate the old
reply lease. Local runtime unload/reload alone does not invalidate that lease;
selecting a local model still stops remote work before local interaction.

`assistant_background_reply_test.dart` exercises the actual page and shell dock
through pause, completion/error, active resume, and account/workspace/mode ABA.
`assistant_local_chat_cubit_test.dart` verifies that semantic mode selection and
transient runtime epochs remain separate. These injected stream tests do not
guarantee that an operating system keeps a suspended app's network connection
alive; device and provider delivery remain separate evidence.

A replacement prompt accepted before pause remains accepted while cancellation
of the previous reply finishes. The composer clears only that captured prompt
under the same durable account/workspace/mode and attachment lease; a newer
unsent edit remains intact. Account departure clears private drafts through the
existing account reset, and mode/account ABA refuses the stale replacement.
`assistant_durable_acceptance_test.dart` exercises deferred real cancellation,
pause/resume, newer edits, and mode/account refusal through the actual dock.

## Mobile playback, transcript and call completion

The Live stage uses a layered gradient blob driven by the assistant's signed
16-bit, little-endian 24 kHz mono PCM admitted to the native playback queue.
Microphone input, text events and byte counts do not synthesize speaking energy.
Spectrum work and visual updates are bounded; a native drained-buffer callback,
interruption or teardown resets activity. Reduced motion keeps the shape static.
These controls do not establish physical speaker output or provider/device timing.

A received completed turn is sealed before waiting for tools, persistence or
history refresh. Subsequent spoken turns receive distinct identities and remain
in receipt order. Pending turns remain visible until scoped history confirms them;
restored Live identities prevent duplicate pending/history rows and preserve order
when server retries receive later timestamps. Failed synchronization stays marked
as unsynchronized and retries use the same turn identity. A successful write does
not remove the visible snapshot until restored history confirms every saved role
for that exact turn, workspace and conversation. A failed history restore retries
restoration without issuing another successful write. Pending snapshots are
in memory; process termination does not guarantee recovery of unsaved content.

Explicit End seals the currently observed partial turn before closing the call,
keeps Live selected and presents centered **Call again** and **View transcript**
actions. Calling again remains an explicit consent/admission action. Account,
workspace and conversation epochs refuse stale persistence and End callbacks.
Logout or other privacy teardown clears local drafts without flushing them to a
remote conversation. Reconnect does not authorize an old actor's work. Queued
provider frames carry an internal connection generation and are checked at
delivery; replacing or closing a connection also invalidates its raw listeners.
A deferred old close cannot revive or close a newer connection. Disposal closes
admission before native teardown awaits, clears retained retry closures and
refuses new session, microphone, camera or screen-capture admission. Repeated
disposal shares one completion; a native cleanup failure still closes the state
and attempts the remaining cleanup. This is separate from explicit End, which
may finish the current admitted turn.

Connected controls use the same shell action button geometry and styling as the
normal navbar, within its existing material. Buttons retain semantic toggle and
busy states and use the shared haptic preference. Calling uses the branded pending
indicator and respects reduced motion. No automatic sound is enabled by this
presentation change.

Regression coverage is in `assistant_live_persistence_test.dart`,
`assistant_live_audio_player_test.dart`, `assistant_playback_spectrum_test.dart`,
`assistant_live_transcript_section_test.dart`, `assistant_live_post_call_view_test.dart`,
`assistant_live_history_confirmation_cases.dart`, `assistant_live_socket_test.dart`
and the Live dock/calling widget tests. Device audio quality, suspended-process
survival and published mobile builds require separate delivery evidence.

### Pinned local runtime configuration

On-device preparation resolves only the app-owned `<catalog-id>.litertlm`
filename after store integrity verification. The pinned Qwen 3 0.6B artifact
uses its publisher-declared 4096-token context; Gemma and SmolLM2 retain the
existing 2048-token configuration. CPU, general-model interpretation, one
concurrent session and 256 output tokens remain unchanged. The Qwen context
is documented by its [immutable publisher README](https://huggingface.co/litert-community/Qwen3-0.6B/blob/a3c5d805ae362dff7f580bc25f2dfb9a5a7eaa76/README.md).

`assistant_litert_configuration_test.dart` checks actual adapter configuration,
unknown filename rejection, real import/verification through a fresh store,
saved selection reload and late native-result disposal after session ABA.
`assistant_local_reselection_test.dart` checks that held preparation is disposed
before the newest local choice activates. Synthetic bytes and native factories
prove persistence and configuration wiring only; they do not prove device
format compatibility or successful inference. Failed local prompts remain local
with visible recovery and never silently fall back to a remote provider.

### Mobile name confirmation and offline intent

The mobile header uses the confirmed assistant name, with Mira as its display
default when no verified snapshot exists. An offline rename keeps the confirmed
header and records a separate local name intent. Queued, conflicted and failed
intents remain available through the existing offline changes sheet; they are
never automatically discarded or promoted to confirmed names. Explicit pending
name presentation is a separate UI step.

Verified Soul snapshots use an account-owned cache envelope. Legacy optimistic
name caches are not evidence of server confirmation, and disappearance of a queue
record alone does not confirm its value. A validated server receipt establishes
confirmation. Account departure and cache-clear epochs fence held reads and
writes, including same-account restoration. Genuine permission and transport
errors remain errors on explicit refresh.

`assistant_soul_provenance_test.dart` exercises real encrypted cache and queue
restart, all three pending statuses, held account/clear boundaries, malformed and
foreign receipts, permission failure, and the Shell header's offline rename.
These tests establish source behavior, not device or deployed-runtime proof.

# Assistant local models
Source: https://docs.tuturuuu.com/platform/features/assistant-local-models

Mobile local text model installation, preparation, recovery, and inference evidence.

Mobile's local text inference adapter uses the pinned Flutter Edge AI LiteRT-LM
engine directly; it does not route prompts to the remote Assistant API or use a
global active-model preference. Remote Chat remains the default. Mira quick
settings and the centralized Assistant settings page share model management:
install or import a verified model, then explicitly choose it for the current
account and workspace. The existing persistent dock remains in place when
switching; local generation exposes a native stop action. Live audio, server
tools, attachments, and workspace context are unavailable in local text mode.
Choosing a remote model is an explicit separate action, never a failure fallback.

Local and remote conversations remain separate; switching never uploads local
history. The unsent composer draft stays in place, and the next send uses the
chosen mode. Local history is encrypted with the existing device cache and
partitioned by actor, workspace, and model. Only the latest 32 messages / 64,000
characters are retained, and cache eviction or clearing can remove them. A new
local conversation clears that local history after stopping and draining any
active generation. Deleting weights leaves local mode selected but blocked;
missing weights, unknown selections, and native load failures never silently
select a remote provider. Account/session changes, backgrounding, and hiding
Mira stop and unload native inference before another scoped load.

The initial catalogue pins publisher revisions, file lengths, and SHA-256
digests for Gemma 3 270M, Qwen 3 0.6B, and SmolLM2 360M. Gemma requires the user to obtain a
licensed file; the app does not accept a gated model's license on their behalf
or collect Hugging Face credentials. Qwen and SmolLM2 use their Apache 2.0 distributions.
Installation verifies the full file before atomic publication, preserves an
existing valid file after a corrupt download, allows cancellation, and enforces
a 1 GiB device weight budget, including temporary replacement space.

Android admission follows the pinned LiteRT-LM library's API 30 minimum;
API 28–29 remain unsupported even when they meet the memory requirement.
Preparation is a separate per-selection operation. After store integrity checks,
the adapter reads only the 32-byte LiteRT-LM prefix and rejects a missing magic
signature, truncated prefix, incompatible major version, or an empty/out-of-file
metadata range before native creation. Its major-version rule matches the
[pinned native reader](https://github.com/google-ai-edge/LiteRT-LM/blob/5e58e9a0/schema/core/litertlm_read.cc);
same-major minor/patch versions remain subject to native section validation.
A valid prefix is not a complete container or inference proof. The native engine
still decides section, CPU backend, and device compatibility.

The compact model status sheet distinguishes invalid files, incompatible format
versions, unavailable runtime/ABI libraries, storage failures, and opaque native
load failures with English/Vietnamese recovery instructions. Raw native exception
messages and private paths are not shown. Selecting the model again starts a new
preparation revision; stale results cannot overwrite newer selections. Downloaded
or installed status never establishes Ready. Ready requires the current scoped
native load to succeed, and restart always prepares again. This applies to mobile
local text models only; remote and Live behavior are unchanged. Synthetic header,
adapter-error and cubit recovery regressions live in
`assistant_model_preparation_test.dart`, `assistant_litert_configuration_test.dart`
and `assistant_preparation_recovery_test.dart`. Actual device model inference
remains a separate required delivery gate.

On Android and iOS, public provider downloads use persisted native background
jobs with pause, resume, and explicit cancellation. Opening or closing settings
observes the same job rather than starting another transfer. A restored job is
not an installed model until its complete file passes the pinned length and
SHA-256 checks. Public weights are device-owned; actor changes do not select a
model or attach private conversation data to the transfer. OS scheduling, force
quit, and connectivity can delay or terminate background work; an interrupted
job offers retry. Gated providers still require an externally obtained licensed
file. Other supported desktop platforms retain foreground downloads.

Wi-Fi-only is the default for model downloads and offline module preparation.
Cellular or unknown connectivity requires an explicit Continue, Use Wi-Fi, or
Cancel choice before any transfer or preparation API call starts. Continue
allows cellular for that requested job; Use Wi-Fi preserves a pending plan.
Offline module plans persist only the requested product IDs and network choice
in the encrypted actor/workspace cache, never bearer tokens. Foreground resume
uses current credentials and scope epochs, coalesces overlapping triggers, and
never expands the requested modules. Network loss retains pending work;
definitive permission denial removes it, while an MFA challenge leaves it
pending. Plans expire after 30 days; clearing the corresponding cache can
remove them.

Settings expose download, checksum, storage, and provider-admission failures
separately. A completed download does not prove native engine readiness: the
existing hardware checks and successful engine load still apply. Embedded quick
settings avoid a second bottom safe-area inset and use content-sized sections.
Transfer verification, cellular choice, and scoped resume regressions live in
`assistant_model_downloads_test.dart`, `download_network_consent_test.dart`, and
`offline_preparation_intent_test.dart` under `apps/mobile/test/`.

Native support is restricted to the archive's supported ABIs: arm64 iOS/macOS,
arm64 Android API 30+, arm64/x64 Linux, and x64 Windows. Other ABIs remain
unavailable. The app's existing OS floors are preserved. Product admission also
requires at least 4 GiB installed RAM; unavailable hardware information fails
closed. This conservative threshold is not a guarantee of available memory or
a working accelerator: successful model loading is
required before readiness. Text generation uses one session, a catalog-specific token
context, a separate 256-output-token limit, and bounded input. Actor/session
epoch changes suppress late output and unload tears down the session before
freeing its model. No local failure silently switches a private prompt to a
remote provider.

Storage and lifecycle regressions are in
`apps/mobile/test/features/assistant/local/`. Exact native CI builds and a real
device generation remain required delivery evidence; synthetic adapters and
downloaded runtime binaries alone do not prove local inference. macOS beta
packaging stages SHA-256-pinned runtime companions before the existing audit,
Developer ID signing, and notarization gates.

# Assistant reaction retention proposal
Source: https://docs.tuturuuu.com/platform/features/assistant-reaction-retention

A bounded cleanup plan that preserves reaction retry and retirement guarantees.

## Status and current behavior

This is a proposal, not an enabled cleanup service or a migration. Native mobile
Assistant uses `private.chat_reaction_operations` for actor-bound receipts and
`private.chat_retired_reaction_operations` to reject delayed retired writes.
Existing web Chat toggle callers do not use these operation receipts.

The current default retains these records. Receipt rows already cascade with
their actor, workspace, conversation or message; retirement rows cascade with
their actor. There is no age-based expiry. Do not delete either table's records
by age under the current protocol: an old request with a forgotten operation ID
could otherwise apply its desired state after a newer choice.

See [native reaction operations](/platform/features/assistant-live#native-mobile-reaction-operations)
for the shipping retry and sign-out contract.

## Proposed expiry contract

Introduce a versioned write contract with server-issued, actor-bound operation
tickets. Bind the ticket to the operation ID, canonical intent and an absolute
server expiry. A proposed starting policy is a seven-day admission window;
confirm that product window before implementation.

Require the ticket for both desired-state writes and retirement. Reject arbitrary
unissued IDs and expired unseen operations without mutating reactions. Preserve
the current actor authentication, conversation admission and intent-mismatch
checks. Issuance needs bounded actor quotas and its own abuse controls.

Check expiry using fresh server time after acquiring the operation lock, before
any new mutation. An ingress-only check or client timestamp is insufficient.
Keep operation/retirement lock ordering and message serialization. Bound database
transaction lifetime and test requests that expire while waiting for locks.

A terminal expiry response lets the client stop replaying that operation and
read the exact current message. A new reaction still requires a new explicit
choice. Expiry must not silently claim that the previous operation never applied.
Provide localized recovery on mobile before changing its replay window.

Only enable deletion after the legacy unbounded desired-state write contract is
closed, its admitted transactions have drained, and old clients fail closed.
Old signed-out journals need terminal reconciliation through the new contract;
they must not be discarded during migration. Existing web POST toggles remain a
separate compatibility path.

After those prerequisites, proposed storage limits are 30 days for terminal
receipts and 90 days for retirement fences. Eligibility must also exceed the
ticket expiry plus a verified transaction-drain grace period. These are proposed
limits, not current promises. Add reliable expiry/creation columns and indexed
eligibility through a new reviewed migration; do not modify the shipped migration.

## Cloudflare cleanup owner and bounds

Use a dedicated Cloudflare Worker with an hourly Cron Trigger and a Durable
Object holding the enabled state, stop generation and bounded run cursor. Do not
use Vercel Cron, Next background work or a database scheduler.

Start disabled. Each admitted run may perform at most ten database batches of
250 rows, with a fixed execution deadline and no automatic retry loop. Select
only eligible rows using indexed expiry and stable keys; deleting an already
deleted row is a successful no-op. Resume unfinished work at the next scheduled
run and finish immediately when there are no eligible rows.

Persist and acknowledge a stop generation before disabling execution. Check it
before every database batch and define completion only after an already-admitted
batch drains. Bound the database statement as well as the Worker request; a
client timeout alone does not establish cancellation. No queue or continuation
may schedule itself after the stop fence.

Record rows selected/deleted, batch count, duration and the oldest eligible age
without actor, message, emoji or operation payloads. Define daily database and
Worker operation budgets and stop on exhaustion. Request rate limits, alerts and
per-invocation CPU limits do not bound total scheduled spend.

## Acceptance before activation

* Apply the additive migration in an isolated full-chain fixture and regenerate
  database types. Independently review service-role access and cleanup admission.
* Prove expiry before dispatch, while waiting on both locks, after an unknown
  response, after sign-out and after a newer add/remove. Exercise concurrent
  connections and verify an expired delayed request cannot change the result.
* Prove old clients and arbitrary retirement IDs fail closed, and mobile retains
  unknown intent until terminal reconciliation. Cover localized expiry recovery.
* Verify retry, restart and cursor behavior with both empty and maximum batches.
  Assert operation budgets, deadline behavior, durable stop and in-flight drain.
* Run exact-commit CI and the real Worker/Durable Object runtime. Obtain scoped
  activation and rollback authorization before enabling the schedule. Rollback
  stops cleanup first and must not reopen an unbounded legacy mutation path.

# Calendar task scheduling summaries
Source: https://docs.tuturuuu.com/platform/features/calendar-scheduling-summary

Actor-scoped batched scheduling reads in Calendar task panels.

Calendar's priority task panel loads scheduling settings and scheduled minutes in
batches of up to 100 distinct tasks. Larger lists use sequential batches. This
applies to both personal and workspace Calendar surfaces, including the shared
Calendar panel in Tasks; scheduling mutations and task history retain their
existing endpoints.

Per-user settings default to no duration, no automatic scheduling, and no
splitting when the user has not configured them. Only member-authorized source
tasks are returned. Personal mode counts events in the personal calendar;
workspace mode counts each task's events in its source workspace. Linked and
direct task events contribute once per task/event pair.

The panel retains its last authorized snapshot during transient revalidation and
MFA challenges, but hides it after definitive access denial. Stale summaries
refresh when the user returns to the browser tab. Failed database reads or
incomplete event pagination fail the refresh rather than publishing a partial or
zeroed summary.

Regression coverage: `task-schedule-batch.test.ts` checks membership, actor-scoped
settings, calendar isolation, defaults, deduplication and late-page failures;
`tasks-scheduling-batch.test.ts` checks request chunking and partial failures;
`task-schedule-snapshot.test.ts` checks transient versus denied visibility.

This is a reduction in scheduling requests, not proof that every Calendar startup
waterfall is resolved. Validate authenticated meaningful-content timing after
production deployment of the exact tested source.

# CMS Site Contract v1
Source: https://docs.tuturuuu.com/platform/features/cms-site-contract-v1

The default reusable content and delivery contract for CMS-backed sites.

## Purpose

Use the CMS site contract for new CMS-backed websites. It is the global version
1 schema, not an external-project adapter or project-specific implementation.
External apps retain their own adapter identity and carry this contract through
workspace-scoped template metadata and collection schema/profile metadata.

Backend routes and database objects retain their existing `external-project*`
names for compatibility. Normal CMS UI should use editor-facing site and
content language.

## Standard Collections

The v1 contract starts with `site-settings`, `navigation`, `pages`, `posts`,
`taxonomies`, `landing-sections`, `redirects`, and `media-assets`. Apps may add fields and
collections through the manifest schema without creating another adapter.

The optional `template` object is versioned independently:

```json theme={null}
{
  "kind": "wordpress-replacement",
  "version": 1,
  "editor": {},
  "publicDelivery": {}
}
```

Template metadata is persisted on the workspace binding. It is returned in sync
snapshots and public delivery, but it does not create content diff operations or
destructive changes.

## Public Consumption

The Tuturuuu SDK exports `buildCmsSiteManifest` and
`normalizeCmsSiteDelivery`. The builder creates the standard schema. The
delivery normalizer indexes collections by slug and resolves relative asset
URLs against the public platform origin supplied by the consumer.

Public sites should consume read-only delivery and keep a static fallback for
availability during migration. Do not place site control secrets in public
runtime configuration.

## Migration Safety

Keep the existing site, administration routes, and realtime endpoints
authoritative while mirroring is introduced. Validate imports, reverse replies,
idempotency, retry after platform outage, and health checks on preview or local
canaries first.

Production authority or routing must not switch until the operator explicitly
approves cutover after deployed verification. A healthy bridge is a prerequisite,
not cutover approval. Rollback must restore direct legacy routing without a
database migration.

Visitor context such as route history or network information belongs in
access-controlled dynamic JSON metadata. Do not add fixed columns that reveal
or imply a particular category of confidential data.

# Colab team prompt workshops
Source: https://docs.tuturuuu.com/platform/features/colab

Run invite-only AI learning workshops on Cloudflare with isolated mock tools.

Colab at `colab.tuturuuu.com` is a standalone React application served by a
Cloudflare Worker. A SQLite Durable Object owns each room. The reusable
`@tuturuuu/multiplayer` package defines room policy and safe member-specific
projections; the Worker owns authentication, inference, storage and WebSockets.

## Vite+ toolchain

Colab uses the pinned local Vite+ CLI for development, tests and client builds.
Its existing React/Tailwind plugins, framework-import bundle guard and Cloudflare
Worker entrypoint remain intact. Tests import `vite-plus/test`; the shared Vitest
and coverage version is aligned with Vite+'s bundled runner. Colab retains a direct
`vite` dependency aliased to the same `@voidzero-dev/vite-plus-core` release, so
Bun resolves plugin peers and configuration types to one Vite implementation.
See the [Vite+ dependency rules](https://viteplus.dev/guide/migrate-rules#vite-and-overrides).
Use Node 24.11+ (CI
pins Node 24), Node 22.18+, or Node 26+; Node 25 is outside the package's declared
support range.

`bun run lint` uses Oxlint through Vite+ and `bun run format:check` provides a
read-only Oxfmt comparison. Explicit `.oxlintrc.json` and `.oxfmtrc.json` files avoid native config-loader
resolution through Bun's shared package store; the CLI uses these files directly. The initial Oxlint gate covers core/TypeScript/Oxc correctness and native-dialog
prohibition. React compiler diagnostics and additional accessibility rules need
separate behavior-reviewed fixes before enabling those rule families; existing
Biome accessibility/hooks checks remain authoritative. Biome
remains the repository formatter until this scope's formatting/rule parity and
editor/generator changes are complete; do not enable competing format writers.
Colab tests use the thread pool with per-file isolation retained. Repeated fork-pool
runs on Vitest 5.0.0 and 5.0.3 failed collection while opening temporary transformed
modules under `/tmp/.../ssr` or `/tmp/.../client`; the same focused suites passed
with `--pool=threads`. One worker, result-cache disabling, and Node 24 did not
resolve that collection failure. Treat it as a runner boundary to investigate,
not evidence that product assertions failed; preserve every suite and assertion.

This tooling change does not alter cookies, sponsorship, Durable Object class
names, bindings, storage, routes or canonical deployment ownership.

## Shared application shell

`apps/colab/src/client/structure.tsx` composes the same
`@tuturuuu/ui/custom/satellite-shell` component used by satellite apps. It uses shared
UI buttons, icons and design tokens, with persistent desktop collapse, a mobile
navigation drawer, account controls and room-section links. The app imports the
shared UI stylesheet through Tailwind's Vite integration. Keep Colab content CSS
in the components layer so shared component utilities remain authoritative.
Colab supplies a History API navigation adapter so the sidebar and account menu
stay mounted between pages.

## Running a workshop

1. Sign in with a confirmed Tuturuuu account. Only an exact `@tuturuuu.com`
   account can create a room. Choose its start/end time, participant limit and
   number of teams. Limits are 5 minutes–8 hours, 2–100 participants including
   admins, and 1–12 teams.
2. In the facilitator desk, allow account emails and share the room URL. This
   adds an account invitation; it does not send email. Alternatively, generate a
   random temporary password and share it separately. The password appears once;
   only its SHA-256 digest is stored. Rotation removes password-only guests.
3. Each team writes and saves a system prompt. Version checks reject concurrent
   overwrites. Drafts remain local until saved. A teammate can explicitly load
   the latest saved version after a conflict.
4. Generate a single skill or let the model split the instructions into up to
   four focused skills. Each download contains YAML frontmatter and readable
   Markdown instructions. Place it in `<skill-name>/SKILL.md` in a compatible
   agent environment after reviewing it. If Workers AI returns incomplete or
   differently shaped JSON, Colab retries once and then produces a conservative
   prompt-based working guide so a learner is never blocked by model formatting.
5. Test the generated skills against the room scenario. The journal records the
   prompt snapshot, scenario, actual sandbox tool inputs/results, final answer
   and AI coaching. Each run starts with a plain-language health summary: its
   completion reason, evidence actions, successful practice-data changes, action
   failures, and apps used. The timeline makes failed actions visually distinct
   and offers a recovery hint; raw JSON and prompt diagnostics stay collapsed
   for facilitators who need them. Coaching is advisory, not proof of agent
   correctness.
6. New rooms share team work live by default. The dedicated Live showcase tab
   follows the team on stage and presents its challenge, system prompt, reusable
   skills, and latest test result in one audience-facing view. Authorized team
   members can run the live test there, while facilitators advance teams in order.
   Saved prompts, generated skills, sandbox records, and run journals update for
   viewers without reloading. Unsaved editor drafts stay local. Room admins can
   turn showcase off or on immediately; disabling it removes other teams from
   participant views and server payloads. Existing rooms retain their saved
   setting. Admins can always inspect all teams. Only staff admins can promote
   other signed-in accounts to room admin.
7. Close to read-only, or set private mode to restrict access to admins. At the
   scheduled end the room becomes read-only. Every mutation checks the clock;
   the Durable Object alarm also updates connected clients. Private mode and
   revoked memberships close affected sockets.

## Sandbox boundary

The eight adapters cover Google Drive, Notion, Zalo, Messenger, Microsoft Teams,
Google Calendar, Jira and Trello. They simulate searchable records and
create/update actions. They are educational mockups, not replicas of the full
products. No third-party app credentials, network fetch tools or real messaging
connectors are available to the agent. Each team's writes affect only its own
records. Admins can reset those records to the seeded RISE dataset.

AI Studio sponsors skills, scenarios, agent decisions and feedback using the
configured `COLAB_AI_MODEL`. Agent execution uses a bounded JSON tool
protocol with an allowlist and runtime validation. New workshops allow 500 AI
operations, 60 turns, and 50 app actions per run; new teams begin with 150 AI
operations, 60 turns, and 50 app actions. Hosts can use Guided, Extended, or Deep
dive presets or set exact room and team limits, up to 5,000 AI operations, 100
turns, and 80 app actions. An app-action limit must stay below the turn limit so
the agent retains a final answer turn. Existing rooms are normalized to the new
defaults only when a value was never stored. A room allows one concurrent AI job.
If room state changes while inference is running, the stale result is discarded.
The system prompt, scenario, practice records and traces are sent to the AI provider;
participants should use workshop examples rather than confidential real data.

## Authentication and deployment

The Worker redirects to central Tuturuuu login with a nonce-bound return URL.
`POST /api/v1/auth/colab/verify` consumes a Colab-targeted one-time handoff and
looks up the confirmed, non-banned user in Supabase Auth. It deliberately ignores
`cross_app_tokens.session_data.email`, which is caller-controlled. Colab signs
its own short-lived, HttpOnly, Secure, SameSite cookie using
`COLAB_SESSION_SECRET`. The Worker never receives a Supabase service key.

Ship the Colab domain registration in `packages/utils/src/internal-domains.ts`
and the verifier on the live web app before accepting production account logins.
The new verifier is tracked as Rust migration backlog; the Rust backend does not
serve production traffic. No Supabase migration or production database push is
required for Colab.

The Cloudflare configuration is `apps/colab/wrangler.jsonc`. It creates
`tuturuuu-colab`, binds the room Durable Object and Workers AI, serves static
assets, and attaches the `colab.tuturuuu.com` custom domain. Use the authorized
Tuturuuu Cloudflare account. Provision a cryptographically random
`COLAB_SESSION_SECRET` through Wrangler's secret input; never commit it.

The exact-commit Cloudflare workflow owns client builds, Worker dry-run bundling,
asset publication and authorized production deployment. Do not run release builds
or build-triggering deploy scripts on the shared host. Provision secrets through
an explicitly authorized secret-management flow, separately from tooling changes.

Rotate the session secret only intentionally: it signs out all Colab sessions.
Room state persists in Durable Object SQLite storage across Worker deployments.
Keep the `v1` migration and class name stable. Read-only rooms are retained;
there is no automatic data deletion policy in this release.

## Verification

Queue focused non-build checks through the shared resource broker:

```sh theme={null}
cd apps/colab
ttr resources run -- bun run test --maxWorkers=2
ttr resources run -- bun run lint
```

Use a supported Node runtime for the CLI. Require exact-commit CI type/lint/test
and real Vite+ client/Worker build validation. Runtime/browser verification may
consume immutable CI artifacts or local dev bundling with isolated persistence;
it does not authorize a local release build or deployment. Do not run `bun validate`
on this shared host because its dependency graph can build workspaces.

The finite runtime script starts a local Worker on port 8795 with a test-only
signing secret, uses isolated in-memory Durable Objects, verifies access and
concurrent updates, and opens headless Chromium for desktop/mobile and Vietnamese
checks. It never creates a production session. It writes screenshots to
`/private/tmp/colab-*.png` and closes the browser/runtime when finished. Install
the Playwright Chromium browser if it is not already available.

After deployment verify `/api/health`, static asset responses, central sign-in,
an invited account and temporary guest, live team updates, skill generation and
an AI run. Correlate the Worker version with its source revision and inspect
Wrangler logs without logging passwords, cookies or prompts. A successful
Cloudflare upload alone does not establish that central sign-in is deployed.

## Automatic deployment

`.github/workflows/colab-cloudflare.yaml` validates affected `main` and
`production` revisions and deploys only `production`. The repository switchboard
in `tuturuuu.ci.ts` controls it. Manual dispatch on `production` retries a release.
The validation job pins supported Node, tests both workspaces, runs Oxlint, builds the client, bundles the Worker,
and uploads revision-specific assets. Deployment downloads those same assets,
records the Git SHA in the Worker version message, and checks canonical health
and every asset hash. Verification retries up to 12 times, five seconds apart,
so a successful upload is not mistaken for immediate edge propagation; persistent
hash mismatches still fail the job. Deployments are serialized and never cancel an active release.

Configure the repository Actions secret (or environment `colab-production` secret)
`COLAB_CLOUDFLARE_API_TOKEN`: Workers Scripts edit, Workers AI read, account read,
and Workers Routes edit plus zone read for `tuturuuu.com`, scoped to Tuturuuu.
The session signing secret stays in Cloudflare and is not regenerated by CI.

An expired or incomplete login returns to a bilingual recovery panel instead of
a JSON error. `/verify-token` unwraps the central portal's callback only for
Colab's own `/auth/callback`; the callback still requires its original nonce cookie.

### Appearance and satellite parity

Colab opens into a compact workshop lobby and uses the shared Tuturuuu logo,
Structure layout, buttons, dropdown menus, and semantic color tokens. The toolbar
provides Light, Dark, and System appearance choices. Like the satellite apps,
`next-themes` stores the preference under `theme`; System follows OS changes.
The initial HTML applies that preference before painting to avoid a light flash.
Account and language controls live in the sidebar account menu. Colab's Vite
runtime uses framework-independent UI primitives rather than Next-only providers.

The runtime verification script covers explicit themes, persistence across reloads,
live system-theme changes, account-menu keyboard dismissal, and mobile navigation.

### Shared shell and framework adapters

Colab, Tasks, Calendar, and the other satellite apps share the shell in
`@tuturuuu/ui/custom/satellite-shell`. The shared layer owns brand markup,
sidebar layout, navigation sections, workspace-selector reveal, nested-navigation
state, and collapse/hover behavior. It accepts React slots and callbacks without
importing Next.js, authentication clients, or translation providers.

`@tuturuuu/satellite/sidebar-structure` remains the Next.js adapter. Its public
props are unchanged; it supplies Next links, pathname, translations, cookie
persistence, workspace context, settings, billing, and the app launcher.
Colab's `structure.tsx` supplies native links, local preference persistence, and
its Cloudflare room/account controls to the same implementation. Theme support
continues through shared CSS tokens and `next-themes`.

Make shell presentation changes in the shared UI components. Keep routing,
authorization, and workspace services in the adapters. Colab's Vite build rejects
Next.js or next-intl runtime modules in its bundle, guarding this boundary.

### Account profile and footer

Colab and Next satellite apps use the same `SatelliteUserMenuItems`, account switcher, language and theme items, Settings layout, report form, and footer components from `@tuturuuu/ui`. Framework adapters supply session and navigation services; they must not replace the shared UI with reduced menu items or a different design. Colab self-hosts the same Noto Sans variable font used by Next apps.

The menu preserves the Next satellite ordering: Dashboard; Sidebar (expanded, collapsed, expand on hover, hidden); Language (English, Vietnamese, system); Theme (light, dark, system); Report a problem; account switching/removal/management; Log out. Settings retain the shared search, keyboard navigation, desktop/mobile layout and guidance controls. The report dialog retains attachments, validation, compression and draft handling. There is no Reconnect account menu action.

Central account changes automatically complete the Colab handoff while preserving the room URL. The verifier resolves display name and avatar from the verified user's profile; confirmed auth email remains the permission authority. Central and Colab sessions expire independently, and signed-out users can continue through the central login portal. Guests can still join with a room password.

The Worker forwards only explicitly allowlisted real account/support endpoints (reports, onboarding progress, and the sidebar preference) to `AUTH_ORIGIN`, with central Supabase auth cookies and same-origin mutation checks. This bridge is separate from the simulated workshop tools, which cannot call real services. Account switching uses the existing central account API with credentialed CORS. Regression checks cover the allowlist, cookie filtering, rejected origins/methods and body limits.

## Workspace entry and notifications

Colab requires a Tuturuuu login when opening the app. The sidebar separates
Workshops (`/`), Join a room (dialog), Host a workshop (dialog, staff only),
and Practice guide (`/guide`). Direct `/?room=...` invitations retain temporary
password entry for guests. Login preserves the selected app destination.

The desktop shell has no page navbar. Appearance remains in the account menu,
and the shared shell retains mobile navigation and the sidebar edge toggle.
The home screen offers the most recent room on this device without implying
that the room is still open or that its access has been verified.

The sidebar notification bell uses the same inbox, archive, pagination, read
actions, and invitation controls as Next.js satellites. Colab supplies native
central-site links and polls the unread count and open notification list every 30 seconds while visible;
Next.js satellites use the shared authenticated API refresh subscription every
120 seconds while visible and online; notification actions and return-to-app
events refresh immediately. Only exact
notification and workspace-invitation endpoints are proxied to the central app,
with central authentication cookies, same-origin mutation checks, and preserved
query filters. These account endpoints are never exposed to simulated AI tools.

Validate with focused non-build tests, exact-commit CI builds, and the finite
`scripts/verify-runtime.mjs` under supported Node using verified Worker artifacts. The runtime
verifier covers default-login redirects, guest invitation documents, separate
sidebar destinations, notification read/archive actions with mock data, and
English/Vietnamese desktop/mobile layouts. No production notification is changed.

Workspace navigation uses client-side history and keeps the shell, account controls,
and notification queries mounted. Join a room opens a shared dialog above the
current page; dismissing it preserves host drafts and guide interactions. Browser
Back/Forward follows navigation and dialog history. Direct `/join` links still
require login and open the dialog over the workspace home. Modified link clicks
retain normal browser behavior. The finite runtime verifier checks document and
sidebar identity, dialog dismissal, draft retention, and mobile overflow.

Hosting also opens above the current page, and its draft survives closing and
reopening the dialog. Direct `/host` links open it above the home workspace.

Colab refreshes its account session before the one-hour expiry using the central
`/api/auth/me` endpoint, which revalidates the Supabase user. Only central auth
cookies are forwarded; rotated auth cookies are returned to the browser.
Confirmed account email remains the permission source. Guest sessions are never
extended by this mechanism. The visible client checks its session every minute
and reopens its room WebSocket when renewed credentials change. Temporary
identity-service failures retain the current workspace and can be retried;
explicit sign-out, account revocation, and private-room access denial still apply.

## RISE learning and sponsored workshops

New workshops start with the RISE Induction Day publishing mission. Teams build a
reusable system prompt, generate skills, gather evidence across practice apps, and
produce a bilingual Facebook draft plus artwork guidance and a publishing
checklist. The catalog has 202 records across 24 apps, including ten connected
Induction Day sources. Conflicting schedules and unconfirmed partner claims are
deliberate research exercises. Dates, venue and registration links are rehearsal
data: replace them with verified event details and obtain human approval before
publishing. Colab does not publish to Facebook.

Existing rooms receive the new scenario as an additional choice without changing
their selected scenario, edited prompts or records. Learning is available from
the workspace guide and as a dedicated workshop destination. It includes six
lessons, an editable Markdown preview, a source map, and interactive RISE and
CRAFT framework examples. Explored lessons are remembered on the device.

The prompt editor provides an immediate, explicitly heuristic structure check.
Ask AI to review performs a sponsored model call, maps exact prompt excerpts to
framework sections, and explains suggested improvements. Reviews are shared with
the team and marked outdated after prompt edits. Suggestions never replace a
prompt automatically. A structure match is not a quality or safety guarantee.

Only accounts with a centrally verified `@tuturuuu.com` email can create or manage
workshops. Hosts may promote only other eligible Tuturuuu accounts. External
members retain attendee, multi-team collaboration, learning and showcase access;
legacy external admin flags are removed during room normalization.

Production AI uses automatic first-party authorization with
`COLAB_REQUIRE_SPONSORSHIP=true`; no AI API key needs to be created or copied.
The authorized room job stores a random, one-use capability bound to the SHA-256
digest of the exact model request. AI Studio redeems it over HTTPS at the pinned
canonical `https://colab.tuturuuu.com/api/sponsorship/verify` endpoint. Redemption
is an atomic delete, expires after 60 seconds, and cannot be replayed concurrently.
The capability never enters browser state, activity logs or billing metadata.
AI Studio revalidates the host's confirmed Tuturuuu account, fixes the billing
workspace to root, and derives request/idempotency IDs from the approved job.
Root workspace model, rate, budget and credit policies still apply. This is metered
first-party usage, not an unmetered external-app credential. No new database
migration is required: the existing reservation procedure supports a null API key.

Deploy the AI Studio endpoint and Colab verifier together before testing live
generation. `COLAB_AI_MODEL` selects an enabled, priced root-workspace model.
Canonical HTTPS reachability is required in both directions; preview deployments
cannot approve their own root-credit requests. No shared machine secret is needed.
`COLAB_AI_API_KEY` remains an optional legacy transport for callers without room
approval support; app-bound keys are rejected. Invalid approval, disabled hosts,
unavailable verification or insufficient credits fails closed.
The direct Cloudflare AI binding remains available only for local/legacy setups
that do not require sponsorship; local verification uses deterministic responses.

The dedicated endpoint checks root workspace ownership, reserves and settles
credits through AI Studio, and records workshop, host, team, participant, scenario,
operation, generation phase, job and request identifiers with a human-readable
sponsorship description. Retries are separate metered calls. Unknown pricing must
not be reported as free usage. Hosts can export the latest 100 confirmed receipts;
attendees receive totals, not receipt identifiers. Workshop totals cover confirmed
responses only; AI Studio remains authoritative for failed or interrupted calls.

The finite browser verifier exercises learning interactions, shared prompt
reviews, skill generation, multi-account showcase runs and reconnection with
isolated Durable Objects. It does not establish real provider output quality or
production credit settlement: verify those separately after deployment.
`node scripts/verify-sponsorship.mjs` additionally exercises keyless generation,
body tampering, concurrent replay rejection and receipts using isolated Durable
Objects and mocked AI Studio responses. It does not spend production credits.

## Reliable practice runs

New workshops and teams default to 60 agent turns and 50 tool calls. Existing
custom limits are preserved; hosts can choose the Deep dive preset for both the
workshop and its teams. The catalog contains 250 linked RISE practice records
across 24 apps, including review workflows, study support, capacity planning,
and the Induction Day evidence pack.

The agent can use `draft` to save a reviewable record without sending or
publishing anything. `generate_image` calls AI Studio using the same one-use
first-party grant and root-workspace billing as text. It requires an enabled,
priced image model in the root workspace; it does not bypass model policy.
Each call generates one image, with at most 50 retained images per workshop.
Unavailable image generation is reported in the action trace with setup guidance,
and the agent can continue with an artwork brief.

Gemini Flash artwork supports `google/gemini-3.1-flash-image` through
Google's multimodal language API using `GOOGLE_GENERATIVE_AI_API_KEY`, even though the catalog classifies it as
`language`. Colab requests one 1K image without search or publishing tools.
Enable the model in the catalog, global access policy, and sponsor plan before
using it. The reservation is conservative; settlement uses Google's actual
modality token counts ($0.50/M input, $3/M text/thinking, \$60/M image output), then applies the sponsor plan's
markup. Root AI Studio runs retain provider response IDs, token counts, image
counts, and workshop sponsorship descriptions. Missing modality data fails closed and
mark measured usage for reconciliation instead of treating artwork as free.
Do not select the retired `-preview` alias; Google lists its shutdown on June 25, 2026.

Generated PNG/JPEG/WebP assets are stored separately from realtime room JSON in
bounded SQLite chunks. Image requests re-check room membership and team visibility,
including showcase access, and return private no-store responses. Workshop
deletion removes its images. Captions, tables, checklists, code, and image outputs
use safe Markdown rendering; structured bilingual answers have separate copy buttons.

Practice actions accept `search`, `read`, `create`, `draft`, `update`, and `generate_image`, including exact
namespaced forms such as `drive.search`. A namespace must match the selected app;
unsupported actions such as publishing or deleting remain rejected. Record IDs
are always checked within the selected app. Normalized actions appear in the trace.
The agent reserves its last available turn for an answer and cannot execute another
tool after exhausting its action budget. Coaching is a secondary step: if it fails,
the answer and actual tool trace remain available with an explicit unavailable notice.

Results containing a JSON object are displayed as readable, separately copyable
sections, including bilingual captions, source notes and review checklists. Plain
Markdown and incomplete responses remain readable without silently dropping text.
The local showcase verifier exercises this output and namespaced actions through
the real room, persistence and multi-browser broadcast path using deterministic AI.

## Workshop directory and activity log

Workshops is the default signed-in screen and is also available at `/workshops`.
Current/upcoming and past sessions have separate searchable tabs. Join and host
remain dialogs. Within a room, Brief, Prompt, Skills, Sandbox, Results, Activity
log and Host controls are sidebar destinations, without a duplicate tab bar.
Host controls appear only for room admins and update with realtime role changes.
Expandable host settings preserve form state while closed. Editor components stay
mounted when sidebar destinations or selected teams change, preserving local
unsaved work. Shared UI labels, checkboxes, cards and selectors use consistent
spacing; sandbox apps are selected from a compact dropdown.

The directory uses per-account Durable Object identifiers in the existing ROOMS
binding. Creation, successful joining and authorized visits register a room.
Reads recheck membership and private mode against each room before returning
metadata; withdrawn access is excluded. The directory returns the 100 most
recently visited rooms. Legacy rooms appear after an authorized visit to their
existing link; no global historical enumeration or backfill is performed.

The room persists its latest 200 successful actions with time, actor display name
and action category. Password values, invitation addresses, prompts and tool
payloads are not copied into audit entries. Host operations are admin-only;
team work entries follow the current live-sharing policy, including immediate
WebSocket removal when sharing is disabled. Old rooms begin with an empty log;
this is a bounded workshop activity record, not a compliance archive.

## Idempotent workshop expiry

The room expiry alarm emits one `ended` audit entry per scheduled end timestamp.
Open rooms become read-only; already read-only or private rooms keep their mode
and still receive that single end event. A durable completion marker is committed
atomically with the room and private audit state. Duplicate alarm delivery and
object restart do not increment the revision, rewrite state or reschedule an
already completed expiry. A host's later end timestamp can expire independently.
Early delivery schedules the existing future deadline; open-ended rooms do no work.

The first expiry performs three state writes (room, audit, completion marker).
Each duplicate performs three bounded point reads and no writes or downstream
calls. This prevents duplicate-write amplification, not all alarm-related billing.
Storage failure rolls back the whole expiry transaction and remains visible to
Cloudflare's bounded platform retry mechanism; the handler adds no retry chain.
`apps/colab/src/server/room-alarm.test.ts` covers 100 repeated wakes, restart,
all room modes, atomic failure recovery, schedule extension and early/no-end cases
using SQLite with a Worker context fixture. `node --test apps/colab/scripts/verify-expiry-runtime.mjs` also invokes the actual
expiry handler in a loopback Worker and SQLite Durable Object through Wrangler's
test harness, including an aborting SQL trigger to verify rollback. The test-only
configuration has a separate fixture identity and no production bindings, remote
services or secrets; the harness closes its temporary runtime after the tests.
Run it through `ttr resources run --` locally; CI runs it before the real app build.
Use a private writable `TMPDIR` if the host's shared temporary directory rejects
writes. This test invokes the handler through fixture RPC; hosted alarm scheduling,
platform retries and production cost caps remain separate acceptance evidence.

# Command Center Dashboard
Source: https://docs.tuturuuu.com/platform/features/command-center-dashboard

A GTD-aligned dashboard with Quick Capture and processing flows to reduce cognitive overload.

## TL;DR

Users are overwhelmed by fragmented information across tools and the mental load of remembering everything they need to do. The Command Center dashboard applies the Getting Things Done (GTD) methodology to centralize daily commitments, capture new ideas instantly, and guide users from brain-dump to organized plans.

## Command Center Dashboard

### Phase 1 – The Consolidated View

* **Feature**: Present all tasks, appointments, and key reminders for the day in a single, glanceable surface.
* **Outcome**: People no longer have to hop between apps to understand their priorities.
* **User Story**: “As a busy professional, I want to see all my tasks and appointments for the day in one place so I can quickly understand my priorities without switching between apps.”

### Phase 2 – Interactive Task Management

* **Feature**: Users interact with the dashboard task list directly—completing tasks, snoozing them, or dragging items to reorder.
* **Outcome**: Daily planning happens in-context without breaking focus.
* **User Story**: “As a project manager, I want to be able to quickly complete and reschedule tasks from my main dashboard so I can efficiently manage my daily workflow.”

## GTD "Quick Capture" Bucket

### Phase 1 – The Basic Bucket

* **Feature**: A lightweight text input that accepts any idea, task, or note without forcing structure upfront. Entries land in a dedicated "Bucket" list.
* **Outcome**: Users can park thoughts instantly, reducing cognitive distractions during deep work.
* **User Story**: “As a creative thinker, I want a place to quickly dump any idea that pops into my head so I don't lose it or get distracted from my current task.”

## From Capture to Clarity

### Actionability First

Every captured item is evaluated with the GTD question: **“Is this actionable?”**

* **If No**: Users choose to trash it, archive it for reference, or send it to a Someday/Maybe list to incubate.
* **If Yes**: Determine the single, physical, visible Next Action required.

### Phase 2 – The Triage View

* **Feature**: A processing workspace dedicated to the Bucket. For each entry, provide controls to assign it to a project, set a due date, add supporting notes, archive it, or drag it directly into the correct project list.
* **Outcome**: Users transform raw thoughts into organized tasks without leaving the triage experience.
* **User Story**: “As a detail-oriented planner, I want a simple way to sort my brain-dumped notes into actionable tasks and assign them to the correct projects so I can build a clear plan of action.”

### Workflow Summary

1. **Capture**: Add anything to the Quick Capture input without worrying about structure.
2. **Clarify**: Decide whether the item is actionable, then define the Next Action.
3. **Organize**: File actionable tasks into projects, schedule them, or archive references directly from the triage workspace.
4. **Reflect**: Use the Command Center dashboard to review what is queued for today and adjust priorities through interactions like snooze or drag-to-reorder.
5. **Engage**: Confidently execute the work knowing the system has captured and clarified every commitment.

By tying the dashboard, Quick Capture Bucket, and Processing Workflow together, the platform helps users offload mental clutter while staying responsive to the day's demands.

## Related Resources

* [Documentation Organization Guide](/overview/organization-guide) – Align workspace conventions and team practices with the Command Center workflows.

# Pricing, usage safeguards and legal review
Source: https://docs.tuturuuu.com/platform/features/commercial-controls

Review commercial changes, reconcile Polar prices, and distinguish verified accounting from launch blockers.

## Approved catalog and automatic display

Commercial direction approved on 13 September 2026: Plus **$9/month or $90/year**
and Pro **$19/month or $190/year per paid member**, with finite included credits
and separately purchased eligible top-ups. `PROPOSED_WORKSPACE_CATALOG` retains
its compatibility export name but now records the approved target version.

`GET /api/v1/public/pricing` projects only the four explicitly bound, active seat
products from the private billing catalog. Both landing implementations read it
through `packages/internal-api`; the response exposes amounts and USD currency,
not workspace/customer records or credentials. It has a 30-second shared cache;
visible clients refresh each minute. An invalid or unavailable catalog displays
no numeric price rather than inventing a fallback. Checkout remains authoritative
for currency, tax, seat count, discounts and the final payable amount.

The production product IDs in `polar-workspace-product-ids.json` were verified in
the authorized Tuturuuu dashboard and reconciled against the private catalog.
The organization ID is `f31a1452-88f6-4979-a03f-3d00424a3100`.
Legacy fixed-price products share the same display names. Existing subscriptions
retain their pricing; new paid self-service purchases use seat products for both
personal and team workspaces. Free-to-paid changes use checkout; paid-model
changes require an assisted migration. Never silently migrate subscribers.

The TanStack browser pricing query uses `VITE_PUBLIC_WEB_API_ORIGIN` at build time,
falling back to `https://tuturuuu.com`. Only use a public API origin for this value;
server-only internal origins and credentials must not be exposed to Vite clients.

Free-to-paid upgrades open Polar checkout; its minimum quantity covers purchased
capacity, members, pending workspace/email invitations, and target bounds. Polar
only supports Free subscriptions in checkout. Paid plan changes and explicit
seat adjustments use the subscription update API after in-app confirmation.
List-price estimates exclude existing discounts, tax and the final prorated
invoice. Seat-only updates do not replace the product, price or discount.

Invoice downloads come from Polar order history, not a subscription-price HTML
receipt. The legacy `/api/billing/[wsId]/invoice` link redirects to that history.
Checkout confirmation requires workspace billing permission, matching checkout
workspace metadata and a succeeded status; its displayed total includes provider
discounts and taxes. A checkout reference is not an invoice number.
Paid plan changes preserve the current quantity: adjust seats first when a target
minimum or reserved invitations need additional capacity. Paid billing-model
changes require assisted migration. Missing counts or bounds block updates.
Paid updates synchronize the database projection before reporting completion. If
projection fails after Polar succeeds, the UI reports pending synchronization and
disables resubmission. Pending billing dialogs offer a read-only status refresh. They unlock only
when the authoritative plan or seat count converges. A retry reconciles an already-applied
plan or quantity without invoicing the same change again. Pending state survives confirmation-dialog dismissal until
the billing page observes the target plan. Subscription projections insert without
overwriting existing rows, then update only for a newer provider timestamp or an
identical projection at the same timestamp. Equal-version conflicting payloads
are not ordered by arrival time. Older webhook deliveries return no subscription data, preventing stale
seat-assignment or cancellation side effects.
Polar's [subscription update endpoint](https://github.com/polarsource/polar/blob/9d20e549052a4dbd2d5b57fa6ea165200530b59f/server/polar/subscription/endpoints.py#L416)
locks the provider subscription row. Its [seat update service](https://github.com/polarsource/polar/blob/9d20e549052a4dbd2d5b57fa6ea165200530b59f/server/polar/subscription/service.py#L2166)
treats an unchanged absolute quantity as a no-op before invoice generation. Keep
sending absolute quantities; do not implement a client-side increment/retry loop.
This is provider-source evidence, not a live concurrent-charge test.
An invitation alone does not increase the purchased quantity. All quantity
reductions must still cover members and both pending invitation tables.
The legacy preview endpoint returns list-price estimates, not discount- or tax-aware
quotes. Do not use those estimates to authorize payment.

## Feature comparison maintenance

The shared comparison covers every app directory, with app/category filters,
accent-insensitive search, selectable tiers, differences-only mode, compact status
icons, keyboard/tap tooltips and visible numeric quotas. Expanded explanations
also support touch users. Internal infrastructure is opt-in in the comparison and is never a purchasable upgrade. Restricted previews remain distinct
from tier access. Standard platform gates share `feature-tier-policy.ts` with web.
Add capabilities, explanations in both locales, and source evidence when changing
an app's public scope. The inventory regression fails when an app is unrepresented.

Approved capacity changes are marked **awaiting rollout** until the database policy
and required meters are deployed. Current database storage defaults remain
**100 MiB / 20 GiB / 100 GiB per workspace** for Free / Plus / Pro, subject to
configured overrides. Do not describe those current defaults as per-seat storage.
The ten-workspace account ceiling remains independent of paid plans.

Production allocation rows verified on 13 September 2026 differ from source
seeds: Free has 10,000 credits per person/month, Plus has 40,000 per seat and Pro
120,000 per seat. The approved 1,000 / 10,000 / 30,000 budgets are reductions,
not retained production defaults. Preserve existing grants and purchased packs;
enroll new contracts through a versioned policy and apply notice/grandfathering
before reducing existing entitlements. Do not rewrite global allocation rows as
an unannounced shortcut.

## Reconcile Polar after commercial approval

Use the checked product mapping; never choose products by display name. Supply
existing authorized production credentials through environment variables, never
in source, command arguments, logs or pull request descriptions. Preview:

```sh theme={null}
bun scripts/sync-polar-catalog.ts --mapping packages/payment-core/src/polar-workspace-product-ids.json --organization ORGANIZATION_ID --environment production
```

Review organization, IDs, intervals, currency, seat tiers, current price IDs,
amounts and the printed plan hash. The script rejects mixed currencies, graduated
tiers, archived/ambiguous products and unexpected seat bounds. An approved
execution adds `--apply --approve-plan REVIEWED_SHA256`. A sandbox preview cannot
authorize production writes. Sandbox IDs require their own explicit mapping.

Application waits for existing webhook/cron reconciliation using read-only
Supabase credentials (`NEXT_PUBLIC_SUPABASE_URL`, `SUPABASE_SECRET_KEY`). Only
successful production verification updates `approved-workspace-prices.json`, which
is an operator snapshot; public cards read the reconciled catalog. No subscription,
customer, discount or direct database mutations are performed by this script.
Deploy compatible webhook handling before changing Polar prices.

Provider updates and webhook processing are **not one atomic transaction**.
A failure can leave some provider products updated. Inspect all four products and
re-preview before retrying; do not reuse a stale hash or assume a rollback. This
is an explicit operator repricing workflow, with automatic propagation into the
public price cards after successful reconciliation.

The existing 100% discounts are assigned to specific internal Tuturuuu workspaces.
Preserve those arrangements. Attribute consumption to sponsored internal cost;
discounts must not bypass resource budgets, permissions or abuse protections.

## Implemented safety controls

* AI rejects unavailable/malformed credit balances and unknown output pricing.
  Generation output is bounded by the credit-derived budget and a technical
  ceiling of 65,536 tokens. Larger credit balances do not bypass that ceiling.
  Existing credit purchases and expiry rules remain in force.
* Drive rejects unknown/invalid quota values and invalid byte arithmetic before
  issuing uploads. Infrastructure uses the same provider implementation. Deleting
  existing data to restore capacity is preferable to unexpected overage charges.
* Meet preview caps rooms at two hours from first admission, without extending the
  deadline on reconnect. Signed participant limits are bounded by server ceilings;
  the defaults remain eight publishers and 96 viewers. Admission and publishing
  check capacity; each publisher can register at most six media tracks. The server records participant-milliseconds through the deadline.
  Expiration disconnects clients and retains provider publication closures for retry.
  Failed cleanup uses exponential retry intervals from ten seconds to one hour;
  unconfirmed closures remain recorded instead of being silently discarded.
  AI and persisted recordings also consume their existing AI/storage allowances.
* Subscription lookup/count failures do not authorize new free subscriptions or
  additional seats. Trialing and past-due states follow the existing seat policy.

These safeguards are not a complete billing meter. Top-ups increase purchased
capacity only where supported; they never bypass abuse, concurrency or safety caps.

## Launch blockers for sustainable usage billing

Track these as required work, not as completed guarantees:

1. Atomic reservations for concurrent AI jobs, invites and uploads, with idempotent
   settlement/release. A read-before-write capacity check alone permits races.
2. Input tokens, cached tokens, retries, tools, embeddings, live audio, generated
   media and hosted execution must have trusted prices and workspace attribution.
   Output-token caps alone do not cover total invocation costs.
3. Durable monthly workspace aggregation across rooms and restarts. Meet's
   participant-time measure is server accounting; browser-reported bandwidth is
   partial diagnostic evidence and must not generate invoices.
4. Storage byte-hours, egress, operations, orphaned/signed uploads and all storage
   providers need reconciliation. A stated upload size is not evidence of the final
   object size; signed uploads require verification and reservation expiry.
5. Mail delivery, automation runs, public forms, hosted compute and other expensive
   product paths need the same reservation/settlement contracts before paid add-ons.
6. Reconcile provider invoices against the usage ledger; track unpriced usage
   separately, refunds/retries/credits explicitly, and contribution margin by tier.
   Prove limits under concurrent load before relying on them for profitability.

Do not claim “unlimited AI”, automatic profitability, complete cost coverage, or
charge unknown usage. Publish included amounts, unit definitions, reset/expiry,
notification thresholds and opt-in spending ceilings before selling new allowances.

## Legal documents

The shared legal registry serves English and Vietnamese terms, privacy, DPA, SLA,
subprocessor, acceptable-use and community documents. September 2026 changes are
marked review drafts; their draft publication date does not establish a new
contractual effective date. Acceptance/version history and existing agreements
must be preserved when a reviewed version takes effect.

Before publication, confirm the legal entity/address, territorial scope, actual
retention/deletion behavior, AI training commitments, processor regions and
subprocessor list. Contractual SLA remedies need an executed order and a supported
Polar adjustment path; do not promise a general SLA or direct refund workflow that
the merchant-of-record arrangement cannot fulfill. Validate consumer cancellation,
refund and renewal disclosures for the actual markets served. Legal drafts are not
an assertion that operational compliance has been audited.

Primary references: [Polar product pricing](https://polar.sh/docs/features/products),
[product updates](https://polar.sh/docs/api-reference/products/update),
[Buyer Terms](https://polar.sh/legal/checkout-buyer-terms),
[Merchant terms](https://polar.sh/legal/master-services-terms),
[Vietnam Law 91/2025/QH15](https://chinhphu.vn/?classid=1\&docid=214590\&orggroupid=1\&pageid=27160),
and [EU controller-processor clauses](https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?from=ES\&uri=CELEX%3A32021D0915).

## Catalog delivery checks

Production catalog publication requires an enabled Polar webhook at
`https://pay.tuturuuu.com/api/payment/webhooks`, the `raw` format and `product.updated` event,
and a signing secret matching the trusted deployment environment. The sync
command checks these before changing prices and sends an unsigned probe: the
handler must return its signature rejection, not browser-session authentication
or hosting protection. Credentials remain in the deployment secret store.

Pay allows only the exact webhook POST and registered payment-cron GET paths
to reach their own signature or bearer-secret validators without a browser
session. Other billing APIs retain session checks and all paths retain edge
protection. Webhook signature headers alone never establish trust at the edge;
requests consume the configured rate-limit budget before signature validation.
Do not replace webhook authentication with an anonymous bypass.

On 13 September 2026, the approved four-product catalog was reconciled at
Plus $9/month or $90/year and Pro $19/month or $190/year per purchased seat.
The existing webhook had been disabled, and the Pay session middleware also
rejected provider deliveries. The endpoint was re-enabled without rotating its
secret or changing its event subscriptions; the four catalog records were
reconciled through the existing product-sync helper. Existing subscription
financial terms and internal 100% discounts were preserved. Verify successful
provider deliveries after deploying the middleware repair.

# Tuturuuu CMS
Source: https://docs.tuturuuu.com/platform/features/external-project-studio

Site editing, publishing, preview, team access, and internal site-template operations for Tuturuuu CMS.

## TL;DR

Tuturuuu CMS now lives in the dedicated `apps/cms` satellite app.

New CMS-backed sites should use the [global CMS site v1 contract](/platform/features/cms-site-contract-v1). Add
site-specific structure through template and collection metadata instead of a
new adapter unless the integration has genuinely different authentication or
runtime behavior.

* `apps/cms` owns the CMS authoring UI, workspace picker, overview/content/preview/members routes, and the root `/{wsId}/projects` linking console (reached as `/internal/projects` for the root workspace).
* `apps/web` remains the only backend/API owner for CMS and external-project traffic.
* `apps/cms` rewrites `/api/*` to `apps/web`, so proxy behavior and bot protection stay centralized.

## Product Vocabulary

The visible CMS experience is a site/content product, not an implementation
console. Bound-workspace UI should say site, site template, connection, content,
section, URL path, custom details, media, publishing, preview, people,
invitations, and team access.

Avoid implementation terms in normal UI copy, including external project,
canonical, adapter, binding, slug, schema, metadata, profile data, payload, and
JSON. If operators need exact implementation values, show them only in collapsed
Developer details panels or internal root-console advanced controls. Keep code,
API routes, database objects, migration names, and integration docs on the
existing `external-project*` contracts.

## Route Model

The route tree below mirrors `apps/cms/src/app/[locale]/(dashboard)/[wsId]`.
Workspace navigation is defined in
`apps/cms/src/app/[locale]/(dashboard)/[wsId]/navigation.tsx`. Every route is
workspace-scoped under `/{wsId}`; the root workspace uses the `internal` slug
(it resolves to `ROOT_WORKSPACE_ID` via `normalizeWorkspaceId`).

### Root workspace

* `/{wsId}/projects` (reached as `/internal/projects`): internal site-template
  registry, workspace-indexed connection list, and connection audit history.
  The internal workspace is not a bindable content workspace, so its overview,
  content, and `/settings` routes redirect into `/{wsId}/projects`.

### Bound workspaces

* `/{wsId}`: overview / continue-editing home.
* `/{wsId}/content`: primary content operations surface (search, status
  filtering, publishing, reusable content).
* `/{wsId}/content/collections/{collectionId}`: collection (section) detail.
* `/{wsId}/content/entries/{entryId}`: entry (content) detail.
* `/{wsId}/pages`: page-builder surface for landing-style sections.
* `/{wsId}/media`: media library.
* `/{wsId}/products`: product catalog content.
* `/{wsId}/storefront`: storefront configuration.
* `/{wsId}/taxonomy`: taxonomy (terms, categories, tags).
* `/{wsId}/games`: game content surface, shown only when CMS Games is enabled
  for the workspace (`getCmsGamesEnabled`).
* `/{wsId}/preview`: site preview.
* `/{wsId}/members`: workspace member search, invite, removal, role assignment,
  and role/default-permission management.
* `/{wsId}/settings`: redirect-only route. It sends the internal workspace to
  `/{wsId}/projects` and every other workspace to `/{wsId}/members`; CMS has no
  standalone settings screen.

## Root Linking Console

* Treat `/{wsId}/projects` (the root workspace's `/internal/projects`) as a workspace-first control room.
* The main left panel is the searchable workspace list.
* Each row shows the current connection state, site type, site template, and most recent change signal.
* The selected workspace panel owns connect and disconnect actions.
* The site-template registry is secondary and stays on the same page for create/edit flows.
* Binding audits stay anchored to the selected workspace instead of living as a detached global feed.

## Workspace CMS

* Use `/{wsId}` as the concise starting point for continue-editing tasks, launch readiness, attention queues, recent activity, and connected-site context.
* Use `/{wsId}/content` for broader content operations: search, status filtering, publishing queues, collection health, and reusable content.
* Use `/{wsId}/pages` for focused landing-style page edits, page readiness, and preview-first section work.
* Use `/{wsId}/media`, `/{wsId}/products`, `/{wsId}/storefront`, and `/{wsId}/taxonomy` for the corresponding media, catalog, storefront, and taxonomy surfaces.
* Use `/{wsId}/games` for game content when CMS Games is enabled for the workspace.
* Use `/{wsId}/members` for routine collaborator management without leaving CMS.
* Keep collection configuration on `/{wsId}/content/collections/{collectionId}` and entry authoring on `/{wsId}/content/entries/{entryId}`.
* Use `/{wsId}/preview` as the delivered-content surface backed by the existing preview delivery route.
* CMS has no standalone settings screen; `/{wsId}/settings` is a redirect-only route to `/{wsId}/members` (or `/{wsId}/projects` on the internal workspace).

## Member Management In CMS

* Workspace member search, invite, remove, and role-assignment controls now have a dedicated `/{wsId}/members` sidebar route.
* The members surface also absorbs the essentials of the workspace roles page so CMS operators can manage named roles and default permissions without leaving CMS.
* This keeps standalone CMS usable without forcing operators back into the main platform app for routine collaborator changes.
* CMS members data must load through external-project-aware `apps/web` API routes and `@tuturuuu/internal-api` helpers. Reads should authorize by CMS workspace access so app-session users do not hit workspace settings-route 403s; writes still respect member and role management permissions.
* Use CMS copy in this area: team access, people, invites, access levels, member defaults, guest defaults, and Advanced access.

## Linked-Site Email Security

Outbound email requested through
`POST /api/v1/workspaces/{wsId}/external-projects/emails` is denied unless the
workspace binding has an explicit `settings.outboundEmail` grant. A valid app
secret and matching workspace binding are necessary but no longer sufficient.

Workspace security managers configure the grant on the main platform workspace
settings page:

* `enabled` must be `true`.
* `allowedRecipientDomains` must contain every exact recipient domain. A grant
  for `example.com` does not include `sub.example.com`, and wildcards are
  rejected.
* `useRootWorkspaceCredentials` allows the workspace to borrow the managed
  platform sender while retaining workspace rate limits, blacklist checks, and
  audit attribution. Only a root user with `manage_external_projects` may
  change this flag.

Missing, malformed, or disabled policy data always fails closed with HTTP 403.
An allowed request still passes the existing small-recipient cap and monthly
budget checks before entering the mail service.

Richfield public submissions use `TURNSTILE_SECRET_KEY_RICHFIELD` when present,
falling back to the platform-wide `TURNSTILE_SECRET_KEY` only for backwards
compatibility. This lets operators add or rotate Richfield's widget without
changing the Turnstile secret used by other platform surfaces.

Validate focused behavior from the repository root:

```bash theme={null}
cd apps/web
bun run test -- src/lib/external-projects/email-policy.test.ts \
  'src/app/api/v1/workspaces/[wsId]/external-projects/email-policy/route.test.ts' \
  'src/app/api/v1/workspaces/[wsId]/external-projects/emails/route.test.ts' \
  'src/app/api/v1/workspaces/[wsId]/external-projects/submissions/route.test.ts'
```

## Implementation Notes

* Keep CMS as a pure satellite frontend. Do not move API ownership into `apps/cms`.
* Continue adding or extending client helpers in `packages/internal-api` for CMS-facing API calls.
* Keep preview sourced from the existing delivery route instead of introducing a second preview payload contract.
* Backend/database naming remains `external-project*`; the product surface is what changed.
* Protect CMS-owned product copy with the CMS copy hygiene test, and add
  explicit admin/developer-detail exceptions only when a staff workflow truly
  needs an implementation value.
* Translation validation now treats `null` leaves as invalid so missing shared keys fail checks instead of silently passing parity.
* External app admin dashboards should call `POST /api/v1/workspaces/{wsId}/external-projects/setup` with their sync manifest before diff/apply. The route uses the existing app-coordination token and requires manage access. If the workspace is already bound to an active canonical project for the same adapter, setup preserves that binding while refreshing the project schema and field definitions; otherwise it creates the canonical `{adapter}-main` project if needed and binds the configured workspace without requiring production Supabase keys in the external app.
* External apps can mark manifest assets with `metadata.publicPath`, `metadata.localAssetPath`, or a relative `sourceUrl` such as `/media/hero.png`.
* For a registered branded app using the `custom` adapter, make its app ID equal to the linked canonical template key (for example, `rennu`). Token exchange and subsequent content requests match that exact key, not the shared `custom` adapter name. Built-in integrations still match their adapter. The registered app workspace allowlist, enabled binding, user membership, and scoped permissions are all still required. A mismatch produces `App is not linked to this workspace`; do not fix it by sharing another site's app credentials.
* Before diff/apply, run the public-folder linker so the manifest stores deterministic Drive paths under `external-projects/{adapter}/{collectionSlug}/{entrySlug}/{filename}`.
* Diff/apply routes are workspace-scoped. They may persist manifest schema into the bound workspace's collections and field definitions, but they must not update `canonical_external_projects` or other root/canonical registry state.
* Before apply, upload those files through the external-project asset app-server upload route. Abort the apply if a local public asset is missing so CMS never receives storage paths for objects that were not uploaded.
* Asset `storagePath`/`storage_path` values must stay under `external-projects/`. Do not point CMS assets at Drive, finance, or other workspace storage namespaces; delivery and admin cleanup only operate on assets that satisfy the CMS namespace invariant.

## Storage analytics cache

The authenticated external-project storage analytics endpoint reads Supabase project
statistics from a private Postgres snapshot keyed by workspace and adapter. It
calculates file totals and highlights from `storage.objects` metadata, with a
1,000-object cap and an explicit `truncated` flag. Archived versions and folder
placeholders do not contribute to file totals.

Snapshots expire after five minutes. Storage inserts, updates, deletes, and moves
invalidate workspace snapshots in the same transaction, including direct uploads.
A shared workspace lock serializes refresh and invalidation so a concurrent file
change cannot leave a newly stored stale snapshot. Workspace quota is read live.
The cache is available only through a service-role RPC, after endpoint access and
rate-limit checks.

R2 uses the bounded provider scan. A missing RPC during an additive migration
rollout also uses that scan; other database failures remain visible. Production
activation requires the normal gated Supabase migration workflow. No cache
backfill is required.

The first-class Next handler preserves bodyless `HEAD` responses and request-time
authorization. Its future Rust port mirrors the Supabase cache response with live
quota and falls through to Next for fully configured R2 providers and unported
methods. Rust is not deployed; satellite-session and rate-limit parity remain
tracked prerequisites for a future cutover.

### Database contract gate

`external-project-storage-analytics-contract.yaml` checks the exact PR head with
all tracked Supabase schema inputs. Its verifier requires the reviewed migration
body under the root-reserved forward filename, runs all 15 strict SQL assertions,
generates actual public/private/storage types, and closes its owned disposable
stack. A skipped wrapper or local source test does not establish this DB gate.
After the 15-assertion sequential fixture, the gate uses distinct bounded psql
sessions for first-cache-row refresh versus insert/update. It observes the
contender waiting on the actual workspace advisory lock (namespace 73007), then
requires invalidation and exact recalculation after both sessions complete.
Authored Node wiring tests do not establish that race; its actual hosted receipt
is required before merge. Linux's shared rootful Docker daemon is not a
qualified contained executor; do not run this verifier there to bypass that gate.

## Team Guidance

* Link into the CMS-native route map directly.
* Prefer the root `/internal/projects` console (the root workspace's `/{wsId}/projects`) for site-template and workspace-link operations.
* Keep bound-workspace collaborator management on the dedicated `/{wsId}/members` route, and do not surface the root projects console inside non-root workspace sidebars.
* Update both `apps/cms/messages/en.json` and `apps/cms/messages/vi.json`, then run `bun i18n:sort` whenever CMS copy changes.

# Forms: question types, embedding, SEO, and collaboration
Source: https://docs.tuturuuu.com/platform/features/forms-embedding-and-seo

The question types a form can ask, how to embed one in a third-party page, how to control its search and social metadata, and how the studio shares editing presence.

## TL;DR

`apps/forms` (`forms.tuturuuu.com`, port `7828`) owns the whole forms product.
Three surfaces are worth knowing about before you touch it:

* **Question types** — twenty block types, of which fifteen collect an answer.
* **Embedding** — six modes driven by a dependency-free SDK at `/embed.js`,
  rendered by the `/embed/<shareCode>` route.
* **SEO** — per-form overrides stored in `private.forms.seo`, applied to
  `/f/<shareCode>` metadata.
* **Realtime collaboration** — presence and broadcast on a private
  `form-studio-<formId>` channel, never `postgres_changes`.

## Question types

Registered in `FORM_QUESTION_TYPE_VALUES` (`schema.ts`) and grouped in
`block-utils.ts`. Adding a type means adding it to the enum, to the right
grouping, to the icon map, and to the studio's block catalog — the type system
enforces the icon map, but not the other three.

### Text inputs

`short_text`, `email`, `phone`, `number` and `url` render one line and differ
only in what the browser is told. That mapping is most of the mobile
experience: `inputMode` picks the on-screen keyboard and `autoComplete` decides
whether the field can be filled from saved contact details.

> [!NOTE]
>
> `number` uses `inputMode="decimal"`, not `"numeric"`. `numeric` hides the
> decimal point on iOS, which silently makes non-integer answers untypeable.

These types validate themselves. `getIntrinsicValidationMode()` maps the type
to a rule that applies whether or not the author opened the validation panel; an
author-chosen `validationMode` layers on top rather than replacing it, so a
`number` with a regex still has to be a number.

A `url` must be `http(s)` with a dotted host. Bare `new URL()` accepts
`javascript:` and `mailto:`, which are not links a respondent can follow.

`number` also takes a `numberStep`, measured **from the minimum** rather than
from zero, so a "1, 3, 5…" question works. The multiple-of check compares
against both ends of the step because floating-point modulo is inexact —
`0.3 % 0.1` is 0.0999…, and a naive check rejects a value the author considers
exact.

### NPS

Fixed at 0-10 by the metric's definition, so unlike `linear_scale` the bounds
are **not** author-editable — only the anchor labels are. A scale labelled NPS
that runs 1-5 is not comparable to one that does not.

Scores band the standard way: 0-6 detractor, 7-8 passive, 9-10 promoter.
Analytics reports the real score — promoters minus detractors as a percentage
of all responses, with passives counting toward the denominator only — under
`analytics.nps`, separate from `meanScore` because it is not an average.

The runtime renders a native `<fieldset>` of radios rather than styled buttons
with ARIA roles, so arrow-key navigation, the group label and the disabled
cascade come from the platform.

### Ranking

Reorderable options whose answer is the resulting order, stored as an ordered
array of option values.

> [!WARNING]
>
> The answer is written only once the respondent moves something. Seeding it
> with the author's order would mark an untouched ranking as answered — a
> required question would pass with nobody having ranked anything, and every
> indifferent response would silently agree with the author.

Reordering uses dnd-kit (already the studio's idiom) rather than native HTML5
drag, which does not fire on touch at all. Move up/down buttons sit alongside
the drag handle so the question works by keyboard and screen reader, and only
the handle is draggable so taps on those buttons are not swallowed.

Stored answers survive the author editing the options later: unknown values are
dropped and new options appended, so an old answer still renders instead of
collapsing to an empty list.

Analytics ranks by mean position, best first, and sorts an option nobody ranked
to the bottom — reporting its average as `0` would float it to the top as if it
were everyone's first choice. Formatted answers are numbered
(`1. Price, 2. Speed`) because the order is the entire answer, and a plain
comma-separated list renders "B, A" and "A, B" identically in an export.

## Embedding

The studio's embed panel generates the snippet; this is what it emits and why.

### Script SDK (preferred)

```html theme={null}
<script src="https://forms.tuturuuu.com/embed.js" async></script>
<div data-tuturuuu-form="<shareCode>" data-mode="inline"></div>
```

The SDK scans for `data-tuturuuu-form` elements, mounts an iframe pointed at
`/embed/<shareCode>`, and marks the container `data-tuturuuu-form-mounted` so a
re-run cannot double-mount it.

An auto-sizing embed never renders shorter than `data-min-height`. The default
of 320px is the smallest height at which a single question stays answerable
without scrolling inside the frame — the previous floor was 120px, which
predates one-question-at-a-time forms and left the host page showing a sliver.

`inline` and `fullpage` render in place. `popup`, `slider`, `popover`, and
`sidetab` are overlay modes: they render a launcher and only mount the form when
it opens.

### Iframe fallback

Hosts that forbid third-party scripts (locked-down CMSes, most email-adjacent
tools) can use a plain iframe. It loses auto-resize, so give it a height:

```html theme={null}
<iframe src="https://forms.tuturuuu.com/embed/<shareCode>"
  title="Form" width="100%" height="640" style="border:0"></iframe>
```

### The framing exception

Framing is denied platform-wide by `createTuturuuuNextConfig`
(`frame-ancestors 'none'` plus `X-Frame-Options: DENY`). `X-Frame-Options` has no
"allow from any origin" value, so a later permissive header cannot override the
deny — the header has to be **absent** instead.

`createTuturuuuNextConfig` therefore accepts `framablePathPatterns`, and builds
the anti-framing `source` as a negative lookahead over every framable path:

```ts theme={null}
// apps/forms/next.config.ts
createTuturuuuNextConfig({
  framablePathPatterns: ['embed/[^/]+'],
});
```

Opt in per route, never per app. Everything not listed stays denied.

`apps/forms/src/proxy.ts` must also treat `/embed/` as public, or the embed
redirects to login *inside the host's iframe*.

### Host-page messages

The embed posts `window.postMessage` events the SDK listens for. The contract
lives in `apps/forms/src/features/forms/embed/protocol.ts` and is shared by the
React page and `public/embed.js` so the two cannot drift.

Every message carries `source: 'tuturuuu-forms'`; verify it before acting, since
a host page may run other iframes.

## Per-form SEO

`private.forms.seo` is a `jsonb` column (constrained to an object) holding
optional overrides. Every key is optional, and an empty string or `false` means
"fall back to the value derived from the form's content":

* `title`, `description` — override the derived page and social title/description
* `image` — `{ storagePath, url, alt }` for the social card
* `keywords` — `text[]`, replaces the derived list
* `canonicalUrl` — points crawlers at a different canonical
* `noIndex` — true emits `noindex,nofollow`; false permits indexing of an
  accessible anonymous snapshot. Public form metadata explicitly overrides the
  private root layout. Protected, unavailable, and closed forms remain noindex.
  The landing page is indexable; studio, responses, and embed wrappers are not.
  Regression: `shared-form-data.test.ts`, `shared-form-loader.test.ts`, and the
  cross-app policy in `packages/utils/src/seo.test.ts`.

It is a single `jsonb` column, matching the existing `settings` and `theme`
columns on the same table, so adding a field later needs no migration.

The studio's SEO panel renders a live search-result preview showing where Google
truncates each field.

## Studio collaboration

The studio joins a **private** Cloudflare channel per form, topic
`form-studio-<formId>`, carrying presence (who is here, which block they are on)
and broadcasts (someone saved).

It uses broadcast and presence rather than `postgres_changes` because the forms
tables live in the Postgres `private` schema with service-role-only access. They
are deliberately off the public Data API, so a browser client cannot subscribe to
row changes on them at all.

Access is authorized by the service-only `private.cloudflare_channel_role` RPC,
which delegates form topics to `private.can_join_form_realtime_topic(topic, user_id)`.
That helper resolves the form from the topic suffix and defers to
`public.has_workspace_permission(ws_id, user_id, 'manage_forms')`. Presence is
gated on the same permission the studio itself requires: analysts who can only
read responses have no reason to appear in an editing session, and would leak
their identity to editors if they did.

> [!WARNING]
>
> `apps/forms` is a registered satellite app, so the `internal-app-auth` guard
> forbids `supabase.auth.*` inside it. Resolve identity server-side with
> `getSatelliteAppSessionUser('forms')` and pass the id down as a prop, and take
> the realtime client from `@tuturuuu/internal-api/realtime`.

Short-lived tickets recheck this permission at refresh and on reconnect.

When a remote save arrives, the studio refetches immediately **only if your copy
is clean**. If you have unsaved edits it raises a reload prompt instead —
refetching blindly would discard your work.

## Gotchas worth carrying elsewhere

> [!WARNING]
>
> `packages/satellite` is **not** in Tailwind's content scan set. Classes used only
> from that package emit no CSS at all, so the markup renders unstyled and
> invisible rather than failing loudly. Shared presentational code that needs
> Tailwind belongs in `packages/ui` — that is why the marketing kit lives at
> `@tuturuuu/ui/marketing`.

Calling `connection()` at the root of a marketing page forces the entire page
dynamic. Scope it to the session-dependent subtree instead, so the static shell
still prerenders.

# Forms studio: build layouts
Source: https://docs.tuturuuu.com/platform/features/forms-studio-layouts

The stacked and three-pane build layouts in the form studio, why three-pane is opt-in, and what it does not cover yet.

## TL;DR

The studio's build tab has two layouts. **Stacked** is the default.
**Three-pane** is opt-in and wide-screen only. Both can now do the same things;
three-pane stays opt-in because nobody has verified it in a browser.

## Stacked

A block rail plus one column of accordion editors: click a block's header to
expand it, edit in place, drag to reorder. This is the layout everything else
in the studio is built around, and it is the only one at viewports below
`1280px`.

## Three-pane

Four columns at `xl` and above: the block rail, an outline, the canvas, and
properties.

Selection lives in one place. The outline and the canvas both write to the
studio's existing `activeSectionId` / `activeQuestionIdsBySection` state, and
the properties pane reads it — so a block is never selected in two places at
once, and the realtime "which block are they on" presence already tracks it.

Two implementation choices worth keeping:

* The canvas renders the **real** `QuestionBlock` from the runtime, not a
  studio mock, so it cannot drift from the shipped product the way a parallel
  preview implementation would. Every block is disabled — it is a canvas for
  selecting, not answering.
* The properties pane renders `QuestionEditor` in its `panel` variant rather
  than a second editor. A field added to the accordion shows up here with no
  extra work; the alternative was two editors that drift.

## Why it is still opt-in

Three-pane now covers what stacked covers:

* **Reordering** — drag blocks within a section from the outline, or use the
  move controls in the properties header. A `DndContext` per section means a
  drag cannot cross a section boundary; moving a block between sections would
  rewrite two arrays and re-key the branching rules that reference it, so that
  stays stacked-only until it is designed properly.
* **Duplicating and deleting a block** — in the properties pane header. They
  are there rather than on each outline row because the outline is 240px wide
  and a control per row would crowd out the labels. Duplicating selects the
  copy, so the author edits what they just made rather than the original.
* **Section fields** — selecting a section shows its title, description and
  cover in the properties pane, rendered by the same `SectionFields` component
  the stacked accordion uses.
* **Form details and logic rules** — the same elements the stacked layout
  builds, hoisted and rendered above and below the canvas.

> [!WARNING]
>
> It stays opt-in anyway, for one reason: **nobody has verified it in a
> browser.** It type-checks, passes `bun check` and builds clean, and the
> selection and reorder logic are unit-tested — but a layout bug would not have
> been caught by any of that. The toggle is what contains that risk.

A reordering drop that would lose or duplicate a question is refused outright
rather than written: silently dropping a block is far worse than ignoring the
drag that caused it.

The preference is stored per browser under
`tuturuuu:form-studio:build-layout`, and a viewport below `1280px` always falls
back to stacked — three panes in 600px is three unusable columns.

## Changing the default

Flipping the default is a one-line change in `useStudioBuildLayout`. The
remaining blocker is a person looking at it, not missing functionality.

Until that happens, treat three-pane as a preview and keep new studio features
working in stacked first.

# Hidden workspaces
Source: https://docs.tuturuuu.com/platform/features/hidden-workspaces

Private workspace choices, recovery and membership separation.

Hidden is a preference of the signed-in user. It never archives, leaves or deletes
an organization, changes another member's choices, revokes access or silences
notifications. Only its owner can read or change the preference.

## Workspace sheet and recovery

The native mobile picker fills the screen, with the Tuturuuu logo, Workspaces
heading, floating Search/Create controls, close and Back support. Browser workspace
selectors, including apps/web and shared satellite selectors, use a standard anchored dropdown at every browser viewport,
including narrow screens. Search stays visible, the list scrolls within the
dropdown, and Escape/outside click closes it. Search and
sorting retain workspace IDs and the objects from the rendered results. Duplicate
names cannot substitute a different workspace when a list refreshes.

The Flutter picker reuses the normal Apps header's brand size, title typography,
and shared app-bar metrics, and the normal shell's floating action pills. Personal,
system, and team rows use the existing theme's semantic accents. The header stays
fixed above one full-height scrollable body containing errors and results; a failed
preference save keeps retained results usable, while an unresolved preference load
still conceals choices.
Retry revalidates preferences; hiding or restoring a row explicitly retries that
change. The default and Hidden editors keep their existing selection semantics.
Regression coverage: `apps/mobile/test/features/workspace/widgets/workspace_picker_sheet_test.dart`
checks narrow screens, large text, keyboard insets, long labels, error-state scroll
clearance, shared header geometry, and normal dock action styling.

Hidden workspaces are absent from current/default choices and workspace filters.
Settings → Hidden workspaces opens a focused restore editor; restoring changes
only the private preference, without selecting a scope or changing the default.
A picker with all workspaces Hidden also offers recovery. Empty preferences,
unknown preferences, no memberships and all-Hidden memberships are distinct.

Mobile switches an actively hidden selection to a visible default, personal or
deterministic first visible workspace. Hiding the last visible workspace clears
the active UI selection and opens the selection/recovery surface. The stored
default remains unchanged and is skipped during normal mobile selection while
Hidden. A browser keeps its existing authorized workspace URL when a choice is
hidden; it offers no Hidden choices in the dropdown. Existing authorized deep links
and notification navigation may enter a Hidden workspace without restoring it.
These rules change discovery, not permission checks.

The following local widget capture uses a synthetic guest fixture, bundled font
and the shared app theme. It contains no real account or workspace data.

![Branded Hidden workspaces restore editor for a synthetic guest fixture](https://mintcdn.com/tuturuuu/SEinzPodFlbNa3FO/images/hidden-workspaces-restore-synthetic.png?fit=max\&auto=format\&n=SEinzPodFlbNa3FO\&q=85\&s=57948a0218280fe23fd6f79ce9803f57)

Global launchers and Settings selectors receive the verified actor at the app root.
Nested route providers for the same actor share that lifetime, so navigation
reuses private list caches. Logout or account replacement purges the owner caches
and rejects delayed responses. Without verified identity, discovery stays empty.
This includes the External SDK example until it supplies an authorized per-user
session; workspace API keys do not identify a preference owner.

## Persistence and actor boundaries

The existing `public.user_workspace_configs` table stores
`(user_id, ws_id, id = 'HIDDEN_WORKSPACE', value = 'true')`. An absent row means
visible. Board-share-only guests have no membership row, so their preferences use
existing owner-only `public.user_configs` rows:
`(user_id, id = 'HIDDEN_WORKSPACE:<workspace UUID>', value = 'true')`.
The owner GET returns the union, with valid UUID IDs only. This uses one key per
workspace and avoids concurrent updates overwriting a whole list. Restore clears both stores across either membership transition. A former member
who still has a validated board share cannot delete the old member row through
membership RLS, so the server performs only that exact owner/workspace/key cleanup
after current access validation. No membership is created or RLS policy changed. There is no new schema or grant. `user_private_details` must not be used:
its shared-member read policy would expose a preference intended to be private.

`GET /api/v1/users/me/hidden-workspaces?expectedActorId=<actor>` returns only the
owner's Hidden IDs with `Cache-Control: private, no-store`. `PUT` accepts
`workspaceId`, `hidden` and `expectedActorId`. The shared first-party app-session audience explicitly includes this endpoint, including Git. Owner GET additionally accepts the existing `cli:access` scope for CLI/MCP discovery; PUT does not accept CLI sessions. Unknown visibility fails discovery closed, while explicit MCP reads still use OAuth grants and canonical resource authorization.
The server derives the owner from
the authenticated session, compares the expected actor to reject a delayed
account-switch request, and verifies canonical membership of either MEMBER or GUEST before writing.
For choices discovered through direct task-board shares without membership, it
instead validates a live view/edit share for the actor's canonical user ID or
owner email, on an undeleted board in the requested workspace. Share inspection
is server-only and read-only; preference writes remain owner-bound. Unknown or
failed access discovery denies the mutation. No membership is added. The existing
owner/membership RLS already permits both; no permission or policy is expanded. App
sessions also stamp and filter by the server actor when using their scoped
administrative client. The response is never joined into workspace/member APIs,
profile activity, audit summaries or notifications.

Web query keys and mobile encrypted cache keys include the authenticated actor.
Optimistic changes suppress duplicate writes, invalidate/revalidate private
queries, ignore stale refreshes and roll back failed server mutations. A confirmed
server update is not undone because a device cache write fails. Cold offline
state cannot claim an empty preference list; cached preferences remain usable
while refresh errors offer retry. Logout/account replacement invalidates mounted
work and prevents late responses from updating another account's state.
Membership refreshes also retain cache-invalidation fences: a response that
arrives after its cache scope is cleared cannot confirm an empty membership or
cancel reminders. The actor is checked before a delayed response is cached.
`reminder_membership_provenance_test.dart` covers both invalidation and account
replacement against the actual repository and encrypted cache.

## Canonical membership and consumers

Mobile `WorkspaceState.workspaces` remains canonical for reminders, access,
notifications, deep links, task-board navigation, quotas and workspace data.
`visibleWorkspaces` and `hiddenWorkspaces` are separate UI projections. A list
with every membership Hidden never sets `emptyMembershipConfirmed`.

Web `listWorkspaces`, workspace summary APIs and permission discovery remain
canonical. Actor-scoped UI hooks project visible choices for the shared picker,
satellite command search, Track move/copy/missed-entry selectors, Tasks source/
planner/create-board/personal-placement choices, Meet assistant/follow-up choices,
Infrastructure AI workspace choices, Mira workspace context, calendar-sync
workspace filters and root link-shortener filters. An optional Infrastructure
Internal/root choice must also respect Hidden/unknown state. A
current-workspace fallback does not reinsert a Hidden choice into those lists.
Inventory continues using the selected authorized workspace and its currency.

The dropdown interaction regression in
`packages/ui/src/components/ui/custom/__tests__/workspace-picker-content.test.tsx`
covers its bounded container, search, Hidden recovery, selection and Escape.
The shared browser selector defaults to this presentation; apps/web also opts
into it explicitly. The normal workspace-switching picker uses fullscreen only on native
mobile. Settings retains its dedicated Hidden-workspace restore dialog.

## Verification and integration hold

Focused synthetic tests cover search/sort/duplicate names/refreshed objects,
current/default selection, owner cache isolation, optimistic rollback, stale
reads, logout, deep links and narrow large-text/keyboard/Back recovery. No real
workspace hide/create/delete operation is used for testing.

The rollback-only native SQL fixture lives at
`apps/database/verification/hidden-workspaces-privacy.sql`. Run it only in a
resource-admitted disposable project with current migrations. Its 15 assertions
check existing privileges/RLS, independent users, workspace-admin owner denial,
restore and unchanged canonical membership. It adds no grants or schema objects.
Synthetic actors must have `auth.users` rows and authenticated JWT claims: the
existing restrictive account MFA policy correctly denies public-only profiles.

The admitted disposable run passed all 15 assertions against 1,331 current
migrations. Rollback verified no synthetic users/workspaces remained; cleanup
verified no project containers or volumes remained. The fixture SHA-256 was
`43c6e05754b59a9c1cf052e2cf4cc09be5f54690e1dfc27b0140d146c9362356`.

MCP discovery and consent choices exclude Hidden/unknown visibility. Explicit
reads/navigation continue to require user-selected OAuth workspace grants,
canonical membership and operation permissions. Hidden is not access revocation.

The mobile Settings integration depends on compact Settings PR #5692, reconciled
at `dbf74ec222`. Its account-scoped restore row is in the root group immediately
after Workspace, independent of current selection, membership role or admin
permissions. Actual Shell/root cases verify guest, no-active and all-Hidden
recovery, one Settings navigation item, search/Back without writes, explicit
restore without selecting/current-default changes, and 320px/2× text scrolling.
The all-Hidden selection surface already provides recovery without an active scope.
Settings root/Workspace routes also remain reachable without an active scope.
Satellite general Settings recovery does not wait for workspace/admin permissions. Exact-commit parent CI remains required before merge.

The guest mutation and audience follow-up have synthetic API/session proofs,
including actual production CLI tokens and signed satellite bearer/rewritten-cookie
sessions. The original 15-assertion member/admin DB proof remains unchanged.
One additional parent-admitted disposable run applied the same 1,331 migrations
and passed all 26 assertions in `hidden-workspaces-board-guests.sql`: the first
17 prove board-share guest owner privacy and admin denial; nine more cover both
restore transitions, genuine actor/MFA, preserved memberships/board shares, exact
server-owner cleanup, and no re-hiding after membership returns. Controlled fixture
membership changes are separate from the Hidden operations. Rollback and owned
container/volume cleanup passed. No grants, policies or live data were changed.

The applied fixture SHA-256 is
`a36184027422006227bc4f4a797371c98586816255971e9f1a7adb38993ee510`;
the migration aggregate is
`cbdcebb2ccd342f23719b3ebcb879a8d2ad12c20d860cf62ce5e23d0f3ef051d`.
In this migrated disposable database, neither preference table belongs to a
publication and both use default replica identity. Captured noninternal triggers
only update timestamps or enforce strict text limits. Six existing public audit,
activity and notification table counts stayed unchanged during the guest
preference operations. This is local migrated-schema evidence, not a claim about
production catalog drift or every external logging system.

## Discovery follow-up

Chat's paginated context rail caches canonical pages under the authenticated actor
and the visibility revision represented by the Hidden-ID signature
and applies Hidden only to its displayed workspace/personal choices. Delayed pages
cannot publish after an account switch. Sparse discovery advances up to eight
canonical 48-row pages per request toward twelve visible team choices, with
actor/cancellation checks between pages. An accessible Load more action keeps
remaining pages reachable when the rail has no overflow. TaskFilter queries source boards only for
visible retained source workspace IDs and displays only their selected choices;
it does not rewrite saved filters or change task aggregation when visibility changes.
Both caches are removed when the actor provider unmounts. Git's Hidden audience
is explicitly allowed without adding Git to unrelated current-user APIs.

## Destination and verification follow-ups

Infrastructure forms submit only a currently visible selected workspace; a stale
Hidden default is cleared until a visible workspace is selected. Planner creation,
save, destination addition and item creation wait for verified visible choices.
An intended Hidden destination cannot silently turn a requested task into a draft.
Normal meeting chat defers workspace discovery until a Mira mention.
Meet chat and live assistant actions require a current visible destination and
recheck actor lifetime after awaited preparation. Infrastructure submission stays
disabled until a visible workspace is selected. Existing running sessions retain their
canonical authorization.

Mira preserves its existing Personal fallback choice when the actor has no personal
workspace; its existing resolver selects an authorized canonical fallback. A real
personal workspace excluded by Hidden preferences is a different state and is
omitted from the picker. No personal workspace is created by this UI rule.

## SQL assertion harness and pending execution

The privacy and board-guest fixtures now enable `ON_ERROR_STOP` and raise SQL
exceptions for false or null assertions. The owner restore assertion checks the
actual absence of the current actor's preference. Synthetic actors, authorization
contexts and final rollback remain unchanged; no helper grants are added.

`apps/database/scripts/verify-hidden-workspaces.js` is a pure, injected-executor
harness. It accepts legacy stdout assertions and psql stderr NOTICE assertions,
requires successful exit and every unique expected assertion (15 or 26), and
checks guest event counts and private storage publication metadata. Negative
controls must fail for the intended false, null or skipped owner restore assertion;
a startup or permission error cannot satisfy a negative control. Each execution
uses a fresh session, followed by a separate owner rollback check, including
failed executions. Its static tests simulate transcripts; they do not execute SQL.
Current corrected fixtures and negative controls remain **runtime unexecuted**.
Earlier fixture runtime evidence does not verify these revised bytes.

The proposed next runtime lane is one cached PostgreSQL 17 container, with an
explicit parent admission and unique owned identity. Pin the locally resolved image
ID; use `--pull=never`, `--network=none`, no host ports, CPU 1, memory 2 GiB and
128 PIDs. Use a bounded disposable data mount, a 3 GiB incremental disk limit,
15 minutes execution plus 5 minutes cleanup, and reject admission below 10 GiB
free disk or elevated memory pressure; stop below 6 GiB free. No image pulls,
seeds, external network, ordinary/shared database access or global Docker pruning.
Cleanup removes only its recorded container and disposable mount and verifies
both are gone, even after failure.

This database-only proposal requires an offline pristine schema/bootstrap from
pinned tracked migrations and the cached image. Required auth functions, roles,
RLS, event tables and publication metadata must be installed unchanged. If the
bootstrap cannot replay without missing Supabase dependencies, stop and report
that dependency; do not invent replacement policies or broaden grants. Only then
can the two fixtures, three negative controls and five rollback checks provide
15/26 assertion evidence. This does not claim full Supabase service, API, realtime
or production-schema parity, and does not authorize starting a database.

The board-guest ASSERT21 data-changing CTE is scoped inside its consuming
assertion query. Structural regression coverage rejects a CTE left before a DO
block; this coverage is not a PostgreSQL grammar check. Revised SQL still needs
fresh admitted runtime validation.

## Mobile preference service recovery

Mobile workspace selection treats Hidden preferences as an optional UI service.
If their read fails (including a server rollback without the endpoint), canonical
membership remains selectable in the selection page and picker sheet, with a
localized warning and explicit Retry. Confirmed account-scoped cached Hidden IDs
remain excluded. Without a confirmed list, membership may be selected explicitly;
this does not save an empty preference list, restore a workspace, or change
membership authorization. Pending discovery still waits for its result. Hide and Restore actions stay disabled until the current account has a confirmed
preference list; explicit membership selection remains available. A failed
preference read never becomes a successful preference refresh. Regression coverage:
`workspace_select_page_test.dart`, `workspace_picker_sheet_test.dart`, and
`workspace_visibility_test.dart`.

# Mobile season prices
Source: https://docs.tuturuuu.com/platform/features/inventory-season-pricing-mobile

Authoritative scheduled sale prices and durable mobile checkout recovery.

Mobile checkout consumes authoritative season prices for **new scheduled sales**.
Operators explicitly select a sales period and wallet. Legacy/unassigned checkout
continues using its existing creation flow. This slice does not author prices,
manage periods, edit scheduled history, or claim complete web parity.

## Current-price contract

Checkout caches period metadata and server quotes for offline drafts. Online
checkout refreshes
`GET /api/v1/workspaces/{wsId}/inventory/sales-periods/{periodId}/prices`.
The response contains price rows and a server `as_of` instant. Resolution uses the
selected period, product, unit, warehouse and explicit wallet currency. Effective
intervals are half-open `[valid_from, valid_to)`; duplicate applicable rows,
malformed responses and missing prices block the sale. Product allow/block lists
apply separately. Period dates are inclusive in the period's IANA timezone,
checked against server time, with final eligibility checked atomically by the
server. No device-timezone date or catalog fallback decides scheduled pricing.

The compact checkout shows season, currency, UTC quote time and period timezone.
Online quotes expire after 15 seconds of local receipt age and are refreshed while the
checkout is open. Automatic failures retry at most once every ten seconds;
manual refresh remains immediate. Failed refreshes clear visible quotes. Missing lines display an
unavailable amount rather than a zero-priced sale or a mixed-currency total.

## Offline draft contract

A downloaded catalog, period, wallet, category, and season quote allow a new sale
to be drafted offline. Checkout explicitly labels saved prices and the pending
server check. It stores immutable price IDs and a stable request UUID, displays
queued status instead of a confirmed amount, and synchronizes on reconnect. The
server remains authoritative for eligibility, current prices, currency, and stock;
a stale or conflicting draft stays visible for review. Cached time permits draft
validation but never proves a completed sale. Missing cached prices still block a
scheduled draft. Existing uncertain online operations continue through the
journal recovery view and cannot become new outbox drafts.

Regression: `season_pricing_controller_test.dart` covers cached-price drafting
without an HTTP send or confirmed journal entry; `finance_inventory_offline_test.dart`
covers persisted product/sale data and offline CRUD. See
[mobile offline preparation](/platform/features/mobile-workspace-tools) for cache
capacity, downloads, server protection, and provider exceptions.

## Atomic creation and retry

Online scheduled sales call the existing authenticated
`POST /api/v1/workspaces/{wsId}/finance/invoices` directly, with
`price_mode: custom`, `inventory_period_id`, `inventory_request_id` and immutable
`price_id` on each line. Confirmed online operations use the recovery journal;
offline drafts retain the same request UUID and price IDs in the encrypted outbox.
Neither flow creates an invoice followed by a separate period assignment. The backend derives
configured workspace currency, checks wallet currency and precision, validates
current prices/stock, and persists historical snapshots plus period assignment in
one transaction. The UI currency is a quote-selection constraint, not authority
to change workspace currency. Zero prices are legitimate only when explicitly
returned by the server.

Before an online scheduled POST, checkout writes and verifies an encrypted operation
journal using the existing secure-storage adapter. It retains the exact request
UUID/body, original currency, quote provenance and frozen product display labels
in an actor/workspace scope. Cache eviction, logout, scope switches and controller
recreation do not erase unresolved operations. Read, corruption, version and write
failures block creation; they never become an empty cart. One app-wide scope lock
prevents simultaneous checkouts preparing distinct operations. Separate business
drafts on another device are outside this local journal contract.

An unresolved operation opens a dedicated recovery view. Metadata Retry and cart
editing are unavailable there; current catalog, wallet, category and period
metadata cannot strand recovery or route it into legacy creation. Operators can
leave and resume in the owning account/workspace. Unresolved journal operations
do not automatically replay. This recovery rule is separate from an offline draft
that has never been submitted.

An actor/workspace switch during a POST or receipt lookup clears the mounted
checkout immediately and queues the current scope's catalog reload until the
active save finishes. Every switch advances a scope revision, including A→B→A;
a late response cannot acknowledge, navigate or display an error on the reset
form merely because its actor/workspace pair matches again. The original scoped
journal retains its UUID and immutable body. Returning to its owning scope opens
recovery (or the recorded confirmed result); switching away loads the new scope.

An explicit Check sale result action calls the authenticated uncached
`GET /api/v1/workspaces/{wsId}/inventory/sale-requests/{requestId}`. The server
verifies current canonical membership and create-sales action permission, derives
the actor from authentication and selects only that actor's workspace/request
receipt. It returns only state, request ID and committed invoice ID. The existing
private receipt/tombstone stays authoritative after invoice deletion. Lost
permissions and unavailable rollout schema are errors, never an empty receipt.

`not_observed` is not proof an earlier transaction cannot still commit. This
explicit action may resend only the original UUID and immutable payload. Every
HTTP rejection retains uncertainty, including 400/401/403/409/422/503. Changed
DEFAULT\_CURRENCY can reject resubmission while the original is in flight; future
receipt lookup resolves a committed outcome independently of current pricing
configuration. No replacement request/key or revised cart is allowed. If the
original never commits and continues to be rejected, the operation stays blocked
for manual reconciliation. This slice does not add a terminal server rejection or
cancellation protocol or permit unsafe journal reset.

A valid invoice response or matching receipt makes checkout terminal. Cache
invalidation and remembered-category preferences are best-effort maintenance and
cannot turn confirmed creation into a resubmittable cart. Confirmation is stored
before its journal can be acknowledged. A confirmation-write failure retains the
prepared record for next-entry receipt reconciliation while keeping known success
terminal in the current view. Acknowledgement removes only a matching confirmed
record. Embedded checkout exits through Android back, shell dock back, or
ordinary navigation acknowledge a known completed receipt when the page leaves.
Pending requests and confirmations not durably written remain recoverable; an
exit never silently discards them. This is covered by the mounted
`inventory_checkout_recovery_exit_test.dart` navigation matrix.
Acknowledgement does not reopen the terminal controller/cart: another sale
requires a new checkout instance. Corrupt or unknown-version journals intentionally
fail closed for manual reconciliation; deletion without a verified receipt could
produce a duplicate invoice. Expired quotes stay non-actionable and hidden while
refreshing, and stale-state notifications occur only on freshness transitions.
Sale-edit scope changes show an explicit instruction to close and reopen in the
owning workspace. Scheduled history stays read only and ordinary historical line prices
remain their recorded prices.

## Checkout defaults and current-cart reconciliation

Mobile reads the same workspace checkout defaults as Inventory web through the
existing product-form-options API, including the revenue wallet, finance category,
and default sales period. The configured period is selected only when active and
current in its timezone. If it is unavailable, exactly one current scheduled
period is selected; ambiguous periods require operator choice. Cached defaults
are included in offline preparation. Explicit wallet/category/period choices,
including an unassigned period, survive metadata refreshes within the same actor
and workspace. Historical edits keep their recorded period and prices.

All selected periods apply their allowlist/blocklist product rules to browsing
and submission, including legacy periods. **Reconcile cart** explicitly refreshes
current metadata and season quotes, removes cart rows whose product/stock option
is unavailable or no longer allowed, and removes scheduled rows lacking a valid
quote. The result shows removed rows or a refreshed total for operator review
before submission. This action is limited to the current editable cart: it does
not reassign historical sales, change frozen unresolved journal bodies, bypass
server checks, or claim an offline draft is confirmed. Account/workspace changes
discard late results. A later server rule change can still reject submission.

Regression coverage: `checkout_defaults_test.dart` covers timezone-aware defaults
and product scope parity; `legacy_period_sale_test.dart` covers atomic submission
and rule rejection; `season_pricing_checkout_test.dart` covers automatic selection
and explicit removal of disallowed cart rows.

## Permissions and rollout limits

Canonical actor/workspace membership remains server-owned. Hidden-module
preferences do not grant or revoke authorization. Period discovery currently
requires view-sales permission while quote GET also permits create-sales. A
create-only actor may therefore be unable to discover a period; mobile fails
closed rather than broadening access. Missing pricing schema/RPC (503), denial,
invalid timezone, missing metadata or wallet-price currency mismatch block
scheduled submission. Source presence on main does not prove production migration
availability. New legacy-period sales now send `inventory_period_id` and a stable
`inventory_request_id` in the invoice request, using the live server's atomic
period invoice operation. Period eligibility and product rules are checked before
committing the invoice; mobile never creates an invoice and then assigns its
period as a separate creation step. Unassigned legacy sales retain their existing
creation behavior.

Revenue/profit remain withheld: the analytics aggregate still needs verified
currency, linked checkout/invoice deduplication, refund/cancellation and reporting
timezone semantics. This change does not modify any financial aggregation.

## Regression evidence

`apps/mobile/test/features/inventory/season_pricing/` covers interval boundaries,
currency separation, malformed quotes, timezone eligibility, product scope,
expiry/offline/denial, actor/workspace races, exact-payload idempotent retry, direct
atomic repository transport and mounted checkout/historical guards. The existing
partial-option checkout regression remains in the focused suite.

Recovery regressions cover persistent-store round trips, write-before-send,
restart/scope isolation, late completion, concurrent checkouts, rejection identity
retention, denied lookup and confirmed receipt handling. Mounted tests exercise
preference/cache failures after success, metadata Retry removal while uncertain,
and recovery after metadata denial. Twelve mounted scope-switch cases cover
actor and workspace A→B/A→B→A during delayed POST success, timeout and receipt
responses; they assert current-scope readiness and preserved original identity.
Route tests verify permissions, canonical actor
filters, minimal output and unavailable versus not-observed semantics.

Native keychain/keystore durability and exact-head mobile/API CI remain release
gates. Mocked storage does not prove native persistence or deployed endpoint
availability. This read-only satellite API uses the existing receipt schema;
no database migration or application is part of the recovery follow-up.

Ordinary catalog rows and legacy history keep their VND denomination even when
a selected wallet has another currency; no FX conversion is implied. Scheduled
rows retain their scheduled/recorded currency. Recovered confirmed sales remember
the income category with the same best-effort policy as initial submissions.

# Mobile Inventory stock health
Source: https://docs.tuturuuu.com/platform/features/inventory-stock-health

Current stock counts, reporting scope, and analytics limitations on mobile.

## Current stock snapshot

The native Inventory Overview shows confirmed server counts from the authorized
`inventory/analytics/summary` API. This is a current stock snapshot of active
(nonarchived) workspace products, independent of the API's sales date range.
It includes their stock rows in archived warehouses because the aggregate does
not filter warehouses. Every successful snapshot shows its server generation
time explicitly in UTC; the device fetch time never substitutes for it.

Product setup counts are separate from stock-row counts. A stock row identifies
a product, unit and warehouse; units and quantities are not summed. Independent
bars compare low, out-of-stock and unlimited row counts. Low and out-of-stock
may overlap; unlimited quantity is null and belongs to neither finite check.
These bars are not percentages or disjoint segments.

Missing or invalid fields show unavailable values and a partial-snapshot warning;
confirmed zero remains zero. Complete means all selected stock-summary fields
and the server timestamp are available, not full Inventory feature parity.
The aggregate includes all active products rather than just the loaded catalog
page. No warehouse, season or date filter is implied by this panel.

## Access and refresh

The server resolves canonical membership and analytics permissions through the
same Bearer-authenticated API as web. Hidden discovery preferences are not
membership or authorization. The panel reads the server on entry and awaited
pull-to-refresh, including short content that fits in the viewport. It retains an
encrypted, account/workspace-scoped last-confirmed aggregate snapshot for offline
reads and never overlays pending local stock edits. The saved server timestamp
continues to identify its age. Actor/workspace changes clear the panel and revalidate.
A denied read removes its cached resource. Transport failures retain the last
confirmed snapshot when one is available; a cold failure shows unavailable state.
See [offline preparation](/platform/features/mobile-workspace-tools) for download
and synchronization limits.

## Financial and pricing boundaries

Overview's legacy income/expense/revenue tiles and owner/category revenue bars
are withheld until the API guarantees currency isolation, linked-checkout
handling, gross/net/refund definitions and reporting timezone. Overview recent-sale amounts are also withheld because that payload lacks
currency; missing historical dates are not replaced with the current time. Sale details and recorded prices are not
modified. Costing-scenario estimates are not realized profit.

Season-price integration is a separate slice. Scheduled checkout must consume
server `as_of`, exact product/unit/warehouse/currency price keys, half-open
validity intervals and immutable price IDs, then use atomic period invoice
creation. A current catalog price or post-create period assignment cannot replace
this contract. Missing production pricing schema/RPC must fail closed (503).
This panel neither authors prices nor recomputes historical sales.

## Stock quantity display

Inventory product rows and Overview low-stock rows preserve the parsed quantity's
shortest round-trippable decimal representation. There is no one-decimal rounding:
`0.04` remains `0.04`, whole quantities omit `.0`, and null remains Unlimited.
Very small quantities may use scientific notation. This display rule does not
change stored quantities, unit comparisons, price formatting, or financial totals.
Precision is bounded by the existing double model; source precision already lost
during parsing is not recovered. Overview quantities wrap within narrow layouts.
Regressions live in `inventory_ui_test.dart` and the mounted
`inventory_fractional_stock_test.dart` 320px/2x text case.

## Native Inventory navigation and analytics

Native Overview defaults to the current confirmed stock snapshot. Its scope and
possible overlap are available through the info control; there are no duplicate
Sell or Create product actions. Products and Sales own their primary floating
create action. While data refreshes, that action uses only a previously verified
permission hint for the same signed-in actor and workspace. Unknown permissions
never grant an action; fresh permission denial revokes it, and API authorization
continues to govern writes and replay. Account/workspace switches clear visible
records, grants and pending-response ownership before loading the new scope.

The receipt activity chart defaults to seven days, with a thirty-day option.
It groups the bounded recent Overview receipts by their recorded creation date
in the device's local timezone, deduplicating IDs. It explicitly shows sample
coverage and missing dates; absent days are unknown rather than fabricated zeros.
This filter does not change the current stock snapshot. Financial totals in Sales
are labeled as loaded receipts, separated by explicit receipt currency, and
exclude receipts with unknown currency and locally pending edits. Quantities
remain beside their original unit and warehouse; unlike units are never summed.

Manage is a catalog hub with dedicated Owners, Categories, Manufacturers, Units,
Warehouses, Finance categories and Sales periods screens. Finance categories
remain a reference list with the existing Finance management contract; no new
Inventory mutation capability is implied. Sales period editing preserves the
existing API and immutable historical receipts. Creating a period requires the
same create-sales permission as POST; editing or archiving requires the
update-sales permission used by PATCH. Each action remains independently gated
when using verified offline hints, and fresh denials revoke it. Audits has its own navigation
entry and uses the existing audit source. Search in Sales and Audits filters
available records and states that limited coverage; Products retains its existing
server/local pagination search contract. Catalog pages use the shell navbar
search and floating create action. Product editor and Checkout use one content
scroll with a stable form action area and show prerequisite/read failures with
retry. The native form navbar owns checkout search; category filters wrap instead
of clipping at large text sizes.

A provider read failure retains the last authorized scoped snapshot and displays
limited-data feedback. Queued product deletion removes the catalog row
optimistically while retaining a visible pending deletion entry linked to the
existing offline retry/manual-conflict controls. Deletion confirmation and server
history/destructive policies are unchanged.

Regression evidence: `inventory_product_action_stability_test.dart`,
`inventory_analytics_redesign_test.dart`, `workspace_permissions_offline_test.dart`,
`inventory_access_cubit_test.dart`, the mounted stock-health/compact/fractional
stock tests, and existing editor/checkout/season/offline replay tests. Source and
widget checks do not establish physical-device, airplane-mode, or release proof;
exact-commit native CI builds and device verification are separate delivery gates.

# Tulletin
Source: https://docs.tuturuuu.com/platform/features/lettin

Workspace-based worldbuilding, creator invitations, and publishing.

Tulletin (formerly (Tu)lettin) is the creator worldbuilding app at `lettin.tuturuuu.com`. Creators
organize worlds, characters, locations, lore, stories, and linked wiki pages in
a private notebook, then explicitly publish revisions for readers.

## Creative studio and dedicated spaces

Tulletin is the public creative identity of the existing Lettin app. Its domain,
app-session audience (`lettin`), and storage remain unchanged. The homepage serves
artists, storytellers, creators, and worldbuilders with a quiet illustrative
atlas; the illustration is not presented as an actual creator project.

The public `/spaces` directory presents the three creative spaces before login;
only this exact path is public. Workspace space pages remain authenticated, covered
by `apps/lettin/src/proxy.test.ts`.

The workspace studio is the complete project shelf with title/description/tag
search and all/private-draft/published filters. Dedicated routes are
`/{wsId}/spaces/art`, `/{wsId}/spaces/story`, and `/{wsId}/spaces/world`.
Art projects use the editable `art` tag; storytelling projects use `story`;
worldbuilding uses `world`. Tags are matched without case sensitivity. A project
can appear in multiple spaces. Existing projects without `art` or `story` default
to the worldbuilding space, so historical work stays discoverable. The main shelf
always includes all accessible projects. Removing a space tag changes its placement,
not its content, ownership, or publication status.

Starting a project offers blank, art, story, and world notebooks. Space pages
preselect their matching starter. Starters save normal editable rich-text prompts
and a matching tag through the existing create-world API. Nothing is published
until the creator explicitly publishes. Spaces add no new access privileges.
Public space cards preserve the chosen space through central
login, default workspace selection, and pending workspace invitation acceptance. Unknown space names return a 404.
Regression coverage: `apps/lettin/src/components/creative-spaces.test.ts` verifies
legacy placement, multiple-space tags, unknown route rejection, and valid starter
content in both languages. `creator-experience.test.tsx` covers shelf search/filter recovery and
workspace-aware tool links, invitation destinations, and nested navigation.

`/{wsId}/toolkit` gives workspace-aware links to Tasks, Drive, Calendar, Chat,
Mind, Finance, Meet, and platform AI chat, plus the complete app directory.
Tools open in their existing apps and enforce their own permissions, authentication,
and any billing rules. These are navigation integrations; project content is not
copied into those services or automatically synchronized. The app directory
is a global destination. Public toolkit links open each app's entry point.

The homepage uses a small wordmark, restrained serif headings, a brief introduction,
and a single set of space cards. Slogans, workflow explanations, duplicate calls to
action, and the full app launcher are omitted there. The full launcher is on the
workspace toolkit page; dedicated space pages omit the space directory.

Motion uses short entrance sequences and subtle state transitions. Essential content is visible without scroll-animation
support; reduced-motion preferences disable animation and decorative hover movement.

## Access and roles

Lettin uses the platform's central login and satellite app-session exchange,
refresh, and logout. Accounts and workspace membership are not duplicated.

Lettin `/login` is resolved by the request proxy before page streaming begins.
Anonymous, explicit `refresh=1`, denied, or unverified sessions receive HTTP 307
with a `Location` header to central login, preserving the normalized destination
through `/verify-token`. A successfully verified Lettin session plus a shared
browser-session marker redirects to that destination and propagates refreshed
cookies. A standalone app claim is insufficient. Localized login URLs first use
the existing canonical locale redirect. The page is an inert fallback: it must
not perform a session lookup inside streamed Suspense, which would turn HTTP
redirects into client-only meta redirects. `login-redirect.test.ts` checks delayed
verification, HTTP status/header/body, destination safety, refresh, and MFA denial;
`proxy.test.ts` verifies dispatch before locale rendering.

Private world access requires all three conditions:

1. An enabled Lettin creator account, or root-workspace administrator status.
2. Current `MEMBER` membership in the world's workspace. Guests are excluded.
3. The existing `manage_documents` workspace permission, plus ownership or a
   collaborator role on that world.

The world owner manages collaborators. Editors save drafts; publishers can also
publish and unpublish. Workspace administrators do not automatically gain access
to somebody else's private world. Changing workspace roles or removing membership
is effective on the next request.

A platform administrator is a root-workspace member with the existing `admin`
permission. They can invite creators and individually enable or revoke the
`can_invite` grant. Delegated inviters can create and revoke their own invitations,
but cannot delegate invitation privileges. Invite acceptance never grants workspace
membership, workspace permissions, or invitation privileges.

Use Creator invitations & access in the studio to create an email-bound invitation.
Share the resulting link with its recipient. Lettin does not send invitation emails.
The recipient must sign in with that verified email and accept within seven days.
World collaborators must already be approved creators and eligible workspace members;
manage workspace membership and roles through the existing platform settings.

## Drafts and publishing

The private notebook Markdown source field has a stable, localized accessible
name independent of its formatting hint or validation message. This applies to
Markdown editing on the world notebook and entry editor; read-only documents
retain their existing editing restriction. The mounted `rich-editor.test.tsx`
regression checks the exact field label with the real editor, and
`lettin-wiki.noauth.spec.ts` checks browser save and reload behavior. Its first
scenario logs fixed phase names and completion/failure markers without fixture
IDs, credentials, or response bodies. The project creation response has a
30-second deadline within the unchanged 180-second scenario limit. Use the last
phase marker to locate interrupted browser runs; missing trace artifacts or a
runner shutdown do not establish that the product scenario passed.
`lettin-e2e-phase.test.ts` covers the bounded response wait, exact response
matching, failure propagation, and safe phase diagnostics.

Editor initialization and read-only permission transitions are presentation
changes, not draft edits. The shared editor must not emit a content-update event
for an unchanged document when synchronizing editable state. Saved notebooks
therefore remain navigable after reload; genuine typing, checkbox edits, and
applying Markdown still mark the draft dirty and keep the navigation guard. This
applies to the shared rich-text editor and both private notebook surfaces.
`rich-editor.test.tsx` mounts saved content with the real editor, and
`editor-readonly-transition.test.tsx` checks permission changes without false
edits while retaining real checkbox mutations. Browser save/reload assertions
remain required in exact-commit CI.

Saving never changes the public revision. Publish a world's notebook to make its
public page visible, and publish entries separately. Unpublishing a world hides all
its entries from public reads. Publishing it again exposes entries that remain
published, so unpublish those entries too if they should remain hidden.

Rich text accepts a bounded node vocabulary with no raw HTML, scripts, arbitrary
embeds, or private resource mentions. Public reads project only published revisions
and filter relationships to unpublished entries. An optimistic version check rejects
stale writes with HTTP 409, preserving the editor's local text for manual merging.

Artwork uploads use the private Cloudflare R2 bucket `tuturuuu-lettin-media`.
Stored references point to a stable application URL. The Worker streams artwork
only to world collaborators or when a published page in its world references it.
Unpublishing revokes future public reads; previously downloaded copies cannot be
revoked. PNG, JPEG, WebP, and GIF uploads are limited to 10 MB. External HTTPS
artwork links are also supported and remain subject to their host's availability.

## Cloudflare architecture

Lettin deploys as `tuturuuu-lettin` on Cloudflare Workers at
`lettin.tuturuuu.com`. OpenNext builds the Next.js frontend and its API handlers
into the Worker. There is no Vercel deployment or central-web content API.

Shared Tuturuuu login, verified email, workspace membership, and workspace
permissions remain authoritative in the platform. Lettin does not duplicate
accounts or store worldbuilding content in Supabase. Identity checks use the
satellite session user and existing workspace permission helpers on every request.

All content APIs live in `apps/lettin/src/app/api/v1`. Shared client access uses
`@tuturuuu/internal-api/lettin`. Local API handlers take precedence over central
platform API fallbacks. The public health route
`/api/v1/lettin/health` checks D1 schema and R2 access and reports the Worker version.

D1 schema migrations live in `apps/lettin/migrations`. Writes use parameterized
statements with revision and role predicates; invitation acceptance uses an atomic
D1 batch. Request-scoped D1 sessions start on the primary so access decisions see
current creator grants. API and artwork responses use `private, no-store`.

## Development and rollout

The app uses Portless name `lettin.tuturuuu` and fallback port 7833.
Run these commands from `apps/lettin` through the shared resource queue:

```sh theme={null}
bun run cf:typegen
ttr resources run -- bun run db:migrate:local
ttr resources run -- bun run test

```

Local development initializes Cloudflare bindings through OpenNext. For runtime
verification, use the collaborative preview or a previously CI-built Worker.
Do not run app or package builds on the agent machine. The exact-commit Lettin
Cloudflare CI workflow provides the real build and type-check evidence.
The private wiki shelf and world routes provide localized route-level loading
boundaries. Their request-time pages stream into these placeholders during client
navigation; the locale layout's Suspense boundary sits above the shared workspace
layout and cannot cover those transitions. The mounted `rich-editor.test.tsx`
exercises the actual shared TipTap editor and Markdown parser. The authenticated
wiki E2E retains creation, save, and reload assertions, with named, bounded editor
actions so a pending control is reported before the overall test deadline.
Before streaming private workspace pages, the proxy checks the same shared
workspace invitation-status contract used by the invitation screen, forwarding
only the refreshed request authentication. Missing or unjoined workspaces receive
an HTTP 307 to the dashboard; anonymous or MFA-required requests return through
login. Pending invitations keep their existing invitation screen, including when
the requested child world ID is invalid. Joined workspace world and wiki-section
routes reject non-GUID IDs, and wiki routes reject unknown sections, with a
localized, private, non-cacheable HTTP 404 before any loading fallback renders.
The wiki-section, moderation, and creator-profile pages each have their own
localized loading boundary around request-time work. This preserves initial wiki
entry selection and actor-scoped profile editing; public worlds, creator pages,
and dashboard retain their existing behavior. Deferred request-boundary coverage
is in `remaining-request-boundaries.test.tsx`. The render-time permission checks remain authoritative;
this preflight never grants access. Regression coverage is in
`workspace-route-status.test.ts` and `proxy.test.ts`; mocked membership results
and real `NextResponse` checks do not replace the exact-commit CI app build.

The storage tests use disposable Miniflare D1 and R2 resources and cover creator
access, invitation delegation, conflicting writes, published snapshots, private
relationships, and artwork publication/revocation.

Set production shared-identity configuration as Worker secrets using the existing
production values: `NEXT_PUBLIC_SUPABASE_URL`,
`NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`, and `SUPABASE_SECRET_KEY`. If the platform
uses a dedicated app-coordination signing secret, configure that same
`TUTURUUU_APP_COORDINATION_SECRET` or `APP_COORDINATION_TOKEN_SECRET` too.
The public Supabase URL and publishable key are also build inputs. Never copy a
devbox's local Supabase settings to the production Worker.

Register Lettin's shared app domain and session audience in the central platform
before verifying cross-app login. Central identity registration and the Lettin
Worker are separate deployment surfaces; a public homepage is not proof that
login works.

The `Lettin Cloudflare` workflow validates pull requests and builds on `main` and
`production`. Only its production-branch job uploads secrets, applies Lettin's D1
migrations, and deploys the built artifact. It maps GitHub's
`PRODUCTION_SUPABASE_URL`, `PRODUCTION_SUPABASE_PUBLISHABLE_KEY`, and
`PRODUCTION_SUPABASE_SECRET_KEY` into the Worker secret names above. Optional
coordination signing secrets retain their names. Use `LETTIN_CLOUDFLARE_API_TOKEN`
for a dedicated deployment credential; the existing account credential is the
bootstrap fallback. Secrets are passed over stdin without temporary files.
Production pushes apply D1 migrations only when the promoted range changes
`apps/lettin/migrations`; those schema releases require D1 Edit permission on the
deployment token. Manual production dispatches apply migrations defensively.
The workflow checks the deployed version tag against the exact source SHA.

For an authorized manual rollout after local validation, apply only Lettin's D1
migration and deploy its Worker:

```sh theme={null}
bun run db:migrate:remote
bun run deploy:cloudflare
```

`wrangler.jsonc` pins the Tuturuuu account, the dedicated resources, and the custom
domain. Verify the active Worker version and `/api/v1/lettin/health`, then verify
central login, workspace switching, invite acceptance, collaborator roles,
membership revocation, conflicting edits, artwork privacy, and anonymous published
world browsing. Require exact-commit CI test, lint, type-check, and real app build gates before
release; record unrelated repository blockers separately from Lettin's focused
validation. Do not run `bun validate` locally because its task graph can build.

Artwork cleanup runs before uploads and claims at most ten unused objects in that world per request after a seven-day grace period. Draft and published references are retained. Claimed objects cannot be newly referenced; failed R2 deletions remain queued for the next upload. A world with no further uploads retains its unused artwork.

Public catalogues use 24-card pages with server-side search and creator filters; full entry documents are loaded only when opening one world.

## Shared creator identity

Tulletin uses Tuturuuu's canonical `users.display_name`, `avatar_url`, `bio`,
`handle`, and additive `banner_url` fields. A username is globally reserved in
`handles`; renaming retains earlier reservations. Existing legacy usernames
remain readable. Public creator surfaces require published notebooks and display
only avatar, banner, display name, and biography by default. Creator names link to
the platform
`/u/[username]` profile when a username exists.

`update_public_user_profile` is a service-role-only transaction. The API must
resolve the authenticated actor before calling it. A conflicting username or
invalid image rejects the complete patch and reserves no new username. Image
URLs use HTTPS; avatar, banner, bio, and username can be cleared explicitly.
The database contract fixture `public-creator-identity.sql` covers actor grants,
claims, conflicts, rollback, rename, clearing, and private-field rejection.

The `Creator identity database contract` PR workflow applies the complete schema
in a disposable Supabase project, runs strict pgTAP assertions, and generates
actual database types. Its exact-head artifact is the type-generation source;
manual production schema pushes are prohibited. This contract does not authorize
production migration or deployment.

The first-class `/api/v1/users/me/profile` endpoint owns identity updates. It
accepts the authenticated actor, preserves same-origin checks for cookie writes,
and returns 409 for a reserved username. Avatar, banner, and username writes are
validated before database access. Until the additive migration arrives, reads
fall back to existing identity fields and biography and avatar
changes continue working; display-name, banner, and username changes return 503 rather than
silently losing them. Rust migration handlers mirror this behavior; the Next.js
API remains the live source of truth. Regression evidence includes the profile
route tests and backend profile validation and outbound-transport tests.

New usernames require 5–32 lowercase letters, digits, or underscores and start
with a letter or digit. Common platform/service names and major brands are
reserved; separator variants and obvious official/support/admin/team/numeric
aliases are reserved for both service names and brands. Ordinary names containing a brand syllable, such as
`pineapple`, remain valid. The canonical pool lives in
`packages/utils/src/username-policy.json` and is checked against the database
migration in regression tests. Existing usernames remain readable and unchanged
legacy values do not consume a change.

Every actual username change, including clearing it, starts a rolling 14-day
cooldown. Display names can change twice in a rolling 7-day window. No-op saves
consume neither allowance. Row triggers enforce both rules on direct writes as
well as the shared RPC; conflicting, invalid, or rate-limited saves roll back the
whole patch. The private per-user change history is pruned to 28 days when a
change succeeds. Public identity read surfaces never select this private history.

### Personal avatar ownership

The central personal-avatar removal endpoint applies the same rule to web cookies,
mobile sessions and satellite app-session bearers: clear only the authenticated
actor's profile field, then best-effort delete only an exact managed public avatar
URL under that actor's prefix with the upload ticket name
`<actor UUID>/<ticket UUID>.webp`. The configured public Storage origin and
`avatars` bucket must match. Traversal, encoded paths, repeated slashes, query
strings and fragments never authorize deletion. External and older noncanonical
avatars are cleared without deleting an object.

Profile PATCH accepts external HTTPS avatar URLs, including OAuth provider
pictures. URLs on our configured public or internal Supabase origin must use the
canonical personal-avatar convention; another user's avatar, another bucket or
malformed managed URLs are rejected. Contact, workspace and public profile-link
avatars have separate owners and are intentionally excluded from personal removal.
Existing images remain readable; older personal filenames are not cleaned up by
this endpoint. No client changes are required for the public API path or response.

Regression coverage: [personal avatar route tests](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/me/avatar/route.test.ts)
exercise two actors through the production session wrapper and signed satellite
tokens, with cookie identity and database/Storage fixtures. Hosted Storage
acceptance remains a separate gate.

### Workspace avatar ownership

Web and registered satellite workspace-avatar PATCH and DELETE retain
`manage_workspace_settings` authorization on the resolved workspace. PATCH
accepts only the upload ticket's exact
`workspaces/<workspace UUID>/avatar-<lowercase ticket UUID>.webp` path. It does not
trim, decode or normalize the submitted path. DELETE first clears that workspace's
field, then best-effort removes only a stored URL whose unparsed string matches
either exact configured Supabase origin (`SUPABASE_SERVER_URL` or
`NEXT_PUBLIC_SUPABASE_URL`), `avatars` bucket, workspace prefix and
exact ticket filename. The DELETE-time ownership check remains authoritative even
for values written directly to the workspace row. Traversal, encodings, extra
segments, backslashes, repeated slashes, query strings, fragments, noncanonical
host/port spellings, other buckets and other owners never authorize removal.
Older filenames and external URLs are cleared without deleting objects.

The central web PATCH and DELETE routes accept existing web/mobile Supabase
sessions; they do not opt into satellite app-session bearer authentication.
Satellites keep their dedicated authenticated workspace handlers. Their central
upload-ticket delegation retains its existing app-session support; a future
workspace-settings-specific scope should replace its profile-write scope.

Web field reads and updates retain the session's RLS client. Only after permission,
field-clear and exact stored-URL ownership checks succeed does web cleanup create
an admin client to remove that one object. Satellite cleanup uses its existing
server client after the same checks. No `avatars` DELETE policy was found in
migrations, so ordinary cookie RLS cleanup would leave objects behind; this
bounded privileged call avoids that policy-denied cleanup without broadening
Storage policy. Failed Storage operations still leave orphans because cleanup is
best effort. Existing images, tickets, public API paths and response shapes are
unchanged.

Regression coverage: [web workspace avatar route tests](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/avatar/route.test.ts)
and [satellite workspace avatar ownership tests](https://github.com/tutur3u/platform/blob/main/packages/satellite/src/routes/workspace-avatar-ownership.test.ts)
exercise two actors and workspaces, direct stored-URL injection, rejected PATCH
paths, permission denial and legitimate set/remove. These use database and
Storage fixtures; hosted Storage policy acceptance is separate.

Avatar uploads are automatically optimized to at most **1 MB (1,000,000 bytes)**;
banners to **2 MB (2,000,000 bytes)**. Source PNG, JPEG, WebP and GIF files may be
up to 2 MiB for avatars or 5 MiB for banners. This rule covers canonical personal
identity uploads from Tulletin, platform web, Nova and mobile; existing objects
remain readable. Browser clients resize and encode WebP before transport. Mobile
uses its existing in-house image library off the UI isolate and stores optimized,
metadata-free PNG in offline queues; older queued avatar payloads are optimized
again before delivery. Contact avatars and public profile-link avatars also use the browser optimizer and
single-use central upload capability. Active public links receive a stable,
link-scoped budget identity and can only write inside their verified link path.
Workspace avatar clients use the same client optimizer and shared server path,
with workspace permission checks before issuance. Their tickets share the actor
budget with personal images. Satellite workspace endpoints delegate issuance to
the central API rather than granting raw Storage writes.
Mobile Profile settings supports both avatar and banner selection. Banner removal
and replacement use the same actor-scoped, retry-safe lifecycle as web profiles.

Tulletin's avatar and banner upload inputs use concise translated labels, with
size and optimization hints attached through `aria-describedby`. A browser test
waiting for an upload ticket can time out before any request when an exact-label
selector cannot find the input; inspect the input's accessible name first.
`profile-media-field.test.tsx` checks exact labels and separate descriptions in
English and Vietnamese, distinct input identities, and the upload callback.

The server independently decodes, applies EXIF orientation, strips metadata,
resizes without enlarging (avatars within 1024 x 1024; banners within 2560 x 1440),
and encodes WebP. Quality then dimensions are reduced as needed; output is checked
before persistence. GIF and animated WebP use their first frame. Transparency is
preserved. Unsupported/corrupt images and sources above 20 million pixels are
rejected. Public buckets accept only WebP, with the final byte caps enforced by
Storage; originals are never persisted. Identity artwork retains public semantics.
Personal banner tickets bind the optimized WebP upload to an immutable actor and
operation path. The optimized upload handler checks the issued lifecycle receipt
before decoding; replay cannot write a different operation or bypass its budget.
Native finalize and web profile saves retain banner retirement and concurrency
checks. Before an outstanding ticket expires, a transparent one-pixel WebP replaces
retired content while retaining its occupied slot; deletion follows expiry.
Regression evidence: banner upload route tests, `profile-media-upload-put.test.ts`,
`profile-banner-lifecycle.test.ts`, and native banner delivery/actor-race tests.
Restrictive Storage policies require server-issued, budgeted upload tickets;
ordinary authenticated bucket uploads cannot bypass quotas. These changes build
on the shared Postgres counter foundation in storage anti-abuse PR #5736 and
require the complete dependent release. The identity contract additionally tests
reserved names, rolling-window boundaries, no-ops, direct-write enforcement,
atomic rollback, byte/MIME ceilings, and raw upload denial.

The shared contract applies to current-user media ticket issuers, including the
avatar endpoint in this foundation and the dependent banner endpoint. Existing
workspace avatar tickets retain workspace-settings authorization and additionally
reserve the resolved account media ceilings and the shared global ceilings before
signing. Registered satellites delegate workspace avatar tickets to the central
optimized media endpoint, which reserves the same actor budget before issuing a
ticket; changing apps cannot bypass the shared account or global limits.
Permission denials reserve nothing; quota exhaustion and unavailable
protection return 429 and 503 without issuing a ticket.
Workspace-user avatar uploads also charge the same verified actor used for
`manage_users` authorization: Web revalidates the request session, while Contacts
injects its verified satellite session. Request body identifiers never select the
budget account; authentication errors, missing membership, and permission denials
cannot reserve or sign. Regression evidence: `packages/users-core/src/routes/users/avatar.test.ts`.
Shared public profile-link avatar tickets reserve the account media ceilings above
against the verified workspace and link identity, plus the shared global ceilings,
before issuing a signed URL; revoked or unauthorized links cannot reserve tickets.
These tickets do not charge the link creator's account. Reservation failure prevents
signing; quota exhaustion returns 429 with a bounded retry delay, while protection
outages return 503 without retry timing. The shared avatar byte/MIME ceilings
also apply. Regression evidence: the public profile-link and workspace avatar
handlers' colocated tests and `packages/satellite/src/routes/workspace-settings.test.ts`,
plus `profile-media-upload-limits.sql` for authenticated
INSERT and UPDATE restrictions.

## Wiki, About profiles, and themes

Workspace wiki pages have dedicated directories for characters, worlds, stories,
locations, timeline events, relationships, roles, organizations, lore, and pages.
Entries retain a canonical world owner and optimistic version checks. Typed
relationships and backlinks are world-scoped: self-references, missing targets,
and cross-world edges are rejected atomically. Public rendering drops edges to
unpublished entries. Dates order the timeline; undated entries remain accessible.
The satellite Structure shell shares workspace navigation, notifications, and
account controls with other Tuturuuu apps.

Wiki entry creation defaults to a blank document. Creators can opt into a guided
outline for any of the nine entry kinds. The selected kind determines three
localized headings and editable prompts; changing the kind before creation uses
the newly selected outline. Prompts are saved as ordinary rich text in the current
UI language, so later locale changes do not translate existing content. Starters
add no tags, links, relationships, dates, or permissions and never publish content.
They apply only to newly created wiki entries; existing entries, notebook starters,
and imports keep their content. Regression coverage: `entry-starters.test.ts`
validates every kind in English and Vietnamese against the live draft schema;
`wiki-create-entry.test.tsx` covers opt-in creation, kind changes, and blocked submits.

The in-house editor accepts rich text and Markdown source, including headings,
lists, task lists, tables, links, images, and inline formatting. Applying Markdown
is explicit; saving is disabled until source edits are applied or cancelled.
Artwork must belong to the notebook. Published inline artwork follows the same
privacy and retention rules as cover images. Unsupported embed HTML cannot grant
access to private task or workspace data.

Canonical identity is available to workspace members. Approved creators with
`manage_documents` can additionally edit their About profile: creative headline,
pronouns, location, interests, portfolio links, and rich biography. About data is
owned by the creator in Lettin D1 and defaults to private, including existing
records without a sharing choice. Owners explicitly opt in with Share my About
profile publicly and save. Turning it off and saving revokes future public reads.
The opt-in shares the entire About section (headline, pronouns, location,
interests, links, rich biography, and theme), only on a creator page backed by a
published notebook. It does not share private workspace data. Private About content is retained for editing and preview.
Regression coverage: `creator-about-privacy.test.ts` verifies legacy privacy,
explicit boolean consent, and revocation; `creator-profile.test.ts` verifies the
public identity allowlist. Paper is the default palette;
forest, midnight, and rose are alternatives, with clean or editorial typography.
World and About themes save with their content. Reduced motion respects user
preference and the saved theme setting.

## Exocorpse imports and private moderation

Only actors with a verified `@tuturuuu.com` email, approved creator access, and
workspace document-management permission can see or call the importer. CMS reads
use the fixed source workspace `3385bd92-3d5e-42f6-b3ad-0d1394af3509` and additionally
require its `manage_external_projects` permission. Canonical JSON file imports do
not require source membership unless they copy managed CMS artwork. Reading the
source does not modify it.

Imports are reviewed before applying, bounded by source collection and payload
limits, and copied into a private notebook. Stable source identifiers map wiki
references; excluded or missing targets are omitted. Import application is
transactional and idempotent. Managed images are copied into owned private target
storage; a failed transaction cleans up its newly copied objects. Interactive CMS
collections are excluded. No source content is included in repository fixtures.

The creator blacklist is a private personal record, scoped to actor and workspace.
It supports adding, editing, and removing records and importing source blacklist
entries. It is never published alongside a notebook. It does not change anonymous
public browsing or imply platform-wide account blocking.

## Profile upload budgets and regression evidence

Avatar and banner tickets always use PR #5736's atomic Postgres budget primitive,
independently of its optional storage-egress activation flag. Per account, both
media kinds share two tickets per UTC hour and ten per UTC calendar week. Avatars
allow three tickets per UTC day; banners allow two. Their combined reserved bytes
are capped at 16 MiB per day and 32 MiB per week. Global caps are 10,000 tickets
and 16 GiB per UTC day. Weeks begin Monday. The full source-upload transport ceiling (2 MiB/5 MiB) is
charged, even for smaller files or unused tickets; clients cannot claim a lower
size to bypass the budget. Quota failures return 429 with a bounded Retry-After; protection
or schema outages return 503 without retry timing and issue no ticket. Tickets expire after ten minutes, are scoped to a fresh actor-owned WebP object,
and prohibit overwrite. They authorize an unauthenticated binary PUT to the central
API so native/offline clients retain their existing signed-upload contract. An
atomic shared counter consumes each ticket once before reading or decoding; replay
returns 409. Actual streamed source bytes are bounded even without Content-Length.
The API stores only the optimized result using service-role credentials. Tickets
never grant direct writes to public Storage. Images are public identity artwork.

Coverage is in creator identity and profile-media pgTAP contracts, shared username
and upload-budget tests, central profile/ticket API tests, actual editor Markdown
round-trip tests, and Lettin's disposable D1/R2 tests. The owned satellite runner
includes `lettin-wiki.noauth.spec.ts` for authenticated editing and reloads,
public/private wiki projections, imports, blacklists, About profiles, actual
banner uploads, Storage byte ceilings, and rename/upload quotas. CI/E2E success
must be verified on the exact candidate before merging; test definitions alone
are not runtime evidence.

For a server using an internal HTTP Supabase origin, set
`SUPABASE_PUBLIC_STORAGE_ORIGIN` to its externally reachable HTTPS Storage origin.
Final profile image URLs use that public Storage origin. Signed upload URLs use
the central web origin (`NEXT_PUBLIC_APP_URL`) and point to the optimization API;
clients must not construct Storage upload URLs from the returned token. The E2E runner registers `supabase.tuturuuu.localhost` through
Portless and pins this setting in its disposable environment file, so banner
uploads use real HTTPS and the production HTTPS profile validation stays intact.

Legacy null-owner handle reservations are reconciled only for a unique existing
canonical profile. Non-null ownership is never reassigned, unmatched reservations
remain unavailable, and unchanged legacy handles consume no change allowance.
The full-schema seed preserves its synthetic names while assigning each profile
reservation to its real actor. Regression evidence is the dependent identity
fixture `public-creator-identity.sql`; ordinary authenticated handle INSERTs are
denied so new claims use the atomic profile RPC.

Both Web and Rust profile PATCH paths preserve bounded unchanged legacy handles
verbatim after checking only the authenticated actor’s canonical handle. Changed
invalid handles return 400 without claiming a reservation; the locked atomic SQL
RPC repeats the new-handle checks and remains authoritative across concurrent saves. API regressions cover
short, reserved, and historically mixed-case no-ops and SQL error mapping.

Signed profile-media PUTs use only the Storage ticket and image MIME header, with
cookies omitted; API authorization/default headers remain on the ticket request.
`packages/internal-api/src/profile-media.test.ts` guards this transport boundary.

Changed avatar URLs are also checked by the shared database trigger on direct
writes; unchanged legacy values remain readable. The database media contract
seeds otherwise-writable objects and verifies restrictive policies block both
authenticated INSERT and UPDATE for avatar/banner buckets.

### Support API parity safeguards

The support form and Web/Rust support creation APIs enforce the existing database
ceilings: 64 characters for a name, 128 for a subject, and 512 for a message. Invalid
payloads, including addresses with multiple email separators, return 400 before
storage. Cookie-authenticated creation and updates require a matching Origin or
Referer; explicit Bearer requests retain their independent authentication checks.
Cross-origin cookie updates return 403 before Supabase access. Regression evidence:
`support-inquiry-guard.test.ts`, the first-class inquiry route tests, and Rust
support/g12 regressions. Profile HEAD follows GET authentication/cache/status but
emits no response body; its Rust regression verifies the same boundary.

Support inquiry string limits count Unicode code points consistently in the live
Zod schema and Rust source. The contact form bounds its disabled profile-name
prefill to 64 code points without splitting astral characters. Both API sources
trim inquiry messages before validating the 10–512 character range and persisting
them, so blank-looking messages are rejected. Regression coverage includes
`support-inquiry-guard.test.ts`, `contact-form-values.test.ts`, and the Rust
support payload boundary tests. Unported inquiry GET/HEAD methods retain the
backend dispatcher’s fall-through sentinel instead of claiming a 405 response.

### Mobile avatar selection scope

Mobile Account settings bind the source chooser, native picker, and cropper to the initiating account and ProfileCubit. Leaving that account cancels the intent permanently, including signing out and returning to the same account before a dialog finishes. Cancellation retains the saved avatar; a fresh selection can retry a failed upload. Offline avatar admission also retains the captured actor across cache and connectivity waits, rather than assigning the selected image to a later account.

Regression coverage: `profile_avatar_picker_test.dart` exercises delayed native stages, account switch, logout, ABA, cancellation, retry, and disposal; `profile_media_actor_race_test.dart` exercises actual outbox admission waits. These checks establish source behavior, not device upload or production delivery.

### Personal banner replacement and deletion

The current-user banner endpoints and consolidated mobile Account settings use
actor-scoped durable operation receipts. Offline and ambiguous mobile upload/removal retries preserve the same
operation ID in the encrypted outbox. Replaying a committed
operation finishes cleanup without applying an old upload or removal over a
newer profile edit. A staged upload captures the prior banner; an intervening
change returns a conflict rather than overwriting it. Avatar behavior is unchanged.

The web Account settings also display the current banner and offer upload,
replacement and removal. Upload retries retain the same operation receipt after
an ambiguous response, keep the saved preview until finalize succeeds, and never
patch the profile or delete Storage objects directly. The web and mobile surfaces
share the existing server quotas and lifecycle; no client success establishes
production migration or Storage availability. Web coverage is in
`profile-banner.test.ts` and `settings-banner.test.tsx`.
Web banner selections are bound to the initiating account. Switching accounts or
closing the editor aborts outstanding requests and suppresses stale notifications.
Upload, finalize and removal requests include an expected actor checked before
privileged effects; existing mobile callers that omit it remain compatible.
Deferred image preparation and account-switch regressions cover this boundary.

Mobile banner delivery validates the exact operation receipt before accepting an already committed or uploaded response, uploading bytes, or finalizing. A missing, malformed, or different operation ID fails as a response-contract error and cannot be replayed as a transport failure. Capability-upload failures retain HTTP status and `Retry-After` delta seconds or HTTP-date with a fixed safe category; arbitrary provider error bodies are not propagated. Capability retry delays use a defensive seven-day client wait ceiling; this does not bypass server quota admission. Negative or malformed delays are omitted, and expired HTTP-dates become zero. Mobile media failures offer localized guidance for image limits, authorization, conflicts, cooldowns, temporary availability and invalid receipts. The inline recovery action starts a fresh image selection (or a fresh removal intent), without automatically replaying ambiguous bytes. Native choosers retain the screen-owned context while clearing the transient recovery alert. Banner failure guidance also appears beside the active banner controls and follows the current actor and operation state. Only the current authenticated owner with a confirmed internal email can copy fixed-field diagnostics; messages, provider bodies, capability URLs and credentials are excluded. Starting a new intent, successful recovery or actor departure retires the old failure metadata. Replay-safe banner server failures retain their original operation ID in the pending queue and remain pending success, not a confirmed upload failure. Deferred avatar and banner choosers retain a sticky initiating actor and cubit lease across every native stage, including account ABA and mounted provider replacement. Regression evidence: `profile_upload_receipt_failure_test.dart`, `profile_banner_delivery_test.dart`, and `profile_avatar_delivery_test.dart`. Consumer evidence: `profile_media_failure_contract_test.dart`, `profile_media_failure_scope_test.dart`, `profile_media_recovery_test.dart` and `profile_banner_picker_test.dart`.

Profile writes retire only canonical banner object paths under the configured
Storage origin and the authenticated actor's directory. External URLs and another
actor's objects are never deleted. Retirement is atomic with the existing locked
profile mutation, including the live Web and future Rust profile handler. Permanent
URL tombstones prevent restoring retired files during asynchronous cleanup.

Supabase signed upload tokens are valid for two hours. The server records a
conservative three-hour lease **before returning a token**, and retirement
preserves an inert non-sensitive Storage slot until all leases have expired.
Cleanup replaces the retired image with a tiny non-image marker using the bucket's
allowed image metadata; outstanding non-upsert tokens cannot overwrite that slot.
The slot is removed only after the lease grace period. This removes original bytes
at the origin after successful cleanup; CDN propagation and previously downloaded
images are not an immediate erasure guarantee. See the
[Storage signed-upload contract](https://supabase.com/docs/reference/javascript/file-buckets-createsigneduploadurl).

Storage failures remain in a service-only durable queue. Authenticated banner
requests perform bounded sweeps; later requests finish expired-slot deletion.
There is no claim that a background scheduler has run. Unfinalized staged receipts
are retired after a 30-day replay window; receipts that already committed remain
idempotent. Receipt creation is bounded to 100 new actor operations per UTC day;
existing ticket/hour/day/week/global/byte quotas remain authoritative. Interrupted
quota reservations are conservatively charged again, never refunded or bypassed.

Regression evidence: `personal-banner-lifecycle.sql` covers actor grants, locked
replacement, ABA prevention, stale-finalize conflict and committed replay;
`profile-banner-lifecycle.test.ts` and banner route tests cover exact path ownership,
lease ordering, storage failure/retry, malformed input and object validation.
`profile_banner_delivery_test.dart` covers stable replay IDs and lost-finalize
responses. SQL application/type generation, real Storage/CDN behavior and device
offline delivery require exact CI and authenticated deployment verification.

### Identity field accessibility

Creator identity fields expose the translated field name as their accessible
label. Username policy help is a separate description, so keyboard and assistive
technology users can locate the field without treating the help as its name.
English and Vietnamese rendered regressions in
`apps/lettin/src/components/creator-profile-labels.test.tsx` cover the exact labels,
help association, and reserved-name validation.

### Saved-entry browsing and publication facets

The creator notebook browser searches saved entry titles, descriptions, aliases,
facts, tags and rich-text body text. It can combine an exact case-sensitive entry
tag with all entries, private drafts, published entries, or saved changes since
publication. “Published” includes entries whose saved draft has changed since
publication; “private” means there is no published snapshot. Saved-change status
compares document values with the published snapshot, ignoring object key order
and omitted optional fields while retaining meaningful ordered-array differences.
It describes saved server data, not the current unsaved editor buffer, and never
publishes anything automatically. Only the creator browser displays that badge.

Card views default to the notebook's existing order and optionally sort by title
ascending/descending or kind then title, using the current UI locale and stable
ID tie-breaking. Timeline views preserve chronological order. Relationship views
require both endpoints to pass publication/tag facets before matching endpoint
names, relationship labels or localized relationship kinds; their result count
reports matching connections. Empty results retain filters and an explicit clear
action. Browsing controls and entry selection are disabled while unsaved editor
changes require resolution. Filters persist while opening and returning from an
entry in the same mounted notebook studio; they are not stored in a public URL or
persisted across sessions.

The authorized notebook query still owns access checks and supplies only entries
available to the creator. These controls do not read another workspace or grant
access. Public reader body search uses the existing published-only projection;
private text, creator facets and saved-change badges are not passed to readers.
No profile sharing rules change. Regression evidence: `wiki-browse-model.test.ts`,
`wiki-browsing-panel.test.tsx`, `wiki-model.test.ts` and `public-world.test.tsx` cover
composed facets, ordering, endpoint fences, saved/public text boundaries, empty
result recovery and dirty-state interaction. Hosted browser acceptance and
exact-head CI remain separate delivery gates.

### Ordered artwork galleries

Lettin notebooks and wiki entries may include an optional ordered gallery of up to
12 images, separate from the cover and inline document images. Each gallery image
requires alt text and may include a caption (up to 1,000 characters) and credit
(up to 200 characters). Creators can add HTTPS URLs or upload artwork through the
existing notebook media service, reorder images, edit metadata and remove images
from the draft. Blank alt text or invalid image URLs block saving.

Content notices remain before cover and gallery artwork. Published document
heading outlines remain available alongside the gallery and target rich document
headings, rather than artwork captions or credits. The combined reader regression
in `document-outline.test.tsx` covers this ordering and scoped heading targets.

Gallery changes use the existing explicit save and publish controls. Public
readers receive only the published snapshot; catalogue summaries omit galleries.
Uploading alone does not make artwork public. Every managed gallery image is
checked against the notebook's live media ownership in the same atomic draft
write as existing artwork. Draft and published gallery references participate in
existing cleanup retention; a removed image remains retained while its published
snapshot still references it. Unpublishing the notebook revokes anonymous access
to its managed media. External HTTPS images remain controlled by their host.

Uploads block save, discard and publish until settled; failed uploads preserve
the existing gallery. Deferred results after leaving the editor cannot mutate
the next document. Read-only galleries render escaped captions and credits,
explicit alt text and revocable media URLs without optimizer caching. Legacy
documents with no gallery continue to render normally. Regression evidence:
`artwork-gallery.test.ts`, `artwork-gallery.test.tsx`, and
`gallery-storage.test.ts`; hosted interaction and exact-head app CI remain
independent acceptance gates.

## Discover notebooks by published tags

The public notebook catalogue displays creator-authored tags from the published
notebook snapshot. Clicking a tag opens the global catalogue with an exact tag
filter. Creator catalogue cards also link to this global tag view; their ordinary
search and pagination keep the current creator scope. The catalogue search form
and previous/next links preserve an active tag filter, and clearing only the tag
retains the text search. An empty filtered result offers a clear-filter action.

Tag matching is case-sensitive and exact, including Unicode and punctuation;
it uses the stored published tag, rather than a partial text match. Server-side
filtering runs before the 24-card page limit and its one-row next-page sentinel.
Catalogue cards now retain published tags, while entry documents, wiki facts and
private draft revisions and longer creation guidance remain excluded from catalogue summaries. Private draft
changes only affect discovery after the creator republishes the notebook.

The `tag` query accepts one nonempty trimmed value of at most 40 characters,
matching the notebook editor limit. Malformed tag/text filters on the catalogue page return not found;
malformed API filters return 400. API and page share the tag validation schema.
No profile field or sharing setting is changed. Publishing a notebook already
makes its tags public in the reading view; this decision extends those same tags
to discovery cards. English and Vietnamese labels cover filtering controls.

Regression coverage: `public-tag-discovery.test.tsx` checks independent tag links,
filter preservation and empty results; `public-catalogue-filters.test.ts` checks
bounds; the public worlds API tests cover rejected filters; `public-catalogue-storage.test.ts`
checks actual local D1 filtering, pagination and published snapshot isolation.
The pagination dataset uses one set-based D1 seed with an asserted 30-row count;
separate real create/save/publish mutations retain snapshot-boundary coverage.
Keep fixture setup bounded so timed-out sequential writes cannot contaminate the
next regression.

### Searchable relationship authoring

The creator entry editor searches relationship targets by title and alias and
filters them by entry kind. It uses only the notebook records already loaded
through the creator's authorized workspace session; it does not discover records
from another notebook or workspace. Search and filters are local UI state.
Creators choose a relationship type before explicitly clicking a target. The
current entry and an existing target/type pair are excluded, while another type
for the same target remains available. Changing an existing relationship type
also prevents a conflicting pair. The existing 100-relationship limit applies to
addition; removal remains available at the limit. Results render in batches of
50, with explicit expansion and reset on filter changes. Type changes retain
the focused row control; legacy repeated target/type rows remain independently
editable until explicitly removed. Target counts follow each locale’s plural rules.

These actions update the editor draft only. Existing labels, facts, aliases and
chronology are preserved. A missing target is shown as unavailable and retained
until explicitly removed; search does not silently repair or delete references.
The normal explicit Save action, permission checks and expected revision still
control persistence. Publishing remains a separate action. No profile fields,
source text, consent or access grants are transferred. This workflow applies to
creator editing, not the public reader or relationship graph.

Regression coverage: `relationship-authoring-model.test.ts` checks target/type
fences, bounds and source preservation; `wiki-relationships-editor.test.tsx`
checks explicit draft actions, search, kind filters, bounded rendering,
unavailable references, focused control identity, legacy repeated rows and
integration with the surrounding wiki details editor.
`relationship-count.test.ts` formats the actual English and Vietnamese messages
for zero, one and multiple targets.
The existing `entry-editor.test.tsx` covers dirty drafts during pending saves.
DOM fixtures do not prove hosted keyboard, layout or account-switch acceptance.

### Private saved notebooks

Any signed-in Lettin reader can explicitly save a published notebook from its
public reading page and manage the private library at `/saved`. Creator approval
and workspace document permissions are not required because saves grant no
source access. Each actor may save up to 500 notebook references. Saves and
removals are idempotent; the actor comes from the Lettin app session, and both
reads and writes require the expected actor to prevent account-switch crossover.
Client query keys also include the actor.

Saves are private to the reader: they never appear on public profiles, in creator
notifications, or in public popularity counts. No copy of the draft, document,
gallery or profile is retained. Library cards read only title, description, cover
and credit from the source's current published snapshot. Unpublishing hides
those details and leaves a removable unavailable reference; deleting a notebook
cascades its saved references. Saving a new unpublished notebook is rejected.
A save never permits publishing, editing or accessing private artwork.

The additive local D1 migration `0005_reader_bookmarks.sql` must be present
before enabling the API. Local migration application and consent boundaries are
covered by `reader-bookmarks.test.ts`, with session/input/cache fencing in the
bookmark route tests and reader controls. Exact-head app build, hosted
session/account-switch behavior and authorized migration delivery remain separate
gates; no production application is claimed by local tests.

### Published document heading outlines

Public notebook and published-entry readers display an “On this page” outline
when the selected document has at least two nonempty rendered headings. The
outline uses only the currently rendered published document, never an editor
buffer, private draft, unavailable entry or another workspace. Content notices
remain before artwork and heading navigation in the combined reader. Creator editor
previews keep outlines disabled by default. No document or publication state is
written and no reader interactions or preferences are recorded.

Heading labels are plain escaped text with whitespace collapsed; markup, author
IDs, image metadata and link targets are not interpreted as navigation targets.
Targets use document scope and tree positions so repeated titles remain distinct.
The outline follows the renderer's depth and leaf-node rules, shows at most the
first 100 headings, and reports truncation. Long labels are capped at 160
characters; full heading text remains in the document. Sources are unchanged.

An ordinary outline click opens enclosing collapsed sections, focuses the heading
and scrolls within the same article. It uses automatic movement and heading focus
styling, avoiding forced animation. The explicit jump does not add browser-history
entries. Modified link clicks retain native anchor behavior. Selected-entry
changes replace outline labels and targets. These are local reading targets, not
stable section-permalink or immutable-snapshot guarantees: future publication can
change heading positions. A copied public link still observes source publication
and retirement boundaries.

Readers can explicitly search the current outline's displayed heading labels.
Search starts empty, normalizes Unicode and letter case, and accepts at most 100
characters. It filters only the bounded outline; full document content and the
truncation notice remain visible. Empty results include a clear-search action.
Each article keeps its own ephemeral search, reset when heading labels or scoped
targets change. Private previews retain their disabled-outline default. Queries
are never stored, sent to an API or added to the URL; IDs, description text,
private drafts and omitted headings are not searchable through this control.
`document-outline-search.test.tsx` covers bilingual controls, normalization,
bounds, clear/empty recovery, current-document resets, isolation and retained
fold-opening focus behavior.

Regression evidence: `document-outline-model.test.ts` and `document-outline.test.tsx`
cover repeated/empty/nested headings, bounds and escaping,
matching renderer IDs, fold opening/focus, article isolation, private preview and
published selection boundaries. Exact-head CI and hosted scrolling/focus/browser
acceptance remain separate gates; DOM fixtures do not prove browser layout.

### Saved entry duplication

In the Lettin notebook studio, a creator with notebook editing access can explicitly
duplicate a saved entry and supply a new title. The copy belongs to the same
notebook, starts at revision one, and is always unpublished. It retains saved
rich text (including ordinary document hyperlinks), artwork, ordered galleries,
content notices, credit, tags, kind,
aliases, facts and chronology; structured links and wiki relationships are cleared.
There is no cross-notebook copy or automatic publication. Unsaved editor changes
block the action; saving or discarding them comes first. After success, an explicit
Open copy action selects the new draft and remains blocked while edits are unsaved.
Mutations are not automatically retried after an ambiguous response.

The server reads the saved draft, validates it, and fences the insert against the
source revision, current creator/collaborator access and notebook artwork ownership.
Every managed gallery image is checked by the same atomic ownership fence.
A stale revision, revoked permission or retired artwork cannot create a copy.
Source drafts and published snapshots remain unchanged. Editors can duplicate
without acquiring publishing permission. Regression evidence lives in
`duplicate-entry.test.ts` and `duplicate-entry.test.tsx`; actual app build and
hosted interaction require exact-head CI and browser acceptance.

## Content notices

Notebook and wiki entry editors support an optional creator-authored content
notice of up to 500 characters. The default is empty, including historical
content. Notices appear before artwork and reading content in document previews,
public notebook reading, public discovery cards, private notebook shelves and
wiki entry cards. Labels are available in English and Vietnamese.

Notices are advisory and do not hide content, replace moderation, grant access or
publish a draft. A saved notice belongs to the private draft until a publisher
republishes that notebook or entry; readers receive the notice from its published
snapshot. Clearing and republishing removes it publicly. Profile identity fields
and consent to share creator details are unaffected. Titles and metadata remain
visible under existing publication rules.

Regression coverage: `content-notice.test.tsx` checks reading/card placement and
legacy empty notices; `content-notice-schema.test.ts` checks limits and command
validation; the entry editor test checks saving notice edits.
`storage.test.ts` exercises the real local D1 mutation and catalogue queries to
confirm later edits and clearing remain private until republished.

### Creation attribution and collaboration guidance

Notebook and entry creators can write creation credits and usage notes of up to
1,000 characters each, and explicitly choose an unspecified, ask-first, open-to-
proposals or closed collaboration preference. The default is unspecified with no
notes; historical documents display no guidance. These fields are separate from
cover-art credit and from profile sharing settings.

Editing changes the local draft. Explicit Save uses the existing revision and
permission checks; only publishing the notebook or entry exposes its guidance.
Later edits and clearing stay private until republished. Public entries also
require a published notebook. Catalogue summaries omit this longer guidance.
Saved-entry copies retain authored guidance in a new unpublished draft.

Reader guidance renders escaped plain text and explains its advisory scope. It
creates no access grant, invitation, ownership verification or automatic usage
permission. Collaboration preferences do not alter notebook roles. Public
profiles retain their separate avatar/banner/name/biography default; no identity
fields are copied into creation guidance. Portability integrations must explicitly
review new fields rather than infer permission to transfer them.

Regression evidence: `creation-guidance.test.ts` exercises real local D1 snapshot,
copy and authorization boundaries; `creation-guidance.test.tsx` checks escaping,
empty defaults, draft controls and content-notice placement. Exact-head app builds
and hosted interaction remain independent delivery gates. Gallery integration
coverage also publishes guidance and artwork together while omitting both from
catalogue cards; the document regression retains notices, artwork credits and
heading navigation alongside advisory guidance.

### Private saved creators

Signed-in readers can explicitly bookmark a creator with a published notebook
from the Lettin creator page and manage up to 500 creator references in `/saved`.
The choice is private to the initiating reader. It sends no notification,
creates no public follower count or list, changes no profile fields, and grants
no source access. Notification subscriptions remain a separate workflow.

Only creator IDs and save timestamps are retained. The library reads a current
published notebook title for navigation; it never copies a profile or draft.
A creator without published notebooks is unavailable but remains removable.
Reads and writes require the expected app-session actor; cache keys include that
actor. Removal is idempotent, failed mutations preserve the confirmed state, and
ambiguous writes are not automatically retried. Anonymous readers receive a
sign-in link with a canonical creator return path. Public profile defaults remain
avatar, banner, display name and biography; no bookmark choices are exposed there.

Regression evidence: `creator-bookmarks.test.ts` applies the additive D1 migration
and checks private actor scope, published-only projection, quota and withdrawal.
The quota fixture seeds 499 references with one SQL operation, verifies the seed
count, then races two real save operations against the remaining slot;
creator bookmark route and rendered reader-library tests cover session/command
fences and explicit UI actions. Exact-head CI and hosted keyboard/account-switch
acceptance remain separate delivery evidence.

### Private quick-note capture

The authorized notebook studio offers explicit plain text quick-note capture.
A title of up to 160 characters and text of up to 10,000 characters and 100 lines
create an unpublished entry through the existing entry command, defaulting to a page. Empty input or
values beyond these bounds cannot be submitted; text is never silently truncated.
Internal blank lines are preserved. URLs and markup remain plain text without
importing remote content or creating references, permissions or publication.

Pending capture locks the form and blocks repeated submission. Failure preserves
the input for an explicit retry. A successful save clears the capture fields and
offers a separate Open action; opening remains disabled while the current editor
has unsaved changes. Notebook/workspace context replacement resets local capture.
Publishing still requires the existing separate role and revision checks.

Closing the quick-note form keeps its local draft until notebook/workspace context
replacement, leaving the studio, or reloading. Discard draft opens an inline review
with Keep draft and Confirm discard choices. Only confirmation clears the local
title, text and selected entry type; saved entries and the latest saved-entry Open
action remain intact. Editing and saving are paused during this review, and editor
blocking or pending creation also blocks discard. This control neither deletes
stored content nor changes publication, collaborator access or source sharing.

Regression evidence: `quick-note-model.test.ts` validates bounds and actual draft
schema; `quick-note.test.tsx` covers commands, failure, repeated submits, pending
and dirty-navigation fences, context resets, translated discard review, cancellation,
local-only confirmation and preservation of saved entries. `storage.test.ts` uses local D1
to verify saved private notes, public omission and workspace/revocation boundaries.
These fixtures do not establish hosted dialog or keyboard acceptance.

### Larger artwork reading view

Every valid gallery image has an explicit, keyboard-accessible View artwork
action. The dialog shows the same source image at a larger size with its authored
alt text, caption and credit. It stays closed until requested, and supports
Escape and a localized Close artwork control. It does not provide an export or
download action. The gallery remains bounded to twelve images in authored order.

Public readers receive only the published gallery projection. Authorized private
previews retain their existing media access checks. Both views use direct media
URLs without optimizer caching or referrer forwarding; opening the dialog does
not publish, copy or grant access to a source. This feature does not change cover
artwork or profile visibility. Regression evidence: `artwork-viewer.test.tsx`
exercises real dialog interaction, focus return, bilingual controls, escaped
attribution and invalid URLs; `artwork-gallery.test.tsx` covers gallery bounds
and `gallery-storage.test.ts` covers publication and media retention boundaries.

### Typed private quick capture

Quick capture defaults to a page and lets creators explicitly choose any supported
notebook entry kind before saving, including character, location, story and event.
The selected kind persists on a failed save; successful capture and notebook context
replacement restore the page default. Pending requests and unsaved editor changes
block the selector together with the existing capture controls. Text limits and
plain text treatment remain the same. Capture adds no structured starter facts,
relationships, source links, profile details or publication metadata. The normal
notebook editor can enrich the saved entry afterward.

This rule applies only to the authenticated Lettin notebook studio. Every kind
uses the existing authorized `createEntry` command and remains unpublished until
an explicit publication action. Publishing the notebook alone does not publish
captured entries. Regression evidence: `quick-note-model.test.ts` checks all kinds
against the shared draft schema, `quick-note.test.tsx` checks English/Vietnamese
selection, explicit commands, reset, failure and blocked controls, and the local D1
`storage.test.ts` covers page, character and story privacy, cross-workspace denial
and revoked collaborator access. Exact-head builds and hosted dialog acceptance
remain independent delivery gates.

### Copying published notebook and entry links

Public notebook readers can explicitly copy the canonical Lettin notebook URL or
the selected published-entry URL. Only an entry present in the current published
projection is included as `?entry=...`; unavailable or arbitrary query-selected
IDs fall back to the notebook URL. Source notebook and entry IDs are routing
identifiers, not access grants. A later unpublish/retirement may make a copied link
unavailable; copying does not freeze content or bypass publication checks.

The shared control copies only a validated public URL. It does not include private
workspace paths, actor identifiers, draft text, titles, profile details, tracking
values or permissions. Clipboard denial exposes a manually selectable URL and a
retry action. Copying never sends a message, notifies a creator, publishes content
or records a reader interaction. Regression evidence: `public-world.test.tsx`,
`public-content-link.test.ts` and `public-link-button.test.tsx` cover published-entry
selection, route fences, explicit intent, failure recovery and stale completion.
Exact-head CI and hosted browser clipboard acceptance remain separate gates.

### Creator catalogue filter recovery

A creator's public catalogue requires at least one currently published notebook
in an unfiltered first-page read. Missing identities and creators without
published notebooks still return not found. Once that publication requirement
is met, a search, exact tag or later page with no results renders a recoverable
empty catalogue instead of treating the creator as missing. The clear-filter
action stays on that creator's canonical page. Paging and clearing a tag preserve
the creator scope and active search. Notebook-card tag links remain global
discovery links. The first unfiltered page reuses its
publication check results rather than reading the same catalogue twice.

Creator routes reuse the public catalogue's normalized bounded filter schema;
malformed repeated query parameters are rejected. Public profile defaults remain
avatar, banner, display name and biography; additional about details require
explicit owner sharing. Filter recovery does not expose unpublished notebooks,
private entry data or additional profile fields, and grants no source access.
Existing English/Vietnamese empty-result controls are reused. Regression evidence:
`creators/[creatorId]/page.test.tsx`, `public-tag-discovery.test.tsx` and the
public publication filters in `server/public-catalogue-storage.test.ts`.

## Private saved-library filters

The authenticated saved-library page lets readers filter their saved notebook
and creator references by availability and current published title. Each library
starts with all references visible and an empty search. Search is case-insensitive,
Unicode-normalized, bounded to 100 characters, and remains only in component
state. Filters do not change the URL, persist preferences, trigger source reads,
remove references, or share the private library. Changing actors resets filters
and uses the existing actor-scoped API and query cache.

Only the title already returned by the authorized library response is searchable.
Unavailable references have no searchable title or source link; search never
falls back to IDs or cached historical metadata. The unavailable facet with empty
search makes those references manageable. A filtered empty result offers a clear
control to recover all references; a truly empty library keeps its existing message.
Removal still requires an explicit action and successful server confirmation,
and denied removal preserves the reference and current filters. Notebook
publication, profile sharing defaults and source-access rules are unchanged.

Rendered regressions in `saved-library-filters.test.tsx` cover both libraries,
local-only read/write counts, unavailable projections, clear recovery, actor
changes, failed removal, Unicode matching and both shipped language bundles.
Existing reader/creator library and bookmark API/D1 tests retain their boundary
coverage. Fixture translations and APIs are doubled; exact-head Lettin builds
and repository CI remain separate delivery evidence.

### Private saved-library ordering

Saved notebooks and creators default to most recently saved first. Readers can
choose least recently saved first or current published title order. Ordering
composes with the existing local search and availability filters, sorts a copy
of the authorized response, and performs no additional source reads or writes.
All controls remain ephemeral: changing actors or clearing library filters
restores the default order together with search and availability.

Date ordering places invalid or missing timestamps last in either direction.
Title ordering uses Unicode NFKC normalization and case-insensitive deterministic
lexical comparison. References without an authorized current title remain last;
IDs and historical titles are never used as substitutes. Equal timestamps or
titles preserve response order. This applies only to authenticated saved notebook
and creator libraries; it does not reorder public catalogues or persisted entries.

`saved-library-ordering.test.ts` covers stable ties, invalid dates, normalized
current titles and source-array isolation. `saved-library-filters.test.tsx`
covers both rendered libraries, sorting with filters, read/write counts, clear
and actor resets, unavailable references and English/Vietnamese labels. Exact-head
CI and Lettin builds remain separate delivery gates.

## Plan work in Tasks

Private notebook and wiki studios offer **Plan a task**, opening the Tasks
composer in the same workspace. The handoff carries only notebook and optional
entry IDs; it does not include draft text, artwork, profile details or task names.
Tasks authenticates its own app session and checks workspace membership. The
creator enters a task name and explicitly chooses a board and non-archived list.
Existing task creation APIs enforce destination workspace/list access.

Attaching the canonical private Lettin reference is optional and **off by default**.
The composer explains that attaching it makes the link visible to people with
access to the destination task. It neither grants source access nor fetches or
copies notebook content. The creator can review the source before opting in.
Creating the task requires explicit submission and does not publish the notebook.
Opening the composer itself creates no task or board.

The first handoff supports task planning and references only. Automatic content
transfer, ongoing synchronization and integrations with other tools remain
outside this workflow. Deleted or inaccessible sources continue to be governed
by Lettin access rules. Malformed source IDs are rejected; IDs alone do not prove
access or source ownership. English and Vietnamese controls cover both surfaces.
Regression coverage: `lettin-task-reference.test.ts`, `task-plan-composer.test.tsx`
and the Tasks composer page tests cover safe links, explicit sharing and session
and workspace boundaries.

### Plan creator work in Calendar

The authorized notebook studio lets creators choose a calendar day and explicitly
open Calendar for the same workspace. Only the day is included in the query;
notebook and entry identifiers, titles, draft text and profile details are never
copied. The link uses Calendar's canonical production origin or its registered
Portless origin in development. No event is created by this action.

Calendar independently authenticates the actor, resolves the workspace and checks
`manage_calendar`; the link grants no access. Creators plan or create events in
Calendar through its normal controls. Invalid dates/workspaces/locales produce no
link. Unsaved studio edits block day selection and navigation until resolved;
the selected day remains available afterward. Workspace/notebook context changes
reset the local day selection. This workflow is day navigation, with no calendar
sync or transfer of source content.

Regression evidence: `calendar-day-url.test.ts` checks exact date-only URLs,
production/Portless origins, leap days and rejected input; bilingual rendered
`creator-calendar-plan.test.tsx` covers explicit selection, source-free queries,
dirty blocking and context resets. Calendar's existing workspace route retains
its session and permission checks. Exact-head Lettin builds and authenticated
cross-app browser acceptance remain independent delivery gates.

## Explicit collaborator access review

Notebook owners review the selected member and capabilities before adding or
changing an editor/publisher role or removing collaborator access. Editors can
read and edit private drafts; publishers can additionally publish and unpublish
content. Existing workspace membership, creator eligibility, document permission
and owner-only server checks still apply. This step is an owner confirmation,
not a new recipient invitation or acceptance system.

Cancel sends no command. Failed requests retain the selected action for retry,
and pending submissions suppress duplicates. Staged actions bind the workspace,
notebook and member ID; changed context, lost owner status or unavailable members
disable confirmation. Switching notebook/workspace resets the owner controls.
Removing collaborator access does not remove workspace membership or unpublish
existing content. The existing server remains authoritative for access.

Regression coverage: `collaborators.test.tsx` covers English/Vietnamese capability
review, cancel, failed retry, duplicate/pending suppression and context/eligibility
changes. `server/storage.test.ts` exercises local D1 editor/publisher boundaries,
workspace eligibility and access revocation. Hosted app-session/browser acceptance
and exact-head CI remain separate delivery gates.

### Published entry collection browsing

In the public notebook reader, choosing an entry kind opens its published entry
cards in the main reading area. Cards retain the existing title, kind, aliases and
content notice; selecting a card opens its published document with the existing
entry deep link. The overview still opens the notebook introduction. Returning to
the notebook while a collection is selected retains that collection and search.

The sidebar reports matching entry counts and offers an empty-search hint. Clear
reading filters resets the search, collection and selected entry to the notebook
overview. The relationship view keeps its existing label/endpoint search and does
not show an entry count as a connection count. Timeline ordering remains unchanged.
These controls operate only on the existing published payload. Private saved text,
profile details and creator publication facets are excluded; no extra query or
access grant is introduced. Draft edits become visible only after publication.

Regression evidence: `public-entry-collections.test.tsx` covers English/Vietnamese
cards and counts, notice/alias context, empty recovery, entry links, snapshot
isolation, chronology and relationship endpoints. `storage.test.ts` retains actual
D1 private/public and workspace/revocation coverage. Exact-head app builds and
hosted browser acceptance remain separate delivery gates.

## Compare draft and published previews

The private notebook and entry editors open **Preview** on the current local
draft, including unsaved edits. The creator can switch to **Published snapshot**
to inspect the saved publication with the same document renderer, notices,
credits and creation guidance. These controls never save, publish, copy content
to another app or change access. Closing and reopening starts on the current draft.

The published choice is disabled when the record is unpublished. A saved snapshot
is not proof that an entry is currently available to readers: its notebook must
also be published, and existing reader and media permissions still apply. Saving
draft edits leaves the published snapshot unchanged until explicit publication.
The preview reads only the snapshots already authorized for the private editor;
it does not fetch a public URL or broaden profile visibility.

English and Vietnamese controls name the selected version and explain these
boundaries. Regression coverage: `publication-preview.test.tsx` exercises local
edits versus saved content, credits/notices, unpublished records, refreshed and
revoked snapshots, accessible selection and reset on reopening. Existing
`entry-editor.test.tsx` and local D1 `storage.test.ts` preserve pending-save,
revision-conflict and publication isolation coverage.

Preview version guidance describes the selected version neutrally in both English
and Vietnamese. It must not identify the published snapshot as the draft. The
bilingual `publication-preview.test.tsx` regression checks the dialog description
before and after switching versions as well as the version-specific status.

### Stage a draft from the published version

The creator notebook and entry editor offer a confirmation to start from the
current published snapshot. Confirmation replaces only the local editor buffer,
including tags and optional metadata; it does not merge newer private fields into
the older version. The current private work-progress label is retained separately;
a historical public label never overrides it. Rich text remounts so its buffer
matches the staged snapshot.
The editor becomes dirty. Saving and publication remain separate explicit actions;
the previously saved private draft and public snapshot remain unchanged until
those actions. Discarding the staged edit returns to the last saved private draft.
Authored credits, usage guidance, links and relationships remain part of the
snapshot. Existing validation may reject a save if referenced targets or media
are no longer available; restoration does not grant access or revive them.

Restoration is unavailable without a current published snapshot and is blocked
while a mutation, cover, gallery or inline artwork upload, or source-mode edit is
pending. All overlapping uploads must settle before staging. Editors can stage
and save drafts but do not gain publication authority. Saves use the existing
workspace, actor and revision fences, so stale revisions conflict rather than
silently replacing newer saved work. Unpublishing removes the available source.
No profile field or owner-sharing rule changes.

Regression evidence: `published-draft-restore.test.tsx` covers bilingual explicit
confirmation, cancellation, clone isolation and changing availability;
`entry-editor.test.tsx` covers notebook/entry commands, optional-field replacement,
local-only staging, gallery replacement, discard and overlapping upload fences. Local D1 `creation-guidance.test.ts` verifies
workspace/stale-revision denial, metadata preservation and unchanged public reads
after an explicit restored-draft save. Exact-head builds and hosted editor/dialog
acceptance remain independent delivery gates.

### Scoped notebook JSON export

The notebook studio offers an explicit JSON document export, using published
documents by default. The notebook owner may instead export saved private drafts
after affirmative confirmation; collaborators cannot bulk-export private drafts.
Unsaved editor changes block export. The server verifies the app-session actor,
workspace/notebook permissions and chosen scope, then rechecks notebook access
before returning the file. Published scope also rechecks that the notebook and
all included entries remain published, rejecting a concurrent unpublish. Actor lifetime and dialog intent fences suppress
deferred downloads after account departure, closing the dialog or leaving the
studio. Nothing is exported automatically on opening the dialog.

Format `lettin-notebook`, version one, includes scope, export time, source notebook
and entry IDs, and validated document fields. Published exports omit unpublished
entries and filter structured links/relationships to included entry IDs. Exports
omit actor/workspace IDs, collaboration grants, profiles and saved-reader data.
They contain artwork URLs rather than image bytes; managed URLs retain their
existing access and retirement behavior. Offline artwork availability is not
implied; the reviewed import below creates private copies without artwork. Downloaded files are controlled by the person who
explicitly exports them; original records and publication permissions are unchanged.

Exports are limited to 1,000 entries and 10 MiB. Each document comes from a saved
server read; this is not an atomic multi-document database snapshot. The active
draft schema projects known fields, so newly integrated document fields must retain
export regression coverage. Regression evidence: `notebook-export.test.ts`, export
route tests and `notebook-export.test.tsx`. Exact app CI and hosted download/account
switch verification remain separate delivery gates.

### Reviewed notebook JSON import

Approved creators with workspace document-management permission can import a
version-one `lettin-notebook` JSON file from the workspace Studio. The creator
chooses a new title and explicitly confirms permission to copy all included
content into the selected workspace, including private material. A stored,
actor/workspace-bound preview expires after fifteen minutes; its entry list must
be reviewed before a separate apply action. Account changes, mismatched preview
owners, expired previews and revoked creator access stop the operation.

Import always creates a new private notebook and new private entries, with fresh
IDs and revision one. It never changes originals, restores publication, creates
collaborators or imports reader/profile/moderation data. Structured links and wiki
relationships are remapped only between included entries; missing targets are
removed. Source notebook ID, export scope/time and entry IDs remain private preview
provenance, not permission claims. File claims are untrusted and grant no access.

Files contain artwork URLs rather than bytes. This importer removes cover, gallery
and inline images and hyperlink targets, retaining inline-image alternative text,
document text and document credits. It performs no remote fetch or media permission transfer. The review
explains this intentional limitation; creators can add authorized artwork later.
Unknown identity/grant fields are discarded through the active document schema.
Source files are limited to 10 MiB and 1,000 entries; the sanitized preview plan
is additionally limited to 1 MiB because it occupies one D1 row; malformed formats, duplicate IDs,
executable nodes and excessive nesting are rejected. Applying the same preview is
idempotent and commits the new drafts in one D1 transaction. Import is a copy
workflow, not an in-place restore or full-fidelity offline backup.

Regression evidence: `notebook-import.test.ts`, the import route tests and
`notebook-import.test.tsx`, including D1 creation, ownership/expiry fences,
relationship remapping, media stripping, source consent, duplicate submissions
and stale actor/dialog completion. Exact-head CI and hosted file/account switching
acceptance remain separate from focused fixture verification.

## Private work progress

Notebook owners and existing collaborators can label saved notebook and entry
work as **Unstarted**, **Drafting**, **Revising**, or **Ready** in the studio.
Historical drafts without a label behave as Unstarted. Labels are shared within
the authorized notebook studio, rather than an actor's personal store. Existing
revision checks, collaborator roles, workspace access and revocation still apply.
Ready is advisory and does not publish content or grant publishing permission.

The editor marks changes unsaved until the creator explicitly saves. The studio
progress filter composes with the existing saved-entry search and section. It
filters saved records rather than unsaved editor buffers; relationship views
require both endpoints to remain in the filtered set. The explicit Clear filters
action resets work stage, search, publication, tag and sort together, restoring
all saved entries in the current section. It preserves the full saved-stage
summary and does not save drafts, navigate, change selection or write preferences.
Dirty editing keeps this action disabled. This is a scoped organizational workflow; dedicated quick-note
capture remains separate.

Progress labels are always private from readers. Publication strips the label
from the snapshot while retaining it in the saved draft. Public notebook,
entry, catalogue and published-only JSON exports also remove it from historical
published JSON. Owner-consented saved-draft exports preserve the private label. Saving
or clearing a label does not publish, unpublish, or change a reader's content.
Private saved-entry copies retain the source's saved label. Public profile sharing
is unaffected. No new migration or external transfer is required.

Regression evidence: `work-progress.test.ts` uses local D1 for publication,
historical projections, copies, revisions, workspace boundaries and revocation;
`world-studio-progress.test.tsx` exercises real studio filtering and opening,
targets search by its label alongside the Calendar date control, and verifies
that changing the work stage retains search without changing the planning date;
`entry-editor.test.tsx` verifies explicit save. These fixtures are separate from
exact-head app builds and hosted browser acceptance.

### Optional source references for private copies

The saved-entry copy dialog offers **Link this copy to the source entry**, off by
default. Selecting it adds only the source entry ID to the new copy's links.
Other links and typed relationships are cleared as before. The operation remains
within the same authorized notebook and workspace, checks the saved source
revision and artwork atomically, and creates an unpublished record. It does not
change source content, publication, collaborators, ownership or profile sharing.

The optional link is a reference to the living source record, not an immutable
history or ownership claim. If the creator later publishes the copy, that source
ID is retained in its stored published snapshot; this is stated before opting in.
The public projection omits the link until the source is separately published.
Source content remains subject to its own publication and access rules. Public
readers offer navigation only to entries in the current published notebook
projection. The source is never automatically published with its copy.

Reopening the dialog clears the choice. A failed request retains the title and
consent for an explicit retry; pending or dirty editors disable the control.
English and Vietnamese labels explain the private default and later publication
boundary. `duplicate-entry.test.ts` uses real local D1 to check the optional link,
clearing other references, unpublished copies, unchanged sources, revision and
workspace fences, and separate editor/publisher permissions.
`duplicate-entry.test.tsx` covers explicit consent, reopening, failure and both
language labels. Cross-notebook variants and canonical-context management remain
outside this same-notebook reference workflow.

## Private writing statistics

The notebook and entry editors show word and character counts for the current
rich-text body, including unsaved edits. Counts are computed locally and are not
stored or exposed on public readers, profiles or catalogue cards. Titles,
descriptions, credits, image metadata and link destinations are excluded.
Whitespace is excluded from character counts; composed Unicode characters count
as one character. Words use Unicode word segmentation, so punctuation is not a
word and Vietnamese space-separated units count separately. These are writing
statistics, not a reading-time or language-proficiency measure.

Unapplied Markdown source is excluded, with an explicit notice until it is
applied. Save, discard and publication keep their existing permission and revision
boundaries. Traversal is bounded to 20,000 attempted nodes, including depth-clipped nodes,
and depth 25; incomplete counts
are visibly labeled partial. Regression coverage: `writing-statistics-model.test.ts`
checks rich-text boundaries, metadata exclusion, Unicode and traversal limits;
`writing-statistics.test.tsx` checks both languages and changing document buffers;
`entry-editor.test.tsx` preserves save/discard behavior.

## Creator fact ordering

Notebook and entry editors, including characters, allow creators to move existing
facts up or down. The displayed order is the stored fact-array order; labels and
values are preserved, including duplicate labels. The first and last rows disable
impossible moves, and keyboard focus follows the moved row to an available move
control. Fact insertion remains limited to 40 rows.

Reordering changes only the private editor buffer. Saving uses the existing
permission and optimistic-revision checks. Public readers continue seeing the
previous published order until the creator explicitly publishes the saved draft.
No profile fields, collaboration permissions or public discovery projections are
added. Regression coverage: `wiki-facts-editor.test.tsx` covers bilingual controls,
duplicate labels, focus, unchanged metadata and limits; `server/fact-ordering.test.ts`
covers real local D1 save/read/publish and stale-write rejection.

### Private reference publication review

The creator preview lists each distinct linked entry or relationship target from
its selected local draft or saved published version. It labels the current target
as having a published snapshot, a private draft only, or being unavailable. Titles
come only from the already-authorized notebook records; unavailable IDs are not
rendered. Repeated targets appear once, and empty reference sets omit the review.

This panel is private to the creator editor. Availability reflects the current
records, not an access promise or an immutable historical target version. The
notebook must also be published before readers can see its published entries.
Publishing the source does not publish linked targets or grant access. Anonymous
reads continue to filter links and relationships using `publishedReferences`;
private or unavailable targets remain hidden. Profile sharing defaults are
unaffected.

Regression evidence: `reference-publication-review.test.tsx` covers bilingual
labels, relationship-only targets, deduplication, revoked publication, missing-ID
concealment, escaped titles and non-mutating review. `publication-preview.test.tsx`
covers version switching and current target refresh. Existing local D1 storage
coverage verifies the public projection; exact-head CI and hosted dialog acceptance
remain separate delivery gates.

### Optional character fact labels

Character entries offer Appearance, Personality, Motivation and Abilities as
optional fact labels in the private editor. The default selection is empty.
Choosing a label alone makes no change; explicitly adding it appends one ordinary
fact with an empty value. Existing labels, values, order, aliases and relationships
remain unchanged, including an existing fact with the same label. The existing
40-fact limit applies. Other entry kinds keep generic fact controls only.

The chosen label is ordinary authored text in the interface language used when
adding it. Changing the interface language does not rewrite saved labels. Creators
may edit labels and values or remove the added fact using the existing controls.
These are creative character details, not account profile fields. They stay in
the private editor buffer until an explicit save and become visible to readers
only through the existing publication flow; no access or profile-sharing rule
changes. There is no template metadata or new schema.

Regression evidence: `character-fact-starters.test.tsx` covers bilingual explicit
addition, duplicate-label preservation, metadata isolation, locale switching,
entry-kind scope and the fact limit. Existing `wiki-facts-editor.test.tsx` and
local D1 `fact-ordering.test.ts` cover order and save/publication/revision fences.
Exact-head CI and hosted editor acceptance remain separate delivery gates.

### Explicit character context copies

The private copy dialog offers an optional context for character entries. The
field starts empty. An explicitly entered context appends one ordinary fact with
the localized Context label to the new saved copy; existing facts, aliases,
content, attribution, tags and gallery remain intact. Matching fact labels are
not overwritten. Other entry kinds cannot accept a context, and the existing
40-fact limit applies. Clear the context to make an ordinary copy at that limit.

Copies use the saved source revision in the same notebook and workspace, including
its existing actor, collaborator and artwork checks. The source remains unchanged;
the copy has no published snapshot or transferred grants. Linking to the source is
a separate unchecked option and never publishes either item. Context labels and
values are ordinary authored creative content, not account profile data. This
workflow does not establish cross-notebook canon, transfer ownership or create
public context indexes; broader context management remains separate.

Regression evidence: `character-context-copies.test.ts` exercises real local D1
source/publication/artwork preservation, revision/workspace/actor denial,
character scope and fact limits. `duplicate-entry.test.tsx` covers bilingual
explicit context commands, source-link separation, retry and reset. Existing copy
regressions retain quota, collaborator and media-retirement races. Exact-head CI
and hosted dialog acceptance remain separate delivery gates.

### Published reading order

The public notebook reader offers explicit Previous entry and Next entry controls
when the selected entry belongs to a filtered sidebar list with at least two
entries. Navigation follows that list's order, respects the current search and
kind filters, and stops at either end. A selected entry excluded by the filters
remains readable but has no sequence controls; clearing filters restores the
ordinary list. The notebook overview has no sequence controls.

Only already projected published entries supply titles and destinations. These
controls do not fetch private drafts, change publication, or grant access, and
use the reader's existing entry URL update. English and Vietnamese controls
share these rules. Regression evidence: `reading-sequence.test.tsx` exercises
ends, excluded selections, bilingual labels and escaped titles;
`public-world.test.tsx` covers selection URL and filtered reader integration.

### Private session word targets

The studio writing statistics include an optional word target from 1 to 100,000.
It starts empty and applies only to the open entry editor. The target lives in
local component state: it is not sent to an API, stored in a draft, published,
or included in exports. Leaving the editor or selecting another entry clears
it; Clear word target removes it explicitly. This is a session aid, not a saved
project goal or a writing streak.

Progress uses the existing current body word count, including unsaved edits.
If Markdown is unapplied or bounded traversal yields partial counts, the target
is retained but progress and completion are withheld until complete counts
are available. Reaching a target does not save or publish the document. English
and Vietnamese controls share the same bounds. Regression evidence:
`writing-goal.test.tsx`, `writing-statistics.test.tsx` and the bounded Unicode
counting cases in `writing-statistics-model.test.ts`.

### Published entry tag filters

The public notebook reader can filter entries by an exact published entry tag.
The filter starts empty, combines with text search and entry kind, and trims
outer input spaces without changing the authored tag's case. Suggestions come
only from published entry metadata, are deduplicated and sorted, and show at
most 100 distinct tags; readers can enter any exact tag manually. Notebook tags
do not become entry tags. No private metadata is fetched.

The sidebar, collection browser and previous/next sequence use the filtered
entries. The relationships browser keeps only tagged endpoints before its own
search. An already selected entry remains readable when excluded by a filter,
but loses sequence controls. Clear reading filters removes tag, search and kind
filters together and returns to the notebook overview. These local reading
filters do not publish, grant access or persist preferences. EN/VI regressions:
`reading-tag-filter.test.tsx` and `public-world.test.tsx`.

### Private saved work-stage summary

The authenticated notebook studio shows totals for all saved entries in the current
notebook across Unstarted, Drafting, Revising and Ready, including zero-count
stages. Historical entries without a stage count as Unstarted. The summary reads
the saved private draft stage, even when a published snapshot has another stage.
It excludes the notebook itself and remains independent of entry-kind, search,
publication, tag and work-stage browsing filters.

This is an authored organization aid, not completion or publication evidence.
Ready does not publish content. Unsaved editor changes are excluded until saved
and refreshed through the existing studio query. The summary appears in private
browsing only, creates no new stored metrics, profile fields, source references,
permissions or public projections, and offers no implicit bulk action. Saving and
publishing retain their existing access and revision checks.

Regression evidence: `work-progress-summary.test.tsx` verifies both languages,
historical defaults, zero stages, saved versus published values, refreshed records
and unchanged input; `world-studio-progress.test.tsx` verifies that filtering the
visible list does not narrow summary counts. Existing `server/work-progress.test.ts`
checks save/publication isolation and public stage omission. Exact-head CI and
hosted studio acceptance remain independent delivery gates.

Regression coverage for complete filter recovery: `world-studio-progress.test.tsx`
checks empty-result recovery across stage/search/tag/publication/sort, unchanged
summary and saved input, and disabled dirty-state controls. Existing standalone
browsing controls retain their local reset when no composed reset is supplied.

## Explicit task planning priority

The Tasks `/{wsId}/tasks/new` composer, including the Lettin handoff, offers an
optional priority choice: critical, high, normal, or low. It starts with no
priority and omits the API field until the creator chooses one. Clearing a
choice omits it again. No notebook content or metadata determines priority.
Failed or unconfirmed creation retains the choice in the locked form; mutation
retries stay disabled. Inspect the destination board before opening another form. Source-reference sharing remains unchecked and independently consented,
and the destination API retains workspace and task authorization.

Regression coverage in `apps/tasks/src/components/task-plan-composer.test.tsx`
checks each API priority, clearing, denied creation, and unchanged source consent.
The composer fixtures render choices from both English and Vietnamese message bundles.
Exact-head Tasks build and repository CI remain separate delivery gates.

## Explicit destination project association

Tasks planning, including the Lettin handoff, can associate the new task with one
existing destination workspace project. This control starts unchecked. Project
choices are loaded through the canonical authenticated internal API only after
opt-in, and the creator must select a currently available project. Opening the
composer never creates a project, task, or source reference. No notebook content
or metadata determines the project; source-link consent remains independent.

Pending or failed project reads and a selection removed by refreshed choices
block submission with association enabled. The creator can retry the read or
uncheck association to continue without a project. Failed or unconfirmed task creation preserves
the project choice in the locked single-use form. Inspect the selected board
before opening another form; neither read failures nor creation failures trigger
automatic retries. The canonical task API revalidates
workspace project ownership and destination task authorization at submission.
Existing project and board access rules apply; notebook grants and publication
never change.

`apps/tasks/src/components/task-plan-composer.test.tsx` covers opt-in-only reads,
required current selection, ID-only creation payloads, opt-out, unavailable and
removed projects, denial preservation, and both language bundles. These fixtures
double the internal API and translation hook; exact-head app builds and API CI
remain separate delivery evidence.

## Authored task planning notes

The Tasks `/{wsId}/tasks/new` composer, including the Lettin handoff, starts with
empty optional planning notes. Creators may enter up to 2,000 characters for the
chosen destination task. Notes are visible under the destination task's existing
permissions. The composer saves only this authored text as literal rich-document
paragraphs; line breaks are retained and markup is treated as text. It does not
read or prefill notebook text, artwork or profile data.

Notebook-link sharing remains independently off by default, and project association
requires its own explicit selection. An opted-in source link is appended as a
separate paragraph; unchecking it removes only the link. Empty or whitespace-only
notes add no description unless a source link is selected. Changing the destination
board preserves the authored plan while requiring a new list choice. Creation still
requires explicit submission and current destination permissions. An unconfirmed
response retains the form and notes in the existing locked recovery state, preventing
an automatic retry or duplicate create. Closing the composer discards these local
notes; they are not a durable draft.

Regression coverage: `task-plan-description.test.ts` exercises literal text, line
breaks, independent link composition and serialized size bounds;
`task-plan-composer.test.tsx` covers empty defaults, both shipped languages, optional
notes without source/project sharing, source removal, oversized input rejection and
uncertain creation recovery. Hosted task creation and the exact-head Tasks build
remain separate delivery gates.

### Compact character facts on entry cards

Character entry cards show the first three authored facts whose labels and values
are nonempty, preserving their saved order. Labels are capped at 80 Unicode code
points and values at 160, with an ellipsis for longer text; opening the full entry
retains the complete authored facts. Non-character cards and characters without
usable facts omit the preview. Text is escaped and creates no links or controls.

The private studio uses its already-authorized saved drafts. Published collections
use only the selected notebook's published entry projections, including for fact
previews; private or unavailable entries and unsaved editor buffers are excluded.
Facts are authored notebook content, not inferred public profile fields. No new
profile defaults, source reads/writes, permissions, publication actions or stored
preferences are introduced. Existing content notices remain ahead of artwork and
previews. `character-card-facts.test.tsx` covers bounds, ordering, languages,
escaping, card selection and published-versus-private snapshot isolation. Exact
head builds and hosted card layout/accessibility acceptance remain separate gates.

### Published heading links

Public notebook outlines expose section links for the displayed published entry
or notebook. Links retain the current route and locale, include only the known
published entry identifier when applicable, and omit unrelated query parameters.
Notebook links clear any entry selection. Private previews retain local outline
navigation and do not opt into these public links. No content, actor details,
access grants or publication changes are included.

Opening a section link, or changing its fragment, opens enclosing folded sections
and focuses only a rendered heading in the current article. Plain clicks preserve
that focus and scroll behavior while updating the address; modified clicks retain
ordinary browser link behavior. Missing, malformed, out-of-scope and removed
headings do not focus another article. Links address the current published text;
heading node positions can change after later edits or republication. The existing
100-heading outline bound and two-heading display threshold remain in effect.

Regression evidence: `document-outline-navigation.test.tsx` covers direct reload,
fragment changes, folded content, query omission, locale/path preservation,
modified clicks and publication/private boundaries; existing outline/search and
public-world tests preserve local navigation and published-only selection.
Exact-head builds and hosted browser acceptance remain separate gates.

### Explicit scoped JSON copies in workspace Drive

Notebook export defaults to the existing local JSON download. Creators can
explicitly choose the same workspace's Drive and must separately agree to the
destination's access and independent-copy boundary. Published exports retain
their existing projection; saved drafts still require notebook ownership and
the separate unchecked private-source consent. Choosing Drive does not imply
source consent, and private-source consent does not imply Drive sharing. Closing
or reopening the export, changing source scope/destination or replacing actor,
workspace or notebook resets the relevant consent and result state.

The explicit command exports through Lettin's actor-bound source API, then uploads
one JSON file of at most 10 MiB through the canonical workspace storage client to
the Lettin directory, with a unique generic filename and overwrite disabled. Drive
independently enforces actor/workspace permissions, directory rules and quotas.
Actor/context and dirty/owner eligibility are checked before export and each
transport stage, including signed upload and finalization. No public URL, source
grant, source write, publication or background synchronization is created. Copies
are separately stored snapshots: source retirement, revocation or deletion does
not delete a previously admitted copy; users manage it through Drive permissions.

Only successful upload and finalization is reported as saved. Failed finalization
is reported as an uploaded file awaiting indexing; other interrupted upload
attempts are unconfirmed and may have left a file. There is no automatic retry,
overwrite, rollback or deletion. Destination consent resets after an attempt,
requiring another explicit confirmation before retry. Requests admitted before
a context/permission change may finish; the guard stops subsequent stages and
stale result display, and cannot retract an already completed storage write.

Regression evidence: `notebook-drive-copy.test.ts` exercises the real canonical
client with isolated transport responses, size/format limits, unique non-overwrite
names, permission denial, stage guards and partial finalization.
`notebook-export-drive.test.tsx` covers explicit separate consents, scope/context
resets, duplicate/pending fences, dirty/owner changes and truthful copy states.
Existing export tests preserve the default download. Fixtures perform no hosted
Drive writes; exact-head builds and authenticated cross-app storage acceptance
remain separate delivery gates.

### Scoped Lettin-to-Drive authentication

Notebook copies use dedicated first-class web upload and finalization endpoints
under `workspaces/:wsId/lettin/drive-copy`. They accept a verified Lettin app
session, recheck the expected actor and workspace membership, and require Drive
management permission. Generic Drive routes retain their existing Drive/Finance
session audiences. Copy endpoints restrict uploads to non-overwriting, uniquely
named JSON objects in the Lettin directory, bounded to 10 MiB. Finalization
rechecks the workspace provider and actual object metadata; a provider change or
unconfirmed object does not report success. No source permission, publication,
automatic retry, rollback, or runtime migration is inferred from this boundary.
Signed-session route fixtures use the production token verifier, with workspace
and provider adapters isolated. Hosted authorization and upload acceptance remain
separate gates.

## Published body length

The public notebook and selected entry reader display word and non-whitespace
grapheme counts from that item's published rich-text body. These are body counts:
titles, descriptions, facts, tags, artwork, URLs, marks and other metadata are
excluded. Expandable body sections are included even while collapsed. Private
drafts and extra fields on incoming records are never used by this reader; the
private document preview does not opt into the indicator. Changing entries
recomputes counts for the selected publication, and a missing entry falls back to
the published notebook. This adds no publication, sharing or storage operation.

The reader reuses the writing-statistics model and its 25-level / 20,000-node
bounds. Words use word-like language segments; characters use graphemes excluding
whitespace. These counts do not estimate reading time or count semantic words in
every language. A visible partial-count warning appears when traversal reaches a
limit. English and Vietnamese labels explain the scope.

Regression evidence: `published-reading-statistics.test.tsx` exercises both locales,
published-only selection, notebook fallback, private-preview omission, metadata
omission and partial-warning reset. `writing-statistics-model.test.ts` covers
Unicode segmentation, leaf/attribute exclusion, block boundaries and traversal
limits. Exact-commit CI and hosted reader acceptance remain separate gates.

## Reader-local text appearance

Published notebook and entry reading views offer default, large and extra-large
text size, plus default or relaxed line spacing. The default keeps the existing
reader styles. These choices adjust inherited article body text; fixed headings,
metadata sizes and author font families retain their existing hierarchy. The
controls appear in reading views and are omitted from printed pages.

Choices live only in the mounted notebook reader, including navigation between
its published entries. Browsing temporarily hides the controls and suspends their
styles; returning to reading restores the choices. Reset restores both defaults.
Opening another notebook or leaving the reader discards the preferences. There
is no local-storage persistence, API request, content edit, creator-profile change
or publication operation. Private studio previews do not receive these controls.
Source availability, media consent and access remain enforced by existing public
projections and media routes.

Regression coverage: `reader-presentation.test.tsx` covers both shipped languages,
independent settings, reset, browsing transitions, bounded choices and notebook
remounts. `public-world.test.tsx` exercises entry navigation and preserves the
published source projection. CSS rules are scoped to the reader wrapper; real
browser layout and the exact-head Lettin build remain separate delivery evidence.

## Private Studio membership filters

The authenticated Studio notebook shelf starts with all notebooks in the actor's
current authorized overview. Creators can explicitly choose notebooks they own or
collaborations where they have editor or publisher access. This local facet combines
with the existing title/description/tag search and publication facet, preserving the
server's order. Empty filtered results offer a single clear action that resets all
three facets. Changing workspace resets them; updates to the overview immediately
replace the displayed records and roles. Shelf statistics still describe the full
current authorized shelf, rather than only the filtered results.

The controls apply to the general Studio and creative-space shelves. They perform
no extra reads or writes, persist no preferences, infer no memberships beyond the
current overview, and change no access, invitations, source consent or publication.
They do not change public catalogue/profile surfaces. Regression evidence:
`studio-membership-filter.test.tsx` covers both collaborator roles,
combined facets, empty recovery, workspace reset, revoked access and both language
bundles. These rendered fixtures do not replace exact-head CI or hosted account and
workspace acceptance.

## Reviewed private notebook copies

A notebook owner can use **Copy notebook** in the private notebook studio to
prepare an independent private copy in the same workspace. The owner names the
copy and explicitly consents to copying all saved drafts and entries. The first
submission exports through the existing owner-only saved-draft endpoint and
creates a server-validated import preview. The owner reviews the title, entry
list and import boundaries, then separately confirms creation. Opening the dialog
or preparing the preview does not create a notebook.

The copy uses existing export/import limits, projection and relationship-ID
remapping. It copies saved source documents with artwork/image sources and
hyperlink marks removed by the existing importer, excludes unsaved
editor changes, and transfers no collaborators, profile information or private
safety records. It stays unpublished and is not synchronized with the source.
Existing staged imports and new copies retain their actor/workspace permissions.
The saved export uses bounded sequential reads rather than an atomic snapshot;
the portable payload is independent of later source edits. Observing a new saved
version in the Studio discards the current review and requires a new preview.

The control is available only to owners, requires a current workspace actor and
a clean editor, and resets consent and review when the actor, workspace, source,
saved version or dirty state changes. Closing, backing out or unmounting cancels
continuation into later API stages. Backing out requires fresh consent and a new
source read. The server remains authoritative for source export and destination
import permissions. An already submitted creation may finish after closure; the
client cannot undo it and does not retry it automatically.

A confirmed creation is shown even if the Studio refresh fails, with a link to
the new notebook and an explicit warning against creating it again. An uncertain
creation result blocks another submission and asks the owner to check the Studio.
Regression evidence: `notebook-copy.test.tsx` covers staged consent, no automatic
creation, source/actor/version/dirty fences, closure, duplicate submissions and
truthful refresh/uncertain outcomes. Existing export/import API and D1 tests
retain server-boundary coverage. UI/transport fixtures are doubled; exact-head CI
and hosted browser acceptance remain separate delivery gates.

Copy creation receipts are scoped to the current actor, workspace and source
notebook in browser-session storage. Closing or reopening the dialog, or a
transient saved-version/dirty-state remount, resets consent and review but does
not clear an admitted unknown or confirmed creation. A submitted creation's
response may update its scoped receipt after closure without refreshing stale
Studio state. Unknown acceptance blocks a fresh creation; inspect the Studio
before proceeding. No automatic retry or reconciliation write is performed.
An unavailable receipt store blocks apply before transport. These receipts contain
only mutation and destination identifiers, never notebook content.
The existing notebook import sanitizer removes artwork/image sources and
hyperlink marks while retaining safe text; copies do not keep artwork URL references.

## Private Studio tag filters

The general Studio and creative-space notebook shelves default to **All tags**.
Creators can select an exact saved notebook tag from the current authorized
overview; tags on wiki entries or unsaved editor buffers are outside this facet.
The tag selector combines with membership, publication and text search, preserving
the server's notebook order. Options are distinct nonblank tags in deterministic
text order. Shelf statistics continue to describe the full authorized overview.

Changing workspace resets every facet. Clearing empty results resets all four
facets. Overview changes immediately remove withdrawn records and their tag
options; a selected tag that is no longer present resets to All tags. No additional
content reads, writes or stored preferences occur. Existing notebook access,
publication, source consent and public profile sharing rules remain unchanged.

Regression evidence: `studio-tag-filter.test.tsx` covers combined facets, exact
tag matching, duplicates, empty recovery, workspace reset, revoked records,
removed tag options and both language bundles. These rendered fixtures are
separate from exact-head CI/build and hosted browser acceptance.

## Browsing reviewed notebook entries

The private import and owner-copy review screens show up to 20 entry titles per
page, in the server preview's original order. Creators can search the titles
locally, ignoring letter case and combining accents, and clear the search to
return to the first page. The result summary always states the total entries in
the approved preview. No extra source read or network request is made.

This is a review aid, not entry selection. Searching, paging or seeing no matches
never changes the stored preview, consent, import limits or final creation scope:
creation includes every entry approved by that preview. Replacing the preview
resets search and page state. Pending creation disables the browsing controls;
existing actor/workspace/owner consent and server permission gates remain in force.

Regression evidence: `notebook-import-entries.test.tsx` exercises bounded pages,
EN/VI labels, accent-aware title matching, empty matches, preview replacement,
pending controls and unchanged apply behavior. Existing import/copy tests cover
server-preview IDs and staged creation boundaries. Hosted browser acceptance and
exact-head CI remain separate gates.

## Private Studio notebook ordering

General Studio and creative-space shelves preserve their existing server order by
default. Creators can choose ascending or descending title order over notebooks
in the current authorized overview. Ordering uses the current interface locale,
compares numbers naturally (2 before 10), and ignores case and accent differences
when comparing titles. Equal titles retain their current server order. The view
combines ordering with membership, publication, tag and search filters.

The choice stays in component state and resets when changing workspaces. Clearing
an empty filtered result restores all facets and the default Studio order. Updated
overviews immediately remove revoked notebooks; sorting never fetches historical
metadata, mutates the response, writes preferences, shares content, or changes
source access or publication. This applies to private creator shelves only.

Regression evidence: `studio-order.test.tsx` covers natural locale comparisons,
stable ties, input immutability, combined facets, workspace and empty recovery,
revoked records and both language bundles. Existing membership and tag tests
retain their coverage. Rendered tests use UI and transport doubles; exact-head CI
and hosted browser acceptance remain separate delivery gates.

## Private Studio cover-artwork filters

General Studio and creative-space shelves show all accessible notebooks by default.
Creators can find notebooks with or without saved cover artwork using a local
facet. The facet follows the existing private cover renderer and the current
authorized draft overview; it does not inspect published artwork, gallery images,
remote image availability or historical metadata. A notebook with gallery images
and no saved cover still appears under **Without cover artwork**.

The facet combines with membership, tags, publication status, search and title
ordering. Changing workspaces resets it; empty-result clear recovery resets every
facet and restores default Studio order. Updated overviews immediately remove
revoked notebooks and move records when their saved cover changes. Filtering
performs no image probes, source reads, writes, persisted preferences or sharing,
and changes no source consent, access grants or publication rules.

Rendered regressions in `studio-artwork-filter.test.tsx` cover both languages,
combined facets, saved-cover changes, revocation, workspace and clear recovery,
and absence of transport. Existing Studio facet tests retain their coverage.
Tests use local UI/translation fixtures; exact-head CI and hosted browser
acceptance remain separate gates.

# Meet calls
Source: https://docs.tuturuuu.com/platform/features/meet-calls

Run Tuturuuu Meet video calls on Cloudflare Realtime SFU, including room signaling, host controls, and in-call recording.

Tuturuuu Meet calls are Google-Meet-style conferences carried by the
**Cloudflare Realtime SFU**. This is a different product from Cloudflare Stream
Live, which powers one-to-many broadcast. Meet opens Personal from the app launcher; use the workspace picker or direct workspace links for team meetings.

Every participant holds exactly **two peer connections** to the SFU — one
publishing, one subscribing — regardless of room size. Connection count stays
fixed; bandwidth and decoding work still grow with subscribed media tracks.

## Preview resource budgets

Hosting is available to all verified Plus, Pro, and Enterprise accounts, as well as verified @tuturuuu.com accounts. Eligibility uses the current confirmed authentication email and the host’s personal subscription; session claims cannot override it. Other accounts can join by invitation. Workspace membership and Calendar permissions still apply when creating or scheduling a meeting.

A room lasts up to two hours for eligible Free hosts,
ten hours for Plus, and twenty-four hours for Pro/Enterprise. The server resolves
the host’s personal subscription in both Meet and the workspace token endpoint.
The deadline starts with the first admitted participant; reconnects keep it. Signed room
limits default to eight publishers and 96 viewers and may be lower. Server hard
ceilings still apply to every role and tier. Each publisher can register at most
six media tracks.

The server accrues participant-milliseconds through the room deadline. Expiration
ends the room, disconnects clients and persists outstanding SFU closures before
provider cleanup. Failed cleanup retries with exponential backoff from ten seconds
to one hour. Progress is persisted after each completed provider session so a
later failure does not repeat already-confirmed work. Unconfirmed tracks remain
recorded for retry/operator reconciliation.

The UI shows the room deadline and explains resource-limit failures. Browser
bandwidth counters are diagnostic, not billing evidence. Monthly workspace media
aggregation and provider invoice reconciliation remain prerequisites for selling
meeting overages. Internal or sponsored workspaces do not bypass these ceilings.

## Empty rooms and owner restoration

Meet and Parley calls end automatically after five consecutive minutes with no
admitted participant connected to the room. The durable timer starts at the last
disconnect, including recoverable transport loss; the shorter media-presence
recovery grace does not extend it. An admitted reconnect cancels the deadline.
Quiet or muted participants with an open connection keep the meeting live;
waiting-room connections do not. Rooms that have never admitted anyone do not
start this timer. The persisted deadline survives room-object hibernation, and
an alarm from an older connection generation cannot end a newer call.

Only the meeting's original owner may restore an ended call. Restoration requires
a fresh room-state version, the same authenticated actor, a same-origin request,
and a server-authorized owner command. It preserves the original room expiration,
participant usage, capacity limits, and outstanding provider cleanup. It never
creates a new resource allowance: expired rooms and rooms whose historical budget
cannot be established cannot be restored. Restoring clears old live-assistant and
share sessions. A restored empty room gets the same five-minute disconnect rule
until an admitted participant connects.

Ended-room browser storage is an actor-scoped hint, not authorization or permanent
state. Meeting-list actions revalidate it against the server so a restored room
can become joinable again. Delayed restoration work cannot clear another account's
hint or finish a newer attempt. The destination still checks access independently.

Regression coverage lives in `room-lifecycle.test.ts`,
`room-do-empty-lifecycle.test.ts`, the room-state route tests, and
`restore-room-button.test.tsx`. These source tests do not establish actual deployed
alarm behavior or browser reconnection; verify both on the deployed commit.
Cloudflare validation runs the explicit durable-object test files from
`RUNNER_TEMP`, using absolute checkout paths. Running `bun test` from the repository
root invokes its preload and redirects to the monorepo test suite instead.

## Pieces

Meet's pre-join preview and in-call controls are rendered from
`packages/meet-core/src/features/call`. Keep that package in the Tailwind source
scan of `apps/meet/src/app/[locale]/meet.css` when moving shared call UI. The scan
must be in the stylesheet that imports the shared UI theme; a separate CSS import
containing only `@source` does not generate those utilities for Meet.

`room.ts` is a pure reducer: it returns the next room snapshot plus the messages
to fan out and any Cloudflare work to perform. Both transports run the same
reducer, so the Bun server and the Durable Object cannot drift.

The app secret never reaches a browser. The client receives only a short-lived
HMAC join token; the room server performs every SFU call on its behalf.

## Running a call locally

Create an SFU app under **Cloudflare dashboard → Realtime → SFU** and put the
values in `apps/meet-realtime/.dev.vars` (gitignored). See the
`apps/meet-realtime` README for variable names.

```bash theme={null}
bun apps/meet-realtime/src/verify-credentials.ts
```

Start the room server and the app, then open a meeting and press **Join call**:

```bash theme={null}
bun wrangler dev -c apps/meet-realtime/wrangler.jsonc
```

Point the app at it with `NEXT_PUBLIC_MEET_REALTIME_URL`, which defaults to
`ws://127.0.0.1:8786/realtime`.

## Verifying without a full environment

Two checks run against real Cloudflare without needing Supabase, auth or seed
data.

**Signaling and host controls** — boots the room server, connects a host and a
guest, and exercises the lobby, chat, hand raise, force mute and removal:

```bash theme={null}
bun apps/meet-realtime/src/integration-check.ts
```

**Media** — bundles the real client modules, opens two browser peers and proves
audio and video traverse the SFU. Tracks are synthesised from a canvas and an
oscillator, so no camera or microphone permission is needed:

```bash theme={null}
bun apps/meet-realtime/src/media-check.ts
```

Then open `http://127.0.0.1:7898/?peer=a` and `?peer=b`. Each tab reports
`bytesReceived` and `framesDecoded`, and renders the other peer's video.

## Two contract details worth remembering

Both of these were found only by running against the live API, and both produce
confusing errors if reintroduced:

* **Read `transceiver.mid` only after `setLocalDescription()`.** It is `null`
  before that, and publishing without it fails with
  `406 tracks[0]: Missing mid in track`.
* **Do not send a `sessionDescription` when pulling remote tracks.** Cloudflare
  returns the offer, which the client answers via `sfu.renegotiate`. Sending an
  empty SDP is rejected as a malformed event.

Creating a session with no local offer must also send **no request body** at
all; `{}` and `{autoDiscover: true}` are both rejected.

## Attributing remote tracks

An inbound track arrives with an opaque id, so nothing on the
`RTCPeerConnection` says who published it. Attribution comes from the track
name, which is deliberately `<deviceIdentity>-<kind>`: the subscribe response returns a
`mid` per track, the client maps `mid → userId` (the device identity, not
the account ID), and the `track` event is matched against that map.

This is load-bearing. Keying inbound streams by the browser's track id instead
means the UI cannot tell participants apart, and every tile ends up rendering
whichever stream arrived first.

One `MediaStream` is accumulated per participant, since their audio and video
arrive as separate tracks but belong to one tile. The map and the streams are
both cleared on reconnect, because mids are only meaningful within a session.

## Reconnection

Signaling drops are expected: servers restart, networks blip, laptops sleep. The
client reconnects with exponential backoff and full jitter, so a room server
restart does not produce a synchronised retry stampede from every participant.

Two details make it actually work:

* **Each attempt fetches a fresh join token** from Meet's Cloudflare-local
  `POST /api/meet-call/<meetingId>/token`, preserving the current device identity. Join
  tokens are short-lived and calls are not, so reusing the original token would
  let a client reconnect for ten minutes and then fail forever on
  "Reconnecting…". Membership is re-checked on every refresh.
* **A reconnect rebuilds room state.** The client re-announces itself with
  `presence.join` and clears its subscription ledger and peer connections, so
  every remote track is pulled again. Without that it would rejoin a room it
  could not see.

A clean close (`1000`) and a host removal (`4403`) are decisions, not blips, and
are never retried.

Media survives a signaling drop: the peer connections to the SFU are
independent, so audio and video keep flowing while signaling is down.

```bash theme={null}
bun apps/meet-realtime/src/reconnect-check.ts
```

That check stops the room server mid-session and asserts the client recovers,
mints a new token for the retry, and stays closed when the close was intentional.

## Meeting codes

Every meeting has a shareable code and a `/r/<code>` link, surfaced by the **Copy invite** button in the call header.

The code is a reversible Crockford base32 encoding of the meeting id rather
than a stored random string, so there is no schema change, no collision risk
and no lookup table — an invalid code is rejected before any query runs.
Decoding tolerates case, spaces, dashes, and the `I`/`L`/`O`/`U` characters
Crockford omits, folding them onto the digits the sender meant.

Only signed-in accounts with a verified `@tuturuuu.com` address can create
online meetings. Other signed-in users can follow an invitation and ask the
host to admit them. Sign-in preserves the room link, and an existing profile
display name is reused. A missing name is saved to the profile before joining.

## Joining and admission feedback

Meet distinguishes connecting to signaling from waiting for host approval. A
confirmed waiting response means the request was sent; the lobby shows approval
copy and a cancel-and-leave action without a spinner. After 60 seconds it explains
that approval is still outstanding and suggests contacting the host or returning
later. It does not resend the request, auto-admit the participant, or treat a slow
host response as a connection failure. Host presence is not inferred from the
absence of a presence snapshot in a waiting response.

The signaling readiness deadline is 10 seconds per attempt, including refreshed
token resolution and the server's `ready` response. Automatic recovery is limited
to 12 retries. The budget resets only after the socket stays open for 30 seconds
after protocol-ready; repeated ready/disconnect cycles still exhaust it. The first
pending admission reconnect uses normal backoff immediately; subsequent attempts are
limited to one per minute, including failed token refreshes. Both the stability
window and throttle use a monotonic clock, unaffected by wall-clock changes. The
server currently re-announces pending admission on every connection,
even for an existing waiting entry; this client limit bounds those notifications
but does not provide server-side deduplication across tabs or page reloads. Late
responses
from expired attempts cannot revive them. Connection errors offer retry and leave;
room-capacity refusals cannot leave a disabled Connecting spinner. Preparing the
page or controls for more than 30 seconds replaces its spinner with an explanation
and a way back. Retrying a join starts from the invitation; it does not grant access.

Admitted participants see confirmation before choosing **Join now**. Declined
requests and host removal show distinct messages with a way back, rather than
claiming the participant voluntarily left. Ended rooms retain the existing ended
screen. Invalid or inaccessible room links show a privacy-preserving unavailable
message; room-page failures offer retry. Meet's retained Next routes and native
router use the same feedback components. Shared Meet/Parley call controls ship
English and Vietnamese copy; admission and workspace access rules are unchanged.

Regression coverage: `join-flow.test.tsx` exercises pending-to-admitted,
pending-to-denied, prolonged waiting, removal, recovery, and loading deadlines.
`signaling-readiness.test.tsx` covers hung token resolution, missing protocol-ready,
bounded retries, cancellation and late-event fences. `room-route-feedback.test.tsx`
covers the native route's bilingual missing/error feedback. These fixtures do not
establish successful hosted SFU/TURN connectivity or reproduce a specific user's
production account failure.

Meet's first-paint theme initializer is a literal script, not a serialized
function. Worker bundlers that preserve function names can inject `__name` helpers
inside functions; serializing such a function with `toString()` loses those helper
bindings. The Meet theme provider leaves the upstream initializer inert and keeps
its hydrated theme context, while its own initializer applies the same configured
theme before hydration. Native and retained Next providers both use it; other
satellites keep their existing provider. `theme-provider.test.tsx` reproduces the
helper failure against the installed upstream script and executes the replacement
with saved/system/forced themes. Require exact-commit CI and deployed first-paint
verification; this console repair alone does not prove an authenticated join works.

## Call controls and admission

The sending and receiving arrow badges open connection details. The displayed
latency is the selected SFU connection's round-trip time, not a measurement to
another participant. Unavailable measurements show a dash. A device stays busy
until its SFU publication and peer connection are ready; a local preview alone
does not prove another participant receives media.

Choose automatic, grid, spotlight or sidebar layouts. Each camera and shared
screen can be focused independently or opened fullscreen. Videos fit their
frames without cropping. Fullscreen uses a viewport-sized fallback when the browser denies native fullscreen. Camera color filters and soft portrait processing run
locally and affect the transmitted video; no image is sent to an AI provider
for these effects. Soft portrait is subtle whole-frame smoothing and lighting,
not face-aware cosmetic placement. Reactions are temporary and rate limited.

The host's People panel contains persistent approved participants. Admission
adds a signed-in identity to this room's approved list, so reconnects and later
visits bypass the lobby. Forgetting approval requires admission on the next
visit; removing a current participant also removes their saved approval.

Transcript and notes sharing is private by default. The host can enable it for
admitted and approved participants, including guests outside the workspace.
Every non-host notes read checks the signed room policy on the Durable Object;
removing permission blocks subsequent reads. Existing downloaded information
cannot be recalled. Transcription mutations remain host-only.

Leaving stops local capture and signaling immediately while recording/notes
finalization continues on the post-call screen. The host can leave alone or end
the room for everyone. Ending is durable, disconnects participants and prevents
rejoining that room. Approved participants can still read shared post-call
notes while the host's sharing setting permits it. Room policy and approval
state live in Cloudflare Durable Object storage; no self-hosted server or new
database migration is required.

## Missing microphone or camera

If enabling a device reports that none was found, the browser returned
`NotFoundError` before media reached Cloudflare. Connect an input device or use a
browser that can see it. Permission denial and a device that cannot start are
reported separately; check browser/system privacy settings for denied access,
and other apps using the device for startup failures. Repeated activation uses
one notification per device rather than stacking identical warnings.

## Recording

A host can record from inside the call. The control creates a row in
`recording_sessions` through the existing `/record` endpoint, captures local
audio with `MediaRecorder`, uploads through the existing `/upload` endpoint, and
broadcasts `recording.state` so every participant sees the indicator.

Because it reuses those endpoints, a call recording is indistinguishable from
one started on the meeting page and feeds the same transcription pipeline.

## Cloudflare hosting

Meet's frontend is packaged with OpenNext and runs on the `tuturuuu-meet`
Worker. Realtime runs on `tuturuuu-meet-realtime`, with one Durable Object per
meeting. Browsers send audio, camera and screen media directly to Cloudflare
Realtime SFU. Neither Worker requires an internal host, Docker or a Tunnel.
Shared platform authentication and APIs remain at `tuturuuu.com`, with the
existing managed Supabase database; this does not move platform API ownership.

`apps/meet/wrangler.jsonc` configures frontend assets, image optimization,
self-reference and the `tuturuuu-meet-cache` R2 bucket. `apps/meet/open-next.config.ts`
configures the incremental cache. Build with `bun run build:cloudflare` from
`apps/meet`; use `NEXT_WEBPACK_BUILD=1` for the existing local Webpack fallback.
The normal CI build uses Turbopack. `bun run preview:cloudflare` runs the built
frontend in workerd for runtime verification. Run `bun run cf:typegen` after
binding changes and `bun run cf:typecheck` to validate the generated environment
with Worker types separately from browser types. CI runs this check after building.

The frontend requires `NEXT_PUBLIC_SUPABASE_URL`,
`NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`, `SUPABASE_SECRET_KEY` and
`MEET_REALTIME_TOKEN_SECRET`. Configure a separate app-coordination signing secret
only if the platform uses one. Public Supabase values are also build inputs;
private secrets belong only in Worker runtime configuration. Realtime requires
its dedicated token secret and the two Cloudflare SFU credentials from its README.
Direct Worker verification requires a `wss://` endpoint; `ws://` is accepted
only for loopback development (`localhost`, `127.0.0.1`, or `[::1]`). Endpoints
must not include credentials, a query, or a fragment. Connected participants get
a ten-minute heartbeat grace period for throttled tabs; the Worker closes and
removes silent connections after that bound so ghost participants cannot persist.
All call token issuers and verifiers must share `MEET_REALTIME_TOKEN_SECRET`;
Supabase service keys are not used for call tokens.

`.github/workflows/meet-cloudflare.yaml` validates both Workers and deploys
realtime before the frontend on `production`. It uses
`MEET_CLOUDFLARE_API_TOKEN`, or the existing account deployment credential
`COLAB_CLOUDFLARE_API_TOKEN` while bootstrapping. The deployment token needs
Workers Scripts:Edit and Workers R2 Storage:Edit on the Tuturuuu account, plus
Workers Routes:Edit limited to `tuturuuu.com`. Store the dedicated token in the
`meet-production` GitHub environment, restricted to the `production` branch.
A Worker-only token can upload signaling but fails when OpenNext populates the
R2 cache, so verify the complete frontend deployment and authenticated smoke check. Automatic Vercel Meet production
deployment is disabled in the CI switchboard. Preserve the Vercel deployment until the canonical
Cloudflare sign-in and call checks pass so rollback remains available.

Before cutover, deploy the frontend with an explicit verification configuration
that has no custom-domain routes. Verify public rendering and API guards there, then deploy the checked canonical
configuration. Sign-in returns to the registered canonical hostname, so complete
signed-in navigation, API proxying and an authenticated two-participant call
after cutover. Do not change DNS until both Worker versions and runtime secrets
are verified, and confirm the active versions after deployment.

For a direct Worker protocol check, set `MEET_CHECK_REALTIME_URL` to its
WebSocket endpoint when running `integration-check.ts`. The same variable works
with `media-check.ts --call-controller`; localhost then hosts only the test page,
not signaling. The check uses a fresh synthetic room and performs no database
meeting writes. A health response alone cannot detect broken SFU calls.

Native fetch must retain its global receiver in Workers. The SFU client binds
`globalThis.fetch` to `globalThis`; calling an unbound native fetch as an object
method throws `Illegal invocation`, even though Bun-based checks pass.

## URL shapes

Meet matches the other satellites: workspace routes sit directly under the
workspace segment, with no `/workspace` prefix.

`plans` and `r` are static segments, which is what frees the bare `/<wsId>`
position — public plan pages previously occupied it, so `/<wsId>` and
`/<planId>` could not coexist.

Every retired shape is permanently redirected in `proxy.ts`:
`/workspace/*` → `/*`, `/call/<wsId>/<meetingId>` and `/join/<code>` → `/r/<code>`,
and a bare 32-hex segment → `/plans/<planId>`, so shared plan links keep working.

## Hosting eligibility and call verification

The meetings POST handler checks the creator’s current confirmed authentication
email and personal subscription. Verified Plus, Pro, and Enterprise accounts can
host regardless of email domain; verified `@tuturuuu.com` accounts remain eligible
on Free. Workspace membership is required, and Calendar scheduling additionally
requires Calendar permission. Both instant creation and scheduled creation use a
trusted server writer only after these checks; the actor is always server supplied.
The older restrictive direct-client INSERT policy remains in place. No production
migration is needed to unlock paid hosting through the application API.

Existing workspace members may still join calls regardless of their email domain.
Signed-in invitees outside the workspace can join a meeting whose creator is an
eligible verified host. They wait in the lobby until the host admits them; the
invite grants no workspace membership, recordings, or archived transcript access.
Guests see a transcription capability notice before joining and in the
call. Meeting-only access is rechecked by the Cloudflare-local
`POST /api/meet-call/:meetingId/token` route whenever the call reconnects. The
creator must still belong to the workspace to receive host privileges.

Anonymous invite navigation preserves `/r/<code>` (including locale) through the
central login and token verification handoff. The call page resolves invite access
directly rather than redirecting non-members through a workspace dashboard. If a
login seems to lose the invite, inspect the nested `returnUrl`/`nextUrl` chain and
the call authorization separately.

Signed-in root navigation opens online meetings. Hosts can start an instant
meeting, and members can enter a room code or paste a same-origin room link.
Legacy UUID room links remain accepted.

The client keeps an audio playback element mounted when cameras are off, selects
the screen track while someone presents, and restores the camera after a share
ends. Publishing uses stable senders with `replaceTrack` for device toggles and
share restarts. Subscribe negotiations are serialized and retried because track
announcements can arrive before the SFU has finished publishing. A ten-second
heartbeat keeps presence alive. Reconnect refreshes the token, preserves the
member's speaker role for calls, and republishes enabled media.

To test the actual React call controller and participant tile against the live
Cloudflare SFU, run the local-only harness:

```sh theme={null}
bun --env-file=apps/meet-realtime/.dev.vars apps/meet-realtime/src/media-check.ts --call-controller
```

Open `http://127.0.0.1:7898/?peer=a` and `http://127.0.0.1:7898/?peer=b` in separate
tabs. Peer A is a host and B is a speaker. The harness supplies synthetic audio,
camera, and screen sources; it does not capture the desktop or microphone.
Verify nonzero received audio energy, zero energy while muted, decoded video
frames, screen-to-camera transitions, two-way chat, host mute, and reconnect.
Stop the harness after testing. It uses scratch room identities and does not
create application database records. This proves the media path through the
real SFU, but does not certify production authentication, OS device permissions,
physical devices, or restrictive corporate networks. Those require additional
checks on the canonical deployed app.

The restrictive insert policy protects authenticated direct database writes.
Satellite app-session requests use a service-role client, so their creation gate
is the API check against the current confirmed email fetched from Supabase Auth; service-role
requests bypass RLS. Neither path trusts handoff or user-editable profile metadata for the
creation domain. The policy is not an additional RLS layer on service-role inserts.

If a browser blocks remote autoplay, use **Play meeting audio**. Any keyboard or
pointer interaction also retries playback. The controller harness deliberately
rebuilds its client bundle on each reload so ongoing controller edits are exercised
without restarting its signaling room.

Presence stays active while its Durable Object WebSocket is open, even when a
background browser delays heartbeats beyond the normal expiry window. Close/error
handlers remove disconnected participants. The direct Worker integration check
includes a 40-second idle interval to verify presence and host controls survive
browser timer throttling.

The `meet-production` GitHub environment must allow only the `production` branch
and contain `MEET_REALTIME_TOKEN_SECRET` matching the Workers and platform API.
Deployment checks required Worker secret names before rollout, then runs the
signed-token realtime/SFU integration check against the canonical endpoint.

## Gemini transcript and post-call notes

Meet's own Cloudflare frontend Worker serves `/api/meet-ai/:wsId/:meetingId` and
its `/chunks` endpoint. These routes do not depend on a self-hosted recording
server. Configure `GOOGLE_GENERATIVE_AI_API_KEY` as a secret on `tuturuuu-meet`;
without it, the panel reports that Gemini is not configured. Do not put the key
in public environment variables or the browser. Existing deployment credentials
do not grant permission to transfer a Gemini key to a new destination.

Apply `20260907040000_meet_ai_sessions.sql` through the normal database release
process before enabling the feature. A missing schema produces a visible
unavailable state without breaking the call. Browser reads require workspace
membership; only the meeting creator can start transcription, submit audio, or
finalize notes. The server independently verifies the signed Meet app session,
workspace membership, meeting ownership, and same-origin mutation requests.

The host opens **Transcript & notes**, tells participants that audio will be sent
to Gemini, then starts live transcription. The panel and call header show an
active-session indicator to members. The browser mixes its current microphone
track with received participant audio; it does not request another microphone or
capture unrelated desktop audio. Muted tracks contribute silence. AudioWorklet
emits independent mono 16 kHz WAV chunks about every ten seconds, skipping silence.
Transcripts arrive after Gemini processes each chunk. This is chunked live
transcription, not word-by-word captions, and overlapping speech is not assigned
to guessed speaker identities.

**Stop & generate notes** flushes pending audio and generates a summary, decisions,
action items, and open questions. Leaving through the call's leave control does
this automatically for the capturing host. Keep the page open while it finishes.
If finalization fails, leaving still works and notes can be recovered from meeting details.
Abrupt tab closure or a browser crash can lose the current unsubmitted chunk;
return to meeting details and finish the active session to generate notes
from saved text. Interrupted or failed captures are identified as incomplete.
A stuck notes attempt becomes eligible for manual recovery after two minutes;
this can incur another provider charge and the earlier unknown usage remains
visible in statistics. Notes are AI generated and should be reviewed.

Only text, notes, and provider usage are retained in Supabase, not audio files.
After a transcription provider result has been generated and settled, the server
retries only its same-attempt transcript write up to three total times, including
returned storage errors and rejected save promises. The transcript, structured
speaker usage, and cost stay identical; this retry does not regenerate audio or
repeat settlement. A missing attempt row is a conflict, and failed-attempt cleanup
only changes a still-processing row, protecting an uncertain completed commit.
Exhaustion returns a safe failure, not a completed receipt. This is request-local
persistence recovery: a later request may reserve a new failed attempt and incur
another provider charge; there is no cross-request charging guarantee. Synthetic
chunk regressions cover thrown/returned errors, CAS conflict, exhaustion, and the
completed-row cleanup predicate; they do not prove live database or provider behavior.

The capture queue holds up to 60 chunks in browser memory and retries each stable
chunk ID for up to five minutes. A recovery status shows pending chunks. Tab closure
still loses buffered audio; keep the page open until uploads finish. Overload and
unrecoverable chunks remain explicit gaps. Sessions retain the three-hour/1,080-chunk
limit. Apply `20260909153000_meet_transcription_recovery.sql` before enabling server
retries: row locks and attempt leases prevent overlapping provider calls and stale
writes. Up to five provider attempts are allowed; uncertain prior costs remain unpriced.

The default model is `gemini-3.1-flash-lite`. Costs are informational estimates in
USD, computed on the server from Gemini usage metadata and a dated price snapshot:
text input $0.25, audio input $0.50, and output including thinking \$1.50 per million
tokens (standard API pricing checked September 7, 2026). The panel separates
transcription and notes costs, submitted audio minutes, and input/output tokens.
Missing provider usage and interrupted attempts are shown explicitly; totals are
not invoice totals and do not debit workspace AI credits. Review
[Google's pricing](https://ai.google.dev/gemini-api/docs/pricing) when changing the
model or rates. Never log raw audio, transcript text, or credentials.

Validation: use the Meet AI API/audio tests, AI package usage tests, a real browser
AudioWorklet check, and the disposable database runner with
`--test supabase/tests/meet-ai.sql --typegen packages/types/src/supabase.ts`.
The disposable runner copies Git-tracked files; new migrations and tests must be
tracked before running it. Run the Meet Cloudflare build before deployment and
verify a signed-in live transcript plus persisted notes against Gemini afterward.

### Production upload and provider diagnostics

If an audio chunk is rejected before reaching the Worker, inspect the request's
Ray ID in Cloudflare Security Analytics. Binary WAV uploads can trigger OWASP
`949110: Inbound Anomaly Score Exceeded`. Meet has a logged managed-rule exception
(`6bcb3c2398ca4f2896222b76bc1ae9b2`) before the managed rulesets, skipping only rule
`6179ae15870a4bb7b2d480d4843b323c` in the OWASP ruleset for this expression:

```text theme={null}
(http.host eq "meet.tuturuuu.com" and http.request.method eq "POST" and http.request.uri.path wildcard "/api/meet-ai/*/*/chunks" and starts_with(http.request.headers["content-type"][0], "multipart/form-data"))
```

Keep the other managed rules active. The Worker still checks the signed actor,
meeting ownership, same-origin request, byte limit, canonical WAV format, and
atomic usage reservation. Do not replace this with a domain-wide WAF bypass.

Provider failures return a safe `502` response. Worker logs contain only a fixed
failure category and provider HTTP status, never provider messages, request URLs,
credentials, audio, or transcripts. Use those categories to distinguish invalid
keys, disabled APIs, quota, access, location, timeout, and runtime failures.
An accepted chunk is not automatically resubmitted to the provider; preserve its
unknown-cost record when investigating a failed attempt.

Google's request logs identified the production synthetic failure as
`412 FAILED_PRECONDITION: User location is not supported for the API use`.
The Meet frontend Worker therefore uses `placement.region: aws:ap-southeast-1`
to run near Singapore, which Google lists as a supported Gemini API region.
Signaling and media remain on the separate globally distributed realtime Worker
and Cloudflare SFU. This is a Cloudflare placement hint, not an AWS deployment or
a strict geographic guarantee; verify the provider path after each release.
See [Cloudflare placement](https://developers.cloudflare.com/workers/configuration/placement/)
and [Gemini supported regions](https://ai.google.dev/gemini-api/docs/available-regions).
Missing keys are classified as `missing_configuration` and return a safe 500;
provider failures return a safe 502 with fixed-category diagnostics.

### Media connection readiness

`SFU_HTTP_425` means the SFU rejected an operation before the session was ready.
After the first offer/answer exchange, subsequent publish and subscribe operations
wait for the browser peer connection to reach `connected` (up to 12 seconds).
`SFU_CONNECTION_TIMEOUT` and `SFU_CONNECTION_FAILED` distinguish a stalled or
failed transport from device permissions. Rejoining creates fresh peer connections.

Receiving a successful SDP response alone does not prove playback: the client
reconciles negotiated receiver tracks with participant ownership and only marks
live, attached tracks subscribed. This also handles receiver reuse without another
browser `track` event. Production verification should include late guest admission,
rapid microphone/camera activation, and media flowing in both directions.

### Muted tracks and media reconnection

Cloudflare expires tracks after 30 seconds without media packets. Keep muted
microphone/camera tracks attached with `enabled = false`, which sends silence or
black frames, so unmuting resumes the existing subscription. Detaching a sender
with `replaceTrack(null)` silently invalidates that track after the timeout.
Stopped screen shares are explicitly closed at the SFU with `force: true`,
removed from the publication ledger, and published afresh when sharing resumes.

Media connectivity is independent of the signaling WebSocket. Meet rebuilds a
failed peer after one second, a disconnected peer after ten seconds, or an
unfinished connection handshake after twenty seconds. Brief disconnections that
recover within the grace period retain the existing connection. Publisher
recovery republishes enabled sources; subscriber recovery clears its ledger and
pulls the current room tracks again.

### Diagnosing media on another device

Open **Connection** in the call header to inspect outgoing and incoming media
transport states and packet counts. **Reconnect media** rebuilds both media
connections without leaving the room. **Copy diagnostics** includes only
transport states, aggregate media counters, and receiver track states; it omits
SDP, IP addresses, track identifiers, participant names, and authentication data.

A working local camera preview proves capture succeeded, but does not prove other
participants can receive it. If enabling a device shows a transmission warning,
record its diagnostic code and the action that triggered it. `SFU_HTTP_*` identifies
an upstream SFU rejection; `SIGNALING_*` identifies the signaling connection or
request timeout; `RTC_*` identifies a browser peer-connection failure. The code
contains no raw provider message, SDP, credential, or meeting content. A successful
retry clears the previous warning for that device. Reproduce on the affected device
before changing transport settings; synthetic sources in another browser do not
establish physical-device compatibility. Browser audio probes should attach the
received stream to a playing media element before measuring decoded audio energy;
packet counts or an unattached analyser alone do not establish working playback.

### Participant names and admission

Meet reuses the participant's saved profile display name. If it is missing,
the invite page suggests an available account name and asks the participant to
confirm or edit it before opening the realtime session. It saves the name through
the current-user profile API, and refreshes the same invite. Later joins reuse the
saved display name. A failed save leaves the form open for retry; a temporary
profile lookup failure does not invite the user to overwrite an existing name.

The lobby separates connection progress from waiting for host admission. Guests
can leave while waiting, and their preview is not published until they join.
Host admission actions are labeled, and a muted participant has one mute status
indicator rather than an additional redundant mute action.

### Cloudflare browser integrations

Meet must not mount Vercel Analytics or Speed Insights: their `/_vercel/*` script endpoints are not hosted by the Cloudflare Worker. A 404 for those scripts is separate from SFU media delivery.

The platform user-config API uses the shared satellite app-session audience list in `apps/web/src/lib/api-auth-audiences.ts`. Keep Meet in that list and in the Rust current-user session targets. A successful local Meet call-token refresh does not verify authorization for proxied platform APIs such as `SHOW_VERSION_BADGE`.

A recovered publisher announces a new SFU session for its stable microphone,
camera, or screen track name. The room retires older registrations for that
participant and track and broadcasts `track.closed` before the replacement
`track.published`, so listeners discard obsolete receivers. Snapshot consumers
also deduplicate old session registrations left by earlier Worker versions.

## SFU commit boundary

Both realtime transports use `MeetCommandExecutor`. SFU operations are serialized
per participant, while other participants and leave/end controls stay responsive.
A track registration or closure is persisted and broadcast only after Cloudflare
returns success without per-track errors. The completed operation is applied to
the latest room snapshot so concurrent host settings are preserved; a participant
who left during the request cannot be resurrected. Closing a track requires the
registered owner to match the signed caller.

Recording finalization targets the specific session with an idempotent status
update, never another toggle. SPA unmount and leave share the same finalizer. The
post-call navigation buttons wait for finalization while capture and signaling
are already stopped. A hard browser/process termination can still interrupt an
upload; do not claim a saved recording without its storage receipt.

## Screen audio and in-call controls

Screen sharing requests audio separately from the microphone, including browser
hints for window and system audio. The browser picker remains authoritative:
capabilities depend on browser, operating system, and the chosen source. Select
**Share audio** when offered. The in-call badge reports whether captured audio is
available; a video-only capture still works. Remote screen tiles play shared audio,
and muting the microphone does not mute shared audio. Stopping screen sharing
stops both its audio and video tracks. The host's shared audio is included in the
existing consent-controlled transcription mixer.

The host can click the meeting title to rename it in a dialog, without changing
the meeting time or calendar linkage, and hover or keyboard-focus a participant's
name to mute their microphone. Touch layouts keep the action visible. Participants
cannot remotely unmute someone. Raised hands use a prominent orange tile badge and
outline; reactions use larger, labeled overlays with reduced-motion support.
Transcript and Notes have separate tabs, with expandable usage and session notes.

Receiving badges distinguish an enabled remote device from an arriving track.
A connected SFU receiver with a live track is not proof of packet delivery. Meet
checks receiving counters with a 20-second grace period and rebuilds only the
subscriber when an expected stream never delivers packets or remains muted and
stalled. Automatic rebuilds are limited to one per minute. Missing statistics,
normal silence/DTX, and a static screen with an unmuted track do not trigger this
recovery. This is a recovery mechanism, not evidence that an affected physical
network or device is fixed; verify each audio/video direction on those devices.

Packet counters that are unavailable or invalid remain unknown rather than being
counted as zero. The tile indicator distinguishes unknown packet statistics from
confirmed receiving and waiting states. Ended tracks are excluded from stall
recovery. Persisted title announcements are acknowledged by the room and retained
across signaling reconnects until delivery; intentional leave clears that outbox.

A browser can keep its signaling socket in `CLOSING` while waiting for a remote
close handshake. Removal, admission denial, and meeting-end messages stop retries
immediately, before the delayed policy close event arrives. Meet watches that state and retries after a five-second grace
period instead of waiting for the browser's longer timeout. Events from the old
socket cannot change the replacement connection or settle its pending requests.
Intentional leave and promptly received policy-close codes still stop retries.

### Media timeout and managed TURN fallback

`SFU_CONNECTION_TIMEOUT` means ICE/DTLS did not connect to the media service.
A working local microphone preview does not prove that audio can reach the SFU.
Meet now obtains expiring Cloudflare TURN credentials with each admitted SFU
session and installs them on both publishing and receiving peer connections
before negotiation. UDP, TCP, and TLS on port 443 provide alternative network
paths; no self-hosted relay is required. Port 53 is filtered because browsers
restrict it. Direct connections remain eligible, avoiding unnecessary relaying.

Create a dedicated Meet TURN app in Cloudflare and install only
`CLOUDFLARE_TURN_KEY_ID` and `CLOUDFLARE_TURN_API_TOKEN` in the
`tuturuuu-meet-realtime` Worker before deploying this change. The permanent key
never reaches the browser or logs. Only authenticated, admitted participants
can create sessions and receive the 24-hour credentials. Each replacement
session receives fresh credentials. Missing configuration or generation failures
log a fixed warning and preserve direct ICE connectivity. Production checks still
fail if relay credentials are unavailable, so degraded coverage stays visible.

To verify restrictive-network behavior, run the isolated call-controller harness
against the production Worker and open peers with `&relay=1`. Confirm a selected
relay candidate, incoming audio energy and decoded video in both directions;
repeat with `&relay=tls` to allow only TLS/443 and rule out direct UDP success. Synthetic
media avoids recording real microphones or cameras. This does not substitute
for checking previously affected physical devices.

### Audio works but a remote camera stays blank

The receiving watchdog also handles video tracks with no initial RTP report when
another incoming track proves that the browser exposes inbound statistics.
WebRTC may create an inbound report only after the first packet, so an absent
video report is not always an unsupported-statistics case. A live, muted video
track with enabled remote camera and working sibling inbound stats gets a
20-second grace period before subscriber recovery. With no usable inbound
statistics at all, the watchdog continues to avoid guessing.

Video that receives packets but reports zero decoded frames also gets a separate
20-second first-frame deadline. Incoming byte growth does not reset this deadline.
A successfully decoded static camera or screen does not trigger this condition.
Disabling media, replacing a publication, or ending its track clears the deadline.
Recovery rebuilds the subscriber connection while preserving local publishing and
room membership, using the existing one-minute recovery throttle. This corrects
missed recovery cases; it does not identify a codec or network fault on a device
that has not been inspected.

### Decoded video with an avatar-only tile

If incoming diagnostics show decoded video frames and a live, unmuted receiver,
inspect presentation before resetting the SFU. Tile readiness uses a React external
store so an unmute event between rendering and listener installation cannot leave
an old avatar visible. Audio and muted video have separate media elements; camera
replacement preserves the audio element's stream. Playback retries on metadata and
can-play events after a replaced stream interrupts `play()`. The incoming-video
retry action preserves local publishing. Rejected subscription responses and stale
publisher sessions cannot take ownership of a replacement receiver. Unexpected socket closure retains presence and SFU tracks for a 30-second grace period. A resumed device keeps its media connections; intentional leave still releases them immediately.

### Call alerts and post-meeting privacy

Join, admission-request, chat and raised-hand changes display actionable in-call
notifications. Short sound cues are unlocked by browser interaction, rate-limited,
and can be muted from the header. Initial snapshots, reconnect snapshots and the
participant's own actions do not produce notification bursts.

Live notes sharing and post-meeting sharing are separate room settings. Both are
disabled by default. The host may enable post-meeting access for approved people
from the transcript panel or centered ended-meeting screen. Ended invite/detail
pages perform a signed read-only room-state check and never open a call socket.
Notes open on demand with transcript and notes tabs; there is no join button for
an ended room. The authenticated host-only sharing mutation reaches the room
Worker over signed HTTP and also works after its WebSocket has closed.

AI read responses use explicit field projections. Non-admin readers receive no
raw provider usage and null cost/token fields; cost totals and breakdowns render
only for the room admin. Sharing permission is rechecked on every notes request.

## Room settings, recordings, and devices

The in-call settings dialog contains audio/video input, supported audio output,
connection diagnostics, notification sounds, and admin-only cost breakdowns.
Changing an input replaces its track on the existing call. Output selection uses
`HTMLMediaElement.setSinkId` where supported; unsupported browsers explain the
limitation instead of presenting a non-working selector.

Each browser call generates a device ID. The server derives a signed device
identity from the account and device IDs; media and SFU sessions use that identity,
while admission approvals use the account ID. Joining another device offers a
switch or an additional connection. Switching only removes that account's other
connections. Keep microphones or speakers muted on nearby devices to avoid echo.

Recording permissions start disabled for participants. Admins can independently
share saved recordings and allow participants to start/stop recording. The Durable
Object holds one recording lease for the room; a remote stop cannot be overwritten
by a delayed start. The recording device composites its available video and mixes
audio locally, and must remain available until saving completes. Recordings stop
at 55 MiB and upload directly to the creator's personal Drive using a scoped signed
URL, followed by server-side metadata verification. Failed saves offer a local copy.
This is browser capture, not a Cloudflare server-side recording service.

## Chat and Mira

Room chat supports Markdown, avatars, and up to five 25 MiB attachments per message. Chat saving defaults on; admins can stop retaining new messages in Settings without deleting earlier messages. The recent 500-message snapshot survives Worker eviction; chat retries reuse a stable message ID to avoid duplicates after lost acknowledgements.
Files use the creator's personal Drive provider and storage capacity checks. Room
admission controls attachment access; a signed URL is short-lived. Mention
`@Tuturuuu` or `@ttr` (case-insensitive) to ask Mira using the recent 40 room
messages. Uploaded file contents
are not automatically read by Mira. The mention author's personal AI allowance is
checked and reported tokens are deducted from that author's quota. Mira uses the plan-default Google language model for checks, generation, and deduction. It has current-time, admitted-participant, and Google Search tools; web replies include source links. The browser supplies the requester timezone, and participant counts distinguish people from multiple devices. All generation steps and reported search queries count toward the requester quota. Search cost estimates use paid list rates before project-wide free allowances; missing provider usage or grounding coverage stays incomplete. Cost estimates use its catalog prices and reported cached input; missing cache prices or tiered pricing remain incomplete.
Requests are deduplicated by chat message ID. The internal server-service token
scope is never included in browser join tokens.

## Bandwidth and cost attribution

Balanced mode caps camera sending at 900 kbps / 24 fps and screen sharing at
1.8 Mbps / 15 fps. Data saver lowers camera resolution and frame rate, while screen
sharing retains text resolution at a lower frame rate. Higher-quality camera mode
allows 1.6 Mbps. These are ceilings, not promised usage or minimum bandwidth.
Speech has a separate 48 kbps ceiling; screen audio uses 96 kbps. Video shares the
available outgoing bandwidth estimate with a reserve for audio. Congestion reduces
quality promptly, while recovery requires four measured healthy samples to avoid
oscillation. Missing statistics never trigger an upgrade. Video pauses when its
share of estimated capacity is too small after reserving speech bandwidth.
Sending pauses when the participant is alone and resumes when an audience joins.
Sender parameter failures preserve the working transport rather than forcing a
reconnect. Initial encodings are capped before negotiation.

Admins see client-reported received RTP bytes and server request counters in
settings. Estimates use [SFU pricing](https://developers.cloudflare.com/realtime/sfu/pricing/)
and [Durable Object request pricing](https://developers.cloudflare.com/durable-objects/platform/pricing/),
checked September 8, 2026, before account-wide allowances or discounts. TURN-to-SFU
traffic is not charged twice. Reports are cumulative and deduplicated across samples.
Per-device accounting retains at most 4,096 identities per room; reports beyond
that limit are marked as incomplete rather than growing storage without bound.

**These are partial usage estimates, not invoices.** RTP payload counters omit
transport overhead and reports can miss disconnected devices. Worker CPU, Durable
Object duration/storage, R2 operations/storage, and shared plan charges are not yet
attributed per room and are shown as unallocated. Reconcile against Cloudflare
account billing before using these estimates as a complete budget. Unknown AI costs
are shown as missing coverage rather than zero-cost requests. Merely reading a cost
panel does not force a Durable Object snapshot write.

### Diagnosing call preparation

The centered **Preparing your call** screen checks the account's device session
before opening the lobby. Its request is `POST /api/meet-call/<meetingId>/token`;
a failure here is distinct from a media or WebSocket connection failure inside
the call. The browser bounds each preparation request to 12 seconds and retries
transient failures twice. Switching an existing device is not automatically
retried, because it can disconnect that device.

The token handler checks the realtime Worker's `/room-device` endpoint with a
five-second timeout. An unavailable upstream returns HTTP 503 with
`MEET_REALTIME_UNAVAILABLE` and `Retry-After: 2`, without bypassing device policy.
Use the request status and Cloudflare Ray ID to distinguish an edge block from
an unavailable Worker; a successful `/health` check alone does not prove the
authenticated device endpoint works. Never collect cookies or bearer tokens.

Cloudflare's Meet-only managed-rule exception skips cookie-character checks
942420 and 942421 for GET and POST requests to `meet.tuturuuu.com`. Other rules
and request-body inspection remain active, and exception matches are logged.
Inspect the contributing rules before changing this scope; do not disable an
entire ruleset to resolve a preparation failure.

After the lobby opens, a WebSocket that remains in its initial connecting state
for ten seconds is replaced through the normal bounded reconnect policy. Late
events from the abandoned socket cannot replace the current connection.

### Room policy verification

`bun apps/meet-realtime/src/room-controls-check.ts` verifies lobby chat privacy,
one room-wide recording, private recording/cost access, and same-account device
switching against the Worker. Set `MEET_CHECK_REALTIME_URL` and
`MEET_REALTIME_TOKEN_SECRET`; the default endpoint is local port 8799. The check
uses a fresh synthetic room, ends it after success, and never uploads files or
calls Gemini. The production deployment workflow runs this after the existing
signaling/SFU check. Each room-controls connection has a ten-second deadline;
failed or closed attempts dispose their listeners and socket without retrying.
The signaling check’s `ALL CHECKS PASSED` line does not establish room-controls
success: require its own assertions and the complete workflow result. Lifecycle
regressions live in `apps/meet-realtime/src/check-socket.test.ts`. Abandoned Mira requests release their per-account pending
limit after two minutes; late provider costs can still be recorded.

## Assistant identity and panel interactions

Mira replies carry a server-only assistant marker and reserved sender
identity. The Nova avatar and official badge require both; choosing the
display name Mira does not grant either. Standalone `@Tuturuuu` and `@ttr`
mentions (case-insensitive) open the assistant mini profile on hover, keyboard
focus, or tap. Code and existing Markdown links are not rewritten into
mentions. Paragraphs containing raw HTML are also inert for assistant requests
and highlighting. Chat message toasts are suppressed while chat is open;
admission and other call alerts remain active.

Desktop chat, participants, and transcript panels have a draggable separator.
Focus the separator and use left/right arrows to adjust it with a keyboard.
The meeting settings button is last in the call header. Returning from the
post-call screen invalidates cached meeting lists and room state before
navigation, including personal-workspace aliases, so newly created meetings
are fetched.

### Private workspace tool reviews in Meet

When composing an assistant mention, choose the workspace for task, calendar,
finance, and time-tracking tools. Personal workspace is the default; billing always
uses the requester personal AI allowance. Meet reuses the platform tool definitions
and executors, checks membership and permissions on every generation, and only sends
detailed schemas for selected tools.

Workspace tool calls require the requester to review and approve the exact inputs.
Their results remain in a private Mira review; **Share with meeting** is a separate
explicit action. Other participants cannot read, approve, or share those drafts.
Draft continuations remain server-side in the room Durable Object and are omitted
from room broadcasts and browser review responses. Revisions and an execution claim
prevent duplicate approvals from repeating a mutation. If a request remains in an
uncertain executing state, do not repeat it; inspect the platform result first. Failed or timed-out reviews can be discarded without making their actions executable again, including after the room ends.
Web search runs in an isolated request containing only the explicit question; model-supplied query rewrites and recent room history are not forwarded. Questions containing known participant names or room-title terms are blocked at that boundary. Missing grounded sources produce an unavailable-search result. Web search is disabled while continuing private workspace results. Unsupported platform-only tools such as E2EE key setup,
file conversion, and client UI controls are not exposed in the Meet tool set.

Verify private reviews with the production React compiler enabled: let a review
arrive inline while its detail query is still loading, then deny the action.
The list can load before the detail query, so callback inputs such as the revision
must remain guarded during that interval. An uncompiled development fixture alone
does not cover compiler-generated callback dependency reads.

Private reviews appear inline beneath the request that created them. Approval,
denial, and the separate sharing decision stay requester-only; orphaned reviews
whose request has left the retained chat history appear at the end of the thread.
Provider citation IDs are resolved only against their exact returned sources.
Older unmapped references show an unavailable-reference badge rather than a guessed
link, and the source footer is displayed as an expandable list of source cards.

Source metadata is limited to eight URLs and 4,000 characters within the 16,000-character message limit; oversized prose is safely truncated.
Empty final synthesis reuses only an available grounded public-search answer, without another paid call.
Otherwise generation fails visibly after incurred usage is accounted for; pending approvals stay private.
Legacy sources-only replies display an incomplete-answer notice. Sources alone never count as a completed answer.

### Fast return to ended meetings

Meeting cards remember an observed ended state on the current browser, scoped to
its signed-in account. Only meeting IDs and observation timestamps are retained,
for up to 30 days and 256 rooms per account. Returning from an ended call updates
this hint immediately, so known ended cards do not queue another room-state
request or poll the realtime Worker. Active and unknown rooms still refresh.
The cache is only a display hint: opening notes or transcripts always performs
server permission checks. No room names, chat, transcripts, or access grants are
stored in this cache, and unavailable browser storage does not block navigation.

## Echo and microphone processing

Settings → Devices exposes native echo cancellation, background noise reduction,
and automatic voice leveling. All three default on. Changes apply to the current
microphone and subsequent device switches in that call, without unmuting it.
The status under each control comes from the captured track's `getSettings()`;
a requested setting is not proof that a browser or device applied it.

Screen capture excludes whole-system audio and requests `restrictOwnAudio` to
avoid returning meeting playback to peers. These are browser hints, so browser
compatibility still matters. Share a browser tab with audio when presenting media.
Each remote camera or screen feed also has a local mute control: it silences only
that feed on the listener's device, without changing room participant permissions.

For persistent echo, identify the participant or shared-audio feed returning the
sound. Enable echo cancellation on the source device, use headphones, or mute
additional microphones and speakers in the same physical room. Native processing
cannot guarantee cancellation across multiple nearby devices. Verify actual
speaker/microphone calls separately from synthetic audio and unit tests.

### Nearby participants and same-room audio

Meet automatically pauses the later device's microphone when the same verified
account already has an active microphone in the call. For different accounts, a
local audio monitor looks for repeated matching speech dynamics and changing
frequency patterns between existing microphone tracks. Only the later device
backs off, using join time and device ID as a stable tie-breaker. This avoids two
devices muting each other.

The microphone is disabled before a compact audio-control popover suggests
**Share nearby audio**. Closing the popover keeps the microphone paused. Confirming
sharing also silences this device's meeting playback, voice assistant and
notifications; video, chat and notes remain available. **Use my microphone**, or
explicitly pressing the microphone control, restores this device's own audio.
Device replacement and pending permission requests cannot reopen a paused mic.
If the identified primary device leaves, local playback resumes and the microphone
stays paused until the user chooses to speak.

Analysis runs only on already-enabled microphone tracks, never screen-share audio.
It creates no extra capture, cloned tracks, recordings or network payloads, and
compares at most eight incoming microphones. Several consecutive matching windows
are required; silence and steady tones are insufficient. An explicit override
suppresses the current device pair. Unsupported Web Audio falls back to native
browser echo cancellation and the manual sharing control.

This is a conservative audio-overlap heuristic, not proof of physical proximity or
speaker identity. It does not use IP addresses or merge independent recordings on
the server. Headphones and one primary microphone/speaker pair remain useful for
rooms where acoustic conditions defeat detection.

The meeting deadline appears as a compact clock button with a circular countdown
ring. Hover or focus shows the remaining time and localized deadline; tap opens
the same details. The ring represents the time remaining when this device joined,
while the deadline always follows the server's room expiry. Resource-limit errors
still appear as actionable notices.

### Audio recovery and meeting previews

In call settings, **Restart microphone** reacquires the selected input and
reconnects media without leaving the room. The control remains disabled while
muted and never intentionally unmutes the user. Use this when the browser input
degrades; synthetic playback tests do not verify physical microphone acoustics.

Transcription retries receive their five-minute window when the upload starts,
not while waiting behind another upload. Credit admission failures stop immediately
and require the user to check AI Hub; they do not advertise a five-minute network
reconnection. Other buffered retry feedback describes transcription retry rather
than claiming the connection failed. Notes generation failures retain saved
transcript chunks for an explicit retry. Empty saved speech completes with empty
notes, zero cost and no provider invocation, even when capture is incomplete;
missing-audio warnings alone do not admit generation. Real saved speech still
generates with its incomplete warning. This applies to Meet and Parley notes
finalization and is covered by `server/sessions.test.ts`. The failure UI uses localized fixed
guidance with allowlisted HTTP status and provider category diagnostics; raw
provider bodies, credentials and meeting identities are excluded. Regression
coverage: `chunk-recovery.test.ts`, `use-meeting-ai.test.ts`,
`server/sessions.test.ts` and `failure-toast.test.tsx`. The per-session notes warning identifies
incomplete results without repeating a global warning after the call.

Room preview images are generated from the same explicitly public meeting policy
as link metadata. Image responses use `private, no-store`; revoked public access
falls back to generic branding on the next request. External chat clients can
retain their own old previews. Preview descriptions omit repeated titles and UTC
times because crawlers cannot know the recipient's timezone. Opened meeting pages
and the rightmost call timer use the viewer's browser timezone and locale.

For intermittent outgoing speech stutter, capture connection diagnostics before
refreshing. Audio streams include jitter (milliseconds), reported packet loss,
and incoming concealment counters when the browser exposes them. Outgoing values
come from the SFU's remote-receiver feedback; they describe that transport hop,
not every listener's playback. Unsupported metrics remain unknown, not zero.
Compare successive reports to distinguish ongoing loss from historical totals.
This report includes no audio, addresses, SDP, or raw track identifiers. Stuttering
is distinct from low microphone volume; reconnection is a recovery action, not
proof of the underlying cause.

### Worker rendering verification

The pinned OpenNext adapter patch preserves component function names during its
server bundling step. React uses these names to resume partially prerendered
boundaries; renaming a component can trigger React 419 recovery even when the
HTTP response is 200. Keep this patch when updating the adapter until its bundler
preserves names upstream. `scripts/ci/meet-cloudflare-render.test.js` reproduces
the failure with a real React prerender/resume cycle and checks the installed
adapter configuration.

After a Meet deployment, verify a fresh browser load as well as the signaling
checks. Check page errors and the rendered interface; a successful HTTP response
or a page that recovers after refreshing does not prove server rendering passed.

## Mobile screen sharing and notifications

Native Meet presents join, room chat, and host admission-request notices with a
shortcut to the relevant sheet. Initial presence and replayed chat stay quiet;
reconnecting does not repeat previously seen messages or pending requests.
Hidden browser tabs retain at most the newest 50 notices and display them once
when the tab becomes visible; disconnect, room end and lost admission discard
that queue. Obsolete admission requests are omitted.

Notification sound can be disabled separately from meeting audio. OS volume,
silent mode, and Do Not Disturb may suppress the sound.

The floating navigation bar owns Leave. Hosts retain the leave/end decision;
ending the meeting remains restricted by server authorization.

Run synthetic fixtures without joining real meetings or publishing real screen,
voice, or chat. Validate failed publication, interrupted consent, removal, room
end, denied admission, reconnect, and repeated start/stop. Device testing must
use controlled fixtures and explicit capture consent. No signing entitlement or developer-account capability is added. A returned WebRTC
track alone does not prove ReplayKit produced frames; verify actual receiver frames
before declaring native capture acceptance complete.

References: [Android media projection](https://developer.android.com/media/grow/media-projection),
[Apple ReplayKit](https://developer.apple.com/documentation/replaykit), and
[browser display capture](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getDisplayMedia).

The installed WebRTC socket implementation previously left a listener open when
capture stopped before its first connection. `ios/MeetSocketConnection.m` is a
repository-owned copy with bounded cleanup changes. The Podfile selects it in
the generated `flutter_webrtc` target and fails closed if the expected source
layout changes; it does not mutate shared Pub cache files. Revalidate this patch
when upgrading the plugin. Native CI must compile/link this replacement.

The iOS reader requires a minimum 10 KiB body to avoid overreading coalesced tiny
frames. Meet pads JPEG trailing bytes; an independent reader model passed 100
synthetic fragmentation/coalescing cases with 10 frames each. The installed
macOS CoreImage runtime decoded a synthetic 8×8 JPEG padded from 707 bytes to
10 KiB and rendered the expected red pixel. iOS receiver-frame decoding and
interruption on physical devices remain release acceptance gates.

The draft parity implementation at `fe6b020b95b2799fad8314969784d06ccd7fadda`
passed exact-head Android, iOS simulator, macOS, Linux, and Windows CI builds,
mobile analysis/tests, TypeScript type checks, and lint. Android artifact
`11182160313` belongs to run `36899884533`; iOS artifact `11181837360` belongs
to run `36899884528`. Build success confirms native compilation and linkage,
but does not establish capture acceptance. Revalidate subsequent changes at
their own exact head.

Those development CI artifacts use the default localhost API/Supabase settings
and do not inject a Supabase public key. They have no authenticated synthetic
Meet room or SFU fixture. Two-peer acceptance therefore requires a separate
fixture artifact configured for an isolated test service, synthetic host/guest
sessions, and its existing authorized SFU credentials. Do not create accounts,
change production settings, or substitute a real meeting to bypass this gate.
The available local runtime inventory contains an Android 11/API 30 image and
iOS 27 simulators, with no attached physical devices. Android 14+ OS-chip/lock
revocation and physical iPhone ReplayKit background/rotation/receiver-frame
acceptance remain explicit release gates.

Android's installed WebRTC plugin ignores `MediaProjection.Callback.onStop`.
The repository-owned `android/overlays/flutter_webrtc` capturer forwards that
callback to the Meet bridge and releases the capture. Each capturer claims an
immutable owner; repeated callbacks and callbacks from a previous share cannot
stop a new share. The assistant's separate projection service does not claim
this owner. Gradle copies plugin Java sources into generated build storage,
replacing exactly this file after checking the reviewed version and upstream
SHA256. It fails closed on an upstream change and never modifies the Pub cache.
Revalidate this overlay when upgrading WebRTC, and require exact-head Android
CI plus OS Stop/lock/restart fixture acceptance for overlay changes.

Capture stops are generation-scoped and preempt media negotiation. Native revoke
and track-ended events trigger one cleanup per capture; a stalled screen track
does not discard the camera. Android engine detach stops its claimed capturer.
The iOS listener accepts one broadcast connection and closes owned descriptors
with Core Foundation socket ownership enabled. Browser Stop retains its capture
until unpublication succeeds, so a failed unpublish can be retried. Regression
coverage lives in `meet_screen_capture_test.dart`, `meet_media_health_test.dart`,
`local-media-controls.test.ts` and `use-call-notifications.test.ts`.

The iOS notice uses an app-owned short WAV loaded through Flutter's asset lookup
and registered as a UI System Sound, rather than a private numeric system-tone
identifier. It plays only while the app is active and does not change the call's
audio session. [Apple's System Sound Services](https://developer.apple.com/library/archive/documentation/AudioVideo/Conceptual/MultimediaPG/UsingAudio/UsingAudio.html)
owns sound-effects policy. Device mute/Focus behavior remains part of the user's
post-merge physical acceptance.

## Collaborative programming

The in-call coding control opens the shared Learn programming/playground workbench
with file cursors and transient pointers. Hosts select the resource; the server
checks admission and resource access before issuing tickets. A verified
`@tuturuuu.com` admin elevates admitted participants only within that room.
See [programming playgrounds](/platform/features/programming-playgrounds) for
Drive ownership, limits and the intentional entitlement exception.

Web screen capture depends on browser getDisplayMedia support. Android and iOS
browsers that lack it can receive screens and co-program, but cannot open a
native screen picker. Missing support and capture denials now display guidance.
See [mobile capture diagnostics](/build/devops/programming-realtime-runbook#mobile-screen-sharing).

### Native mobile sharing

Tuturuuu mobile calls use Android MediaProjection with a foreground capture
service and iOS ReplayKit with the broadcast extension. The in-app Share screen
control starts native OS consent and publishes the resulting track through the
same meeting SFU. Native stop, meeting exit and revoked admission stop capture.
On unsupported mobile browsers, Open mobile app preserves the room code in a
verified platform app link. The app opens the native call; capture still requires
a separate user action and OS consent. Tokens and capture permission are never
carried in the link.

## Collaborative documents and mobile parity

Every admitted Meet participant can edit the room's private rich-text document.
This document does not require a paid playground entitlement. It belongs to the
meeting workspace and is created once per meeting. Cloudflare merges and persists
Yjs updates, then checkpoints the rich-text content to the private workspace
Document. Cursor labels and selected ranges use authenticated account identity;
multiple connections from the same account remain separate sessions. Editing the
workspace Document through another surface creates a conflict: a room checkpoint
never overwrites that external edit silently. The durable room state is retained
for reconciliation. Web and native editors display a backup conflict warning;
transient checkpoint failures display a delayed-backup warning. Editing continues,
and a successful checkpoint clears the warning. Rejoining restores the current
backup status. The Worker rejects client-authored backup status notifications.

Native mobile opens the same shared web rich-text and programming editors inside
an authenticated app-owned WebView. This preserves Yjs, formatting, remote
cursors, pointers, selections and reconnect behavior across web and mobile.
The app bridges a small allowlist of meeting-scoped API actions; it never sends
platform tokens to editor JavaScript or runner preview content. A separate
loopback capability serves private preview assets. Android denies mixed content;
[Chromium treats loopback as trustworthy](https://codereview.chromium.org/1931063004), preserving the private `127.0.0.1` preview exception.
External navigation and previews cannot invoke the bridge; calls continue.

Native collaboration pins the account separately from the admitted device ID.
Account/device changes, revoked admission and ended calls suppress late results;
preview capabilities never transfer access. Server admission remains authoritative.
Task cubits cancel subscriptions and close only default-owned clients/APIs;
injected clients remain caller-owned. Refresh cleanup failures reconnect; disposal fences late cleanup.
Navigation denies malformed, hostless and non-HTTP schemes without throwing.
One-shot broadcasts preserve ticket/handshake errors; subscribed channels reconnect.
Per-send socket setup remains a tradeoff; shared-channel reuse is not implemented.
Coverage: `meet_collaboration_owner_test.dart`, `meet_preview_proxy_test.dart`, `meet_collaboration_policy_test.dart`, `task_broadcast_lifecycle_test.dart` and `cloudflare_channel_test.dart`.

Both clients refresh short-lived channel tickets on the existing socket. Actual
reconnects reauthorize admission and replay missing document updates. Expired
access closes quiet connections; disconnected editing and persistence failures
must remain visible. Room programming editors can save and run the selected
resource; only its owner can grant permanent collaborators outside the meeting.

Regression coverage includes the real local Cloudflare document/channel probes,
shared caret/range tests, mobile channel tests and meeting admission/entitlement
checks. Native WebView bridge, private-preview and MediaProjection/ReplayKit
acceptance additionally require configured exact-commit mobile CI artifacts.

## In-call document workspace

Meet and Parley explicitly enable the rich-text editor collaboration binding with
the room Yjs document and provider. This applies to every admitted editor: passing
a provider without enabling the binding must never create a local-only document.
`document-panel.test.tsx` guards the binding; shared provider tests cover peer
updates and reconnect reconciliation. Hosted multi-user verification remains a
separate delivery gate.

Meet and Parley render the shared document editor edge to edge, without a separate
Shared document heading or padding outside the editor. The editor keeps its own
text padding. Backup status sits in the editor toolbar; secondary formatting,
media, and copy controls open from Tools, while bold, italic, and strike remain
directly available. Other shared-editor surfaces keep their full toolbar.
Healthy live synchronization stays quiet. Reconnecting
is announced as a status; delayed or conflicted backups use a keyboard-focusable
warning icon with an explanatory tooltip, without pushing the editor downward.
Document and programming controls use the same icon-button tooltips as media
controls, and meeting action triggers expose consistent tooltips. No room access,
checkpoint behavior, or document broadcasting policy changes.

Regression coverage: `document-panel.test.tsx` checks the toolbar status placement
and seamless editor container; `fixed-toolbar-contents.test.tsx` exercises actual
Tools opening and formatting actions alongside the unchanged full toolbar.
`document-status.test.tsx` verifies quiet healthy state, accessible reconnection,
and distinct backup-warning labels without inline alerts.

### Programming preparation and resource discovery

Meet web hosts open Programming into a blank Python project when the room has no
selected resource. Opening an existing selection reuses it; participants only join
the host's selection and never create a project automatically. The existing
authorized collaboration ticket, hosted runtime, Run, and problem Test controls
remain responsible for connecting and executing code. Creating a meeting project
keeps its runnable entry file empty; standalone playground template defaults are
unchanged. Internal checkpoint uploads explicitly permit zero-byte source files
only with valid positive Drive quota and verified usage accounting; over-quota or
unknown quota still blocks creation. Signed browser uploads retain their nonempty
file policy. `empty-playground-storage.test.ts` exercises actual capacity guards
for both Drive providers, including blank creation, quota denial, and cleanup.

Hosts choose existing personal projects or authorized workspace problems through
shared UI dropdowns. Problem discovery supports cursor pagination, while project
discovery checks the response actor against the signed-in account. The native
collaboration bridge retains its existing explicit resource-ID selection until
that bridge provides authenticated discovery metadata. Regression coverage lives
in `prepare-programming.test.ts` and `playground-service.test.ts`.

## Private My day panel

During a Meet call, My day shows the current authenticated account’s assigned
Tasks feed and next seven days of its personal workspace Calendar. It is closed
by default and local to that participant; it is never room state, signaling, or
shared document content. Team meeting workspaces are never used as a fallback.
Account identity is verified before and after reads, and queries are scoped by
account ID. Calendar collection GET accepts a signed Meet session only for that
actor's personal workspace, with MEMBER and manage\_calendar permission checks.
Team-workspace reads and Calendar mutations do not gain Meet-session admission.
Temporary failures retain same-actor, same-workspace source snapshots
with an explicit stale-source notice; definitive access denials clear that source. Dedicated Tasks and Calendar links open the full apps separately.
Parley does not show this Meet-only action.

`personal-tools.test.ts` covers personal scope, actor changes, missing personal
workspaces, and partial source availability. `calendar-event-meet-read.test.ts`
uses signed sessions to cover personal scope, actor/audience/signature/expiry
denials, membership and permission failures; Calendar events route tests keep
the audience opt-in exclusive to GET.

## Meeting-list startup and hosting eligibility

The signed-in Meet workspace heading renders after session and workspace membership
are verified. Hosting eligibility is resolved inside the content Suspense boundary,
so a slow verified-identity or account-tier lookup does not block the heading.
Creation controls remain unavailable until that lookup confirms eligibility; lookup
errors retain the unavailable notice and never grant creation. Session and workspace
redirects stay outside streaming boundaries. This applies to the workspace Meetings
list, not room admission or meeting creation authorization. Regression evidence:
`authorized-meetings-content.test.tsx` exercises deferred identity reads, workspace
denial, eligible accounts, restriction notices, and failed eligibility reads.

Measure signed-in server response and meaningful-content times separately. A fast
public homepage is not evidence that an authenticated app is fast, and a Suspense
skeleton is not a loaded meeting list. Re-measure the deployed source after rollout.

## Meeting-detail policy and permission reads

After the signed-in actor, joined workspace, and workspace-scoped meeting are
verified, Meet details starts the read-only room-policy lookup and workspace
permission lookup together. The policy still decides the ended-room shortcut
before any Calendar event access; Calendar links continue to require the existing
`manage_calendar` permission. Permission failures are captured immediately, ignored
for ended rooms as before, and propagated only after a successful active-room
policy lookup. Policy failures retain precedence. No reads start before the
workspace and meeting gates, and this changes neither room admission nor creation.
`page-loading.test.tsx` covers deferred overlap, scoped identity, ended-room bypass,
and rejection precedence; `meeting-calendar-event.test.ts` retains denied-access
coverage. This source change still requires deployed meaningful-content timing to
establish a customer-visible latency improvement.

## Collaboration layout and document presence

Opening Meet's shared document or Programming keeps participant cameras and
shared screens visible alongside the active content. The existing layout selector
also controls collaboration: automatic/sidebar uses a compact desktop rail,
spotlight emphasizes content with a narrower rail, and grid balances content and
participants. Narrow screens keep a horizontally scrollable filmstrip beneath the
content. These choices are local to the active call; they never alter admission,
media publication, or another participant's layout.

The same media stage and keyed camera/screen tiles stay mounted when content,
layout, or focus changes. Local playback mute state and media element identity
remain intact, and no second stage duplicates audio. Regression evidence:
`collaboration-stage-layout.test.tsx` exercises real participant tiles and
camera/screen audio elements through content and layout transitions.

Shared-document avatars represent users in that document provider's actual
collaboration awareness, not everyone connected to the meeting. Clients with the
same authenticated identity appear once; departures and provider switches remove
old identities, and disconnected document transport hides the roster until it
reconnects. Four avatars are shown in the editor toolbar beside backup status, with an accessible overflow count.
`document-panel.test.tsx` verifies that the live provider awareness is connected
to that toolbar roster.
`document-presence.test.tsx` uses real awareness updates for join, rename,
departure, duplicate clients, malformed identity fields, and provider/disconnect
transitions. Source fixtures do not establish deployed multi-client delivery.

## Recovering the final AI notes write

Meet retries a failed final notes persistence step at most twice after its initial
attempt, reusing the already generated and settled notes, usage and cost. These
retries retain the same session/attempt predicate; they do not repeat provider
generation, credit admission or billing. A missing compare-and-set row is a
conflict and stops immediately. Failure cleanup only changes a still-processing
row, so an uncertain transport response cannot demote already completed notes.

If every persistence attempt fails, the request reports failure without claiming
that notes were saved. Saved transcript chunks remain unchanged. This is bounded
recovery within one request, not durable cross-request output recovery: a later
explicit retry can generate and bill again. The existing unpriced-attempt counter
also remains conservative when generation succeeded but persistence failed; this
packet does not reconcile that counter against settled billing runs.

`server/sessions.test.ts` reproduces successful generation followed by a returned
storage error or a thrown unknown-commit error, and covers equal output/usage/cost,
same attempt predicates, exhausted recovery, safe errors and immediate conflict.
These source fixtures do not identify the original incident's provider status or
establish deployed database/provider delivery.

## Transcription capture scope

Transcription capture and its pending uploads belong to one verified actor,
workspace and meeting lifetime. Admission changes only when that lifetime commits;
a suspended or abandoned render cannot revoke the still-committed capture. A
cleanup epoch also rejects operations held across lifecycle cleanup/replay.
Queued overflow finalizers and duration callbacks check their captured epoch before
calling the current finalizer, so an old callback cannot end a replacement capture. Departing that scope disposes local audio and
aborts recovery. Returning to the same IDs creates a new lifetime; delayed old
responses cannot install capture, alter current state, finalize an old session or
refetch into the current view. The call shell also binds its account ID to the
verified actor. Requests already admitted by the server are not promised to be
cancelled or rolled back.

A delayed start allocation received after departure does not issue an
authenticated finalizer from the new scope. That server session remains subject
to existing reservation expiry and authorized recovery. Same-scope finishing still
waits for the final worklet flush, batch drain and queued uploads before generating
notes. Explicit retries of ended sessions remain available to the current actor.

`use-meeting-ai-scope.test.tsx` exercises held start/upload responses across actor,
workspace and meeting departures, including switches away and back, new capture
survival, retained callbacks, missing/mismatched actor admission, suspended
transitions, held preparation across cleanup/replay and old overflow/duration
callbacks after an Activity hide/show effect replay. Existing
capture, batching and recovery tests retain final-audio ordering coverage. This
does not establish the original incident's reconnect/provider cause or real
Radix workspace-selector interaction; those runtime checks remain separate.

### Public deployment identity

Only exact `GET /api/build-info` skips Meet app-session refresh so a
credential-free deployment probe can read the bundled production identity. The
shared API guard still applies, including security and abuse controls. Other
methods, trailing-slash or prefix lookalikes, and private APIs keep their existing
session admission; this exception grants no meeting or workspace access.

The production verifier requires the exact app, full source SHA, production
ref, and environment. HTTP failures report only a validated numeric status,
never response bodies or raw transport diagnostics. Proxy regressions cover
anonymous and stale-session GET admission, the real metadata handler's no-store
response, protected API/method/lookalike denial, and preserved MFA/rate guard
failures. A 403 without an app-assurance or challenge marker remains unclassified;
these source fixtures do not establish the blocking layer or deployment identity.

### Assistant workspace choices

Meet and Parley's shared assistant picker shows compact loading, lookup-failure,
and empty states in English and Vietnamese. Choices stay disabled until private
visibility and workspace data are available; guest and hidden workspaces remain
excluded. Lookup failures expose a safe localized message and an explicit retry
through the existing actor-scoped visibility and workspace queries. They never
expose a raw transport/provider error or grant membership.

Actual Live dialog regressions cover Radix pointer selection, personal/member
context, focus retention, loading/error/empty feedback, explicit retry, and a
held account A→B→A lookup. Pointer selection passes this fixture; the demonstrated
repair is missing state feedback, not proof of the reported production portal
failure. Browser/provider runtime verification remains separate.

### Offline room document checkpoint budget

Meet's private rich-text document keeps its durable unsaved state when checkpoint
callbacks fail. Without a currently valid editor connection, it reserves at most
three automatic attempts within two minutes, at least 30 seconds apart. Reservations
persist before callback I/O; duplicate alarms, restarts and failed completion writes
cannot replenish them. Exhaustion or age expiry stops automatic checkpoint work.
An authorized editor rejoin can recover the retained document; a viewer rejoin cannot
restart the stopped job. Active editor ticket leases keep their existing checkpoint
behavior. This rule applies to meeting-document channel rooms, not programming
project checkpoints, media cleanup or a platform spending cap.

Regression evidence: `channel-retry-budget.test.ts` counts operations and tests
failure/clock/restart/recovery boundaries; `test-fixtures/channel-retry` verifies
reservation persistence against real local Worker SQLite with controlled callback
failures. Hosted alarm delivery and actual workspace storage remain separate gates.

# Meeting follow-ups
Source: https://docs.tuturuuu.com/platform/features/meet-followups

Review meeting-note suggestions and create personal tasks or calendar events with the correct identity and timezone.

## From notes to action

Completed meeting notes show suggested next steps. Review an action item as a task,
review a suggested follow-up meeting as a calendar event, or choose **Reserve time
for this** to schedule work on a task. The original owner and scheduling wording
remain visible. Nothing is created when notes are generated or opened.

Calendar suggestions are included in newly generated notes. Older saved notes still
work and expose their existing action items. Dates resolve against the saved meeting start and supplied timezone. Unspecified dates, times, durations and owners
stay unspecified; incomplete transcripts remain visibly marked.

## Identity, destination and time

The review defaults to the signed-in user's personal workspace and saved calendar
timezone, falling back to the browser timezone for an automatic setting. The user
can choose another workspace where they are a full member. Tasks require a chosen
active board and list. Search destination members and select one or more assignees, use the suggested owner when uniquely matched, or leave the task unassigned. A suggested name alone never silently assigns a person. Priority, description and deadline are editable.
Events require a reviewed start and end and are saved to the selected enabled native calendar. Calendar and location are editable. The review checks overlap with saved
events in the selected workspace and reports when availability is unknown;
unsynced external calendars are outside that check. All created items include a source link
to the meeting notes; this does not grant recipients access to private notes.

The review shows local wall times and converts them to UTC before persistence.
Invalid dates, nonexistent DST times, repeated DST hours, invalid zones and reversed
event intervals are rejected. The user can select another local time or enter the
intended instant explicitly in UTC. Changing the timezone reinterprets the displayed
wall times, as explained in the form.

## Speaker attribution

New capture keeps microphone and shared-audio tracks separate in one audio context.
Each new segment carries a source kind and may carry a source account ID. The server verifies supplied accounts against
room admission before resolving the saved display name, falling back to email.
Segments display the source name and whether the source is a microphone or shared
audio. Historical mixed recordings remain unattributed. A source identifies a
device owner: it cannot distinguish several people speaking into the same microphone.
Notes must preserve that uncertainty rather than infer identity from voice.

Speaker clips are sent together in one upload window every ten seconds. One batch
uses one database reservation, retaining the existing sequence/rate contract and
three-hour session boundary. Capture stops 15 seconds before expiry to flush pending audio. Individual timestamps and source labels survive batching.
The provider returns one indexed transcript per file; missing or duplicate indices
fail validation rather than silently mixing speakers. Batches are bounded to 48 clips
and 12 MB, with at most 48 MB awaiting upload. These are explicit upload-capacity
limits; exceeding them marks the session incomplete. They do not multiply the
sequence counter by participant count.

Source metadata is stored alongside chunk usage without a schema migration. Notes
receive stable source IDs; generated owner IDs are checked against that roster.
The review matches those IDs against the chosen destination's actual members.
Changing workspace clears board, list, calendar and assignee selections.

## Server boundary

`/api/meet-ai/[wsId]/[meetingId]/followups` runs inside Meet. It verifies the Meet app
session and source-note sharing policy, then separately verifies full membership and
existing task/calendar permissions in the destination. Actor IDs come from the
verified session. A changed account invalidates an open review. Tasks call the shared Tasks creation handler with injectable Meet authentication, retaining task sorting, rich-text description formatting, relation writes, quotas and actor-aware access checks. Selected assignees must still be full destination members. Workspace member-name and email privacy settings are respected in the picker. Calendar writes resolve the selected enabled native calendar and use the existing encryption helper before inserting. Meet performs these authorized writes with its own verified session. Calendar encryption runs in strict mode: a key lookup, configuration or decryption failure rejects the write; only a workspace with no encryption key can store unencrypted fields.

A creation request has a UUID, timestamp and payload fingerprint. Existing private
room receipts prevent replaying the same request within the one-hour receipt window;
expired timestamps are rejected. The client also retains a per-user, per-suggestion
attempt marker and saved result URL, without storing note text. After an uncertain
write, check the destination before creating another copy. Confirmed pre-write failures release the matching pending room receipt and clear the local attempt marker so the user can correct the destination and retry. Receipt persistence can
fail after a successful write, so the server never automatically retries creation.

## Verification

Run the Meet meeting-ai tests, shared AI meeting-generation tests, internal API build,
`bun validate`, and the actual Meet build. Use `NODE_ENV=test` for tests when the shell
inherits production mode. Verify authenticated task assignment, destination and
calendar timestamps in a dedicated test workspace before claiming production
end-to-end coverage. These changes require no database migration.

## Public meeting details and long calls

The host can enable **Public meeting details** from meeting details or call
settings. It is off by default. When enabled, the invitation page and its
Open Graph/Twitter metadata expose only the title, scheduled time and ended
status. Anonymous visitors can read that projection, then sign in to request
admission. Notes, recordings, calendar descriptions, host email and participant
identities never enter the public metadata. Private meetings keep generic,
non-indexable metadata. Policy failures also return the private projection.
Disabling visibility affects the next server request; external search/social
services may retain earlier previews. The sitemap contains only public Meet
landing pages and does not enumerate invitation codes.

Call duration follows the host's personal account subscription: Free has two
hours, Plus ten hours, and Pro/Enterprise twenty-four hours. The join-token route
resolves the host's active subscription on the server and signs the duration into
the token for every participant. The realtime room fixes its deadline on first
admission and retains it across reconnects and later tier changes. Existing rooms
keep their original deadline. Entitlement lookup failures do not silently turn a
paid host into a Free host. The UI displays the deadline with date and timezone.

These are call limits. Each transcription session still uses the existing
three-hour database reservation contract and ends just before expiry. Hosts can
start another transcription session during a longer call; each keeps its own
notes and usage. This change requires no production database migration. It does
not change participant capacity, AI credits or storage allowances.

# Meet Live assistants
Source: https://docs.tuturuuu.com/platform/features/meet-live-assistants

Operate personal and room-wide Mira voice sessions with private context, explicit approvals, and metered usage.

Meet Live uses `gemini-3.1-flash-live-preview` through a Durable Object in the
existing `tuturuuu-meet` Worker. It does not require a self-hosted process.
The Worker holds the Gemini API key; browsers receive short-lived,
purpose-bound session tokens and connect through `/live-connect`.

## Audience and permissions

A personal session captures only its owner's microphone and plays replies only
on that device. Starting it mutes the meeting microphone. If the user unmutes
the meeting, personal capture and reply playback pause. Pausing also clears
queued speech; incoming private audio is blocked while the room microphone is on. Use headphones:
speaker audio can otherwise be picked up by an open physical microphone.

Only a room admin can invite the room assistant. One room assistant can be
active at a time. Its initiating device captures the meeting audio available to
that device, limited to microphone tracks of participants who explicitly enable **Talk to Mira**. Screen-share audio is excluded. Audio unavailable to that device
cannot be transcribed or understood. Participants see the assistant's presence
and may need to enable playback once because of browser autoplay restrictions.
Room output is published through server-authenticated events. Browser tokens
cannot impersonate Mira's audio.

The model can inspect current public meeting context, recall earlier session
turns, and organize its context. Personal memory is not included in room mode.
Personal sessions can use the selected workspace through the same permission-checked
tools as text chat. The workspace picker validates the authenticated account
against the current workspace actor; the per-device participant ID remains
reserved for room transport and chat attribution. Hidden workspaces, guests,
foreign actors and stale actor leases remain unavailable. The actual nested Live
dialog regression uses distinct account and device IDs
(`live-workspace-identity.test.tsx`). Every workspace read or change requires an inline private
approval before execution. Membership, current permissions, and arguments are
validated again at execution time. Room sessions never receive these tools.
A room admin can stop the shared assistant even when another admin invited it.
The room presence expires automatically if its initiating session disappears.

## Mira in the meeting

Room chat is the default, including solo meetings. Mention **@mira**, **@ttr**,
or **@tuturuuu** to request a text answer. While room Live is active, its
initiating device also forwards new mentions to Live for a spoken answer.
Mira Live posts its completed spoken answers in room chat using the room's
existing retention setting. Private turns never enter room chat automatically.

Mira has its own tile, AI badge, speaking animation, pin control, and participant
list entry. **Talk to Mira / Mute to Mira** controls only whether your microphone
enters the Live mix; it does not mute you for other people. **Listen to Mira /
Deafen Mira** independently controls local assistant playback. Listening starts automatically;
microphones start excluded for every new Live session. Browser autoplay
restrictions may require one click on **Listen to Mira**. Explicitly deafening
Mira stays respected when playback reconnects.
Participant badges expose both directions and distinguish an allowed input
with a muted meeting microphone from an input excluded from Mira.

The initiating browser must remain connected and receiving participants' audio.
During recovery, new chat mentions are queued in that browser; replayed room
history does not retrigger Live. Acoustic spill from another opted-in person's
microphone cannot be separated from their voice, so use headphones where needed.

Deploy the realtime protocol changes and Meet Worker together. Older clients
without explicit microphone preferences are excluded from the new input mix.
Older initiating clients must refresh before starting room Live; the Worker
rejects microphone input from legacy sessions without the opt-in audio policy.
Restart any room Live session created before this release to use voice input.

## Explicit approvals

A personal assistant may propose remembering a fact or sharing an exact reply
with the room. The owner sees the proposed text, can edit it, and can approve or deny it.
Workspace requests show their exact arguments. Approval claims each operation
once before execution; an uncertain result is not automatically retried.
Pending proposals expire after five minutes. No timeout implies approval.
Interrupted actions are marked failed and are never silently replayed.

Approved public replies use a fresh speech session containing only the approved
text. The private session's audio, memory, context, and resumption handle are
never forwarded to the room. If speech delivery fails after the text was posted,
the text remains in room chat; inspect the result before approving a retry.

## Memory and context

Memory is disabled by default. Owners can enable it and inspect, edit, or delete
saved entries in meeting settings. Database policies restrict reads to the owner.
Memory changes first stop the owner's active personal sessions so cached private
context cannot continue speaking after a deletion. A durable pending command
blocks new personal sessions until an interrupted mutation has recovered.

Context compression and session resumption support long conversations within
available quota. They do not create a literally infinite model context window.
The active journal keeps bounded recent turns and rolling checkpoints; a private
Durable Object archive supports searching earlier turns in that session. Model
summaries can omit details. Ending the session clears its journal, private review
text, resumption handle, and archive in bounded batches; approved user memories
and billing receipts remain separate. The client retries interrupted connections, including temporary token-refresh failures.
Provider GoAway events use resumable sessions; bounded checkpoints are the fallback
when a handle is no longer valid. Choose a voice before starting. Microphone and
speaker changes in meeting settings also apply to the active personal assistant.
Pausing or interrupting speech clears queued playback on the receiving devices.

Audio is not archived, and audio never received by
the service cannot be reconstructed after an outage.

## Usage and costs

Live reservations and settlement use the platform's existing AI credit ledger
and charge the initiating user's personal workspace. Usage is accumulated from
provider events by modality. Reservations use nine-minute holds and renew after eight minutes or before exhaustion; failed
settlements remain durable and retry after the session ends. Final provider usage
is collected during shutdown. Interrupted turns without a final usage receipt
remain marked incomplete even if subsequent turns succeed.

Room admins can see aggregated Live provider costs in meeting settings.
The count represents billing periods, including renewed reservations and
separate approved speech requests, rather than unique people. Updates are
sequence-checked so retries do not count the same period twice. Personal
transcripts and memories are not included in the cost response.

Prices come from the existing model catalog and
[Google's Gemini pricing](https://ai.google.dev/gemini-api/docs/pricing#gemini-3.1-flash-live-preview).
The published paid rates verified on 2026-09-10 are $0.75 per million text input
tokens, $3 audio input, $1 image/video input, $4.50 text output, and $12 audio
output. Google Search is $14 per thousand queries after shared allowances.
Project-wide free allowances and Cloudflare Live Worker duration, storage, and
requests are not fully allocated to individual meetings. Missing usage stays
marked incomplete; these estimates do not replace provider invoices.

## Active-session alarm scope

A successful active Live tick schedules the next alarm for twenty seconds later.
The tick first settles pending public billing and expires reviews, then maintains
registry discoverability, sends the room heartbeat or personal context command,
and performs primary quota settlement and usage reporting when billing exists.
Renewal can add settlement, usage and reservation work; reconnect and queued tool
responses add separate provider operations. Count those calls and persisted keys
separately from the alarm itself.

Pause suppresses provider input; it does not skip this alarm's registry, room or
billing work. The registry lease renews after successful registration. Its
23-hour failure boundary limits tolerated registry outages, not the lifetime of
an otherwise healthy session. A future recurring-work bound must preserve active
consent, quota coverage and privacy discoverability, with explicit expiry and
an authenticated durable stop checked before dispatch and rescheduling.
These are source-path findings, not measured billed-operation or hosted shutdown
evidence; duplicate/restart, slow downstream, no-progress and Stop-race probes
remain required before certifying a cost envelope.

## Ended-session compensation and retry safety

Ending Live stops capture and provider output, but unresolved server obligations
can still require work. The session retains registry removal, room release,
quota settlement, usage reporting and private-context erasure independently.
`cleanupEndedLiveSession` handles registry/room compensation while
`finalizeSessionBilling` handles billing and context. The session alarm can invoke
both after `ended` is persisted. A completed flag for one obligation does not
prove completion of the others.

The current registry/room helper arms a future alarm before I/O and persists
completion flags afterward. It does not reserve a finite attempt count or job
expiry before the registry call. Repeated registry failure can therefore keep
scheduling work; a successful external operation followed by a failed progress
write can replay after reconstruction. Persisted session termination alone is
not an independent stop fence for this background work. The nominal one-minute
retry interval is not a hard operation or spending cap: billing retries, duplicate
invocations and restarts must be counted separately.

Active-session registry renewal has a separate privacy lease. It starts at the
12-hour boundary, and retryable failure is tolerated until 23 hours since the last
recorded renewal; at that boundary the helper throws after attempting registration.
These age checks do not reserve attempts: repeated reconstructed calls before the
boundary still each perform a registry RPC. Successful renewal suppresses later
calls only when its timestamp survives persistence. Invalid or future recorded timestamps
now fail closed before registration, as described in the clock-integrity contract
below. This clock fence does not reserve finite retry attempts.
If Stop arrives during registration, the helper attempts compensating removal;
removal failure must remain recoverable without authorizing an unlimited retry job.

Context erasure separately lists at most 128 archived turns per wake and deletes
those keys in a batch; each deleted key remains part of the storage envelope.
A full batch schedules a confirmation wake to discover any remaining turns.
Deletion failure retains the archive and schedules another attempt. Session
finalization persists state from both public-billing settlement and its final
step when the persisted completion receipt is absent, incomplete or inconsistent
with current obligations. Context erasure alone does not establish completion.
The completed-receipt guard described in the runbook performs one session-key
read and skips finalization writes only when durable and current completion agree
for the same session and owner, with no pending usage or public billing. It
rechecks obligations after the read. An in-memory flag alone cannot establish that
a prior progress write succeeded; registry and room compensation remain separate.

Public-billing settlement currently iterates the entire saved billing map in one
invocation. A record needing quota settlement, share completion and usage reporting
can perform three downstream requests and two session-state writes, followed by
one write for the map. Successful quota settlement is persisted before usage
reporting, so a usage failure can retry reporting without re-settling quota.
However, each failed record requests retry scheduling separately, and a failed
final map write can replay reporting after reconstruction. Count those scheduler
calls separately from delivered wakes: repeated scheduling can overwrite one alarm.
A bounded replacement needs a durable cursor and per-record progress; truncating
the map or dropping acknowledged-but-unpersisted obligations loses recovery state.

This is an operating limitation, not permission to discard unresolved work.
Approved memories, private-context deletion obligations, quota reservations and
billing receipts must remain distinguishable and durable. Do not mark cleanup
complete, delete recovery state or settle unknown usage as zero to stop retries.

Before changing this path, require a joint compensation contract:

* Reserve attempts and a finite job deadline durably before downstream work.
  Persist each obligation's idempotent progress and stop automatic scheduling on
  terminal completion or exhaustion while retaining unresolved obligations.
* Bound downstream calls, response consumption and storage keys/rows per wake.
  Include registry/room cleanup and independently scheduled billing/context work
  in the operation envelope; an outer alarm cap alone is insufficient.
* Provide authenticated recovery for pending obligations and a durable stop fence
  checked before dispatch and rescheduling. Concurrent Stop, privacy revocation,
  queued callbacks and billing retries must not replenish or bypass the budget.
* Test duplicate alarms, reconstruction, clock boundaries, no progress, repeated
  downstream failure, reservation-write failure and successful downstream work
  followed by failed persistence. Count actual downstream calls and written keys,
  and exercise the corresponding real Worker/SQLite storage boundaries.

`packages/meet-core/src/features/live-assistant/session-cleanup.test.ts` verifies
that registry failure does not prevent independent room cleanup and that confirmed
completion stops later helper work. It does not establish finite retries,
reschedule-race safety, billing bounds or hosted alarm behavior. Keep those gates
explicit until their implementation and evidence exist. Billing alerts and
per-invocation CPU limits do not establish a total-spend cap.

## Registry lease clock integrity

Active Live sessions require nonnegative safe-integer start and renewal timestamps.
A renewal must lie between session start and the current server clock. Corrupt,
nonfinite or future timestamps fail before a registry request; the session tick
uses its existing `session_unavailable` stop path to end capture and retain billing,
room-release and privacy cleanup obligations. A server clock rollback can therefore
end an active session instead of silently extending privacy discoverability.

This applies to personal and room Live sessions. Valid leases retain the twelve-hour
renewal and twenty-three-hour retryable-failure boundaries. Ended sessions still
attempt registry removal even when their lease timestamps are invalid. These checks
do not introduce finite compensation attempts, authenticated background Stop or a
spending cap. Count those independent obligations separately.

Regression coverage: `registry-heartbeat.test.ts` exercises invalid timestamps,
reconstruction without registration I/O, exact lease boundaries, duplicate renewal
and ended-session removal. `session-cleanup.test.ts` checks independent compensation.
These helper tests use controlled namespaces; real SQLite persistence, hosted
privacy revocation and the complete stop/reschedule path remain release gates.

## Deployment and verification

Apply the additive `meet_private_ai_memory` migration through the repository's
normal migration pipeline. The Worker needs its existing Supabase configuration,
`MEET_REALTIME_TOKEN_SECRET`, and `GOOGLE_GENERATIVE_AI_API_KEY`; no key is sent
to another Worker or to the browser. Wrangler's `meet-live-v1` migration creates
the SQLite Durable Object binding `MEET_LIVE`.

Build the Cloudflare artifact, not only the Next application. The custom wrapper
re-exports OpenNext's cache Durable Objects and delegates every unrelated route.
Verify the final uploaded bundle against the Workers size limit.

Before release, verify two devices can distinguish private and room audio,
room guests cannot mint an assistant stream, memory changes cancel personal
sessions, explicit share approvals publish only the previewed content, and quota
settlement remains accurate after reconnects. Use synthetic conversation content
and isolated test rooms. Do not end an employee's active meeting during checks.

### Voice recovery and review outcomes

Microphone capture uses the browser's 16 kHz resampler and flushes its final
partial frame when stopped. A disconnected personal microphone pauses Live input;
select a working microphone in settings before resuming. Starting personal voice
mutes the meeting microphone; a failed startup restores its previous enabled state.
Room playback requires the listener to enable audio, with at most three seconds of
recent audio buffered while the browser awaits that gesture.

Approved tool outcomes are saved before provider delivery. After a reconnect they
are supplied as completed results, never automatically executed again. A workspace
operation with no completion acknowledgement after two minutes becomes an unknown
outcome for the requester to inspect and discard; discarding never retries the action. Permission checks and approval are required
for every private workspace operation. Task metadata tools without a matching
permission gate are not exposed.

Deployment checks require `GOOGLE_GENERATIVE_AI_API_KEY` on the Meet Worker.
Missing provider token allocation or search grounding usage remains marked as
incomplete cost coverage instead of being counted as free.

Server requests carrying room tokens or database credentials use `redirect: 'manual'`
and reject non-success statuses. Cloudflare's workerd runtime does not implement
`redirect: 'error'`; using it throws before the request reaches the upstream and
can fail the Live WebSocket upgrade. Do not replace this with `follow`, which
could forward credentials to a redirect target. Verify the deployed upgrade in
addition to the Next.js start-session route and provider-only tests.

### Continuous speech playback

Live output is scheduled consecutively on the browser audio clock with an 80 ms
startup/underrun buffer. Provider bursts longer than three seconds do not interrupt
speech. Interruption, playback mute, privacy suppression, and session teardown
still clear the queue; pausing input lets the current answer finish. Room transport
preserves generation and sequence fences, stamps freshness
at dispatch, and bounds queued PCM to 120 seconds. Test slow delivery and a burst
of at least twelve seconds before releasing playback changes.

## Local playback volume and finishing a turn

Use **Playback volume** in the meeting header to adjust master volume, Mira voice,
and each participant. Master volume scales the individual settings, including
screen-share audio and notification sounds. These settings affect only your local
playback for the current call; they do not change anyone else's microphone,
recording, or audio sent to Mira. Deafen and per-feed mute remain independent.

**Ask @mira in chat** opens Everyone, adds a mention without replacing your draft,
and focuses the composer. Private drafts stay private.

When the last microphone included in Mira's room input is muted or excluded,
the final buffered audio is flushed and Mira receives an end-of-input signal.
Other included microphones can continue the shared turn. Pausing personal input
also ends the input turn while allowing Mira's answer to play; privacy suppression
still prevents private playback while your meeting microphone is on.

# Meet solo mode and recovery
Source: https://docs.tuturuuu.com/platform/features/meet-solo-mode

Idle transport costs, private Mira conversations, and reconnect verification.

## Solo meetings

With one connected device, camera and microphone capture remain local. Meet does
not create a publishing SFU session until another device joins. When the last
other device leaves, Meet retires its publishing and receiving peer connections
without stopping local capture. The serialized `media.idle` command removes only
that device's retired session from room discovery; it does not wait for an
already-disconnected upstream session to close. AI still requires an internet connection and
uses the requester's normal quota; solo mode is not an offline AI model.

An idle signaling socket stays open so join requests and new participants arrive
immediately. Cloudflare answers the `meet:ping` / `meet:pong` keepalive through
WebSocket auto-response without waking the room. Presence is broadcast on change,
not every ten seconds. Grace-period alarms run only for disconnected participants.
Open sockets are not expired merely because a tab is backgrounded; keepalive
failure causes client reconnection. Usage reports skip unchanged byte counters
and resend after a signaling reconnect.

## Private Mira and room chat

The conversation panel opens Private Mira by default when alone. This context
stays private when someone joins. It does not import room chat, send prompts to
room services, or broadcast responses. The server charges the requester and
returns the answer only in their authenticated response. Search queries must not
include private history. The conversation view is kept in the panel's memory and clears when it closes or
the user leaves. A bounded requester-only receipt cache, stored separately from shared room
snapshots to avoid rewriting it on media/presence events, retains generated replies
for retry recovery for up to one hour of access (expired entries are pruned on
the next private request). Receipts are never returned by room/admin reads or
broadcast as messages. This is transient delivery recovery, not AI memory.
A request with uncertain generation/settlement is not generated or charged again.
Private generation reserves quota atomically before provider calls; search
reserves additional quota only when used.

The Everyone tab remains shared even when the sender is alone. Saved room
messages can be replayed to future admitted participants. Sharing a private Mira
reply requires reviewing the exact text and selecting Share with everyone; only
that text is posted under the requester's identity. Live assistant support is a
separate feature and must preserve the same private-to-room approval boundary.

## Recovery verification

Chat transport retries and manual retries after uncertain delivery use one client
message ID. Server replay is marked as history, deduplicated without moving the
newest message, and does not produce new-message notifications or unread counts.
Do not deduplicate by message body: intentionally repeated messages are valid.

Use the real call-controller harness in `apps/meet-realtime/src/media-check.ts`
with synthetic media. Verify zero publisher sessions while solo; then join a
second peer and verify both audio/video directions. Leave that peer, verify the
publisher closes without ending capture, and rejoin. Repeat with signaling
interruptions, screen audio, and TURN/TLS. Use an isolated room and never interrupt
an employee meeting for verification.

Partial SFU subscription responses must preserve the returned SDP even if an
individual track is unavailable. Discarding that offer can leave Cloudflare
waiting for an answer while the browser retries new subscriptions, leading to
406 and 410 errors. Failed or uncertain subscription negotiations rebuild the
receiving peer; publishing and receiving remain separate.

Retired publishing sessions keep bounded tombstones until the participant leaves,
so a late publish cannot revive them. A small client outbox repeats idle notices
on signaling reconnection; both publication and subscription work stop while solo.
Private search reserves multi-query planning headroom, then charges actual usage.
The unit-test CI job allows 20 minutes: a measured full-suite run passed all 52
tasks in 14m22s but its setup and cleanup exceeded the previous 15-minute job limit.

# Tuturuuu Meet
Source: https://docs.tuturuuu.com/platform/features/meet-together

Tuturuuu Meet helps you find and finalize the best time to meet with everyone.

![](https://mintcdn.com/tuturuuu/mFGDFuN77oMS85eY/images/meet-together/hero-light.png?fit=max\&auto=format\&n=mFGDFuN77oMS85eY\&q=85\&s=08ca7c2b292ddd7c98c23de40d4a0e74)

## Usage

To use [Tuturuuu Meet](https://tuturuuu.com/meet), create a plan and invite participants with its canonical sharing link.

This will require you to select the `dates` and `times` that you are available to meet, and optionally change the plan `original timezone` as needed.

> [!NOTE]
>
> Once you have done this, a link will be **automatically generated** for you so
> that you can share with your friends and/or colleagues.

They will be able to see the plan and select the dates and times that they are available to meet. Once everyone has selected their availability, you will be able to see the best time to meet with everyone.

## Saved Plans

You can also save your plans by logging in with a [Tuturuuu Account](https://tuturuuu.com/login). This will allow you to access the plan at a later time without having to manage links. Plans that you have filled out will also be automatically saved under your account.

Workspace Meet plans are scoped to their owning workspace. A public workspace
plan link is shareable with workspace members, but it is not globally readable
by ID. Anonymous access is only valid for public plans that are not attached to
a workspace.

## Plan Management

Everyone who has access to the plan will be able to see the plan details and the availability of everyone. Additionally, they will be able to change the plan name and delete the plan.

> [!WARNING]
>
> Only send the link to people you trust, as they will have access to the plan
> details and the availability of everyone.

> [!TIP]
>
> Plans are not automatically deleted, so make sure to delete them once you are
> done with them.

## Limitations

> [!WARNING]
>
> Timezone support is currently partiallly supported, it's not recommended for
> usage across different timezones yet.

> [!WARNING]
>
> Mobile support is experimental, so it's recommended to use a desktop browser
> for the best experience.

# Mira client actions
Source: https://docs.tuturuuu.com/platform/features/mira-client-actions

How Mira UI tools (theme, panels, navigation) are offered only to clients that can apply them.

Some Mira tools change the app rather than workspace data: `set_theme`,
`set_sidebar`, `show_workspace_artifact`, `manage_workspace`,
`set_immersive_mode` and `open_app`. The server returns a success marker and the
client applies the effect. Mira must never report an effect that no client
applies.

## Capability declaration

Each client declares the effects it applies with `clientCapabilities`:

The server removes undeclared UI tools from the registry, tool discovery and
forced tool steps. When a forced tool is unavailable, the step falls back to
discovery instead of requiring an impossible call. Every request gets a short
prompt note naming the effects its client cannot apply. For
example, without `artifact_panels` Mira uses `open_app` or answers in chat.
Unknown capability names are ignored so newer clients stay compatible. Data
tools are never gated by capabilities; permissions still apply.

An absent declaration means no UI effects, on every transport. Only clients
that explicitly declare an effect receive its tool:

* Web Mira chat declares `theme`, `sidebar`, `artifact_panels`, `immersive` and
  `navigate`.
* The shared AI chat route, including the retained legacy mobile transport,
  the native `/chat/conversations/:id/messages` route and canonical Live
  (`/api/v1/assistant/live/tools/execute`) forward only what the client sends.
  Without a declaration they expose no UI tools, so older mobile builds lose
  `set_theme` in chat until they update. That is preferable to Mira claiming
  effects nobody applies.
* AI agents and Mind have no client that applies markers and get no UI tools.
* Canonical Live also resolves the user timezone (client value, then saved
  personal, then workspace preference).
* Web dashboard Live declares `open_app` as a client function, alongside the
  existing theme, sidebar and panel functions.

## `open_app`

`open_app` switches to another app in the current workspace. Destinations:
`home`, `assistant`, `tasks`, `habits`, `calendar`, `finance`, `time_tracker`,
`mail`, `drive`, `meet`, `notes`, `chat`. It only navigates; it does not read or
change data. Each client maps destinations to its own routes. Web uses
`/:wsId/<segment>`, and Web's proxy redirects satellite segments to their owning
app. Web ignores markers with an unknown destination or an unsafe workspace
segment. Web Live navigation leaves the Live page.

## Mobile bridge and screen context

The mobile app registers one app-level bridge (`AssistantClientActions`) in
`app.dart`. It owns the router and theme, so chat and Live apply markers without
the Assistant page.

* **Chat** declares `theme`, `immersive` and, with the bridge, `navigate`. Theme
  and immersive are applied by the chat cubit; `open_app` goes through the
  bridge.
* **Live** declares the bridge's set (`theme`, `navigate`) with each canonical
  execution, and sends the verified device timezone. When
  `execute_workspace_tool` returns a `set_theme` or `open_app` marker, the device
  applies it before answering the model.
  * A marker the device could not apply is returned to the model as an error,
    never as a success.
  * This includes a theme that failed to save, a marker for a workspace other
    than the one selected on the device, and a marker whose turn went stale.
  * An unexpected client action exception becomes `apply_failed`; the response
    contains no success marker and subsequent tool calls can continue.
* **Scope:** each action is bound to the actor and workspace that requested it.
  A sign-out, account or workspace switch, or the caller's own turn guard
  cancels it until the effect is dispatched. In Live, an interruption or a new
  typed turn also cancels UI actions still pending from the earlier turn.
* **Theme writes:** the cancellation point is the synchronous scope check and
  preference dispatch. A scope change before it skips the write; after it, the
  write stands and the device theme follows the stored value. Mira never claims
  a cancellation it cannot guarantee. A storage write the platform reports as
  failed, or that throws, is returned as `theme_not_saved` and the current
  theme is kept.
* **Overlapping theme choices:** writes never wait on each other. One ledger
  per preference store gives every dispatch a sequence, including the repair
  writes it issues, and records the newest saved choice. When no write is
  outstanding, it rewrites the newest saved choice if a write was stored after
  a newer one or the cache holds a newer failed value. A choice is shown only
  if it is still the newest saved choice when its write returns.
  * Result: the UI, the cache and the store end on the newest saved choice
    for every completion order of overlapping choices and repairs.
  * Limit: a repair that itself fails or throws is not retried. The UI and
    cache keep the newest choice, but the store may hold an older value until
    the next theme write settles it.
* **Destinations** map to shell routes (`time_tracker` opens Timer). Access
  gates stay with the router redirects.
* **Leaving the Assistant:** when the app switches away, Live continues only if
  the user enabled Live while browsing; otherwise it disconnects as it does
  today.

`get_mobile_screen_context` (Live) still requires the Live while browsing opt-in.
It returns:

* the app section;
* `visibleRecords`: type and id pairs that the foreground screen registers;
* `form`: the open form's fields.

The rules for that content:

* Values are read only when Mira asks and are capped (20 records, 30 fields,
  500 characters per value).
* A field is sent as `[redacted]` when:
  * its rendered control is obscured or uses the `visiblePassword` keyboard;
    these are read from the real `EditableText`, not declared by the screen;
  * no rendered `EditableText` uses the registered controller (for example a
    custom widget with its own internal controller), so obscuring cannot be
    verified;
  * it is a closure field (no controller) that is not a well-formed `boolean`,
    `date`, `time` or `datetime` value;
  * its input type normalizes to a password, PIN or OTP type;
  * its key or label names a credential or identifier, in English or
    Vietnamese: password or passphrase, PIN, OTP, token, secret, private or
    API key, auth, bearer, credential, cookie, session, JWT, seed, mnemonic or
    recovery phrase, card, CVV, IBAN, account, routing, SWIFT or sort code,
    tax, national or social security ID and passport (for example
    `mật khẩu`, `tài khoản`, `xác thực`, `bảo mật`, `khôi phục`). Matching is
    deliberately broad, since a false match only withholds a value;
  * any recoverable reading of its value contains a secret (below).
* The whole field is redacted, not just the match, because a match in a
  normalized or decoded reading cannot be mapped back safely.
* Values are scanned before truncation, first folded (invisible format
  characters removed; fullwidth forms, superscript digits, punctuation
  look-alikes and the ellipsis folded; tab, NBSP and other spaces collapsed),
  also read without diacritics, and then decoded up to three layers (percent, `\x`/`\u`/HTML numeric escapes, base64 and hex
  runs that decode to valid text). Each reading is checked for:
  * credential shapes: JWTs, `sk-`/`sk_live_`, GitHub, Slack, AWS, Google and
    GitLab keys, bearer tokens and private keys;
  * Luhn-valid card numbers;
  * mod-97-valid IBANs;
  * long high-entropy tokens that mix letters with digits or both cases.
* **Supported characters only.** The app does not claim full NFKC coverage.
  Every supported character whose NFKC reading contains an ASCII letter or
  digit (for example the rupee sign, long s, ligatures, digraphs, ordinal
  indicators and fractions) is folded to that reading first. The fold table
  is generated from the supported ranges by
  `apps/mobile/tool/generate_assistant_compat_fold.mjs`, together with the
  NFD base letter of every supported precomposed character and a validated
  list of stroked, barred and hooked letters; rerun it after
  changing the ranges. `--check` verifies the committed table and runs in the
  mobile CI analyze job and `bun check:mobile`. Every reading,
  raw and decoded, may then contain only ASCII, Latin letters and marks
  (Latin-1, Extended-A/B and Additional, combining diacritics), common
  punctuation, currency, arrows, shapes and emoji. Dotless i and j are
  rejected as look-alikes. Any other character, including other scripts and
  non-ASCII digits, redacts the field. An encoding still decodable after three
  layers also redacts the field.
* **Diacritics.** Combining marks are supported for decomposed Vietnamese, so
  every reading is also scanned without them: NFD with every nonspacing mark
  removed. Marks inserted between a secret's characters (accents, or overlays
  such as U+0337 and U+0338) and precomposed accented letters therefore
  cannot hide it. The same reading maps Latin letters with a stroke, bar,
  hook, curl or tail that have no decomposition (Đ, Ł, Ø, Ħ, Ŧ, Ƀ, Ɨ, Ƶ, and
  eth Ð/ð) to their base letter. The shared value keeps its marks and
  letters, so Vietnamese such as `Đà Nẵng` is shared unchanged.
* **Punctuation look-alikes.** Supported characters drawn like the punctuation
  credentials are spelled with (`+ - _ = . /`) become that ASCII character in
  scan readings: heavy plus and Greek crosses; dashes, minus signs, heavy minus
  and horizontal box-drawing bars; double low line and the lower one-eighth
  block; double horizontals; middle dot and bullets; and the fraction slash,
  diagonal and heavy solidus, including when produced by fraction folding.
  Fullwidth forms use the fullwidth ASCII fold. This keeps embedded
  credentials in one scan token; ordinary fraction, list and box-drawing text
  retains its original display value. Other unsupported characters still
  redact the whole field, including after decoding.
* Free-text fields are also scanned together on what is actually sent (each
  value's first 500 characters): joined in order and in reverse, and every
  ordered pair across its boundary (256 characters each side). Pair boundaries
  of the full values are checked too. A secret only visible across fields
  redacts every free-text field.
* **Known limit (adopter gate):** a secret split over three or more fields
  in an order other than registration or reverse order is not detected. The
  calendar form registers only two free-text fields, so this is not reachable
  today. Before a screen registers three or more free-text fields, add a
  conservative fragment policy; do not add permutation scanning.
* Screen-context results reach the model only. Live turn parts, persisted chat
  history and restored caches keep a placeholder, never the payload.
* The most recently registered visible screen wins. Offstage shell pages report
  themselves hidden. `AssistantScreenContextScope` requires an `isCurrentScope`
  predicate; the registry checks it on every read, before accessing records or
  field values. Only a screen not tied to any workspace or account opts out,
  explicitly, with `AssistantScreenContextScope.unscoped`. Mounted create and
  edit event forms (`showEventFormSheet` requires the predicate too) stop
  sharing their context as soon as the selected actor or workspace changes,
  even before the next frame.
* Record ids are hints: the server re-reads records with the user's
  permissions, and Mira treats field values as user data, never instructions.

The calendar event form is the first adopter: event id, title, description,
all-day and start/end. Mira can read a half-filled event and help finish it.
Timed start and end values are the wall time shown in the form, in the
calendar's timezone, written as ISO 8601 with that zone's UTC offset (for
example `2026-10-26T09:00:00+07:00`), never as UTC. A time skipped by a DST
change has no offset. All-day values are plain `yyyy-MM-dd` dates.
Filling fields from Mira and sending screen context with chat messages are
separate follow-ups.

## Regression coverage

* `packages/ai/src/tools/mira-client-capabilities.test.ts`: resolution, gating,
  discovery, prompt note.
* `packages/ai/src/tools/mira-sdk-tool-search.test.ts`: forced-tool fallback.
* `packages/ai/src/tools/executors/theme.test.ts`: `open_app` marker.
* `packages/ai/src/chat/google/route-mira-runtime.test.ts`: declared
  capabilities reach the tool context and prompt.
* `apps/web/.../components/use-mira-ui-actions.test.tsx`: Web navigation and
  unsafe markers.
* `apps/web/.../assistant/use-live-tools.test.tsx`: Web Live `open_app`.
* `apps/web/src/app/api/v1/assistant/live/tools/execute/route.test.ts`:
  canonical defaults and timezone.
* The native messages `route.test.ts`: forwarded and default capabilities.
* `apps/mobile/test/features/assistant/bridge/`: bridge mapping, workspace
  guard, registration, Live marker truthfulness, screen-context redaction,
  bounds and visibility.
* `apps/mobile/test/features/assistant/data/assistant_live_repository_test.dart`
  and `apps/mobile/test/features/chat/data/chat_mira_timezone_test.dart`:
  declared capabilities and timezone.
* `apps/mobile/test/features/assistant/bridge/assistant_secret_scan_test.dart`
  and `assistant_screen_context_test.dart`: tab, NBSP, zero-width, fullwidth,
  percent, escape, base64 and hex readings; digit-free base64; unsupported
  characters in raw and decoded readings (other scripts, encoded non-ASCII
  digits); supported characters with an ASCII compatibility reading (long s,
  the rupee sign and vulgar fractions), folded and redacted only when the
  folded reading holds a secret, raw and encoded; the depth limit; secrets split across fields, including
  at the end of a bounded long field; custom controls with their own
  controller; structured closure fields; misleading field names;
  credential-bearing English and Vietnamese field names while ordinary
  calendar labels stay shared; real-control obscuring and `visiblePassword`.
* `apps/mobile/test/features/assistant/bridge/assistant_secret_lookalike_test.dart`:
  keys with combining marks inserted, precomposed accented letters or stroked
  letters, raw and base64; Bearer and GitHub tokens split by each punctuation
  look-alike, solidus overlay or stroked letter, in both fragment orders;
  ordinary decomposed Vietnamese, `Đà Nẵng` and `đường`, fractions, fraction-slash dates, diagonals, paths, URLs and bullet lists
  stay shareable while unsupported characters still redact the field.
* `apps/mobile/test/features/calendar/widgets/event_form_assistant_context_test.dart`:
  read-time scope checks and mounted create/edit forms across a
  `WorkspaceCubit` switch, including no reads of stale fields; start and end
  pinned to the calendar zone's offset in a non-UTC zone.
* `apps/mobile/test/features/calendar/utils/calendar_wall_iso8601_test.dart`:
  wall times with positive, negative and half-hour offsets, a DST gap and
  parsing back to the stored instant.
* `apps/mobile/test/features/assistant/assistant_live_screen_context_persistence_test.dart`:
  the serialized persistence request has no screen payload.
* `app_assistant_client_action_bridge_test.dart`: a thrown and a `false`
  theme storage result, and an account switch during a delayed theme write.
* `apps/mobile/test/features/settings/cubit/theme_action_scope_test.dart`: a
  held platform write keeps its result after a scope change; a `false` result
  keeps the old theme; a failed older write cannot roll back a newer
  same-value write; a failed newer write reconciles to the older saved value;
  two successful choices completing newest first end on the newest, in the UI
  and the store.
* `apps/mobile/test/features/settings/cubit/theme_write_ledger_test.dart`:
  repairs held across a newer choice (newest saved first and newest failed
  first), a newer dispatch failing during a repair, a repair that fails or
  throws, a throwing write, and all 56 two- and three-write success and
  completion-order schedules, checked at the UI, cache and store.
* `apps/mobile/test/features/assistant/assistant_live_client_action_turn_test.dart`:
  an interruption or new typed turn cancels a pending Live UI action.

# Mira body weight, habits and day overview
Source: https://docs.tuturuuu.com/platform/features/mira-health-planning-tools

How Mira logs body weight and habit entries and builds a one-read plan for a day.

Mira exposes five server-side tools from the shared `@tuturuuu/ai` tool
registry. Web chat, mobile chat and mobile Live (through the canonical
`execute_workspace_tool` bridge) use the same definitions and executors.

## Data ownership and transport

Habit data lives only in `workspace_habit_trackers` and
`workspace_habit_tracker_entries`. Mira calls the Tasks satellite habit API
(`/api/v1/workspaces/:wsId/habit-trackers`) with the caller's forwarded
authorization. The satellite enforces membership, the workspace habits feature
flag, input sanitising and RLS, so the tools need no extra Mira permission.
The Tasks origin must use HTTPS outside local development. Sessions without
forwarded request headers get a truthful "unavailable in this session" result;
nothing is logged.

Mira does not copy weights or habit entries into AI memory. The tools return
the stored values to the current conversation only.

## Body weight tracker selection and auto-create

Habit trackers and their entries are visible to every member of a workspace;
there is no per-user private tracker. Mira therefore resolves the tracker in
this order:

1. An active `use_case = 'body_weight'` tracker in the current workspace. The
   user created it there, so Mira logs there.
2. An active body weight tracker in the user's personal workspace.
3. Otherwise `log_body_weight` creates a **private** "Body Weight" tracker,
   always in the personal workspace. If the current workspace is a team
   workspace, Mira never creates a shared health tracker there. The result
   reports `trackerCreated: true` and the `workspace` used (`id`, `personal`,
   `isCurrentWorkspace`), and Mira tells the user. Without a personal
   workspace, nothing is created or logged.

The release authority approved auto-create on 2026-10-25. One function,
`createPrivateBodyWeightTracker`, owns creation. `get_body_weight_history` never
creates a tracker.

The new tracker follows the Tasks `body_weight` template: a daily summary,
maximum aggregation, `weight` as the primary metric and `kg`/`lb` as supported
units. Its unit is the logged unit, or kg when none is given. Its name,
description and field labels use the user's language: Vietnamese ("Cân nặng")
when the forwarded `NEXT_LOCALE` cookie or, failing that, `Accept-Language`
prefers Vietnamese, otherwise English. Mobile clients currently send neither,
so trackers created from mobile are named in English.

## Idempotent writes

Retries and concurrent requests must not duplicate habit data, and a retried
older operation must not undo a newer one. Migrations
`20261025125500` through `20261025125800` enforce this in the database:

* **Tracker `creation_key`.** A partial unique index allows one active,
  unarchived tracker per (workspace, creator, key). Mira creates its Body Weight
  tracker with the key `mira:body_weight`, so two concurrent first logs converge
  on one tracker. The Tasks API answers a repeat with the existing tracker and
  `created: false` (HTTP 200); only the request that inserted it reports
  `trackerCreated: true`. Archiving or deactivating the tracker releases the key.
* **Entry receipts.** Every accepted keyed entry operation gets an immutable
  receipt in `workspace_habit_tracker_entry_receipts`, bound to the tracker,
  member, key and a SHA-256 of the request body. The function
  `record_habit_tracker_entry_with_receipt` claims the receipt and writes the
  entry in one transaction, so a crash leaves neither.
  * A repeated key with the same body returns the entry with `replayed: true`
    (HTTP 200) without writing, and Mira reports `alreadyLogged: true`.
  * Daily summaries keep one mutable row per day, but receipts are separate:
    after A (70) and B (71), retrying A replays and the day stays 71. The
    result reports the current stored weight (71), not the old requested 70.
  * Reusing a key for a different body is rejected with HTTP 409.
  * Deleting an entry keeps its receipt, so a late retry reports 409 instead
    of bringing the entry back.
  * Concurrent calls with the same key wait on the receipt key and replay;
    concurrent calls with different keys for one day serialize on that day's
    row, and each keeps its receipt.
  * Receipts and the function are service-role only.

Mira derives entry keys by hashing the operation scope and normalized input:

* **Body weight:** the conversation (or tool call when there is no
  conversation), tracker, day, explicit occurrence time when supplied, stored
  value, unit and note. Re-logging the same weight without an explicit time on
  the same day in a conversation replays. A different value or explicit instant
  is a new operation; equivalent time-zone representations normalize to one
  instant.
* **Generic entries:** the tool call ID plus tracker, time, values and note.
  Counters legitimately repeat identical input, so only a retry of the same tool
  call is deduplicated. Without a tool call ID, no key is sent.

Both executors omit `occurred_at` when no time was supplied, so the server's
receipt hash stays stable across retries. An explicit time is sent and binds
the receipt. The cross-boundary regression tests call the real Tasks sanitizer
and request hasher from both Mira executors in
`apps/tasks/src/lib/habit-trackers/mira-idempotency.test.ts`.

The tracker column is new and nullable, so existing rows, including duplicate
trackers already in the data, keep `NULL` keys and cannot violate the index.
UI writes send no keys and behave as before. The Tasks API ignores keys while
the column or function is missing, so app and migration rollout order does not
matter. The migration sequence keeps existing-table scans outside the short DDL
transaction:

1. `20261025125500` adds the nullable column without a default or table rewrite
   and adds its check as `NOT VALID`, then commits its exclusive table lock.
2. `20261025125600` validates the check with `SHARE UPDATE EXCLUSIVE`, which
   permits ordinary reads and writes.
3. `20261025125700` contains only `CREATE UNIQUE INDEX CONCURRENTLY`. The pinned
   Supabase CLI 2.117.0 executes this lone statement outside a transaction batch.
   Keep it alone; adding transaction-scoped setup statements breaks that path.
4. `20261025125750` checks `pg_index` and fails if the named unique index is
   missing or invalid. `IF NOT EXISTS` alone cannot distinguish an invalid
   leftover from a usable index.
5. `20261025125800` creates the empty receipt table, its indexes and the RPC.
   Foreign-key setup briefly locks referenced tables; it does not scan existing
   tracker or entry rows.

The DDL and validation migrations use a 5-second `lock_timeout` to bound lock
acquisition waits. That setting does not limit how long an acquired lock is
held. No index is built on the entries table. The receipt table also has
leading-column indexes on `user_id` and `ws_id` for cascading parent deletions;
these are built while the table is new and empty. Columns, constraints and RPCs
retain the original combined migration's definitions. Regression coverage is in
`supabase/tests/habit-tracker-idempotency.sql` and the Tasks habit writer and Mira
habit executor tests.

### Recover a failed concurrent creation-key index

A failed or cancelled concurrent build can leave an `INVALID` index. Retrying
`20261025125700` can then skip that index because of `IF NOT EXISTS`; the
`20261025125750` guard stops the chain instead of treating uniqueness as ready.
The writer already checks for an existing key before inserting, but concurrent
first writes can still race between column creation and a valid unique index.
Coordinate recovery and any necessary pause of keyed writes with the release
owner. Do not delete tracker history or bypass the guard.

1. Inspect the index on the affected database:

```sql theme={null}
   select indexrelid::regclass, indisvalid, indisunique
   from pg_catalog.pg_index
   where indexrelid = to_regclass(
     'public.idx_workspace_habit_trackers_creation_key_active'
   );
   ```

2. Find conflicting active keys. Resolve each group through the supported
   tracker archive/deactivation flow, retaining the intended active tracker
   and its history. Do not choose winners automatically.

```sql theme={null}
   select ws_id, created_by, creation_key, count(*)
   from public.workspace_habit_trackers
   where creation_key is not null and created_by is not null
     and archived_at is null and is_active
   group by ws_id, created_by, creation_key
   having count(*) > 1;
   ```

3. After confirming the index is invalid, run this as a standalone statement
   outside a transaction. Do not drop a valid index merely to retry a migration.

```sql theme={null}
   drop index concurrently if exists
     public.idx_workspace_habit_trackers_creation_key_active;
   ```

4. If `20261025125700` is still pending, rerun the authorized migration workflow.
   If an earlier retry already recorded it as applied, execute that file's
   exact lone `CREATE UNIQUE INDEX CONCURRENTLY` statement through the authorized
   database operator, outside a transaction, before rerunning pending migrations.
   For a missing index, skip the drop and use the same rebuild path. Verify
   `indisvalid` and `indisunique` are both true, then rerun the pending guard and
   remaining migrations. Do not mark the guard applied or edit the migration
   ledger to bypass a failure. Production recovery requires release-owner
   authorization; agent checkouts must not run `sb:push` or `sb:linkpush`.

No automatic preceding drop is included: PostgreSQL cannot conditionally run
`DROP INDEX CONCURRENTLY` inside a `DO` block, and an unconditional drop could
remove an already-valid uniqueness fence on a retry.

## Units, bounds and dates

* A weight given in the other unit is converted to the tracker's unit
  (1 lb = 0.45359237 kg) and rounded to 0.01. The result includes
  `convertedFrom`. A tracker with any other unit is rejected rather than
  mislabelled.
* Accepted weights are 2 to 650 kg (or the same range in lb). Out-of-range
  values are rejected before any tracker is created.
* Daily-summary trackers keep one entry per day. A second log on the same day
  replaces that day's value (Tasks service behaviour).
* `entry_date` is the calendar date of `occurredAt` (default now) in the user
  timezone. With a missing or invalid timezone, Mira uses UTC and returns
  `timezoneAssumed: true`.
* History reads the caller's own entries from the Tasks entry list, which holds
  the 50 most recent entries per tracker across all members. When that limit
  may hide older entries in the window, the result includes
  `mayBeIncomplete: true`.

## Day overview

`get_day_overview` takes an optional `date` (`YYYY-MM-DD`, default today in the
user timezone) and computes the day window `[start, end)` in that timezone.
Sections load in parallel and fail independently: a failed section is `null`,
its message is under `errors`, and `partial: true` is set. `success` is false
only when every section fails. No section is filled with guessed data.

The Tasks entry list holds only the 50 most recent entries per tracker across all
members. When a tracker's list is full, entries for the day may be hidden, so
the tracker reports `progress: "incomplete"`, `dayTotal: null` and the
`visibleTotal` it could see, never a false zero. `met` is `true` only when the
visible entries already prove a `gte` target under an aggregation that hidden
entries cannot lower (`max`, `count_entries`, `boolean_any`); otherwise it is
`null`. Below the cap, progress is `"complete"` and exact.

The calendar section requires `manage_calendar`, like `get_upcoming_events`. When
the session cannot verify that permission, the section fails closed.

## Regression coverage

* `packages/ai/src/tools/executors/body-weight.test.ts`: forwarded auth, the
  missing-header result, find vs create, personal-workspace creation from a
  team workspace, no-personal-workspace refusal, a retried log storing one
  entry, racing first logs creating one tracker, Vietnamese and English tracker
  labels, unit conversion, bounds and the history summary.
* `packages/ai/src/tools/executors/habits.test.ts`: conversion, Ho Chi Minh
  City day boundaries, UTC fallback, locale resolution, stable operation keys,
  list mapping, generic entry logging and a retried tool call storing one
  entry.
* `packages/ai/src/tools/executors/day-overview.test.ts`: timezone bucketing,
  per-section partial failure, calendar fail-closed, caps, date validation and
  capped habit history reported as incomplete instead of zero.
* `apps/tasks/src/lib/habit-trackers/writes.test.ts`: keyed tracker replay and
  races, receipt-function calls, request-body binding, key reuse (409), a
  deleted entry (409) and the pre-migration fallback.
* `apps/database/supabase/tests/habit-tracker-idempotency.sql`: the tracker
  index, key release on archive or deactivation and legacy duplicates; for
  entry receipts, the A/B/A daily retry, different keys on one day, key reuse,
  event retries, retry after deletion, workspace binding, key format and
  service-role-only access.
* `packages/ai/src/tools/mira-tool-discovery.test.ts`: English and Vietnamese
  discovery of the health and planning tools.

# Mira Mail Tools
Source: https://docs.tuturuuu.com/platform/features/mira-mail-tools

How Mira reads recent email and creates reply drafts in Tuturuuu Mail without ever sending.

Mira can list recent email, read a thread, and create a reply draft in Tuturuuu
Mail. It cannot send email. Sending always requires the user to tap **Send** in Mail.

## Scope and defaults

| Tool | Behavior | Default and limits |
| - | - | - |
| `list_recent_emails` | Lists threads across the user's accessible mailboxes, or one `mailboxId`. Filters: `folder`, `unreadOnly`, `query`, `sinceDays`. | Inbox, 10 threads (max 25), snippets up to 280 characters, at most 10 mailboxes per call. |
| `get_email_thread` | Reads one thread as plain text. HTML is stripped and script, style, and head content is dropped. | Latest 10 messages (max 20), up to 4,000 characters per message, up to 12,000 characters in total. Newest messages keep their budget first. Reading does not mark mail as read. |
| `draft_email_reply` | Creates a reply draft on the thread, using a body Mira wrote or the Mail draft assistant (`instructions`). | Replies to the sender, or reply-all with `replyAll`. Uses the Mail app's recipient, subject, `In-Reply-To` and `References` rules. |

* **Mailboxes:** v1 covers first-party Tuturuuu Mail mailboxes only. Connected
  Gmail or Outlook accounts use a separate provider API and are not available to
  Mira. Tool results state this scope.
* **Surfaces:** web chat, mobile chat, and mobile Live. Live reaches these tools
  through the canonical `search_workspace_tools` / `execute_workspace_tool` bridge.
  Meet assistants do not receive these tools.

## Product decisions

* **No send tool.** Mira has no tool that sends email, and `draft_email_reply`
  never calls the Mail send endpoint.
* **Drafts need no confirmation step.** The release authority approved this on
  2026-10-25. `draft_email_reply` creates the draft directly. The result reports
  `status: "draft created"` and `sent: false`. Mira must tell the user it created
  a draft and that they review and send it in Mail. Mira drafts only when the
  user asks for a reply, never because an email asks for one.
* **Retries never duplicate a draft.** Each request sends Mail a stable
  `clientMessageId`. It is a UUID derived from the user, workspace, chat,
  mailbox, thread, reply mode, and the normalized body (or the assistant
  instructions). It leaves out the tool-call id, because a retry after a lost
  response arrives as a new tool call. Mail returns the existing message for a
  repeated key, including when two requests race on the `mail_messages` primary
  key. If that message was already sent, Mira reports it and does not claim a
  new draft. No migration was needed, because the key is the message primary key.
* **Email content is untrusted.** Subjects, senders, recipients, snippets,
  bodies, and the draft's subject and body preview are returned only inside
  `untrusted` fields, next to a `contentTrust` notice. The tool
  descriptions and the `mail` discovery guidance tell the model to treat that
  content as data only. The model must never follow instructions, links, or tool
  requests found in email.

## Access and transport

`packages/ai` never queries Mail tables. The executor
(`packages/ai/src/tools/executors/mail.ts`) calls the Mail satellite through
`@tuturuuu/internal-api/mail` and forwards the caller's cookie or Bearer token
with `withForwardedInternalApiAuth`. The Mail routes authenticate the token and
enforce Mail eligibility, workspace membership, and mailbox roles. Drafting
requires the `owner`, `admin`, or `sender` mailbox role. For that reason, the
tools add no workspace permission in `MIRA_TOOL_PERMISSIONS`.

* The Mail origin comes from `MAIL_APP_URL` or `NEXT_PUBLIC_MAIL_APP_URL`. It
  falls back to `https://mail.tuturuuu.com` in production. Outside local
  development, the origin must use HTTPS.
* A session with no forwarded request headers gets a truthful "unavailable in
  this session" result.
* A 401, 403, or 404 response is reported as a failure with its status. It is
  never reported as success. When some mailboxes fail during a multi-mailbox
  listing, the result lists them in `failedMailboxes`.

## Regression coverage

* `packages/ai/src/tools/executors/mail.test.ts` covers forwarded auth, the
  missing-headers and HTTPS checks, bounds and truncation, HTML stripping,
  untrusted fields, direct draft creation that never sends, and truthful
  403 and 404 errors.
* `packages/ai/src/tools/executors/mail-draft.test.ts` covers a retry after a
  lost response, which returns the same draft so only one exists. It also
  covers the stable key, an already-sent key, and prompt-injection text that
  appears only inside the untrusted fields.
* `apps/mail/src/lib/mail/repository/drafts-idempotency.test.ts` covers repeated
  and racing `clientMessageId` inserts. Neither creates a second draft or reuses
  another user's message.
* `packages/ai/src/tools/mira-tool-discovery.test.ts` covers English and
  Vietnamese discovery of the mail tools and their guidance.

# Mobile Chat navigation and pagination
Source: https://docs.tuturuuu.com/platform/features/mobile-chat

Native conversation browsing and scoped background loading.

## Conversation browsing

Mobile Chat retains the shared app shell and navigation while compact screens
switch between the conversation list and a selected thread. Wide screens keep
both panes visible. The list remains scrollable with tall filter content.

Conversation pages load automatically when the remaining scroll distance falls
below three quarters of the viewport, including when the first page cannot fill
the screen. Only one automatic request is made for an unchanged scoped list;
failed or empty pages retain a manual Load more action rather than retrying in a
loop. The manual action also remains available when filters show no rows.

Pagination results and failures from an older workspace or refresh generation
cannot publish into the current list. Pending local rows continue to use the
existing scoped Chat collection overlay.

## Composer

Attachments use the adaptive sheet shared by compact and expanded mobile
surfaces. Send remains disabled while a message or attachment upload is in
flight, and the icon exposes a localized tooltip. This changes neither message
transport nor attachment permissions; live device and production verification
are still required for delivery.

Regression coverage: `chat_conversation_layout_test.dart`,
`chat_pagination_scope_test.dart`, and `chat_thread_layout_test.dart` in
`apps/mobile/test/features/chat`.

### Assistant settings route chrome

Mira quick settings and the Assistant entry in general Settings open the same
account- and workspace-scoped editor. Because this imperative route covers the
app shell, it owns a branded Assistant Settings header, top safe area, and the
shared floating Back action. Content reserves space above that action. Model
selection and download state remain in the existing scoped model controller.
The actual header and saved preference are covered by
`assistant_settings_hub_test.dart`.

Calendar and Finance product entries open their existing preference editors
directly, matching general Settings: Calendar edits the first day of the week,
and Finance controls amount visibility. Legacy Preferences deep links still
redirect to general Settings. `settings_product_editor_checks.dart` covers
opening each product editor and persisting a choice on the actual Settings host.

### Mobile link browser choice

General Settings offers a device-persisted built-in browser (default) or external
default browser choice for ordinary web links, including assistant Markdown and
model publisher/license links, Mail, Meet chat, Notes and storefront previews.
Authentication, app-update and signed-download flows keep their dedicated
launchers. Mail, phone and SMS links use the system handler. Visible link actions report a localized generic failure without exposing URLs
or platform details, or silently switching browser modes. Initial app-link
opt-outs return a safe failed result when no UI feedback surface is available.
Late settings reads cannot replace a newer read or a saved selection. Helper and settings widget
regressions cover persistence, URL admission, mode selection and retry errors.

### Account notification preferences

Account notification preference reads and writes accept browser cookies and mobile
Bearer sessions. Reads remain scoped to the authenticated user and account rows
(`ws_id IS NULL`); writes derive the actor from the session. This authentication
repair does not establish cross-platform notification delivery or enforcement.
Route regressions cover credential forwarding, anonymous rejection, account
isolation, invalid writes and bodyless HEAD responses. Rust GET already uses
caller-token reads; unported methods continue through the live Next API.

## Stream completion

Native Chat and Mira replies stop reading their NDJSON response after a verified
`done` event. Chat requires a saved message receipt; Mira requires a saved
assistant message receipt. Text or tool deltas alone do not prove persistence.
An explicit server error remains a failed reply even when followed by `done`.
Malformed data before completion and EOF without completion remain errors.
Completed replies ignore post-terminal rows and bytes, and UTF-8 decoding retains
partial characters across transport chunks. Response cancellation starts at
completion; cleanup failures or stalls do not replace the saved receipt or an
earlier transport failure. This applies to native Chat streaming;
legacy Assistant SSE and explicit Live sessions keep their separate protocols.

Regression coverage: `chat_stream_terminal_test.dart` and
`assistant_chat_transport_terminal_test.dart` exercise the real repository and
Assistant cubit with synthetic response bytes, alongside parser and scope tests.
These checks establish source behavior; production provider/storage failures
and actual device transport still require separate runtime evidence.

### Durable assistant receipt and cleanup

After the native Chat/Mira batch RPC returns saved assistant messages, shadow
resource cleanup is supplementary. A thrown cleanup failure cannot remove the
saved JSON/NDJSON receipt or turn an accepted reply into a retry prompt. Failures
before authoritative persistence, including permission or database errors,
remain failures; no text-only success or remote fallback is introduced.
`native-ai-cleanup-receipt.test.ts` covers the actual message route with durable
save followed by failed cleanup. This establishes a source boundary, not the
cause of every missing reply or device/provider delivery evidence.

### Compact on-device status in the header

Native Mira Chat shows on-device readiness, preparation or attention status in
its shared branded header, rather than a repeated block above the conversation.
The accessible control opens full model status and failure guidance with an
explicit model-settings action. It retains a 48px touch target and truncates the
compact label on wide layouts. Editable assistant titles have a separate 48px
on-device recovery control, so tapping the name always opens rename. History and
Assistant Settings share the overflow menu; Live exposes Settings there and
keeps its separate information action. An editable assistant title or registered
Chat local status uses a 48px header content minimum; default and
other-route geometry stays unchanged, and floating content clearance matches. The current saved assistant
name appears in both Chat and Live; Live hides the local-text chip because voice
uses its separate remote runtime. Returning to remote Chat removes the chip.
Retained recovery actions reject actor/workspace/selection changes and disposal.
No status control sends a failed local prompt remotely or proves native readiness.

`assistant_compact_model_header_test.dart` covers the actual page and header in
English/Vietnamese at 320px with enlarged text, recovery guidance, remote return,
Live visibility and stale actions. `assistant_mode_title_test.dart` preserves
fallback titles and verifies current name changes. Actual-device safe-area,
accessibility and native model loading remain separate delivery checks.

## Assistant name write admission

The mobile header shows the current custom name, or `Mira` when none is set, in
both Chat and Live. Tapping its name opens an explicitly focused dialog with
native text selection and paste controls. Save trims the draft and permits
1–50 characters. Pending saves prevent duplicate submission; failures retain
the draft with a localized safe error for explicit retry. Cancel closes the
dialog and does not undo a request already admitted by the server. Account or
workspace departure invalidates retained dialog actions, including returning to
the same account or workspace. On-device recovery remains a distinct control.
Opening an unsent local draft is a presentation action and does not require
network authentication. Its retained action still checks the captured account,
workspace and departure epoch. Live, overflow and network actions keep their
authenticated admission requirements.

`assistant_name_dialog_test.dart` covers English/Vietnamese save, keyboard,
native paste, safe retry, busy/cancel and held-write departure cases.
`assistant_name_navbar_test.dart` exercises the production page and action rail
at 320px with text scales 1, 2 and 3, stable callbacks and stale actions.
`shared_navbar_large_text_test.dart` retains default factories and other-route
geometry. These are source/widget checks, not device or server delivery proof.

Mira's custom name is personal to the authenticated account, including when the
mobile assistant is opened from a workspace. A rename captures its account and
cache identity before awaiting storage or network admission. Logout/cache-clear
and superseded local rename intents cannot publish into a successor session or
enter the outbox after departure. Rename and Soul refresh share a publication
generation so an older response cannot replace the latest accepted local view.

An online update requires a valid server Soul receipt; missing or malformed
receipts do not become a fabricated `Mira` success. Offline names remain pending
account-owned intents, rather than confirmed server writes. This client admission
boundary does not provide cross-client compare-and-swap or claim that ambiguous
network writes are safe to replay automatically. Genuine permission and transport
failures retain their existing behavior.

Successful live `update_my_settings` tool results also force an account-owned
Soul refresh, resolving the SDK's nameless result from its matching input in the
current assistant message. Preliminary, failed, conflicting and unmatched
results do not refresh; duplicate results refresh once per submission. Restored
history never replays this effect. Departed actor/workspace operations cannot
admit effects or report late refresh errors. A metadata refresh failure keeps the
confirmed reply and last accepted name, and offers a localized notice to reopen
assistant settings. Genuine reply persistence and transport failures remain
separate failures. This rule does not settle conflicts with pending offline name
edits or provide cross-client ordering guarantees.

Workspace-context and immersive-mode effects use the same current-input identity,
definitive-success and duplicate admission rules. Workspace context requires a
nonempty destination; immersive mode requires an explicit boolean, including
`false`. A missing or malformed value does not become a fabricated UI action.

`assistant_tool_receipt_test.dart` exercises the actual native NDJSON mapping,
tool admission, duplicate/history isolation and delayed scope changes;
`assistant_tool_name_title_test.dart` verifies the production shell title in both
languages using native-mapped submission events. These tests do not establish
device or production runtime delivery.

Regression coverage: `assistant_soul_name_writer_test.dart`,
`assistant_name_publication_test.dart`, and
`offline_queue_disposal_regression_test.dart` cover held cache/queue/network
admission, actor and workspace departure, same-actor logout restoration,
superseding writes/refreshes, malformed receipts, and admitted ACK cleanup.

## Assistant reply error and save receipts

Native Chat and mobile Mira use the canonical messages POST adapter. By default,
an upstream SSE error produces the fixed public message `AI response unavailable`
when request-scoped server history contains no saved assistant reply. Upstream
error text, provider bodies, credentials, URLs, and model diagnostics are never
used as public error messages. Unknown error payloads use the same fixed fallback.
This applies to streaming and ordinary JSON requests.

A saved partial assistant reply remains authoritative even when the upstream
stream fails. Failed history readback retains the separate send failure response.
Without an upstream error, missing saved history retains `AI response was not saved`.
Replaying a saved client request returns its existing messages without generating
or charging again. This error mapping does not establish the cause of any
customer save incident or repair database persistence.

Regression coverage: `ai-stream-error-regression.test.ts` beside the canonical
`apps/web/src/app/api/v1/workspaces/[wsId]/chat/conversations/[conversationId]/messages/route.ts`.
The migration backend owns GET only; POST remains tracked Next.js backlog until
mutation parity is implemented. Live native build and save/reopen verification
remain separate delivery requirements.

## Explicit mobile Assistant model and credit settings

Native Chat-backed Assistant model and credit-source choices use the authenticated
conversation settings PATCH, with its `manage_chat` permission check. The client
admits one request after credential preparation, bound to the current actor,
workspace, conversation, selection revision and page lifetime. It validates the
returned conversation ID and complete model, credit source, credit workspace and
thinking-mode tuple before publishing the choice or its local preferences.
Concurrent choices are denied while one is pending. Native history restoration
hydrates the complete validated model, credit source, nullable credit workspace
and thinking mode before admitting Send. It is a read-side operation under the
current actor/workspace/chat generation; opening history never PATCHes settings
and needs no manage permission. Old native snapshots without a complete tuple
must revalidate it. Server-default nullable credit scope and fast mode remain
exact values, rather than being replaced by workspace preferences.

Permission denial, malformed receipts, uncertain transport and stale completion
retain the prior local settings and draft. A stale or missing response can still
follow a physical server write; the client does not compensate or retry it.
Localized notices direct the user to inspect settings before another explicit
choice. This is a client lifecycle fence, not cross-client compare-and-swap.

With no selected conversation, a choice is a local intent. First native creation
captures a one-use model/credit/thinking tuple and includes it in the existing
creation request. The route retains `view_chat`; the canonical creation transaction
retains `create_chat` for AI conversations and writes the complete initial settings
with the conversation and owner membership. It returns the stored tuple bound to
the actor, workspace and new chat. There is no automatic post-creation settings
PATCH and no new `manage_chat` requirement for otherwise authorized first use.
Explicit later settings edits still require `manage_chat`.

Workspace credits may target only the active workspace; personal credits resolve
to the actor's personal workspace. An explicit null scope is retained while billing
resolves the corresponding authorized workspace. An unavailable selected model is
rejected rather than silently replaced by a plan default. No-tuple creation clients
retain existing defaults; DM/group/channel creation cannot provide the new AI tuple.
Malformed, mismatched, unknown or retired creation receipts retain the draft and
creation hold, without a replacement creation or blind retry. Creation POST checks
the captured actor/generation after awaited credential preparation and before its
single HTTP dispatch;401 or challenge responses are not replayed. Ordinary
follow-up sends only read and validate stored settings; they never PATCH them.
The optional creation tuple requires the atomic database migration before activation;
a route-only rollout cannot acknowledge an old RPC response missing that tuple.
Regression coverage includes `assistant_first_create_v100_test.dart`, the actual
creation route's `initial-settings.test.ts`, and `chat-initial-ai-settings.sql`.
Route/page fixtures do not certify migration execution; isolated SQL qualification
and exact-commit CI remain delivery gates.
The strict saved-message and request-identity checks remain in force. Legacy
prefixed AI conversations cannot provide this complete stored-settings receipt,
so this control denies their stored model/credit edits before PATCH; their
AI SDK SSE protocol remains supported. A legacy turn binds a top-level
`persistenceRequestId` to its original user request. Authenticated owner-filtered
history readback must confirm one durable USER row with that request identity,
source and original submitted text before the composer clears. The AI route saves that request-scoped USER row before claiming the persistence lease, including on a first turn whose history holds only that message; only unscoped first turns rely on chat creation having saved them (`packages/ai/src/chat/google/request-scoped-first-turn.test.ts`). The server derives `requestText` metadata from the normalized UI input,
separately from prepared attachment content; rendered
file/image markers in stored content are not stripped or guessed by the client.
Historical text-only receipts without that metadata retain exact-content checks. Text, stream completion and
`[DONE]` are not receipts. An unknown result keeps the draft and attachments;
an explicit repeat retains the original identity and checks durable history
before another dispatch. A confirmed USER receipt precedes any reply failure:
the composer consumes the saved draft while the model/transport failure remains
visible. One deferred stream error is retained while checking the receipt. Existing server request leases and request-scoped user
persistence provide idempotency. No automatic retry or new identity is used for
an unknown turn. Local on-device conversations and
explicit Live sessions retain their separate flows.

Regression coverage: `assistant_repair_regression_test.dart`,
`assistant_settings_selection_test.dart`, `assistant_settings_receipt_test.dart`,
`api_client_acknowledged_patch_test.dart`, `assistant_restore_send_v87_test.dart`,
and `assistant_creation_admission_v87_test.dart` cover actual page hooks and first
Send, raw receipt mismatches, permission/uncertainty, overlapping choices,
actor/workspace/chat ABA, disposal, and one-dispatch HTTP admission. These use
synthetic auth and HTTP dependencies; hosted permission behavior, provider/device
sessions and the original Hive incident remain separate delivery evidence.

## Handled Assistant operational failures

Mobile Mira reports active handled failures through an injectable typed boundary.
The phases distinguish server conversation creation (`assistantCreate`), local
conversation-pointer persistence (`assistantPreferencePersist`), and reply
transport or protocol failure (`assistantReply`). A protocol error contains no
trusted persistence classification, so its text never determines a save-failure
code or a customer root-cause claim. Successful durable completion is not an
incident. Superseded operations, stopped streams, workspace ABA and session
invalidation are excluded.

By default, the production flavor sends a nonfatal Crashlytics event containing
fixed phase/failure codes, valid HTTP status when available, a Retry-After bucket,
and bounded numeric app version/build. It sends no original exception, captured
stack, chat content, personality, memory, email, token, URL or request body.
The SDK receives a fixed synthetic frame and event-local information, rather than
persistent custom keys. No correlation ID is included because these call sites
have no independently trusted opaque request ID. Global fatal hooks remain a
separate path and retain their existing stack behavior.

Repeated signatures are suppressed for five minutes with a 128-entry cache that
prunes expired entries and evicts the oldest at capacity. This is best-effort
bounded reporting, not a per-occurrence alert, event queue or autonomous repair
bridge. Sink failures never delay chat state or retries. Development collection
stays disabled. Provider retention/consent and authenticated device ingestion
must be verified separately before release; this client path adds no private
feedback storage or staff access.

Regression coverage includes `assistant_chat_operational_reporting_test.dart`,
`assistant_chat_transport_terminal_test.dart` and
`operational_error_reporter_test.dart`. These exercise actual native NDJSON and
legacy SSE adapters, separate creation/local persistence/transport failures,
privacy, cancellation and sink isolation. They do not prove a customer incident's
cause or native Crashlytics delivery.

## Assistant conversation persistence

Mobile Assistant uses an explicitly acknowledged native Chat creation response.
Offline placeholders remain available to ordinary Chat consumers, but cannot
become an Assistant conversation identity. Attachment preparation and a queued
send share one creation acknowledgment for the same actor, workspace and fallback
generation. The repository retains one instance-local result for that current
generation. An uncertain failed result retains the existing creation hold. Upload and send use
the same validated durable conversation ID. Cancellation settles the send without
dropping a still-current attachment creation.

Workspace loading, actor lifecycle through workspace loading or closure, and a
confirmed explicit reset invalidate this generation monotonically. A raw actor
getter changing away and back without any lifecycle signal is not observable;
callers must use these lifecycle boundaries. A stale acknowledged result cannot
qualify a later generation. Opening a different conversation also invalidates
pending creation before changing selection. Creation publication and ordinary
selection writes share one actor/workspace preference lock. An already-admitted
old write drains before the current selection is durably written; stale callbacks
cannot change the newly selected history or start an old attachment upload. The native creation API validates
its committed receipt before returning it. A later realtime publication failure
does not change that known receipt into a failed creation response.

Bare conversation UUIDs select native Chat storage. `ai-chat-` and `legacy-ai-`
prefixes select existing AI storage. Native permission or availability failures
never switch stores. Restore failures preserve the selected conversation and
its history. Only an authoritative missing response for an explicitly selected
legacy conversation may remove that selection. Ambiguous historical bare UUIDs
remain selected with an error rather than being silently rewritten.

Native sends read authorized stored AI settings. They do not PATCH persistent
settings merely to send a message. The native message endpoint has no per-turn
model, credit, or thinking override; an unsupported selection produces an error.
`manage_chat` permissions remain required for editing stored settings.

Saved user receipts retain the original client request ID alongside the server
message ID. Restore and retry preserve that original identity. Changed payloads
remain subject to the server's idempotency conflict checks. Attachment ownership
and saved assistant receipts retain the existing stream completion behavior.
The native composer helper waits for `submitAcknowledged`, which distinguishes
acknowledged, denied, unknown, and stale outcomes. Only a matching validated saved
user receipt for the original request can consume the current draft. Starting a
stream or receiving an assistant reply is insufficient. Composer attachments
remain until that acknowledgment and are cleared only if their snapshot is still
current. A later model failure preserves the known saved user and its retry ID.
Identical follow-up text uses a new request identity; explicit retries retain the
original one. Queue discard and stale transport completion settle waiting callers
without a new request or retry timer. A validated saved user acknowledgment
returns independently of observer cleanup. Cleanup remains owned and drained;
a delayed or failing cancellation cannot replace that receipt or settle a newer
request. Selecting another chat retires only the stale request’s still-owned queued
entry before its debounce can send; drafts and attachments remain available, and
a later send requires its own matching USER receipt. Default stop and explicit supersession settle only the queued or active
request they cancel. A canceled attempt retains its draft and attachments; idle
status is never an acknowledgment. Pre-stream failures, including decoder errors,
settle the owning request without bypassing uncertainty holds.

For an unresolved native request, ordinary repeated Send reads the original saved
USER receipt through the authorized messages endpoint; it does not issue another
POST or allocate a new request identity. The pending turn retains immutable text,
attachments and actor/workspace/chat identity for the current Assistant session,
including selection retirement during settings preparation. Known pre-dispatch
preparation failures release that tentative hold.
Changed draft or attachments remain held until that original turn is resolved.
Missing, denied or malformed readback remains unknown; no timer retries generation.
A stale actor/selection generation cannot consume the current draft. A validated
original USER receipt resolves persistence even if the model failed afterward;
it does not claim an assistant response succeeded. Once acknowledged, an equal-text
follow-up is a new turn. Explicit model Retry keeps its existing request identity.

The active creation and native message API boundaries validate PostgreSQL receipt
timestamps and return UTC ISO text before strict mobile decoding. SQL space
separators, microseconds and numeric offsets normalize without dropping fractional
precision; invalid calendars, offsets or fractions fail closed after persistence.
This response adaptation does not change global SQL serializers or prove migration
execution. Regression fixtures cover SQL-shaped creation with and without an initial
tuple, native JSON/NDJSON/history receipts, invalid dates and retained-draft identity
in `assistant_native_identity_v108_test.dart` and the active route tests.

Native stream and JSON receipts validate raw UUIDs, canonical message kinds,
string content, explicit ISO timestamps and metadata before generic model
coercion. User receipts also require the original request UUID. Malformed batch
rows reject the batch instead of disappearing during filtering. Ordinary Chat
parsing retains its existing compatibility behavior.

Assistant snapshots capture the injected actor, workspace, conversation, locale,
lifecycle epoch and cache revision before awaiting storage. Reads check that origin
before and after storage/network work; writes pass its revision and scope fence to
the existing cache store. A changed scope or revision cancels an obsolete snapshot
without moving it to another actor or retrying it. Completion snapshots are immutable,
tracked and serialized per key; identical protocol/transport completion requests
share one publication. A completed failed or cancelled result is evicted so a later
explicit request can publish the same snapshot after recovery; this schedules no
automatic retry. Pending requests and published results still coalesce.
Same-scope supersession skips work before admission;
an admitted authorized write and its rollback finish before the successor. Local
queue order cannot revoke rollback authority. If the successor fails, the last
authorized snapshot survives. Close invalidates their leases and drains owned work.

Cache cancellation does not undo a validated USER receipt. Genuine storage failures
retain the prior authorized snapshot and produce safe diagnostics; valid network
history remains usable. Explicit restore observes all thrown failures and retains
selected history on failure. Real disposable encrypted-store controls cover held
publication, latest reopen, storage faults, scope departure, clear, held reads and
close drain. Synthetic transport in those tests does not prove live authentication,
provider behavior or a device session.

Provider-free contract fixtures exercise creation, two sends, reopening after
each send, and retry after reopening. They also cover malformed IDs, workspace
mismatches, pending creation rows, denied or unavailable restore, and interrupted
creation. These checks prove source contracts with synthetic dependencies; they
do not prove provider calls or an authenticated device session.

Mobile Assistant stores the selected chat, workspace context, and creation hold
in one private versioned actor/workspace envelope. Every owning reader and writer
uses the same scope lock and reloads the host value. Legacy selected/context keys
are read-only fallback only when the envelope is absent; a legacy clear marker
never grants creation. Malformed or unsupported records require inspection and
cannot be overwritten or replaced by legacy fallback. The envelope contains IDs,
status, revisions, and reset evidence, with no prompts, attachments, or credentials.

Native reset prepares a pure, current shell capability before making any effect.
An acknowledged pending intent first retains the selected/context beforeimage and
holds creation. Only its known current receipt permits a second whole-tuple write
that selects no chat, selects personal context, advances the generation, and binds
informed consent to that operation and prior hold. Pending intent on restart stays
held and retains the beforeimage; it is never finalized automatically. A known
current final receipt publishes the prepared shell/chat reset synchronously.
Loading a workspace reads its stored context without writing it back, preserving
pending reset beforeimages and known process consent. Other model and credit
normalization remains separate from this context read.
Postcommit notifications are observed and cannot veto a known commit.

`resetConversationAcknowledged` reports `deniedBeforeEffect`, `committedCurrent`,
`committedStale`, or `uncertain`. The compatibility `Future<bool>` is true only for
`committedCurrent`. False, thrown, or stale host writes can have physical effects;
callers must retain drafts/history and show honest uncertainty rather than promise
that persistence stayed unchanged. An absent prepared adapter denies before effect.
The former effectful guarded callback cannot qualify this protocol. The owning
page now prepares the pure shell capability and consumes the typed outcome.
An uncertain or absent creation envelope offers localized Cancel, Check history,
and Start a new chat choices. Consent is an opaque, one-use process capability
bound to the observed actor, workspace, selection, context, and hold beforeimage;
a changed hold or an observed departure cannot reuse it. Cancel, denial, stale
completion, and uncertainty retain the current draft and attachments. Only a
current committed reset clears its still-owned draft. History stays open until
that reset completes; Live cleanup failures remain explicit after a known reset.
These defaults apply to remote Assistant Chat; local conversations retain their
separate reset flow. Regression coverage is in `assistant_new_chat_reset_test.dart`,
`assistant_new_chat_confirmation_test.dart`, and
`assistant_reset_consent_target_test.dart`; device/provider behavior remains a
separate delivery gate.

A known selected chat denies new creation before any hold write or POST; its clear
status remains truthful and its history remains usable. Empty selection is required
independently of clear status or informed consent.
Only a current-process final receipt authorizes one next creation. Restart,
lifecycle departure, or another selected/context write revokes that grant. Close
entry fences reset immediately, before waiting for stream cancellation. Creation
rechecks its captured origin after host acknowledgement and immediately before
transport admission. Beginning
creation consumes it and writes the next unknown attempt before HTTP. A validated
server acknowledgment writes the durable selected ID and clear status together;
only the exact verified pre-effect coded validation denial may release a failed
attempt. Timeouts, transport errors, server failures, and uncoded rate limits hold
creation with no automatic retry or replacement UUID. Known-history follow-up
remains available. This is one-key logical tuple atomicity with a process scope lock,
not multiprocess CAS or a physical disk guarantee. If intent storage is unavailable,
no durable hold can be promised and no other reset/create effect proceeds.

Regression coverage: `assistant_shell_recovery_test.dart`,
`assistant_reset_commit_test.dart`,
`assistant_chat_reset_order_test.dart`, `assistant_chat_reset_close_test.dart`,
`assistant_chat_persistence_contract_test.dart`,
`assistant_creation_marker_test.dart`, `assistant_chat_persistence_test.dart`,
`assistant_chat_submission_ack_test.dart`, `assistant_chat_cache_publication_test.dart`,
`assistant_chat_cache_lifecycle_test.dart`,
`assistant_chat_creation_interleave_test.dart`,
`assistant_chat_creation_selection_test.dart`,
`chat_creation_receipt_test.dart`, and the existing Assistant restore and
transport completion tests in `apps/mobile/test/features/assistant` and
`apps/mobile/test/features/chat`.

Stream fixture diagnostics record mock entry, response readiness, body listening
and cancellation separately. Delivery deadlines begin after bounded readiness;
primary phase failures retain their error and stack when cleanup also fails.
Synthetic held-mock controls exercise the never-listened body path. These controls
do not identify an earlier incident's blocked await without its readiness evidence.

# Mobile Home and Notifications
Source: https://docs.tuturuuu.com/platform/features/mobile-home-notifications

Layout, grouping and state rules for the mobile Home dashboard and the Notifications inbox

Home and Notifications use the grouped design language of mobile Settings:
muted captions above rounded grouped cards, Lucide line icons in tone-tinted
tiles, and theme tokens only. Data sources, actions and routes did not change
with the redesign.

## Home

* **Header.** Today's date, a time-of-day greeting with the profile display
  name when one is set ("Good morning, Linh"), and a workspace switcher pill
  that opens the existing workspace picker. The shell navbar keeps the "Home"
  title, so the greeting is not a second page title.
* **Widgets.** The existing widgets keep their order, visibility and
  **Customize Home** editor: assigned tasks, upcoming events, mail, meetings,
  finance, notes and the Today summary. Each widget is a caption with an
  **Open** link above one grouped card.
* **Task rows** show the due state first: Overdue (destructive tone), Today
  (warning), Tomorrow (primary) or the localized date, then board and list.
  **Event rows** show a calendar-leaf date tile, weekday and time.
* **States.** First loads show placeholder rows inside the card. Failed loads
  show an inline "Something went wrong / Pull down to try again." row. Empty
  widgets show an inline message with the widget's icon.
* **Responsive.** Page kind `root`. Widgets flow in content-sized columns of
  at least 340dp: one column on phones, two on portrait tablets and up to
  three on laptops and desktops. The header puts the switcher beside the
  greeting from 560dp of content width.

## Notifications

* **Grouping.** The inbox and archive are grouped by device-local calendar
  day: **Today**, **Yesterday**, **Last 7 days** and **Earlier**. Groups keep
  the server's newest-first order; an out-of-order item starts a new group
  instead of being moved.
* **Rows.** Each row has a type tile (invites warning, security and rejections
  destructive, completions and approvals success, mentions and mail info), a
  primary unread dot on the tile, a semibold title while unread, the body (up
  to three lines), then the workspace and relative age. Open invites show
  **Decline** and **Accept**; answered invites show a status badge. A
  48dp read toggle sits at the trailing edge.
* **States.** First loads show placeholder rows; load failures and empty tabs
  show a centred message, with **Retry** on failures. Raw error text is never
  shown.
* **Responsive.** Page kind `detail`: full width on phones and a centred
  readable column (600dp on tablets, 720dp on desktops). A notification opens
  its destination route, so the list does not use a list-detail split.

## Calendar reminder alerts

Mobile local calendar reminders show the event name in the title and the
localized lead time plus occurrence date/time in the body. English and Vietnamese
omit the timezone label by default for both timed and all-day events. Timezone
resolution and clock conversion remain unchanged; all-day reminders show only
the occurrence date. This rule applies to mobile scheduled OS alerts, not the
server-backed inbox or attendee emails, which do not use this formatter. Task
reminder copy is unchanged.

Regression coverage: `test/features/reminders/reminder_notification_copy_test.dart`
checks both languages, the Asia/Saigon alias, date-only all-day copy and a timed
occurrence projected into a different calendar day.

## Regression coverage

* `test/features/shell/view/appearance_root_tabs_render_test.dart` (parts
  `home_render_cases.dart` and `notifications_render_cases.dart`) renders both
  screens in the real shell with fixture data at 390x844, 820x1180 and
  1440x900 in Classic light/dark, a gradient and a blob theme. It asserts the
  phone gutter, the column count, the 44dp targets, the four group captions,
  and the loading, error and empty states. Set `SETTINGS_RENDER_DIR` (plus
  `SETTINGS_MATERIAL_FONT` pointing at a Roboto TTF, and optionally
  `SETTINGS_RENDER_PIXEL_RATIO`) to write PNG captures.
* `test/features/notifications/widgets/notification_day_groups_test.dart`
  covers calendar-day bucketing and feed-order preservation.
* `test/core/layout/grouped_rows_test.dart` covers tones, row targets and
  state actions.

# Mobile Profile overview and timeline
Source: https://docs.tuturuuu.com/platform/features/mobile-profile

Layout, identity, private-activity and timeline presentation rules for the mobile Profile root tab

The Profile root tab uses the shared mobile design language: theme tokens,
Lucide line icons, the composition kit and the grouped row vocabulary. Data
sources, privacy scope and navigation did not change with the redesign. The
overview still shows only the signed-in user's own identity and personal,
user-filtered activity. Opening the timeline never shares it.

## Overview

* **Identity card.** The cover (or a soft accent wash when no cover is set),
  an 80dp avatar overlapping the cover, the display name, email and bio, and
  an **Edit profile** button that opens the existing profile editor
  (`/settings/profile`). The shell navbar keeps the page title, and identity
  from a previous account is never shown while the current one loads.
* **Private activity.** It is introduced by a section header with a lock
  icon. Tracked time for Today, This week and This month appears as kit stat
  tiles in compact units ("1h 30m", "45m"); the full "N min tracked" reading
  is the tiles' semantics label. The 12-week heatmap sits in a panel and uses
  the info tone, with intensity by tracked time and muted cells for empty
  days.
* **States.** First loads show static tile shapes. A failed load shows an
  inline destructive message with **Retry**. A missing personal workspace
  shows an inline "timeline unavailable" message.
* **Responsive.** Page kind `root`. Below 840dp of body width, identity sits
  above activity. From 840dp, a 360dp identity column sits beside the
  activity column. The three stat tiles share one row when it fits; where
  only two columns fit, Today leads at full width so no cell is left empty.

## Timeline

* **Day cards.** Each day has a caption (Today, Yesterday or the localized
  date) with a per-type summary. Its rows stack into one rounded grouped card
  with inset dividers. Rows keep the fixed row extent the browser uses for
  anchoring and date jumps.
* **Rows.** Each row has a tone tile per source: tasks primary, transactions
  success, notes warning, calendar info. Openable sources show a chevron.
* **Date strip.** It shows the month label, Today, and previous/next week as
  48dp icon buttons, plus a week of rounded day chips. The selected day is
  filled with the primary colour, days with activity are tinted and carry a
  dot, and every chip keeps its semantics label and tap action.
* **States.** First loads show skeleton rows. Empty, partial and unavailable
  timelines show a centred state message. Load and partial failures still
  raise a toast (now `showAppToast`).
* **Responsive.** The browser keeps one full-width scroll view and pads its
  content with the `detail` page insets (a readable column of up to 600dp on
  tablets and 720dp on desktops).

## Regression coverage

* `test/features/shell/view/appearance_root_tabs_render_test.dart` (part
  `profile_render_cases.dart`) renders Overview and Timeline in the real
  shell with fixture data at 390x844, 820x1180 and 1440x900 in Classic
  light/dark, a gradient and a blob theme. It asserts:
  * the phone gutter;
  * the two-column desktop layout;
  * the compact stat values;
  * the 44dp edit target;
  * the day captions and rows.
* The existing `test/features/profile/view/*` suites cover activity scoping,
  timeline anchoring, paging, races, navigation and account changes against
  the restyled widgets.

# Mobile settings shell
Source: https://docs.tuturuuu.com/platform/features/mobile-settings-shell

Shared shell chrome, profile settings routes and accessible edit entry

## Settings row grid

Settings sections and detail rows share `SettingsRowLayout`. Muted captions sit
4px inside a rounded (24px) grouped card. Rows use a 16px inset, a 24px slot for
a thin Lucide line icon, a 14px gap before a medium-weight (w500) title and a
44px trailing action column with a 17px Lucide chevron. Settings and Appearance
use Lucide icons only. Inset dividers start at the title column (54px), not under
the icon. Rows have a 56px minimum height and expand for translated or enlarged
text. A row shows its current value as a muted summary under the title, or as a
short trailing value before the chevron (for example, the Appearance theme name).
It does not show both, except the Time zone rows below. A trailing value keeps its natural width, flush right,
while the title still fits on one line; otherwise it moves under the title, so
titles never break mid-word at enlarged text. Full-size controls such as
switches widen the trailing column and centre vertically instead of scaling
down. Multiple timezone actions
stack in the trailing column, keeping the text width and action centers
consistent with chevrons. Existing English and Vietnamese labels and tooltips
remain unchanged.

Settings scroll lists use the design foundation's tokens (`AppLayout`): content
starts 8px below the shell header (`pageTop`) and ends with the shell-provided
dock clearance plus a 24px end gap (`scrollEndGap`). Row height (56px), row inset
(16px) and the gap between groups (24px) are the foundation's row and section
tokens. They inherit the shell surface and keep Back in its floating dock. These presentation defaults do not change timezone reads, writes, retries
or permissions. `settings_design_checks.dart` covers row geometry, action touch
targets and the final control clearing the dock; the compact navigation suite
also exercises enlarged text in both languages and themes.

### Time zone rows

Each Time zone row shows one value line: the zone as a city with its current
GMT offset, for example "Ho Chi Minh City (GMT+7)". Offsets follow daylight saving
time, and the offset stays attached to its city. Raw identifiers such as
`Asia/Saigon` are never shown, so they can't break mid-word. Legacy device ids
map to their current city, and Vietnamese shows "TP. Hồ Chí Minh". When the
personal choice is Automatic, the row shows "Auto" on its title line and names
the zone that applies. An explicit choice shows only that zone. The workspace row
shows only the workspace choice, so the effective zone is never repeated.
Loading and account states replace the value rather than adding lines. Errors and
rate limits keep their wrapped explanation and Retry action.

These rows are the one place a row shows both a value line and a short trailing
value. When a row has a value line, its trailing value sits on the title line, so
the value keeps the full text width; at enlarged text it moves under the title.
The explanation of Automatic and the zone list stay in the picker opened from the
row. Offsets resolve through `core/utils/timezone_location.dart`, which loads the
full tz data when a native alias such as `Asia/Saigon` is missing.
`timezone_label_test.dart` checks every supported zone,
`settings_timezone_rows_checks.dart` checks the one-line rows in both languages,
and `timezone_resolution_scope_test.dart` checks the scoped states.

## Settings detail shell and profile settings

All mobile Settings children use the same shell background and one shell top
navbar with the destination title and actions. In-app Back appears only in the
floating bottom navbar, never in the top navbar. Android system Back remains
available. Offline is `/settings/offline`; its
Finance, Inventory, Tasks and Calendar details are `/settings/offline/<module>`.
They do not add body title/back bars, nested AppBars or another top safe area.
Their scroll content reserves the shell-provided bottom padding, so the floating
dock clears the last actionable row. Pushed destinations return to the screen
that opened them; direct links fall back to their Settings parent.

Settings → Edit profile, opened from the Settings profile header, is the one
place for account and profile settings at `/settings/profile`: Identity (display
name, full name, email with any pending change), Avatar (Photo, Remove avatar
and a Cover banner row that adds, changes or removes the banner), Account (Manage
accounts at `/settings/accounts`, Sessions and devices) and Account status, as
captioned grouped cards with the shell title "Edit profile". Its identity card is
borderless with a circular avatar, matching the Settings header, and an unknown
join date is omitted. Manage accounts appears only here; the root has neither a
You row nor a Manage accounts row, and its group caption is General. Legacy
`/profile/edit` and `/profile/accounts` links redirect to those destinations.
`/profile` retains the Overview/Timeline activity surface. Its edit entry is a
compact icon with an accessible Identity label and tooltip. Account-switching
shortcuts remain available there. These defaults apply in both mobile languages;
workspace permissions and queued profile writes retain their existing rules.

Profile identity fields use the shared Settings tiles in grouped cards, with
read-only values until a field is opened for editing. Manage accounts uses the
same grouped Add account row and account panels; its shell title is not repeated
in a hero card. The Profile account-management entry has one label, and What's
new keeps its description and installed version without repeating the shell
heading. Account removal confirmations and queued profile writes are unchanged.
These defaults apply to both languages, light/dark themes and enlarged text.

Avatar removal in Settings → Edit profile captures the authenticated account when its
confirmation opens. An account switch or logout invalidates that confirmation,
even if the original account returns before confirmation. Removal uses the
existing avatar DELETE and offline queue contracts, with the original actor
bound through queue admission and HTTP dispatch. Denied removals show localized
media recovery; only an explicit Remove avatar action retries. A confirmed
removal reloads the profile and persists the returned avatar state. Banner
upload/removal and storage policy retain their existing contracts.

`profile_avatar_removal_test.dart` covers confirmation lifetime, cleared-avatar
reload/persistence, and EN/VI recovery. `profile_media_actor_race_test.dart`
covers queue/cache actor changes and HTTP failures without automatic retry.
These tests use synthetic actors and storage; authenticated device and real
storage verification remain separate gates.

Licenses, onboarding replay and explicit admin edit forms intentionally open
above the shell on the root navigator with their own full-screen chrome. Sheet
editors retain their existing modal presentation. They never stack a second
navbar within a shell body.

Home Agenda, Profile Overview/Timeline and Calendar Agenda reclaim the dock's
bottom scroll clearance while it is hidden, retaining the physical safe area.
The viewport remains full height; reverse scrolling or idle restores the dock
and its clearance. Other screens keep stable clearance by default. Text Assistant
publishes a lifecycle-scoped composer/action slot into the same shell-owned
floating dock used by every root and detail destination. The material stays
mounted as navigation and prompt content change; width and root bodies animate
independently, with only the current dock controls interactive. No page mounts a
second dock. Reduced motion disables transitions, and a focused composer remains
visible above the keyboard. Draft controllers stay with the cached Assistant
page, while disposed publishers cannot overwrite a newer registration. Text
immersive mode retains the same composer and navigation toggle,
including when entered through an Assistant tool. Live keeps normal navigation while idle or connecting; only connected call
controls replace it, retaining the navbar width and the same shell material. While no workspace is resolved, shell
navigation remains available.

Shell profile reads and cache mutations are fenced by current actor and request
generation. Account changes, logout and newer edits reject late results; cache
writes and clearing remain ordered. Feature-level identity guards also remain.

Regression coverage: `settings_detail_shell_checks.dart` exercises actual
Offline registrations, inherited background/header and dock clearance, enlarged
text, system/dock back without a top Back button, and unknown module links;
`profile_overview_shell_test.dart` covers the icon edit entry and return path.
`floating_shell_dock_test.dart` verifies hidden clearance and stable viewport;
`shell_assistant_composer_test.dart` verifies one dock, draft/focus and Live
transitions, and `shell_profile_races_test.dart` covers delayed account/cache
completion. These widget checks do not establish installed-device or production evidence.

### Centered navigation and action group

Root and mini-app destinations center the combined visible navigation island and
its actions whenever they fit. Empty action columns do not consume space after
exit. Dynamic actions reserve width first, moving navigation left, then fade and scale into the free space. On
exit, controls disappear before their width is released and navigation recenters.
The combined navigation/action group stays centered at every intermediate frame;
actions do not animate through a size clip. An interrupted transition reverses
from its current geometry, and a replaced outgoing action cannot accept input or
accessibility focus. Reduced motion settles both phases immediately. Actions
keep 52px slots and share the bottom baseline, including when large text makes
the composer taller; narrow layouts keep secondary actions in the top navbar.
When the viewport becomes too narrow, the second dock column is removed
immediately rather than retaining it while shrinking navigation touch targets. The navigation and Assistant dock share horizontal and safe-area bottom insets, and
switching root destinations retains one dock while bodies ease between tabs.
Only the active body receives pointer input or semantics. Visited tabs remain
mounted, preserving drafts and scroll positions; reduced-motion changes retain
the same page elements. Navigation and prompt slots never paint two docks.
Coverage: `dock_action_choreography_test.dart`, `persistent_shell_dock_test.dart`,
`lazy_indexed_stack_test.dart`, `floating_dock_rail_test.dart`,
`apps_search_submit_test.dart`, and `shell_assistant_composer_test.dart`.

Leaving Apps or launching a module clears Apps search so returning starts in
navigation mode. Workspace picker search replaces the shell title, and its
visible footer actions are centered. Hiding and restoring workspace shortcuts
belongs to Settings; the normal picker never exposes hide buttons. Coverage:
`workspace_picker_sheet_test.dart`. Native dark launch backgrounds match the
actual app theme, checked by `native_splash_theme_test.dart`; the locked screen
shows only the lock status and unlock action. Device visual, transition, and
keyboard checks on the exact CI-built artifact remain required.

## Notification navigation and refresh

Mobile Notifications keeps its scoped snapshot visible while revalidating on
entry. Concurrent unread badge refreshes share one awaitable request; the visible
feed owns its push listener, and count-only changes do not rebuild page rows.
Unchanged counts do not serialize the retained feed again. Workspace switches
clear the visible feed and reload the selected tab; responses from an older
workspace or actor cannot replace current reads. Pagination and offline pending
read overlays retain their existing behavior. These defaults apply to the native
Inbox and Archive; the sheet also updates its unread header. Empty and error
messages use a minimum height rather than a fixed height, so narrow screens and
enlarged text can wrap without clipping. The real 320px root transition matrix
in `shell_assistant_composer_test.dart` covers this responsive empty-state path.

`notifications_cubit_test.dart` covers coalescing, retry, delayed scope responses
and close safety. Focused tests establish request behavior, not a measured device
frame-time improvement.

The persistent notifications action button coalesces unread refreshes only for
the same signed-in actor and workspace. An account transition clears the badge,
retained feeds and pending state before starting a new request, including a
switch away and back in the same workspace. Delayed old requests cannot replace
the new count or end its loading state. This applies to the native shell action
button and shared notifications cubit; delayed-actor and same-workspace ABA
regressions are in `notifications_cubit_test.dart`.

## Settings > Apps: one home for app settings

Every native app's settings live in Settings under a captioned **Apps** group.
Each row shows a summary of current values and opens that app's settings. This
applies to both mobile languages, all themes and enlarged text. Each setting
has exactly one editor and keeps its existing storage, scope cancellation and
permission gate. Rows appear only when the app is available. Timer appears when
its opt-in experiment is enabled. Mail requires mail discovery and a workspace.
Assistant requires a signed-in account and a workspace. The registry does not
grant permissions or invent settings.

Device-wide preferences stay at the root: Appearance and language, Time zone
(personal and workspace), and Notifications and interaction (reminders, haptics,
link browser). Tasks, Calendar, Finance and Timer render as routed sub-screens in
the shell with one top title, dock Back and dock-clearing scroll. Offline module
pages link to the app sub-screen instead of repeating its editors. The app
sub-screens link back to their offline data. Mail and Assistant keep their
account-scoped hubs, which an account or workspace switch cancels.

Summaries state the current value rather than repeating a title: Tasks reads
"Board view" or "Board list", Finance "Amounts shown" or "Amounts hidden", and
Calendar the effective first day. Each sub-screen group has a footer naming the
scope it changes: this device (Tasks board, Finance amounts, Pomodoro, offline
data), your account (first day of week) or the whole workspace (approval
threshold, calendar accounts). Calendar also links to the shared Time zone group
on the Settings root. The approval threshold editor uses grouped rows: a Require
approval switch, inline day and minute fields and a footer explaining both.

A threshold write is queued when offline and still reports success. The saved
threshold and grace period are therefore published into the cached workspace
settings that Timer and Requests read. A reload shows the saved value, not the
previous one, and live revalidation later replaces it with the server copy.
Overlapping saves apply in the order they were made.

In-app entry points use the same editor. The Timer gear and the Requests gear
deep-link to Apps → Timer. On return, Timer reloads Pomodoro lengths and Requests
reloads its threshold and permissions for the same workspace. The Mail gear
opens the current mailbox in the shared Mail editor. The Mira menu opens the
shared Assistant settings route at `/settings/apps/assistant`.

These stay contextual on purpose:

* quick toggles that edit the same stored value, such as the Finance eye
  action;
* the layout editors of their own surfaces, Home customize and Apps arrange;
* per-entity settings, such as a Meet room, a chat conversation's model and a
  habit tracker.

Routes and redirects:

* `/settings/apps` and unknown or hub-only app ids, such as
  `/settings/apps/mail`, redirect to `/settings`.
* `/tasks/settings`, `/calendar/settings`, `/finance/settings` and
  `/timer/settings` redirect to the matching sub-screen. They are registered
  ahead of the app registry's parameterised routes, so `/calendar/settings` is
  not read as the `/calendar/:eventId` detail. The app does not register a
  `/tasks/:taskId` route.
* Web and app links of the form `<workspace>/settings/apps/<app>` and
  `<workspace>/<app>/settings`, plus the Tasks host's `<workspace>/settings`,
  resolve to the same locations.
* `/settings/preferences` still redirects to `/settings`, and existing Settings
  routes are unchanged.

Settings search is the Settings root's primary floating dock action, not an
inline field. Opening it turns the shell's top navbar into the query field, and
results replace the root list, profile header included. Search matches titles,
sections and the settings on app sub-screens, ignoring case and Vietnamese
diacritics, including decomposed input with combining marks. A result for a
routed destination opens it. A result for an inline root row clears and closes
the search and scrolls that row's group into view. Isolated previews without the
shell chrome registry keep an inline field as a fallback. Settings and Offline
search retain the floating dock above the keyboard; dock and system Back clear
and close search before leaving the destination.

Coverage:

* `settings_apps_checks.dart` covers the Apps rows, sub-screens, renders and
  search, including the dock search action and its light/dark renders.
* `timer_app_settings_test.dart` covers the threshold permission gate, workspace
  switch, Pomodoro persistence, the cache write-through and `focus=threshold`.
* `time_tracker_threshold_cache_test.dart` covers offline reads of a queued
  threshold through the same cache keys the repository uses.
* `time_tracker_settings_entrypoint_test.dart` covers the Requests gear deep
  link and reload.
* `app_settings_routes_test.dart` covers redirects, deep links and precedence in
  the real app router.
* `settings_search_test.dart` covers folding and matching.
* `profile_page_test.dart` and `profile_page_render_test.dart` cover the Edit
  profile groups and renders.

### Calendar settings offline behavior

Week-start and time-zone preferences restore encrypted account/workspace
snapshots, then revalidate in the background even when the snapshot is fresh.
Leaving an account or workspace clears its visible preference; reconnect and app
resume refresh the active scope. A failed save preserves the last confirmed
selection and shows a localized recovery action. These settings do not queue
writes: their PATCH contract currently has no operation receipt or revision
precondition. Offline editing and cross-device conflict resolution remain pending
API work, rather than silently reporting success. Coverage is in
`calendar_settings_cache_test.dart`, `calendar_settings_offline_test.dart` and
`timezone_settings_offline_test.dart`.

Calendar and Timezone refresh on entry, scope changes and app resume rather than
every unrelated outbox cycle. Known preferences remain editable during refresh;
a save fences the obsolete read. Stored week-start values are validated before
restoration. Offline Calendar and Timezone writes remain a follow-up requirement;
this cache layer does not claim queued edits.

### Mail settings offline behavior

Mail account rows and mailbox settings restore an encrypted account/workspace
snapshot before background revalidation. Long addresses wrap within their row.
Save belongs to the floating navbar, and unsynchronized changes remain visibly
queued or require review until acknowledged by the server.

Cached mailbox roles never grant editing. Restored settings open immediately in
read-only mode until current-session membership can be verified. A previously
verified editor can queue an offline edit; an uncertain send retains its original
operation identity for manual review. Before a queued settings PATCH leaves the
device, its manual-review state is persisted. An interruption therefore cannot
automatically resend it after restart; an interruption before actual transmission
also conservatively requires review because the API has no operation receipt.
Settings use a separate outbox scope,
including legacy retained records, so a held settings write does not hold inbox
actions. Saves send changed top-level fields only; nested automation and group
policies remain complete objects. A sender-name edit preserves an unrelated web
signature change, but concurrent edits to the same field or policy still use the
server's existing last-write-wins contract. No revision precondition is claimed.
Server-setting controls stay read-only while that mailbox has an unresolved
edit, including when reopened, and until a fresh response installs the next
confirmed baseline. Retry after a mailbox denial requires a fresh owner/admin
management grant; cached roles never restore editing. Failed
edits do not overlay confirmed settings. A mailbox settings 403/404 removes only
that mailbox's snapshot; workspace bootstrap denial still revokes workspace Mail.
Authorization denial removes the affected snapshot;
a verification challenge retains it without granting new management access.
Refreshes preserve dirty form values. This behavior is covered by
`mail_settings_cache_ui_regression_test.dart` and
`mail_settings_offline_regression_test.dart`. Restart and in-flight Retry fencing
are covered by `mail_settings_dispatch_restart_test.dart`.

### Assistant settings layout

Mira's settings action and Settings → Apps → Assistant open the same routed
screen at `/settings/apps/assistant`. The shell keeps its destination title,
background and floating bottom navbar; the screen adds no inner navbar. Nested
personality and memory editors also stay routed, with Save in the shell dock.
Editors explicitly retain the dock above the keyboard, including disabled or
pending Save actions, so Back and Save remain reachable while typing. Other
destinations retain their keyboard visibility policy.
Back closes a custom explanation dialog before returning through the editor
history. Standalone previews without shell providers retain fallback chrome.

Personality restores only a verified actor-owned snapshot from the existing
Assistant cache while revalidation runs. Personality editors remain read-only
until fresh settings succeed, including after a failed refresh. An offline snapshot never enables an
unknown memory-consent setting; unresolved consent shows progress during loading. Memory items, consent changes and revisioned
memory edits remain authoritative network operations; full personality saves
are not queued without a matching receipt contract. Cache and generation fences
are covered by `assistant_personal_settings_cache_test.dart` and
`assistant_personal_settings_cache_first_test.dart`.

On-device models use compact rows with size and download/selection status.
Installed rows expose Remove directly and distinguish Use from selected status.
License and source actions live in custom explanation dialogs. Existing
preference, memory consent, selection and download semantics remain unchanged.
This scope applies to English and Vietnamese, including enlarged text.

`assistant_settings_dock_route_test.dart` covers action lifecycle, blocking
repeated or covered saves, and dialog Back.
`assistant_routed_editors_test.dart` verifies Back and Save at 320px, doubled
text size and an open keyboard. Compact rows are covered by
`assistant_compact_settings_models_test.dart`; real caller-to-editor paths and
EN/VI coverage remain in `settings_compact_navigation_test.dart`. Native
acceptance requires an authenticated device running the exact CI-built artifact.

## Native text editing and keyboard dismissal

Across mobile routes and modal forms, editable fields keep their native copy,
cut, paste and select-all actions while the keyboard is visible. Tapping a
selection toolbar, selection handle or a `TextFieldTapRegion` accessory keeps
editing focus. A genuine outside tap dismisses the visible keyboard through
Flutter's `EditableTextTapOutsideIntent`. Dialogs that consume the inherited
keyboard inset still recognize the visible keyboard from the view. A field's
explicit `onTapOutside`
callback retains control of its behavior. The task interaction dismissal guard
still suspends outside dismissal. Without a visible keyboard, the existing
focus policy is delegated to Flutter, including mouse and stylus outside
dismissal.

Shadcn text fields and areas explicitly pair the platform menu builder with
native handle-only selection controls. Android and iOS retain draggable
selection handles; desktop keeps its platform handle policy. The device-name
and QR-link inputs use the same native editing controls. Workspace search
already uses a native Material field.

This applies to Material fields and shadcn fields and text areas, including the
Assistant composer and settings forms. Disabled fields remain disabled,
read-only fields allow selection and copying without mutation, and obscured
fields retain Flutter's restrictions on copying and cutting. Input formatters
and IME composition remain owned by the field.

Regression coverage lives in `test/app/view/text_editing_*_test.dart` and
`dismiss_keyboard_on_pointer_down_test.dart`. It exercises real clipboard menu
press/release gestures with a frame between pointer down and up, Android/iOS,
English/Vietnamese, single and multiline inputs, modal and enlarged text,
selection replacement, keyboard shortcuts, field policies and composition.
Widget evidence does not replace native-device clipboard and IME verification.

## Private error diagnostics

Mobile Mira reply failures and timezone read/write failures offer Copy debug
information only to an authenticated account with a confirmed `@tuturuuu.com`
email. External addresses, unconfirmed addresses and MFA-required sessions do not
see this control. Email/confirmation changes update auth-state equality; logout
and account changes revoke the control and its stale callback.

Copying writes a local, fixed-field envelope to the clipboard: operation stage,
error category, HTTP status, retry delay and allowlisted rate-limit policy fields.
It never includes messages, prompts, response bodies, URLs, email addresses or
credentials, and never uploads diagnostics. Retry and cooldown rules are unchanged.
Recovery clears old diagnostics; timezone actor/workspace changes discard them.
Streamed HTTP errors retain at most 64 KiB before parsing. Error-body reads have
a total deadline matching the request timeout (30 seconds by default), even if
small chunks keep arriving. Deadline, source failure or overflow requests source
cancellation and discards partial payloads while preserving HTTP status and
headers for typed errors; transport cleanup cannot delay that result. Logout or
actor departure during this read cancels it and rejects publication, including
a return to the same actor. Successful streams keep their existing lifetime. Oversized bodies are
canceled and become generic status failures; status/retry headers survive.
Successful streams remain unread until consumed by the assistant transport.

Coverage: `safe_error_diagnostics_test.dart`, `api_client_stream_error_test.dart`,
`bounded_stream_error_test.dart`, `stream_error_deadline_test.dart`,
`internal_diagnostics_copy_test.dart` and
`timezone_safe_diagnostics_test.dart`. These tests establish local capture,
clipboard privacy and cooldown behavior; they do not establish the cause of a
production 429 or stopped reply.

## Component localization fallback

The mobile app supports English and Vietnamese. App and Material strings keep
the selected language, including native text actions. The installed Shad
component library supplies English resources only, so its built-in control
strings use an explicit English fallback in Vietnamese sessions. This does not
expand the app's supported locales or claim those component strings are
translated. The shared widget-test app uses the same production delegate.
Coverage: `shadcn_localizations_fallback_test.dart` renders the actual Shad date
picker and Material/app strings in both locales without missing delegates.

## Compact settings sections

General and product settings share one rounded card per group, with inset
separators and unboxed line icons, rather than a separate outlined card for every
action. On solid pages, the card is a quiet tonal step from the page background
that keeps muted text at WCAG AA. Over a gradient or blob appearance, the card is
translucent at the chosen card opacity. Edit profile uses the same captioned
groups; its cover banner keeps its preview panel, and explicit destructive
confirmations retain their grouping.
Preference categories use one consistent gap between groups and no trailing group
gap; the parent owns spacing to the next section. Row touch targets remain at least
48 logical pixels, while translated labels and enlarged text may increase height.
These defaults apply to mobile English/Vietnamese and light/dark themes; settings
permissions, destinations and persistence are unchanged. Assistant settings leaves
use the same shell and row vocabulary.

`settings_design_checks.dart` exercises the actual Settings host spacing and
320px enlarged-text navigation in both languages/themes. Its harness uses the
production localization fallback and explicit theme/locale. Widget renders are
bounded evidence; exact-build device safe-area, keyboard and visual checks remain
required.

Preferences observes the active workspace id, and Overview observes its displayed
name. Workspace loading, module visibility and creation state do not rebuild
these sections when those values remain unchanged. Renames update the workspace
row; workspace switches retain calendar preference loading and permission
revalidation. Other Settings data sources retain their subscriptions, and compact
spacing, row alignment, editing and persistence keep their existing behavior.

`settings_rebuild_test.dart` observes real widget rebuilds after synthetic
workspace state emissions, with rename and workspace-switch controls. This
isolates unnecessary subscription work; it does not measure frame latency or
establish a TestFlight performance improvement.

## Handled timezone operational failures

Mobile timezone diagnostics distinguish preference load (`timezoneRead`), API
write (`timezoneWrite`) and unresolved native timezone after a successful write
(`timezoneResolve`). A genuine handled HTTP 429 records its status and bounded
Retry-After bucket once, while preserving the existing cooldown, failed edit and
explicit retry. A cooldown-blocked tap, logout, closed cubit or superseded ABA
request does not create an incident. Native lookup that is unnecessary for a
named preference also creates no incident.

The production Crashlytics boundary follows the fixed-field privacy and bounded
dedup defaults documented in [mobile chat](/platform/features/mobile-chat#handled-assistant-operational-failures).
It excludes timezone values and actor/workspace identifiers. Tests can inject a
sink without Firebase. Sink rejection leaves existing UI failure and retry
behavior intact. `timezone_operational_reporting_test.dart` exercises genuine
HTTP 429 responses through the authenticated API client and repository with
synthetic credentials, separate read/write phases, cooldown/recovery, stale
requests and sink failure. Native authenticated provider/device evidence remains
pending; this does not identify the cause of any customer's 429.

## Timezone pickers and sheet Back

The Personal timezone and Workspace timezone rows open a large sheet built on
the shared sheet host (`showAppSheet`). It shows every supported zone by city,
with its region and current GMT offset (for example, "Ho Chi Minh · Asia ·
GMT+7"). Zones are sorted west to east. The saved choice is pinned under
**Current** with a check mark. **Automatic** explains what it means:

* Personal: it follows the workspace timezone, or this device's when the
  workspace has none, and names the zone it resolves to now.
* Workspace: members without a personal timezone use their own device's.

Search is the floating dock's dynamic search action. It turns the shell's top
navbar into the query field, and the sheet has no inline search field. The query
matches city, region, IANA id or offset (`gmt+7`, `utc-5`, `+05:30`).

System Back, the dock Back and dragging the sheet down all close the picker
without saving, and the user stays on Settings. The same rule applies to every
sheet or dialog opened through `showAppSheet`, `showAppDialog` or
`showAdaptiveSheet`: Back closes the topmost overlay first and never pops the
page beneath. Saves, rate-limit cooldowns, permissions and the
account/workspace cancellation of an open editor are unchanged. These defaults
apply in English and Vietnamese, light and dark, and enlarged text. Coverage:
`settings_timezone_picker_checks.dart`, `app_sheet_host_test.dart` and
`timezone_choices_test.dart`.

## Settings overview and Appearance

The Settings overview opens with a profile header: the signed-in user's avatar,
display name and email, and the number of workspaces they belong to. The identity
and its Edit profile pill open `/settings/profile`. The workspace count keeps its
natural width on one line and opens the workspace list; a long name ellipsizes
instead. With enlarged text, if the name would have less than about 96px, the
count moves to its own line under the identity. The Workspace pill opens
`/settings/workspace`. These are shortcuts; every destination remains reachable
from a captioned group, with per-app rows under Apps. The header does not show
social counts or
invented destinations. The shell keeps the single top-navbar title and the
floating dock Back control; the page adds no large in-body title or back chevron.

Root preference rows still open nested editors and save only an explicit choice.
The no-root-switch decision recorded in
[`apps/mobile/docs/settings-calendar-timezone.md`](https://github.com/tutur3u/platform/blob/main/apps/mobile/docs/settings-calendar-timezone.md)
remains, so Settings shows no inline toggles at the root even though the visual
reference does. The Appearance row opens `/settings/appearance`. That is a child
page, and its controls apply and persist instantly because choosing there is the
explicit action. Visiting the page and returning writes no appearance preference.

Until a user first opens Appearance, its root row shows a "New" chip. Opening it
from that row features Aurora with a "New" chip in the gallery
(`/settings/appearance?highlight=aurora`). Any visit, including a deep link,
retires the chip through the `appearance-intro-seen` preference. Aurora is listed
first in the gallery; whether fresh installs should default to Aurora is an open
product decision.

### Appearance options and defaults

Classic dark (Neutral accent, Solid background) returns the original shad and
Material themes. Classic light uses an iOS-style grouped page: a `#F2F2F7` page
with white cards and darker muted text (`#5E5E66`) that stays AA on the tinted
page. Gallery swatches always show each theme's gradient or blobs at full
intensity, so dark Classic, Mono and Ember remain distinguishable.
Picking a theme in the gallery also applies its recommended background style:
Aurora, Forest and Blossom use Blobs; Sunset, Ocean, Ember and Mono use Gradient;
Classic uses Solid. Reset to default restores every option, including System mode.

Curated colour values live only in `lib/core/theme/appearance/appearance_palettes.dart`.
`AppearanceTheme` derives the shad colour scheme and the Material bridge theme
from them; widgets use theme tokens. Foreground, muted, card and popover text keep
WCAG AA (4.5:1) against any blend of each theme's base, gradient, blob, card and
subtle-surface colours, in light and dark. Primary (accent) and destructive
colours are derived per theme: each is stepped toward black or white until it
reaches 4.5:1 against that worst-case blend. Labels on primary, secondary, accent
and muted fills, and Material `onError`/`onPrimary`, also reach 4.5:1. Non-neutral
accents also drive Material primary/secondary/tertiary containers and surface
tint, so chips, FABs and indicators follow the accent.

`AppearanceBackdrop` also installs `accessibleDestructiveButtonTheme` for every
appearance. shad's built-in destructive button paints a fixed white label on a
50% destructive fill (about 2.5:1 on light pages). The override uses the
theme's solid `destructive` fill with the `labelOn` label instead, so it reaches
4.5:1. Hover and press shift the fill slightly toward the label without losing
AA, and disabled buttons keep shad's styling. Default Classic dark uses the base
scheme, so its destructive buttons also change from a translucent to a solid
fill. Segmented-control labels (Mode, Background) scale down to fit rather than
truncate.

### App-wide application and cost

`AppearanceBackdrop` sits in the app builder around the router. For Gradient and
Blobs, it paints one ambient layer behind every route and makes shad scaffolds
transparent, so the theme shows across Settings, root tabs and detail pages. Its
child keeps a stable position, so changing styles never remounts navigation.
Imperatively pushed Material/Cupertino pages carry their own copy of the layer
beneath their content, so transitions never reveal the page below. The shell
header is clear on detail routes, so the gradient reaches the title and status
bar. On root tabs, where content scrolls under it, the header is frosted
(translucent background with an 18px backdrop blur). Solid themes keep the opaque
header. Adaptive
sheets, drawers and dialogs restore opaque scaffolds. Solid styles add no layer.

The layer uses radial and linear gradients, not image blur, inside a
`RepaintBoundary`, so its picture is recorded once. Impeller has no raster cache:
the GPU still redraws it every frame, which is cheap for gradients. Animated blobs are opt-in
and drift on a 48-second loop driven by a 15 fps timer. Only the painter repaints;
no widget above it rebuilds per tick. Motion stops when the system Reduce Motion
setting is on or tickers are disabled. The clock stops immediately when the app
leaves the foreground and resumes from the same phase.

#### Frosted glass on Android

Glass chrome (the dock material, the frosted root-tab header, adaptive sheets
and dialog scaffolds) goes through `GlassEffects` in
`lib/core/theme/appearance/glass_effects.dart`. A live `BackdropFilter`
re-reads and re-blurs the content behind it on every frame that content changes.
That is every scroll, sheet and transition frame. Each filter also splits the
GPU render pass. Android GPUs are tile-based and pay heavily for that, so on
Android (`defaultTargetPlatform`) the same surfaces draw without the blur. Their
fill closes 75% of the remaining gap to opaque: dock 0.72 becomes 0.93, header
0.55 becomes 0.89, and sheets and dialogs 0.88 become 0.97. iOS and desktop keep
the live blur. High contrast is always opaque with no blur. Shapes, borders,
shadows, colours and the ambient layer are unchanged on every platform.

Coverage: `glass_effects_test.dart` asserts the composited `BackdropFilterLayer`
count and fill per platform, and `adaptive_sheet_test.dart` checks both
platforms. The on-device frame benchmark
`integration_test/perf/glass_effects_benchmark_test.dart` compares blurred and
flat glass over Solid, Blobs and animated Blobs (`flutter drive --profile`; see
its header).

Persistence uses `SharedPreferences`: mode keeps the original `theme-mode` key and
customization is stored as versioned JSON under `appearance-v1`. Installs without
that key migrate to the default appearance with their saved mode. Unknown or
malformed values fall back field by field. Bootstrap preloads both values, so
cold start does not flash the default theme. A newer change or closing the cubit
fences older pending writes. Slider drags preview live and persist when released.

Coverage: `appearance_contrast_test.dart` checks every rendered text and role
pair (including destructive and Material `onError`) for every theme, background
style, brightness and accent, plus the defaults. `appearance_application_test.dart`
checks app-wide application without remounting, pushed-page layers, pixel output
for solid, gradient and blob styles, that reduced motion schedules no frames, and
that the blob clock stops in the background and resumes. `theme_appearance_test.dart`
covers migration, restart persistence, preview, write fencing, reset and decoding.
`settings_appearance_shell_checks.dart` runs the real shell for Classic
light/dark, Aurora blobs and Sunset gradient. It also covers instant
apply/persist/reset, reduced and full motion, the New chip and Aurora highlight,
the one-line workspace stat, 320px pages at 2x text in English and
Vietnamese, and screen-reader activation of theme tiles and accent swatches.
`appearance_root_tabs_render_test.dart` renders the Home and Apps root tabs in
Classic light and dark Aurora blobs. `settings_design_checks.dart` covers the row
grid. These are widget-level checks. Device visual, battery and frame-time
acceptance on the exact CI-built artifact remain separate gates.

### Custom controls and modal editors

Appearance, Storage and Offline use the shared design-system controls. Appearance
sliders preview immediately and persist on release. Storage opens as a large
hosted sheet; its clear confirmation remains disabled during an active download
and clears data only after explicit confirmation. Back dismisses the current
picker or cancels the confirmation before leaving Settings; outside dismissal
also cancels the confirmation.

Offline module search lives in the floating navbar. Browsing a stored namespace
opens a hosted sheet with its own navbar search and lazily rendered record details.
Search scans all locally retained records in that namespace, without fetching the
network. An open browser refreshes on a content revision; losing its owning actor,
workspace or permission dismisses it. Reopening starts a fresh search. The
standalone preview uses an inline search field when no shell is present.

Assistant quick settings and the central Assistant entry both open the routed
Assistant settings screen.
Nested personality and memory editors retain account/workspace cancellation and
write fences. System-owned license and permission screens keep their framework
or operating-system presentation.

Regression coverage: `settings_appearance_shell_checks.dart`,
`cache_storage_review_test.dart`, `offline_stored_items_test.dart`,
`offline_module_page_test.dart`, `offline_search_chrome_test.dart` and
`settings_assistant_entrypoint_checks.dart`.

# Native mobile Timer
Source: https://docs.tuturuuu.com/platform/features/mobile-timer

Session controls, task links, and tracking history in the shared mobile shell.

Mobile Timer keeps Start, Pause, Resume, and Stop in the existing shell-owned
floating action surface. The page does not mount another floating bar. Available
controls follow the current session; while a control is awaiting completion,
other session controls are disabled to prevent repeated taps.

The missed-entry action uses the same shell action registration on Timer,
History, and Statistics, instead of a separate floating button. It remains
available only with an authenticated workspace context. On narrow screens,
secondary actions can move to the shared header overflow rather than clipping.
Existing threshold approval, category selection, task links, and tracked-session
history keep their established behavior.

The clock scales down to fit narrow layouts and enlarged text. Pomodoro phase
and running/paused/stopped labels use the app locale. Scroll content includes
the shell-provided bottom inset so session details remain reachable above the
dock. This presentation does not change billing, offline replay, or server
tracking semantics.

Regression coverage: `timer_native_controls_test.dart` checks state-dependent
shell registrations, disabled in-flight controls, route disposal, a long-running
clock under enlarged text, and Vietnamese Pomodoro labels. Actual native
session timing and dock transition smoothness require device verification;
widget tests do not establish either.

## Shared Pomodoro preparation is inactive

The private time-tracker control foundation prepares actor/workspace-scoped
configuration only. Its schema requires `mode=off`, `phase=idle`, and no deadline;
its service-only RPCs initialize, read, and update configuration with revision
checks. Browser roles cannot read, write, or execute those RPCs. Configuration
contains positive integer minute durations up to 180 and a cycle length up to
24, with explicit boolean automation choices. These are foundation storage
bounds, not a change to the current mobile or web controls.

A repeated latest command with identical input returns its existing revision;
a stale revision or reused command with different input fails. An optional
prepared-session reference must belong to the same actor and workspace. It is
an inert reference, not a live session binding: existing session deletion stays
possible. The foundation changes no tracked work, breaks, approval policy,
client timer, settings preference, notification delivery, or scheduler.

Activation requires a later reviewed contract that normalizes Web, Track,
quick-start, AI, direct-write and approval lifecycle paths under the same lock
order and atomically updates phase and existing tracker accounting. This
foundation is a prerequisite and does not deliver cross-platform Pomodoro or
completion while every client is closed.

The `time-tracker-control-contract.yaml` workflow checks out the exact source,
replays the complete schema in the repository-owned isolated lifecycle, runs
`time-tracker-control.sql` with strict TAP validation, and runs actual concurrent
configuration-CAS and command-replay races. It then generates actual public
schema types as an exact-SHA artifact and requires owned lifecycle cleanup.
No generated type file is hand-edited. The new private preparation objects do
not imply new public API types.

Focused runner tests can run through `ttr resources run -- node --test
apps/database/scripts/time-tracker-control-contract.test.mjs
apps/database/scripts/programming-database-tap.test.mjs`. The full SQL verifier
starts a disposable database and belongs in exact-head CI or an explicitly
admitted host; it must not be run under a no-local-setup restriction. Local
script tests alone are not schema, SQL concurrency, device, or production proof.

### Unwired OFF-only replacement boundary

A private service-only operation can atomically close the expected running
session and start its replacement while the existing control is OFF and idle.
No mobile, web, quick-start or AI caller uses it. It carries a separate operation
revision and retained input-bound command receipt; configuration revision is
unchanged. A receipt reports its **applied** result, including an older replay,
and does not claim to describe the latest session.

The operation acquires the existing actor/workspace advisory key before control,
linked requests, session and break rows. One database timestamp captured after
contention closes and starts work. Existing accounting and policy triggers remain
in force; closing work supplies canonical integer elapsed seconds from that same
clock before the existing productivity trigger executes. To close already-running
work older than a positive edit threshold, only that canonical close update uses
a transaction-local update-limit bypass; the prior value is restored before the
new insert and on close failure. Other policy guards and legacy triggers remain
unchanged. A future-starting running
row or any open break for that actor/workspace, including a paused session's
break, is rejected without mutation or work credit. Historical breaks must already
be completed; this operation never closes them automatically. Any
failure rolls back session writes, operation revision and receipt. Browser roles
cannot call the operation, and even the service role cannot directly mutate its
private bookkeeping tables.

Full-schema catalog assertions retain an explicit baseline of legacy writers,
RLS policies, triggers and FK actions, including the task-workspace guard and
approval activity/notification effects. Unexpected drift fails validation. This
baseline intentionally leaves writer closure **open**: the new operation cannot
become authoritative until legacy direct writes, bypass RPCs and every lifecycle
caller use a consistent boundary. CI executes real pgTAP and two-connection CAS,
replay and shared-scope contention tests with actual type generation and cleanup.
The replacement pgTAP fixture reuses the workspace creator membership inserted
by `add_ws_creator`, and checks it again before the edit-threshold scenario.
It must not insert that same membership a second time.

Shared phase/settings, pause/resume/skip, deadline reconciliation, cross-client
realtime and background notification behavior remain separate prerequisites.
This unwired boundary provides no all-clients-closed completion or device proof.

# Mobile Workspace Tools
Source: https://docs.tuturuuu.com/platform/features/mobile-workspace-tools

Shared mobile navigation, tablet layouts, caching, and workspace application behavior.

## Overview

The mobile app now ships first-party workspace surfaces for:

* Drive at `Routes.drive`
* CRM at `Routes.crm`
* Education at `Routes.education`

These modules are registered in the Apps hub and available through the mini-app navigation system.

The mobile Apps hub uses the v0.9.2 colored cards with consistent icons and clear descriptions. Keep module ordering explicit in the hub view rather than relying on registry insertion order. For workspace modules that need dense controls, prefer the same shell-owned chrome used by Calendar:

* `ShellMiniNav` for mode or section switching
* `ShellChromeActions` for quick actions such as filters, create, sort, and view toggles
* A compact overview with a small number of relevant metrics
* The v0.9.2 AppCardPalette gradient cards, consistent icon blocks, readable labels, and shared theme colors

The Apps screen defaults to the compact grid. A List/Grid switch in the top
shell header sits beside Customize and changes the same visible, ordered modules
between icon-and-name tiles and descriptive cards. Grid tiles have more space below
the shell header and can be held and dragged to reorder without entering Customize.
Holding an icon enters persistent ordering mode: icons shift during a drag and
continue to wiggle after release until an empty area is tapped. Compact hide
controls sit over icon corners only in grid ordering mode; list cards never show
hide controls. The choice stays in the mounted Apps screen while navigating
within the mobile shell; search and workspace access rules apply to both layouts. Descriptions remain
searchable in grid mode even though they are hidden from the tiles.
Holding a tile produces a pickup haptic, moving onto a new navigation target
produces a selection tick, and completing a drop produces a light confirmation.
The floating dock uses the same semantic feedback. Haptics are enabled by default
on iOS and Android, can be disabled in Preferences, follow system haptic policy,
and throttle repeated feedback during a continuous gesture.
Shell actions and standalone primary actions give a selection tick, and a
speed dial distinguishes opening from choosing an action. Finance transaction
actions give a light completion tap after the local edit is accepted; this tap
does not claim that a queued offline edit has synchronized.

Background warmups for optional products should also respect access state before fetching. Do not let Apps hub or boot-time cache warmups call product endpoints blindly; skip the warmup when the corresponding access cubit is not loaded and enabled, and fail soft on opportunistic `404` responses.

Tasks, Calendar, and Finance are the default launcher modules. Meet, Mail, Chat,
and Notes join the existing opt-in apps in Settings → Experiments; all four are
off until the user enables them. The choice is cached on the device and restored
at launch. Turning a module on exposes it in Apps and its eligible Home card;
turning it off removes those launch surfaces. Mail still requires its account
access rule, and workspace visibility flags still apply. Deep links retain the
existing route access rules. Meet includes meeting search, scheduling, editing,
and deletion when enabled. Every launcher module has an English and Vietnamese
description.

## Navigation preferences and recovery

Phones and tablets share a compact floating icon dock. Leaving a mini-app returns
to its Home or Apps launch screen. Root screens remain mounted with hidden
animations paused, preserving search and scroll state. The brand control opens
the Apps screen within the normal shell, with compact search and arrange actions.
Tapping a dock item glides the inner highlight to the new position without a
button splash. During a hold or drag, the highlight follows the finger freely;
it snaps to the selected item only on release. Reduced-motion settings shorten
these transitions to an immediate state change.
Switching between peer sections in any mini-app replaces the previous section in
navigation history. Back follows the current context's outer layer: a detail
returns to its parent section, a peer section returns to the mini-app root, and
the mini-app root returns to the Home or Apps launch screen. This also applies
to deep links, so Back never visits a sibling section by accident.
Personal Tasks boards are the Tasks entry surface. Their dock and Android system
Back return to the root tab that launched Tasks, rather than the board directory
that automatically opens the default board. Workspace board details retain their
board-directory parent; task overlays return to their owning board.
Apps is always available in the root dock. The Apps grid supports long-press
reordering: nearby icons shift across rows during the drag, with a subtle
motion cue, and the new order is saved on release. Tapping an app's icon or
label exits reorder and opens that app. Empty cell margins, row gaps, and unused
grid space never open an app; tapping them exits reorder. Leaving Apps through
any route also exits reorder, while preserving its search and scroll state.
Long-press pickup and ordinary scrolling retain their existing gesture thresholds.
App taps provide selection haptics. The list editor provides drag handles and visibility controls. Hiding
an app requires confirmation. Hidden apps remain accessible at the bottom of
Apps, separated from shown apps by a divider, and can be shown again without a
confirmation. The editor places hidden experiments below Hidden Apps; enabled
experiments appear in the regular shown order, while disabled or locally hidden
experiments can be enabled or shown from Hidden Experiments. App order and hidden
choices persist on the device. The editor disables Show when current account or
workspace access would still prevent an experiment from appearing; access changes
can make that control available later. Workspace permissions and experimental-app
visibility still take precedence; a locally hidden app is only moved out of
the shown launcher section, not disabled or removed from navigation.

Home's task, calendar, Finance, daily summary, and eligible Mail, Meet, and Notes
cards can be reordered or hidden through the compact top-bar Customize action.
Available cards are shown
in their current order by default, and hidden cards remain in the editor for
recovery.
Unavailable modules do not appear as Home cards or editor choices; their saved
layout preferences remain intact if access returns. The workspace picker and
security prompts remain outside customization.

The shell provides bottom scroll clearance, including for explicit-padding
lists; pages must not add another dock inset. Downward scrolling hides the dock;
reverse scrolling or idle restores it. Profile/Agenda reclaim hidden clearance;
other pages keep it stable. Primary actions register with `ShellActionSpec.inDock`.
`ExtendedFab` uses that registration inside the shell and remains standalone
elsewhere. Actions use icons on phones and labels on tablets. Do not duplicate
these actions in page-level floating buttons or top-bar actions.

Nova spins once when entering Assistant and remains static afterward. Loading
indicators continue animating, while pull-to-refresh uses an opaque circular
surface. Reduced-motion preferences disable spinning.

Calendar forms and event details use readable, blurred root-navigator sheets.
High-contrast mode uses an opaque surface. Failed event
edits or deletions restore the previous in-memory and cached list and expose the
server error. Verify the next reload as well as the immediate rollback.

Dock action handoffs retain presentation only, never callbacks or permission
state. Destination actions remain disabled until their mounted page registers
current handlers; missing destinations discard previews after a short handoff.
Long-press navigation supports freeform dragging between destinations, including
when the pointer leaves the dock. The pill stays under the pointer within the
capsule; crossing the nearest enabled tab gives selection feedback, and release
snaps to and selects that tab. The floating surface blurs content behind it,
uses one translucent outline, and contains the moving glow inside the capsule.
Pressing gently scales the island and smoothly brightens that internal glow,
which fades on release. Dock controls use accessibility labels without hover
tooltips. The Profile dock reserves its avatar space with a default placeholder,
shows a skeleton while an image downloads, and displays the cached image when
ready. Back from a peer navigation section exits to
the root tab that opened that context; back from a detail page returns to its
parent section. Shell search actions across Apps, Chat, Finance, Habits, Mail,
Meet, Notes, task boards, and Timer focus the top search input on entry. The
search icon, input, and close control share one vertical center; submitting an
empty or whitespace-only query closes search mode except in Apps, which keeps
its current search. Chat shows message matches
in the page, while task boards and Timer keep filtering their current lists.

The App, Workspace, and You dock destinations consolidate into one Settings
screen at `/settings`, with Workspace and You as nested navigation rows. App
preferences use compact grouped items, retaining two columns at widths of at
least 840dp. Root rows
show the current value and open nested choices; Finance visibility, haptics, and
Task board behavior never switch directly from a root tap. Opening, canceling,
dismissing, or pressing Back in a child does not write a preference. An explicit
choice is required, and an account/workspace switch cancels a pending editor,
including a switch away and back. This replaces the earlier inline-root-toggle
design. Existing theme, language, calendar, finance, and haptics sources remain
the owners; personal timezone still overrides workspace, then device timezone.
Timezone loading, unknown, retry, same-scope failure retention, and workspace
permission states stay visible. Permission reloads fail closed and stale results
cannot expose an editor or administrative destination.

Production native timezone reads use the Infrastructure Calendar gateway. Verified
Bearer sessions use the same hashed session trust key as server authentication;
header presence alone never grants a trusted bucket. A 429 response retains its
`Retry-After` cooldown across workspace changes for the same account. Settings
show the wait state and suppress repeated reads until that time; the previous
account's cooldown and preferences do not apply to a different account. A successfully read personal or
workspace preference stays visible if the other read fails, while effective
timezone can remain unresolved; an independently loaded preference remains
editable after any 429 cooldown ends, while the failed read retains its retry
state.
Diagnosis must distinguish gateway status, preferences reads and native plugin
resolution; an Unknown label alone does not establish which failed.
Concurrent loads for the same account and workspace share one pending resolution.
The repository also shares pending personal reads across that account's workspaces,
while workspace reads and all account data stay separate. Completed reads are not
cached by this mechanism; the next explicit refresh reads again. After a pending
read's existing load deadline expires, a retry starts a new read; late transport
results cannot overwrite it. A resume refresh for the same scope does not
invalidate an in-flight preference save. Any 429 without
a positive parsed `Retry-After` uses a conservative 30-second cooldown. A failed
save keeps its requested value for an explicit retry after the cooldown; no timer
automatically retries reads or writes. Shared repository callers honor the account's
cooldown, and late results cannot overwrite the current account or workspace.
`timezone_load_coalescing_test.dart` and `timezone_gateway_retry_test.dart` cover
these contracts, including HTTP-date retry headers and partial preference recovery.
The Infrastructure Calendar gateway forwards only bounded scalar rate-policy,
caller-class, window, limit, remaining, reset, block-reason and Turnstile challenge
headers plus `Retry-After`. Cookies, credentials, redirects and arbitrary upstream
debug headers are excluded; JSON responses remain private and uncached. Gateway
tests cover the allowlist and malformed values. These diagnostics help identify a
blocking layer; source checks do not identify the cause of a production 429.

Settings choice sheets scroll the heading and choices together in one bounded
viewport, so a long heading at large text sizes cannot consume the entire choice
area. Cancel stays outside that viewport. Other non-sliver dialog callers retain
their fixed heading by default; timezone choices keep their existing lazy slivers.
Mounted compact navigation coverage verifies visible choice space, real Finance
scrolling, dismissal without a write, and isolation from the underlying dock.

The app-wide Home/Apps dock is unchanged. Workspace is a child of Settings, so
Back returns to Settings; deeper workspace pages return to their parent. You opens
the existing Profile, preserving its navigation and account behavior. Legacy
Settings URLs and the Preferences redirect remain supported. Session, About, and
open-source licenses remain accessible. Root rows use existing theme tokens,
quiet shared borders, concise labels, muted values, and at least 48dp touch targets;
they grow with large text. Contextual Time Tracker, Mail, Meet, and Assistant
settings intentionally remain with their own app and permission context.

Settings tiles center a single title with the icon. For tiles with a value or
supporting line, the first title line aligns with the icon. Workspace settings
use the shell's Workspace title and omit a second in-content heading. Settings
subpages likewise use the shell title once, without a repeated introduction.
Finance and Inventory read the workspace currency from the encrypted local
snapshot before their first frame. Inventory product and sales lists likewise
show cached rows and periods while background revalidation runs; a cold workspace
still fetches its first snapshot normally.

Notification Inbox and Archive actions share a bordered segmented control with
primary selected colors and accessibility selection state. Use `segmentGroup`
on related `ShellActionSpec` entries instead of unrelated highlighted icons.

Mobile notifications use `App: item title` as the title and put the event detail
or timing below it. This is the default for every module that sends mobile push,
for the mobile notification inbox, and for locally scheduled Task and Calendar
reminders. The app label follows the device language in the inbox and local
reminders; server-sent push currently uses English module names. An unknown
notification type uses `Tuturuuu`. Existing stored notification records keep
their original fields; display formatting does not change routing or read state.
Security approval pushes use `Security` while retaining their challenge data
and approval safeguards.

Mail owns folder, mailbox, and filter selectors through `ShellMiniNav`. Opening
a message replaces the shell title with its subject and reuses the dock back
action. Child composers and attachment previews suspend reader chrome. Background
read-state changes and revalidation do not display a refresh indicator; explicit
pull-to-refresh does. Reply-all and forwarding remain in the message actions sheet.

Chat bubbles expose copy through long press or secondary click. Markdown in these
bubbles must not install a competing native text-selection long-press recognizer.
Other standalone markdown views remain selectable.

## Responsive Loading And Cache Verification

### Device task and calendar reminders

Settings → Notifications & interaction → Reminders controls task and calendar alerts separately.
Both default on, with selectable 3-day, 1-day, 12-hour, 3-hour, and 1-hour
lead times. The app refreshes the existing user/workspace-scoped task and
calendar caches after sign-in and when it resumes after 15 minutes. It then
schedules the nearest 60 future device alerts, replacing outdated entries and
cancelling them on sign-out. An all-day event uses 9 a.m. local time as its
reminder anchor. Android boot/package-replacement receivers restore pending
alarms after a restart or update.

Calendar alerts use a localized timing title (for example, “Calendar: In 3
days”) and the event name as the description, including for all-day events.
Tapping one opens that event in the mobile Calendar detail sheet. If the event
was removed or cannot be loaded, the app returns to Calendar and shows a brief
message. This behavior applies to device-scheduled reminders on iOS and Android;
task reminders keep their existing title and description.

The Reminders page shows the last successful fetch, the number of alerts still
pending in the operating system, the next scheduled alert, notification
permission, and a manual refresh action. A scheduled count is local state,
not proof that the device displayed an alert. If the app remains suspended,
new items created on another device cannot enter the local schedule until the
next app refresh. The deployed web cron checks watched task deadlines every five
minutes across workspaces, queries only the active reminder windows, and creates
notifications through each user's channel preferences, including mobile push.
Workspace task reminder settings can change or disable the lead times; without
an override, the server uses the five device
defaults. Its receipt includes the due date, so a rescheduled task is eligible
again. Calendar event reminders still depend on the device schedule until the
server calendar reminder flow is shipped.
Verify this flow on physical iOS and Android devices with the app closed,
notifications enabled and disabled, account switching, changed due dates, and
completed tasks.

Root tabs initialize on their first visit and retain their state afterward. Hidden
tabs stop ticking animations. Page content and navigation no longer wait for
staggered entrance animations. Opening Apps does not prefetch every product.
Screen routes use subtle fade and horizontal motion on Android and desktop;
iOS retains the native swipe-back transition. Reduced-motion settings skip the
custom transition. The floating shell tabs animate their content in place.
Home shows Finance wallets and recent Notes alongside its existing summary cards
when those modules are available to the current account and workspace. Both cards
use scoped snapshots while refreshing, and clear their displayed rows when the
account or workspace changes. They link into their corresponding mobile screens.
The Notes link picker uses scoped snapshots and the local entity index for
Tasks, Calendar events, Finance wallets, Notes, and Meet rooms. It overlays
queued edits and marks unsynchronized options. Reopening a cached category
shows its rows while revalidating. A new category without any local entities
still waits for its first response.

`CacheStore` shares initialization and concurrent fetches for the same scoped key.
Prefetch returns stored snapshots immediately and starts background
revalidation, even past their expiry window. Explicit refresh waits for the network.
On startup, the encrypted
store consolidates legacy aliases into canonical scoped keys and retains the newest
snapshot for each identity. Pending offline mutations remain separate and intact.
An encrypted entity index now materializes rows with stable IDs from scoped
snapshots. It is rebuilt automatically from existing snapshots when its schema
version is absent, updates alongside new snapshots, and removes rows when their
source is cleared or evicted. Local queries require a user ID, workspace scope,
and namespace; they can overlay the matching queued edits without a network
call. Storage limits include the indexed entity payloads. This is the database
foundation for module read adapters, rather than evidence that every module is
already locally readable or writable.
Mail keeps an explicit request path for authorization cleanup on 401/403.
Meet now returns the scoped meeting snapshot immediately, refreshes in the
background, and purges denied data if the refresh returns 401/403.
Meet room costs, ended-meeting reviews, and assistant review details use scoped
snapshots. Assistant review decisions queue with revision conflicts surfaced for
manual review; a queued review card uses the pending frame. Live call tokens and
assistant generation still require a connection.
Pending Notes, Mail, Finance, Calendar, and Inventory product edits are stored in the account-scoped encrypted
mutation queue and replayed in order per module and workspace on reconnect. Every
authenticated replay request remains bound to the queued edit's account, including
after asynchronous local-ID resolution and between requests in a multi-step
operation. Switching accounts pauses that edit in the queue; it cannot send with
the new account's credentials. API account and offline-sync regression tests cover
this boundary. A
conflict holds dependent edits in that scope while other modules continue. A queued item uses a dashed
border and lower opacity until the server confirms it; conflicts and failed
writes remain visible in Settings > Offline > Offline changes for retry or removal.
Removing a queued change requires confirmation and does not undo a write that
may already have reached the server. A user-initiated retry gives a completion
haptic only when that specific outbox entry is removed after replay. Finance
creates and transfers, Mail sends and attachments, and Notes creates use stable
client IDs so replay can recognize a prior successful write. The queue checks
structured local ID references across modules and holds a dependent edit until
its source create has synced. The replica stores account/workspace-scoped ID
mappings across module namespaces, so a queued Note mention can resolve a Task
created offline. Operational actions that require a live server calculation or
fresh authentication remain explicit online paths.
Calendar event lists use scoped snapshots and overlay pending edits. An uncertain
Calendar create stays in manual review because it may have already reached an
external calendar provider.
Connected Calendar accounts and visibility settings also read encrypted snapshots
while revalidating. Offline disconnects and visibility toggles remain queued and
visibly marked until confirmed. Provider OAuth URLs still require a live request.
Inventory product lists overlay queued creates and updates on their cached
catalog; an uncertain product create also requires manual review.
Inventory setup choices (owners, manufacturers, categories, units, and
warehouses) use the same queue. Their local chips carry the dashed pending
frame and stay available after an offline refresh. A failed authorization
refresh removes the protected snapshot.
Storefronts and their listings use the same scoped read and write path. A newly
created offline storefront keeps a local ID so queued listings can reference it;
replay maps that ID to the server storefront before sending dependent edits.
Queued storefront and listing cards retain the dashed, dimmed treatment.
Education course, quiz, and flashcard edits and basic CRM user and feedback
edits use the same encrypted queue. Education course, quiz-set, quiz, flashcard,
and attempt reads and CRM user, group, feedback, and audit reads use scoped
snapshots while revalidating. Education authored cards and CRM user and feedback
cards show queued edits with the pending treatment. Education attempts are
read-only in the mobile app and use scoped snapshots.
CRM user merges and bulk imports enter the outbox as ordered commands. A queued
merge marks its source user pending; a bulk import reports queued instead of
claiming users were imported. User avatars stage encrypted bytes, obtain a new
upload token at replay, and map their local placeholder to the returned URL
before the dependent user edit runs. Duplicate detection remains a live server
calculation and does not represent a local edit.
Workspace secret create, edit, and delete queue in the encrypted settings
outbox; pending secret cards are dimmed and dashed. A newly created secret is
matched to its server ID after replay before dependent edits run. Ambiguous
secret writes stop for manual review. Storage migration remains an online
operational command and is never represented as a completed offline change.
Documents lists and details use scoped snapshots. Document create, update, and
delete enter the encrypted outbox when offline, and list rows expose their
pending state. A newly created offline document uses a local ID for navigation;
its create must finish syncing before edits to that document can be replayed
against a server ID. The outbox persists a scoped local-to-server ID mapping
when the create response supplies an ID and rewrites dependent queued paths and
structured payload fields before replay.
Drive directory and analytics, CMS collections and entries, and Habit tracker
lists and details also read scoped snapshots while revalidating. CMS collection
and entry CRUD uses the outbox and marks pending tiles. CMS entries targeting a
locally created collection use the persisted ID mapping during replay. Drive
folder create, rename, folder and file delete use path-scoped
queued edits with pending rows. Drive uploads also queue encrypted file bytes;
replay requests a fresh signed URL, uploads the bytes, and finalizes the file.
An uncertain upload remains in manual review to avoid overwriting a file twice.
Habit trackers, entries, and streak actions also queue edits, with pending
cards and activity rows. Create responses that omit a server ID still need
dedicated replay support. Habits repository reads capture the original account
before API/cache and pending-edit awaits; only that account's queued records are
overlaid. A member detail includes queued entries only for the selected target
member. Writes require authentication before queue admission and invalidate the
owning account/workspace. `habit_tracker_actor_scope_test.dart` verifies owner
filtering, delayed reads, anonymous transitions, and member-target isolation.
The native Habits screen recreates its cubit when the authenticated account or
workspace changes. Screen snapshot keys and pending asynchronous publication use
the initiating actor; closed or departed sessions cannot publish late list or
mutation responses, and workspace switches reset mutation busy state and quick-log
drafts. Authentication cache cleanup also invalidates work when the same account
signs out and back in. Forms and details remove only their owned route on scope
departure, including a route covered by another modal. These rules are covered by
`habits_actor_lifetime_test.dart`, real encrypted storage in
`habits_cache_lifetime_test.dart`, `habits_host_scope_test.dart`, and
`habits_owned_overlay_test.dart`. A definitive 401/403 from a native Habits
list, detail, or activity request clears visible rows and blocks every secondary
snapshot query variant for that account/workspace. A separate durable denial
marker prevents reopening private history when snapshot deletion fails. Purges
and subsequent publication are serialized; only a fresh authorized list saved
successfully can remove the marker. Draft edits and queued mutations cannot
reauthorize it. MFA/verification challenges and temporary transport failures keep
the last authorized screen snapshot. The native cubit requests fresh repository
responses while supplying its own stale snapshot, so a lower-level cached response
cannot masquerade as renewed authorization. Other repository callers retain the
default read-through contract. `habits_snapshot_access_test.dart` covers durable
revocation, storage failures, fresh-read provenance, ordered recovery, private
member removal, and actor/workspace isolation.
Habits overview search is hosted by the persistent shell dock; closing search or
leaving the section clears its query. A tracker detail sheet opens immediately
while its scoped request loads. Reopened details revalidate in the background
while keeping their last authorized snapshot; cold loads and background refreshes
reuse an already-running request for that tracker. Duplicate taps cannot open stacked detail sheets. The scope-owned route
still closes on account/workspace departure. These native-only presentation rules
are covered by `habits_page_search_test.dart` and
`habits_page_personal_detail_test.dart`; the API remains an unpaginated list.

Meet meeting create, edit, and delete also queue offline with a pending list
treatment. Assistant model favorites and name changes now queue offline and
overlay pending values on their scoped cached reads. Live room access,
realtime tokens, and assistant generation remain network-dependent and must not
be represented as queued calls.
Task summaries, board lists, and board task pages read scoped snapshots while
revalidating. Core task create, edit, description, delete and restore, plus
board create and lifecycle edits, enter the outbox offline. Task and board
cards expose pending status. Label, project, and initiative lists revalidate
from scoped snapshots. Their
create, edit, and delete actions queue offline with pending cards. Task
relationships and task/project/initiative links queue as scoped edits. Bulk
task actions queue as one ordered edit with every affected card marked pending;
the bulk action reports a queued result without claiming server success.
Partial bulk replay stays in manual conflict review so successful tasks are not
silently retried with failed ones.
Board task create, edit, and move and board list create, edit, and reorder
also queue offline. Their list reads overlay pending edits; task cards and
list headers distinguish unsynchronized rows. Project updates read scoped
snapshots and queue create, edit, and delete with pending cards.
Board estimation settings also queue offline, overlay pending choices on the
cached board list, and mark the board tile until the edit is acknowledged.
Task description images stage encrypted bytes and request a fresh signed upload
URL during replay. Their unique local image markers are replaced only in queued
task description fields after upload; arbitrary prose is never rewritten. An
ambiguous upload remains in manual review before its dependent description edit.
Converting a Note checklist item to a Task uses the cached board/list reads and
Tasks outbox. The Note mention carries the local Task ID until replay maps it;
tapping an unsynced mention shows its queued state, and a synced mention opens
the resolved Task.
Chat conversation and message lists also return scoped snapshots while
revalidating. Conversation create, edit, and delete and user message sends enter
the encrypted outbox offline. A queued message appears immediately with a
dimmed dashed frame. Each send carries a stable client request ID so replay can
use the server's idempotency check. Message edit, delete, read acknowledgment,
reactions, AI settings, and friend requests also queue offline. Attachments
stage encrypted bytes in the outbox, request a fresh signed URL on replay,
and rewrite dependent queued message paths after upload. An ambiguous upload
remains in manual review. Assistant generation remains network-dependent.
Notification feeds and unread counts also return scoped snapshots while
revalidating. Read state, metadata, viewed Mail thread archiving, and workspace
invite decisions queue offline. Pending read state is applied to the feed and
unsynchronized notification tiles use the dashed treatment.
Profile's former preferences snapshot migrates into the encrypted account-scoped
replica on first read. The visible cached profile stays in place during each
refresh. Profile text edits and activity sharing queue offline; identity and
sharing controls show the pending treatment until acknowledged.
Avatar changes stage encrypted image bytes offline and request a fresh signed
upload URL on replay. A lost upload connection remains reviewable because the
server may already have accepted the image.
Workspace member, role, and invite-link settings use scoped snapshots and queue
edits while offline. Permission and invitation changes only become effective
after server acknowledgment; uncertain writes require review in Offline changes.
Workspace selection migrates from preferences into the encrypted replica, and a
cached workspace list always triggers revalidation when loaded. Creation limits
and module visibility metadata use the same read behavior. Finance exchange
rates, wallet details, transaction pages, and stats retain snapshots during
refresh, including the initial Finance screen load.
Workspace creation, name and default changes, and avatar edits queue offline.
New workspaces receive local IDs; replay maps those IDs before dependent edits.
Workspace avatar bytes remain encrypted in the outbox until a fresh signed URL
is requested. An uncertain creation or upload requires review to avoid a
duplicate workspace or avatar operation.
Timer sessions, history, categories, goals, requests, and summaries use scoped
snapshots while revalidating. The native Timer root captures its actor lifetime,
workspace, and request generation before loading. Account and workspace changes
invalidate old cache, network, and disk publications; a same-account return after
logout cannot revive the old request. Current-scope snapshots remain visible
while revalidating. Deferred repository and encrypted-storage regressions in
`time_tracker_scope_test.dart` cover these boundaries. Session start, stop, pause, resume, edit, missed
entry creation, and deletion queue offline, with dimmed dashed session cards.
Timer category creation, goal create, edit, and delete, request create and edit,
approval changes, comments, and threshold updates queue too. Request images
stage encrypted bytes, obtain fresh signed URLs during replay, then submit the
request with the resulting storage paths. Category, goal, request, and comment
cards show pending sync state. Local ID reconciliation supports edits made
before a create syncs; ambiguous sends remain in manual review. Running session state applies
queued lifecycle edits over the latest snapshot.
Finance category and tag lists also read scoped snapshots while revalidating;
their create, edit, and delete actions queue offline, and queued cards use the
dimmed dashed treatment. An uncertain transaction
update or delete enters manual review rather than automatic replay. Once a
transaction or transfer update is acknowledged, failure to refresh its detail
does not invite another money write.
Wallet checkpoint create, batch create, edit, delete, and reconciliation also
enter the finance outbox. The timeline overlays queued checkpoints while
keeping server-confirmed latest balances and interval calculations separate;
pending rows have the dashed treatment. Finance feedback says queued or needs
review when the write has not been acknowledged. Transaction attachments stage
encrypted bytes, request a new signed upload URL on replay, and show queued
state until delivery. An ambiguous money write or upload waits for manual review.
Inventory sales-period create and edit, sale create and edit, period assignment,
and delete queue offline. Sales lists overlay local edits; pending sale cards do
not show an unconfirmed amount. Their local details remain readable and editable. Invoice replay maps
its returned ID before sending a queued period assignment. Pending period and
sale cards use the dashed treatment, and unknown outcomes require manual review.
Invalidation and logout prevent older
in-flight requests from writing back into the cache. Keys must include user,
workspace, and all query filters.

Offline refresh consistency (cache-backed reads in all mobile products): a
two-phase read and its
nested repository reads share one refresh cycle. Reconnect first revalidates
visited resources, then visible projections reuse those completed reads. A later
explicit refresh starts a new cycle; scope changes and invalidation fence earlier
results. Explicit setup/catalog refreshes report transport failure; ordinary
offline reads retain confirmed rows and project queued edits. Checkout coalesces overlapping quote reads, while an explicit retry after
a settled request remains available. Removing one retained resource invalidates
only the corresponding downloaded product for its actor and workspace.
Each product must retain its shared permission snapshot before download readiness
is accepted; Finance also requires retained exchange rates. Eviction of either
dependency prevents readiness even when the product's own catalog is complete.

Snapshot replacement, source indexes, authoritative download reconciliation,
and pressure eviction share one resource ordering boundary. An encrypted durable
journal restores the previous completed snapshot after interrupted publication
or cleanup. A persisted clear intent takes priority over rollback on restart;
logout, actor changes and explicit invalidation must not resurrect old data.
Resource-only clearing preserves unsynchronized outbox edits and local-ID mapping
provenance. Replica extraction accepts known response envelopes, not arbitrary
nested relation or metadata objects. Canonical domain fields survive sparse
responses, while explicit clearing values stay cleared. Regression evidence:
`cache_store_publication_test.dart` and `cache_replica_policy_test.dart`.

Connectivity fallback is restricted to typed transport failures (socket, timeout,
or HTTP-client transport errors). Invalid JSON, unexpected response shapes,
oversized bodies, and failed session refreshes remain visible failures rather
than presenting a cached response as a successful refresh. Download pacing wait
is outside the actual HTTP request timeout. Search patterns are compiled once per
retained search pattern rather than once per candidate row.
Mutation queue admission uses the same typed transport rule. The explicit
`OFFLINE_CONTRACT_UNAVAILABLE` exception is admitted only for replay-safe writes;
session, malformed-response, and unknown failures never become pending writes.

Reopened sale details immediately project queued sales-period assignments,
including explicit removal, over the scoped confirmed snapshot. They retain
queued status and local IDs until acknowledgment; pending IDs never become server
mutation targets.
Definitive not-found responses, including a locally queued deletion, clear
retained sale details and mutation controls. Transient refresh failures retain
the authorized snapshot. Regression evidence: `offline_mutation_admission_test.dart`,
`cache_revalidation_test.dart`,
`offline_download_manifest_test.dart`, `offline_preparation_coordinator_test.dart`,
`api_client_transport_failure_test.dart`, `inventory_sale_period_projection_test.dart`,
`inventory_sale_detail_refresh_test.dart`, and `season_pricing_controller_test.dart`
under `apps/mobile/test`.

Failed disk writes do not hide successful network responses. Mail and Meet retain
the original authorization error and disable their cache if denied-data cleanup fails.
Keys longer than Hive's 255-byte UTF-8 limit use a SHA-256 digest of the complete
scoped identity. Keep short keys stable, and test persistence/reopening with real
UUIDs and long search filters; short mock IDs can hide storage failures.

Mail list snapshots use the existing encrypted Hive store, with a one-minute
freshness window and a seven-day retention window. Cached rows appear while a
background refresh runs, including after their freshness window. A background
authorization denial revokes the affected workspace snapshot, clears the inbox,
and closes an open reader. Pull-to-refresh forces a network read, and successful mutations
invalidate the workspace's Mail variants. Thread details use the same scoped
cache; permissions and individual messages (including editable drafts) are
fetched from the server. General attachment bytes, credentials, and active compose buffers are
not cached. Authorization failures discard the displayed list. Search waits 300ms
after typing, and list rows are built lazily. Folder metadata loads independently
so it cannot hold up the inbox.
Small inline images keep an encrypted thread-scoped copy. A cached image renders
immediately while one shared background request refreshes it; a denied image
request revokes the affected Mail workspace and clears its thread media.

Inventory can synchronously restore an unexpired user/workspace-scoped snapshot
before currency and permission requests finish. Editing remains disabled until
current permissions are confirmed. A denied request removes displayed content;
cached data must never grant mutation permissions.

### Tablet layouts and shared controls

Use the available window width, including split-screen windows, when choosing
columns. Home uses a full-width workspace selector and independently flowing card columns;
the Apps hub uses content-sized rows so larger text can grow.
Drive and CMS allow their grids to use the wider workspace. Kanban and timeline
are work surfaces: do not wrap them in the reading-column width constraint.
Tablet Kanban fills the available height and puts dock clearance inside each
scrolling task list. It shows multiple independently scrolling lists; compact windows keep
the swipe-between-lists interaction. Leave room for the shell dock and task actions.

The shell's Apps button opens a searchable picker using the same module visibility
rules and descriptions as the hub. Primary top-bar actions remain visible; extra
actions use the overflow menu. Tablets can display more actions. Register Mail
workspace actions only while its nested workspace route is current, so a reader
or composer cannot leave stale workspace actions active.

Mail controls scroll with the message list, and formatted messages render inline
in an isolated native WebView. JavaScript, file access, forms, and browser-session
sharing remain disabled. Remote images require an explicit action. Its shared
document builder sanitizes the original body HTML off the UI thread, preserves
newsletter styles and email tables, and uses the web reader's typography and
overflow rules. Do not force every table into fixed equal-width columns. CID
images load through the authenticated attachment API, limited to raster images,
12 requests and 8 MiB retained bytes per message. The WebView receives only
prepared image data, never API credentials. Large attachments remain available
through the attachment actions.

Meet uses cached, account/workspace/query-scoped pages, explicit refresh, and
mutation invalidation. Workspace changes must invalidate pending UI requests even
when the new workspace is absent. A 401/403 clears the cached and displayed data.
The native Meet room keeps the shell's top bar and places its leave/back control in
the room content, so the route title and dock follow the rest of the app.

Verify at least 768×1024, 1024×768, and 1366×1024, plus a compact split window,
larger text, and an open keyboard. Check dock height and taps, multiple Kanban
columns, horizontal and vertical scrolling, task-detail return position, picker
filtering, and the last visible row above the dock. Widget checks supplement
authenticated simulator checks; native email rendering requires device verification.

When changing this behavior, verify cold launch, returning to a visited tab,
pull-to-refresh, slow/failed requests, rapid search changes, and switching accounts
or workspaces. Run the focused cache, Mail workspace, lazy tab, and shell back
navigation tests, followed by `bun check:mobile`. Use an iOS simulator to inspect
light/dark appearance, larger text, keyboard interaction, and narrow layouts.

Time Tracking and CRM user mobile calls stay on the live platform origin: Track and Contacts require
app-session credentials, while mobile currently uses Supabase Bearer sessions.
Do not move those paths to their satellites until mobile supports that authentication contract.

### Native API requests and hosting challenges

An HTTP 429 HTML response with `x-vercel-mitigated: challenge` is a Vercel browser
challenge, not the application's JSON rate-limit response. Native HTTP clients
cannot complete that challenge.

Production mobile Calendar requests use the infrastructure app's
`/api/v1/mobile-calendar/api/v1/…` gateway. Development uses the local Calendar
app directly. The gateway validates the Bearer session with Supabase before
reading any forwarding credential. It forwards only event CRUD, connected-account
list/disconnect, calendar connection list/toggle, and OAuth URL discovery to the
fixed `https://calendar.tuturuuu.com` origin. Calendar validates the original
session again and enforces workspace permissions. Incoming cookies, forwarding
headers, and client-supplied gateway credentials are never relayed. Redirects and
non-JSON upstream responses are rejected; mutations are never automatically retried.
Authenticated requests preserve `x-tuturuuu-offline-download` and
`x-tuturuuu-turnstile-token` when supplied, so Calendar applies the same bulk-read
protection and verification flow. Ordinary reads stay unmarked. Regression coverage
lives in `apps/infrastructure/src/lib/mobile-calendar/gateway.test.ts`.

The server credential is stored as a versioned encrypted envelope in the root
workspace's `workspace_secrets` row named `mobile_calendar_gateway:v1`. Its data
key is encrypted with the infrastructure app's existing `ENCRYPTION_MASTER_KEY`.
The envelope contains `version: 1`, `encryptedDataKey`, and `encryptedSecret`.
Only the server decrypts it; it must never enter mobile build configuration,
logs, source control, or the signing bundle.

Configure Calendar's custom WAF exception to require both its API path and an
exact `x-tuturuuu-calendar-gateway` header value matching that private credential.
Do not accept the mere presence of an Authorization header as a WAF bypass.
The private credential allows verified gateway traffic through hosting challenges;
it does not replace Calendar's application authentication or authorization.

For cutover, deploy and verify the gateway, then publish clients using it. Replace
the old path-plus-Bearer exception with the server-credential rule once both store
builds are available. Verify invalid sessions return JSON 401 from the gateway
without an upstream request, a signed-in Calendar loads real events, and direct
Calendar requests with a forged Bearer or gateway header still receive the hosting
challenge. Older clients that call Calendar directly need the mobile update.
Keep publication on hold if gateway verification fails. Inspect the exact project's
active rules and unpublished draft before changing or publishing its WAF config.

For credential rotation, create a new encrypted envelope, temporarily allow both
old and new **server credentials** at the WAF, update the secret row, verify a live
Calendar read, then remove the old credential. Never restore the public Bearer
exception as a fallback. Missing or invalid secret configuration fails closed with
JSON 503. Responses use `private, no-store`; request bodies are limited to 512 KiB,
response bodies to 8 MiB, and forwarding to 20 seconds.

## Locked Notes

Mobile Notes defaults to a device-first encrypted lock. Where OS local
authentication is available, Face ID or Touch ID gates a random note key in
device-only secure storage; otherwise the lock sheet defaults to a six-digit
app PIN. The lock encrypts the note body; the title and list metadata retain
their existing visibility. The PIN gates that local key and is never used as
the encryption password. Five incorrect PIN attempts pause retries for 30
seconds. The server
also stores a wrapped copy of the random key in the note envelope using the
configured encryption master key. Creating a device lock fails if wrapping is
unavailable. Web releases that key only for the note creator after a verified
passkey sign-in within five minutes, on web or mobile. Account sign-in alone
does not release it. Native passkeys use `webcredentials:tuturuuu.com` on iOS
and the `get_login_creds` Digital Asset Links relation for the production
Android signing certificate. Keep the association files and mobile signing
identities aligned when changing app IDs or certificates.
The user can also show a two-minute QR code on web and scan it from the
original phone's note actions; the phone requires fresh local unlock and sends
the key encrypted with a one-time QR secret. The QR secret stays on the two
devices. The server relays only the sealed key. A custom passphrase remains
available and existing passphrase-locked notes keep their current behavior.
Server-wrapped recovery means this lock is not end-to-end encrypted against the
server. Preserve the configured encryption master key when rotating deployment
secrets; losing it disables passkey recovery for existing locked notes, though
the original phone or its QR transfer can still open them. On compact layouts,
Back closes any open Notes action sheet and returns
from note detail to the Notes list.

## Mobile App Lock And Web QR Approval

The mobile app supports a device-level app lock from Settings > Session. The
setting is stored in secure storage and uses the OS local authentication prompt
with device PIN/passcode fallback allowed. When enabled, the app locks on an
authenticated cold launch and after at least 30 seconds in the background.

The locked surface centers the existing transparent logo at the generated native
artwork size: 104 points on iOS and 80 dp on Android. Its light background is
white and its dark background is `#09090B`, matching the native launch canvas.
Entry stays centered. With text scaled above 1.5×, recovery moves the
decorative logo to the top with 24 pixels
of clearance after the system inset, keeping it above the instructions. It does
not expose protected content to touch, keyboard focus, or accessibility. Recovery controls
appear five seconds after entering the lock, including when authentication fails
or remains pending; retrying does not restart that deadline. Unlocking still uses
the OS biometric/device-passcode prompt, not a separately stored application PIN.
A failed or cancelled prompt leaves the app locked. Authentication completions
from a reset account lifetime or disposed lock are ignored. A physical
in-flight authentication guard also survives settings reloads until the OS
prompt settles. Delay saves run sequentially; a completed current-lifetime save
preserves the locked state, and only the latest intent updates the visible delay.
Reset/disposal prevents queued stale writes from starting. An already-started
secure-storage write cannot be cancelled by resetting the UI lifetime.

Regression coverage is in `app_lock_splash_timing_test.dart`,
`app_lock_boundary_test.dart`, `app_lock_auth_lifetime_test.dart`, and
`app_lock_review_races_test.dart`. Widget
checks cover entry timing, compact English/Vietnamese recovery, large text and
reduced motion. `app_lock_splash_visual_test.dart` decodes native logo assets and
compares rendered artwork bounds and canvas colors at matching viewports. Those
source fixtures do not prove an installed launch, native biometric or TestFlight
behavior. Android legacy and Android 12 logo inputs retain the canonical
320-pixel RGBA artwork inside transparent 768/1152-pixel canvases. Regenerate
Android only from `apps/mobile` with `dart run tool/generate_android_splash.dart`;
it preserves the canonical logo and excludes iOS/web generation. Pixel tests
verify transparent native padding and 80 dp artwork across all densities.
Installed OS launch scaling and release artifact qualification remain separate.

### Device authenticators and trusted registrations

Home suggests registering the current device when local authentication is
available, the account has no verified authenticator on that device, and new
registrations are unlocked. “Not now” suppresses this invitation for seven days
per account. A failed policy lookup never produces a misleading invitation.
Settings > Session always provides the explicit management entry point.

Registration creates a Supabase TOTP factor and a separate random device proof.
The mobile app saves both in account-scoped secure storage before verifying the
factor. iOS uses a non-synchronizing, this-device-only Keychain item. Each code
reveal, approval and management change requires fresh OS authentication; PIN or
passcode fallback is allowed. Codes disappear when the app backgrounds.

`/api/v1/auth/mfa/devices` uses request-scoped authentication for web cookies and
mobile Bearer tokens. Server-owned `app_metadata.tuturuuu_device_authenticators`
contains the registration policy and proof hashes, never TOTP secrets. The
registry API serializes writes with a bounded Upstash lease and fails closed if
`UPSTASH_REDIS_REST_URL` or `UPSTASH_REDIS_REST_TOKEN` is unavailable. Do not log
registration response bodies, proofs, TOTP secrets, or session tokens.

The trusted-device list supports revocation and locking new registrations.
Enabling the lock requires two currently verified trusted factors. Unlocking
requires a current trusted-device proof and AAL2; the last trusted device cannot
remove itself while locked. Keep a backup trusted device: there is no automatic
lost-all-devices recovery bypass. The lock governs Tuturuuu device registrations;
it does not disable third-party enrollment through Supabase's own MFA APIs.
Only canonical, verified registry entries with valid proofs can approve Tuturuuu
sign-ins. A client-supplied device identifier or editable profile cannot grant
trust. Provider-level MFA enrollment can invalidate other sessions, so setup
explains that other devices may need to sign in again.

### QR and number-matching approvals

The scanner at `Routes.settingsQrLoginScan` accepts Tuturuuu QR payloads from
allowlisted origins; manual link entry supports devices without a camera.
Approval requires fresh local authentication, a trusted-device proof and a
verified mobile MFA session. The server checks the challenge secret, origin,
protocol kind, expiry and one-time consumption. QR handoff creates a new session;
Supabase MFA requirements still apply to that new session.

The web MFA screen creates a session-bound
`/api/v1/auth/mfa/mobile/challenges` request and shows a six-digit number.
The mobile user must enter that number. The pending-approval API never returns
it to the approving device. Approvals are rate-limited, expire after their short
challenge lifetime, and cannot be approved by the requesting session itself.
Users can explicitly deny an unexpected request.

`MobileMfaApprovalListener` polls while authenticated, foregrounded and unlocked.
Push receipt triggers an immediate refresh. A notification contains only account
and challenge identifiers plus expiry, never a code or credential. Tapping it
opens a page that re-fetches the authorized request. Notifications do not approve
from the lock screen. Polling remains the fallback when notification permission
or provider delivery is unavailable.

After consumption, the web poller sets the HTTP-only
`ttr_mfa_mobile_approval` cookie, bound to the same user, web session, hidden
challenge secret and unexpired canonical approval. This is an application-level
web approval; it does not mint a Supabase AAL2 token. Mobile AAL2 still comes from
Supabase MFA verification.

### Sessions and account connections

Settings > Session > Devices and connections lists active sessions and linked
sign-in identities. Users can revoke another session, revoke other sessions,
connect a supported OAuth provider, or disconnect an identity while retaining
another sign-in method. Destructive actions require confirmation and local
verification. Account changes during an asynchronous operation fail closed.

Multi-account persistence snapshots the current session after profile loading,
so a refresh during that request cannot save an older token. Authenticated API
retries are account-scoped and refuse to replay after an account switch.

* Multi-account removal and all-account logout must treat Supabase
  `auth.signOut()` as required before clearing the local account store or
  emitting an unauthenticated Cubit state. Google/provider logout and stored
  refresh-token revocation can be best-effort, but a failed Supabase logout must
  leave the account visible with an error so the persisted session cannot
  silently reappear later.
* Auth account models may serialize refresh tokens and session JSON only for the
  encrypted secure-storage store. Do not include those raw secrets in
  `Equatable.props`, `toString`, or other Cubit/Bloc state debug output because
  the global Bloc observer logs state changes during development.

## Mobile Drive Coverage

The Drive screen in `apps/mobile` supports the main dashboard Drive flow:

* Workspace permission-gated loading
* Storage analytics summary
* Folder navigation and breadcrumb-style path movement
* Search, sort, grid/list toggle, and pagination
* Folder creation, rename, delete, bulk delete, and upload
* File preview, external open, share, and path copy
* Folder export-link generation and sharing

The mobile implementation talks to the same authenticated workspace storage routes used by the web product:

* `/api/v1/workspaces/:wsId/storage/list`
* `/api/v1/workspaces/:wsId/storage/analytics`
* `/api/v1/workspaces/:wsId/storage/folders`
* `/api/v1/workspaces/:wsId/storage/rename`
* `/api/v1/workspaces/:wsId/storage/object`
* `/api/v1/workspaces/:wsId/storage/share`
* `/api/v1/workspaces/:wsId/storage/export-links`
* `/api/v1/workspaces/:wsId/storage/upload-url`
* `/api/v1/workspaces/:wsId/storage/finalize-upload`

## Mobile CRM Coverage

The CRM screen in `apps/mobile` supports:

* Workspace permission-gated users and audit tabs
* Search, filters, pagination, and audit range filters
* Create, edit, and delete user records
* Avatar upload during create/edit flows
* Feedback create/update/delete flows
* Duplicate detection and merge flows
* CSV import with preview and deduping by email
* CSV export of the currently filtered users dataset

CRM mounts a separate native screen session for each signed-in account and
workspace. The default users tab reads only that tab, renders the scoped stored
snapshot, and publishes the refreshed result; pull-to-refresh awaits revalidation.
Temporary transport failures and explicit MFA/abuse-verification challenges retain
authorized rows. Optional group reads do not delay customer rendering. Row fields
are intersected with current workspace permissions even when a refresh falls back
to older cached data. Cold loads reserve row geometry and announce loading. Definitive access denial
clears visible customer and audit data. Changing scope closes that session's
forms and sheets and rejects late responses and queued writes.

Search lives in the persistent shell dock. Customer rows open a compact detail
view using the permission-redacted `/users/database` result; private contact
fields require its private-information permission flag. Pending local edits are
redacted again using that metadata, so they cannot restore newly denied fields. Detail viewing does not
call the individual-user GET endpoint. The shell owns the title and Back action.
The existing create/edit/avatar, feedback, filtering, import/export, and
permission-gated duplicate/merge tools remain available. Lists build rows lazily,
load another page near the viewport end, deduplicate overlapping IDs, and stop
when an empty page disproves a stale total. A failed page offers an explicit retry.

Regression coverage: `crm_workspace_test.dart` covers scoped late responses,
permission-redacted detail, enlarged text, automatic paging, empty-page termination,
and retained-versus-denied refreshes. `offline_mutation_admission_test.dart`
ensures model-returning CRM commands cannot queue for a departed account.
These checks do not establish authenticated device or production behavior.

The mobile CRM uses the existing authenticated routes:

* `/api/v1/workspaces/:wsId/users/database`
* `/api/v1/workspaces/:wsId/users`
* `/api/v1/workspaces/:wsId/users/:userId`
* `/api/v1/workspaces/:wsId/users/groups`
* `/api/v1/workspaces/:wsId/users/feedbacks`
* `/api/v1/workspaces/:wsId/users/audit-logs`
* `/api/v1/workspaces/:wsId/users/duplicates/detect`
* `/api/v1/workspaces/:wsId/users/merge`
* `/api/v1/workspaces/:wsId/users/bulk-import`
* `/api/v1/workspaces/:wsId/users/avatar`

For CRM list and duplicate/merge routes, keep workspace resolution request-aware on the web side. Mobile calls authenticate with Bearer tokens rather than dashboard cookies, so routes that resolve the workspace with cookie-only helpers can fail as `Workspace not found` even for valid workspace members.

## Mobile Education Coverage

The Education screen in `apps/mobile` supports:

* An overview dashboard with counts for courses, quizzes, quiz sets, flashcards, and attempts
* Course search, create, edit, delete, and paginated browsing
* Library management for quizzes, quiz sets, and flashcards
* Quiz authoring with answer options, correctness flags, and explanations
* Attempt browsing with status and quiz-set filters plus attempt-detail review

Education's native session is keyed to the current account and workspace. Its
repository binds API reads, cache keys, pending-edit overlays, mutation admission,
and tag invalidation to that actor. Legacy callers without an explicitly bound
account capture the active actor before each request and retain that identity
through cache reads, pending-edit overlays, and write admission. Anonymous reads
cannot publish after sign-in; writes require an account before queue admission.
`education_actor_scope_test.dart` covers delayed
responses/queue reads and exact actor filtering across all four collections.
Changing either scope removes the old list,
search, and owned modal routes immediately; late responses cannot repopulate it.

Course/library search uses the persistent shell dock and resets when the section
changes. Collection rows build lazily, page ahead when the viewport is within
400 pixels of the end, deduplicate stable IDs, and stop when the server returns
an empty page even if its count is stale. Temporary failures and verification
challenges retain authorized rows while offering explicit retry; definitive
authentication/permission denial clears visible collections. Normal entry has a
cached phase followed by revalidation, while pull-to-refresh awaits a fresh phase.

Attempt details likewise retain their authorized snapshot during revalidation and
clear on definitive denial. Authoring forms keep server failures in the form for
retry instead of letting an exception escape. No new teaching or assessment API
behavior is implied by this presentation change; existing endpoint permissions
remain authoritative. Widget regressions in `education_workspace_test.dart`
cover account/workspace transitions, paging, lazy rendering, challenges/denial,
and dock search reset. Owned creation routes also close when another modal
covers them: session cleanup requests a frame and removes only the departed
route, preserving the unrelated modal above it.

The mobile Education module uses authenticated workspace routes from `apps/web`:

* `/api/v1/workspaces/:wsId/courses`
* `/api/v1/workspaces/:wsId/courses/:courseId`
* `/api/v1/workspaces/:wsId/quizzes`
* `/api/v1/workspaces/:wsId/quizzes/:quizId`
* `/api/v1/workspaces/:wsId/quiz-sets`
* `/api/v1/workspaces/:wsId/quiz-sets/:setId`
* `/api/v1/workspaces/:wsId/flashcards`
* `/api/v1/workspaces/:wsId/flashcards/:flashcardId`
* `/api/v1/workspaces/:wsId/education/attempts`
* `/api/v1/workspaces/:wsId/education/attempts/:attemptId`

For mobile-facing collection APIs, keep list routes request-aware and list-shaped. A cookie-only helper or `.single()` response on a collection endpoint can work in the web dashboard but break mobile Bearer-token callers or pagination assumptions.

The mobile endpoint registry is guarded by `bun check:mobile-api-mappings`.
The check extracts Flutter `/api/*` templates from `api_config.dart` and the
production endpoint catalog used by the `ttr` CLI SDK. It verifies that both
legacy clients still resolve to a canonical owner in a checked-in Next
satellite, the legacy route wrappers, or the Rust/TanStack migration manifest.
The `Mobile API Mappings` workflow runs whenever either client catalog, an app
API route, or the migration manifest changes. If a route is migrated or
removed, update Flutter and the CLI SDK in the same change instead of leaving a
legacy client to discover the break in production.

## Mobile Inventory And Storefront Coverage

Inventory is a native mobile workspace with overview, product CRUD, checkout,
sales, setup, audit-log access, and storefront management. Storefronts support
create/edit/delete, status and visibility controls, public preview, product
listing CRUD, stock-row selection, pricing, and per-order limits through the
same authenticated inventory satellite APIs:

Mobile sales also support workspace sales periods. Operators can create a
season or event such as `Summer 2026` or `TuCon 2026`, filter the mixed
invoice/checkout history by that period, and assign the period during sale
creation or editing. Archiving preserves historical reporting.

* `/api/v1/workspaces/:wsId/inventory/storefronts`
* `/api/v1/workspaces/:wsId/inventory/storefronts/:storefrontId`
* `/api/v1/workspaces/:wsId/inventory/storefronts/:storefrontId/listings`
* `/api/v1/workspaces/:wsId/inventory/storefronts/:storefrontId/listings/:listingId`

Keep Storefront in the five-item Inventory mini navigation. Audit logs remain
discoverable from Inventory Manage so compact phones retain a stable native
navigation bar.

When an Education mobile list needs derived counts from workspace-protected join tables such as `course_module_quiz_sets`, verify workspace membership first with the request-scoped client, then run the joined read on an admin-backed client. Also select real join columns such as `module_id`; do not assume those bridge tables expose a synthetic `id`.

## Import And Export Format Notes

* The web CRM page still has richer spreadsheet tooling, including XLSX-oriented flows.
* Mobile import and export currently use CSV plus native share sheets.
* Keep the server contract for bulk import as a raw JSON array of `{ email, fullName }` rows.

This format choice is intentional for now: the current Flutter dependency graph in `apps/mobile` does not accept a stable XLSX package cleanly without conflicts, so mobile should prefer CSV/share flows unless spreadsheet generation is moved server-side later.

## Verification

For Drive, CRM, or Education mobile changes:

1. Update `apps/mobile/lib/l10n/arb/*.arb` for every new user-facing string.
2. Run `flutter gen-l10n`.
3. Run `bun check:mobile`.
4. Run the applicable mobile test and native build workflows in CI on the exact
   authored commit. Use CI for routine branch verification; if its queue is
   demonstrably stuck, record the pending jobs and local evidence, then resume
   exact-commit CI before claiming release readiness.

## Offline preparation and synchronization

Finance, Inventory, Tasks, and Calendar keep visited responses in the encrypted,
user/workspace-scoped cache. Reopening uses local snapshots immediately while
revalidating. Loaded list pages and detail responses also materialize local rows;
searching a new query offline does not require that exact query to have been
requested online. Reconnect, app resume, and refreshed authentication replay the
outbox before refreshing visited resources. Visible lists reload after replay.
Only one replay runs at a time. Cached screens publish their first snapshot,
then await fresh data without starting a second cold fetch or a cache-notifier
loop. Transport failures retain the original scoped snapshot and its timestamp.
Settings and pending rows distinguish queued,
syncing, failed, and conflicting writes. An uncertain money operation stays in
manual review unless its endpoint guarantees idempotency; replay must never turn
a cache refresh failure after acknowledgment into a second write.

Settings → Offline → Download all is an explicit download for the current
account and workspace. Products settle sequentially, with per-product state,
historical completion time, and targeted retry. Inventory downloads catalog pages
and each product detail; sales, audit, and finance transaction history are paged.
Audit pages are indexed by their server audit record IDs and reused across UI
page sizes, ordered by occurrence time descending.
Finance also prepares checkpoint summaries, wallet-specific statistics, and
account-scoped global exchange rates, so these reads work on a first offline visit.
Tasks include board collections, task details, relationships, and supported
history. Calendar cursor pages cover the API-supported year range 0001–9999 and
connection metadata. Its paginated requests cap each page at 500 rows; normal
unpaginated requests accept at most 400 days. Pagination has finite safety bounds and fails rather than silently
claiming completion when a cursor does not advance. Wallet checkpoint preparation
currently follows the mobile endpoint's latest-50 window; it does not promise a
lifetime checkpoint archive.

Completed full collections reconcile obsolete list/detail snapshots so removed
server rows do not survive in local search. Failed downloads retain older
snapshots and pending writes. Each explicit download requires successful
persistent writes and a final check
that its requested snapshots survived storage limits. A full run checks earlier
products again for eviction. A restored completion timestamp is historical and
shows **Needs refresh**, never proof that all rows remain stored. Cache eviction, clearing cache, changing quota, or changing account/workspace
invalidates readiness. A scope
switch stops subsequent requests; an already-started request settles before
another bulk run starts. Normal visits fill a bounded older history window with
15-minute throttling, rather than rerunning Download all automatically.

Bulk GETs are globally serialized on the device and spaced by at least 750 ms at the request boundary, using a monotonic clock after queued authentication preparation. Early timer wakeups are rechecked; regression coverage lives in `offline_api_pacer_test.dart` and `api_client_offline_preparation_test.dart`. This stays below the hourly session budget even
when the gateway and owning app both enforce the guard. Ordinary unmarked
foreground reads do not consume these additional bulk-download budgets.
The additional server download protection applies only to eligible GET/HEAD requests explicitly marked `x-tuturuuu-offline-download: 1`. Ordinary daily enterprise operations in Finance, Inventory, Contacts, Tasks and other apps always continue through existing authentication, authorization, MFA, abuse and API protections without accessing this additional guard's Redis clients, quotas or CAPTCHA, even when it is activated. This scope applies to the web API and every registered satellite proxy. `OFFLINE_DOWNLOAD_PROTECTION_ENABLED` defaults to inactive and activates only for the exact value `true`; while inactive, marked bulk downloads return 503 with `Retry-After: 30`. Omitting the bulk marker never bypasses baseline protections or grants access.

### Mobile download protection readiness

The default production mobile Download all path needs protection readiness at
Web, Finance, Inventory, Tasks and Infrastructure. A release/configuration owner
must verify every serving replica and fallback, using exact deployment identities.

This serving map follows `core/config/api_origins.dart` in mobile, each app's
`proxy.ts`, and `apps/infrastructure/src/lib/mobile-calendar/gateway.ts`.
No checked-in workflow or application configuration assigns the activation flag.
That establishes source wiring only: deployed flag values, Redis/Turnstile
provisioning, mixed-replica consistency and authenticated canary results remain
unknown until the release owner observes them. The Infrastructure gateway can
also return a separate gateway-unavailable 503; status alone does not identify
which service failed.

Mobile presents one localized paused-download message after a 429 or 503 and
stops the remaining modules instead of printing each server error. It preserves
the selected modules, Wi-Fi consent and retry deadline. A service failure waits
between 30 seconds and 15 minutes, using the bounded Retry-After delay.
An explicit Download all or module retry tap starts a new plan immediately;
automatic retries retain the cooldown. One explicit plan permits
three service-failure attempts total, including the initial attempt; its retry
budget and deadline survive restart. Reconnect, app resume and a scoped one-shot
timer can resume that plan. After the limit, only an explicit retry starts a new
bounded plan. Pause cancels the retained plan. Ordinary screen reads and saved
data remain usable. Regression coverage is in
`offline_preparation_service_pause_test.dart` and
`offline_preparation_intent_test.dart`.

Before enabling offline prefetch, provision `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` on every gateway and owning-app replica that can handle these reads. Verify distributed limiter operations, shared clearance storage, Turnstile configuration, and authenticated ordinary-read and marked-bulk canaries on the exact deployment. Enable the activation flag only after those checks pass, consistently across the request path; available Redis or elevated account trust never implicitly activates the feature. Keep the flag inactive during initial provisioning. Once activated, Redis/configuration/runtime failures still return 503; there is no automatic outage bypass or process-local substitute.

When activated, the shared proxy enforces explicitly marked eligible bulk reads: 1,200/minute and 30,000/hour per IP, plus 600/minute and 12,000/hour per session when present. Gateway and owning-app enforcement may both count a marked request. Bulk requests require Turnstile clearance unless the server has verified elevated trust; clearance lasts 15 minutes and never bypasses authentication, permissions, MFA, blocks, or quotas. Ordinary unmarked requests do not spend these additional offline-download allowances.
Regular reconnect refreshes are paced without the bulk marker; optional history fills use silent bulk mode. Background work never opens a verification modal and pauses when challenged. Verification-required 403 responses preserve existing authorized snapshots; authorization-denied responses purge the denied resource. A 429 stops downloads and delays queued replay according to Retry-After, with at least a minute's wait.
Regression coverage in [offline-download-guard.test.ts](https://github.com/tutur3u/platform/blob/main/packages/utils/src/__tests__/offline-download-guard.test.ts) proves unmarked ordinary reads avoid Redis, offline quotas and CAPTCHA with activation on or off, inactive bulk remains blocked, and activated bulk storage failures, quotas and CAPTCHA remain enforced.

Local Inventory search mirrors name-only SQL ILIKE, trimmed whole query, case
insensitivity, preserved accents, `%`/`_` wildcards, and backslash escaping.
Catalog ordering is creation time descending, then stable ID. Finance matches the
untrimmed query against descriptions and orders by taken time, then creation time,
both descending. Cached `[CONFIDENTIAL]` descriptions are not searchable: offline
search cannot reconstruct hidden server fields or newly granted permissions.
The cache represents the last authorized download; changes made elsewhere,
permission revocations, and authoritative stock/balance calculations require a
server refresh. Sales can be drafted offline from cached catalog and season
prices, but remain queued until the server validates price IDs and commits them.
Mobile applies configured current-period, revenue-wallet, and finance-category
defaults while preserving explicit choices. Legacy period sales also use the
atomic invoice request with a stable request ID; period rejection must not leave
an already-created invoice. Reconcile cart refreshes current metadata/prices and
removes incompatible or unavailable lines, then asks the operator to review the
total. It applies only to the editable current cart, never historical sales or a
frozen uncertain checkout journal.
Stock health remains the last confirmed snapshot and excludes local drafts.
Workspace permissions are refreshed online and persisted as an encrypted
account/workspace-scoped UI hint. A missing network interface or transport failure
may reuse that hint; authorization failures remove it, and switching accounts cannot reuse grants.
Download all also prepares this metadata. Local permissions never authorize
server writes: the server checks current permissions when replaying each mutation.
Product images are cached as encrypted bytes when displayed and during Inventory
Download all. Cards, checkout rows, and editor previews use the same scoped cache.
Image bytes share the storage quota and clearing/eviction behavior with product
records. Downloads accept HTTPS media with at most three HTTPS redirects, never
send app credentials, and enforce an 8 MiB file and 16 megapixel image limit.
A required image that cannot be retained makes the product download fail rather
than claiming full offline readiness. Cache keys digest image URLs so signed
read tokens are not exposed in plaintext keys.

Offline inventory acceptance is scoped to the current account and workspace. A queued checkout receives a local pending identifier, never a committed invoice receipt; pending local catalog/setup edits must synchronize before checkout. Read-through helpers retain their default compatibility behavior while pinning an available account at entry, checking it at request and cache publication boundaries, and rejecting late responses after account changes. Request generations also prevent older workspace loads from replacing the active screen.

For marked bulk reads, the authenticated gateway uses a session budget when the client IP is unknown; an anonymous marked request without an attributable IP fails closed. Known-IP bulk requests retain their IP budget. These controls do not grant offline clients server authorization. Product images share one 60-second deadline across redirects and body streaming, and unrelated resource eviction does not cancel their fetch.

Deferred cache transaction/refresh sharing, transport draining, search performance, and cosmetic improvements are tracked in [#5737](https://github.com/tutur3u/platform/issues/5737). App disposal invalidates preparation readiness immediately; an already-started read may fail when its HTTP client closes. Graceful draining remains a followup and does not permit a disposed preparation to publish readiness or replay writes. Regression coverage includes `inventory_product_image_cache_test.dart`, `inventory_product_editor_page_test.dart`, `api_client_account_test.dart`, and `packages/utils/src/__tests__/api-proxy-offline-response.test.ts`.

Provider authorization, live calls, AI execution, and uncached attachment bytes still require connectivity; Download all is scoped to these four product data collections, not every external service or file.

Regression evidence: `offline_sync_test.dart`, `local_search_test.dart`, `offline_preparation_coordinator_test.dart`, `offline_download_manifest_test.dart`, `offline_preparation_repository_test.dart`, `finance_inventory_offline_test.dart`, `inventory_audit_offline_test.dart`, `season_pricing_controller_test.dart`, and `packages/utils/src/__tests__/offline-download-guard.test.ts` cover replay, scope changes, strict persistence, search rules, offline draft state, and server rate/challenge enforcement. `cache_revalidation_test.dart`, `workspace_permissions_offline_test.dart`, and `finance_scope_races_test.dart` cover fresh visible data, permission hints, scoped invalidation, and late-response rejection. Native airplane-mode and real Turnstile verification remain release checks beyond unit tests.

Synthetic render evidence for the offline status and targeted retry surface:

![Offline cache with targeted retry, synthetic Flutter fixture](https://mintcdn.com/tuturuuu/SEinzPodFlbNa3FO/images/mobile-offline-preparation-retry-synthetic.png?fit=max\&auto=format\&n=SEinzPodFlbNa3FO\&q=85\&s=6f9520cf1213312f236896988fdd659d)

These images come from Flutter widget fixtures, not an installed-device build.

## Floating navigation and compact Profile

The first floating navigation tap opens its destination. Reselecting the active
destination scrolls its content to the top. Reselecting again resets its top
section to the default; if already at the top, reset happens immediately. Rapid
third taps during scrolling must also reset. Notifications returns to Inbox and
Profile to Overview within at most three taps; scrolling manually restarts the
sequence. Apps resets to Grid, Finance taxonomy to Categories, and Calendar to
Three days on phones or Week on tablets. Notes returns to Inbox and Assistant
to Chat through their existing guarded handlers. Time Tracker sections remain
separate routed destinations. Home defaults to Home; its second tab, Personal
Agenda, uses only the signed-in user's personal membership, with no shared fallback or global scope change.
Agenda resolves user, personal workspace, then
device timezone and reloads after preference changes; Home retains its mounted
dashboard state across tabs. Agenda retains cached events during retry and offers
read-only details; Calendar remains the editing surface. Apps defaults to Grid
before List. Shared search replaces the top navbar; empty submission dismisses and unfocuses. IME visibility
and hardware search focus animate the whole dock and its actions out together;
route changes clear focus. Workspace visibility has a subtle icon, a named tooltip,
and a 44-pixel target. Regression coverage: `personal_agenda_test.dart`, `personal_agenda_scope_test.dart`, `shell_keyboard_chrome_test.dart`,
and `apps_search_submit_test.dart`. Apps opens with one tap and keeps its picker on long press.

Profile uses the shell title for Overview and Timeline, with no duplicate
body heading. Place the day-trail action before the rightmost Overview/Timeline
switch, including compact/overflow layouts. Identity and metric layouts adapt to
available width and text scale; avoid nested bordered panels and fixed three-column
cards on small screens. Timeline mounts activity rows lazily and keeps transient
provider failures in a bounded toast, without a persistent retry/status row.
Preserve privacy and do not announce a partial response as complete history. These are defaults
for the mobile Profile and comparable shell section switches; semantic borders
for unsynchronized drafts and destructive confirmation dialogs remain intentional.

Regression evidence: `shell_dock_reselection_checks.dart`,
`shell_chrome_actions_test.dart`, `profile_overview_shell_test.dart`,
`profile_timeline_section_test.dart`, and `profile_timeline_races_test.dart`.

Synthetic Profile renders use placeholder identity and activity data:

![Compact Profile Overview, synthetic Flutter fixture](https://mintcdn.com/tuturuuu/SEinzPodFlbNa3FO/images/mobile-profile-overview-synthetic.png?fit=max\&auto=format\&n=SEinzPodFlbNa3FO\&q=85\&s=9db3f5c8ea19680233824d64017c81c9)

![Profile Timeline at double text scale, synthetic Flutter fixture](https://mintcdn.com/tuturuuu/SEinzPodFlbNa3FO/images/mobile-profile-timeline-large-text-synthetic.png?fit=max\&auto=format\&n=SEinzPodFlbNa3FO\&q=85\&s=82762bea2ee0c9eedf6884cb8dcb6d5f)

## Profile activity privacy

The Profile timeline shows the signed-in user's task creations, transaction
creations, and notes from the verified personal workspace. Calendar rows are
**workspace events**, shown only with `manage_calendar` permission. The API first
checks actor membership and Calendar permission before its audited Calendar read;
missing permission omits that source, while lookup failures mark the result partial.
Finance keeps its permission-aware RPC. Calendar titles are not returned.

Overview is the default view and has no edit shortcut. Profile editing and full
banner controls live in consolidated account settings. Avatar/banner uploads are
optimized off the UI isolate: input is bounded to 20 MiB/40 MP, orientation is
applied, and JPEG output is limited to 1024/2048 pixels and the existing 2/5 MiB
bucket ceilings. Animated images become a static first frame; re-encoding strips
source metadata. Banner tickets reserve the existing actor-derived upload budget;
failed tickets retain their reservation. Only public first-party actor-owned
avatars/banners enter the scoped disk cache. Signed, private and foreign URLs do
not. Account changes fence asynchronous profile loads and media dispatch.

Timeline groups records by local day, links to native views, and reveals days near
the bottom, including an initially short viewport. Day headings and activity rows
are mounted lazily, with row extents adapted to the effective text scale. Further API pages contain at
most 200 rows per source, with a pinned upper time boundary and a maximum of 1000
pages per browsing session. Offset continuation can omit or repeat records during
concurrent inserts/deletes; client deduplication does not guarantee snapshot
isolation. Refresh starts a new session. A partial or failed page pauses automatic
continuation and keeps loaded rows. No persistent warning, retry row or completion
footer occupies the Timeline; a failure notice automatically dismisses after five
seconds. A capped or partial result must not claim an empty complete history.

The loaded snapshot is encrypted and actor/personal-workspace scoped, shown before
revalidation. Successful pages persist merged, deduplicated history. Partial
refreshes retain stored rows from failed providers while replacing successful
providers, with truthful partial flags; they do not retain newly permission-denied
Calendar rows. Older partial responses without source metadata retain their
stored rows as explicitly incomplete. Missing, ambiguous or unverified
personal membership fails closed; neither Overview nor Timeline follows the
selected team or tracked-time sharing preference. An unreadable local snapshot
does not block refresh. Regression coverage includes
`profile_timeline_incremental_test.dart`, `profile_timeline_races_test.dart`,
`core/media/profile_media_optimizer_test.dart`, `profile_media_image_test.dart`, and the
first-class mobile-activity/banner-ticket API tests.

Profile Overview and Timeline show personal data only and expose no team-sharing
controls or opt-in team aggregates. Nothing is shared by default. Existing team
sharing consent still gates workspace-scoped tracked-time totals and daily
activity, excluding raw session titles, email addresses, personal aggregates and
other workspaces. Revoking consent or membership blocks future shared reads.

The API uses the existing owner-scoped `user_workspace_configs` preference
`PROFILE_ACTIVITY_VISIBILITY=workspace`; missing or other values mean private.
It checks viewer membership before privileged reads and subject membership and
consent before and after aggregation. Shared activity is never stored in the
mobile persistent cache. Test private defaults, confirmation cancellation,
revocation, former members, and account/workspace changes before release.

## Assistant and task verification recovery

A task write returning HTTP 403 with `X-Abuse-Challenge: turnstile` requires
verification, not broader workspace permissions. Mobile opens the existing
security dialog and retries the same request once using the returned token.
Cancellation sends no retry; an account change aborts the request. Other 403
responses remain permission failures. Never bypass the server authorization or
abuse check to repair this flow. Log status and error codes, not response bodies
or verification tokens.

Every satellite enforcing this challenge needs its own production
`TURNSTILE_SECRET_KEY` configuration matching the mobile `TURNSTILE_SITE_KEY`.
The mobile release vault also supplies `TURNSTILE_BASE_URL`. A successful client
challenge followed by another 403 requires checking the server challenge audit:
`not_configured` means the satellite secret is missing. Configure the existing
matching secret through the provider vault and redeploy the current production
source; never disable verification. Check names and readiness without logging
secret values.

Assistant credits must load independently of optional task, Calendar, soul, and
model-catalog insights. Calendar insights use the authenticated workspace
`/api/v1/workspaces/:wsId/calendar/events` gateway. A failed credit read offers a
retry in the credit-source sheet rather than displaying a fabricated Free tier.
Chat errors remain visible after stream completion, with the user's message
retained for retry. Older Assistant UUIDs are not native Chat conversation IDs:
the specific `Conversation is not an AI chat` settings rejection must use the
legacy Assistant stream through the shared authenticated API client, including
challenge and refresh handling. Other malformed-settings errors stay errors. Read-only `ai-agent-thread-` mirrors belong in Chat, not Mira's
editable history. Do not restore them as Assistant conversations or send their
synthetic identifiers to Live's UUID-backed chat endpoint; Live starts a new
owned session when no resumable UUID is available.

Live initializes PCM playback before starting microphone capture on iOS. Its
serialized audio queue preserves chunk order and discards queued chunks when
playback is interrupted or disposed. The vendored PCM plugin preserves existing
`AVAudioSession` category options when the category is already correct; resetting
those options can disturb an active microphone route. Native microphone failures
are recoverable UI states. A simulator without a valid input format cannot prove
physical-device audio quality; verify recording, playback, interruption, and
headset reconnection on hardware before claiming that a reported device crash or
stutter is resolved.

## Apps search submission

Submitting a nonempty Apps query with exactly one current matching app clears
the field, closes search mode, and opens that app. Zero or multiple matches
keep the query and results visible while unfocusing the keyboard. Empty queries
close search mode. Submission uses the same current localized
results as the hub, and repeated submissions cannot launch the app twice.

Apps discovery retains its case-insensitive substring matching over the localized
label, description, and module ID; this submission change adds no plural stemming.
A queued selection is canceled if workspace, account, experiment, access, or
locale inputs change after its match was resolved and before navigation.

## Workspace picker search selection

The mobile current-workspace and launch-default pickers keep search text and
filtered results when the search field loses focus, including keyboard dismissal
before a result tap completes. Clearing search is an explicit action. Each result
uses its workspace ID for identity and selects its rendered workspace object,
including after sorting, duplicate display names, and list refreshes. This rule
applies to the sheet opened from the navbar, dashboard and Workspace Settings;
it does not change membership discovery, permissions, or default persistence.

## Private Hidden workspace recovery

The compact Settings root places **Hidden workspaces** immediately after
Workspace, before You. Its restore editor is account-scoped and available for
guests, without an active workspace, and when every workspace is Hidden.
Opening, searching and dismissing perform no preference write; explicit Restore
changes only that user's preference and does not select a scope or change its
default. The all-Hidden workspace selection screen also offers recovery.

See [Hidden workspaces](/platform/features/hidden-workspaces) for canonical membership separation,
actor-scoped caching and web/satellite selector behavior. Regression coverage is
in `settings_hidden_recovery_checks.dart` (actual Settings/Shell root, one mini
navigation item, guest/no-active/all-Hidden, Back and 320px/2× text) and
`workspace_visibility_test.dart` (rollback, logout/account replacement, deferred
module flags and explicit deep links before preference discovery).

## Shared navbar text scaling

The compact mobile navbar keeps its normal size at the default text scale. At
larger accessibility text sizes, its height grows to fit the title line without
shrinking that text. The floating content inset grows with the same measurement,
while icon switches stay compact in the top navbar. Read-only titles normally
use one line with an ellipsis and retain their full accessibility label. When
ellipsis would remove every title character, a clipped prefix remains visible.
Editable titles scroll horizontally under a fade instead of ellipsizing.

Mounted Assistant chat/live coverage confirms that its existing inner Row allows
its scaled title to paint within the taller outer navbar: 56px at 2× and 84px at
3×. That inner Row does not clip the text vertically. Horizontal space remains
limited by the compact mode controls; narrow layouts can show only a clipped
prefix rather than the complete title. Its full semantics label remains
available. The shared-navbar regression verifies actual ink in the first title
glyph for both modes at both widths and all three text scales. Scroll threshold
geometry is cached and refreshed for theme, text-scale and safe-area changes;
drag notifications do not perform title layout.

Title measurements follow inherited text style and platform bold, line-height,
letter-spacing and word-spacing overrides. The painted-prefix check selects a
complete first grapheme, so emoji and joined characters retain ordinary ellipsis
when they fit. Full title semantics remain available in either overflow mode.

## Profile Timeline date navigation

Overview and Timeline read only the signed-in account's verified personal
membership, even with a team selected. Missing or ambiguous personal memberships,
authentication mismatch and account transitions clear data and make no
fallback request. Cached and delayed responses stay scoped; opening records selects their personal workspace.
Timeline has one primary scroll: optional week controls scroll with activity,
rather than pinning a second header. Closed shell-controlled dates add no month
row or empty refresh slot. Header clearance is inside the scroll; it leaves the
viewport as the shell hides. Returned days and further provider pages append near
the bottom, including a short viewport, with stable item positions and type/id
deduplication. Date navigation expands returned days as needed. No completion
label implies that the user's complete history has been loaded. Partial responses
retain existing rows and pause continuation; refresh starts a new paging session.
Calendar attribution, device-local grouping, reduced motion and DST stay intact.

Home's personal calendar tab is titled **Agenda** in English and **Lịch trình**
in Vietnamese. Its header clearance scrolls away; all-day progress is clipped
by the card's exact edge. Regression targets: `profile_personal_scope_test.dart`,
`profile_timeline_incremental_test.dart`, existing Timeline race/date tests,
`personal_agenda_test.dart` and `agenda_view_test.dart`; device proof is separate.
The week strip reveals the selected date when opened or when the selected date,
week, width or text scale changes; ordinary snapshot rebuilds retain the user's
manual horizontal scroll. Browsing another week begins at its first day when
that week does not contain the selection. Calendar-day comparison uses UTC date
carriers rather than elapsed DST-length days. Unknown cold failures and empty
partial/capped snapshots show unavailable/partial state, never a confirmed
absence of activity. A successful complete empty response can confirm the
empty state. Actual padded Profile/Shell regressions cover the single activity
viewport, selected-date bounds and existing compact navbar at 320px/3×.

Opening date controls before the first activity response does not lock the
default date: the newest returned day is revealed unless the user explicitly
chooses a date. Empty stored snapshots stay provisional while revalidation is
pending, using the fixed skeleton viewport rather than announcing absence.
The section owns one bounded failure toast per failure streak; the embedded
browser does not add a persistent provider-status banner, refresh icon, retry row,
or completion label. Every entry shows the last authorized in-memory snapshot
immediately and revalidates in the background, including snapshots marked fresh.
Temporary network failures and verification challenges retain those rows;
definitive authentication or permission denial clears both visible rows and the
stored snapshot. A scoped secure-storage revocation marker is written before
cache removal, so cache initialization or deletion failure cannot reopen that
history after a restart. Until a new repository checks that marker, synchronous
peek stays empty; unreadable markers fail closed. A successful actor-fenced refresh
confirms a new snapshot was persisted before clearing the marker. If that write
fails, fresh online rows may display but the stored denied history remains blocked. If both marker persistence and
cache deletion fail, the client reports `TIMELINE_CACHE_REVOCATION_FAILED` and
blocks the current session; durable erasure cannot be guaranteed during combined
storage failure. Verification challenges, including `MFA_REQUIRED`, preserve
history and continuation. Cold skeletons announce Loading as a live region without
adding a visible refresh control. An account or personal-workspace change fences
delayed responses.
These defaults apply to mobile Profile Timeline; partial provider failures retain
only previously loaded rows from the failed sources and pause provider continuation
until a successful complete refresh. Viewport-near-end loading still expands
returned days and complete provider pages automatically, including short lists.
Regression evidence: `profile_timeline_repository_test.dart`,
`profile_timeline_races_test.dart`, `profile_timeline_revocation_test.dart`,
`profile_timeline_browser_test.dart`, and `profile_timeline_paging_test.dart`.

Mounted Profile regressions locate the lazy activity section by its rendered
position and wait within a bounded interval for fetched statistics. Fixed pixel
scroll distances depend on the test font and can leave the section unmounted at
large text sizes. Restore a hidden shell header with reverse user scrolling
before tapping its selector; resetting content offset alone does not reveal
the header. Validate both the default CI font and the optional capture font.

## Offline settings and stored-data inventory

Mobile Settings groups Preferences into Appearance & language, Time zone, and
Notifications & interaction; per-app settings live under Settings > Apps (see
[mobile settings shell](/platform/features/mobile-settings-shell)). Offline
module pages link to that app's settings. Downloads, cache
limits, cache removal, and unsynchronized changes belong to a dedicated Offline
section. Account, workspace, experiments, and help retain their existing access
rules. Each stored namespace expands to a local-only item list, searchable by name or ID.
Rows render lazily in a bounded viewport; search covers the complete scoped local
collection and survives unrelated coordinator updates. Namespace source-content
identity triggers rereads only when that namespace changes. Payload sizing is
deferred until visible item details open and is memoized for that content version.
Item details show its stored identity, logical payload bytes and last fetch time;
these persisted rows exclude queued-only edits. Account/workspace changes and loss
of module access immediately remove the list and its expanded details.
Regression coverage: `offline_module_page_test.dart` verifies item search, scoped
isolation and permission redaction. Offline module detail pages offer stored-collection search, per-namespace
inventory, and the applicable existing Finance, Tasks, or Calendar preference.
Inventory has download, refresh, and eviction controls; it does not invent a new
module preference.

Available-item counts deduplicate persisted replica IDs within each namespace
across overlapping pages and snapshots. Ordinary successful reads count as well
as explicit downloads. Valid retained expired snapshots remain counted as
available offline, with expiry reported separately from freshness. Counts never
sum unrelated namespaces into a supposedly complete catalog. Server-reported query totals are displayed only when retained pages agree on
the query and total; otherwise expected totals are unknown. These totals never
establish complete download coverage. Pending-write coverage of server totals
is unknown; the pending count is shown separately. Sizes measure logical encrypted-store payloads
including snapshot and replica copies, excluding filesystem overhead. Expected
download sizes and transferred network bytes are unknown.

Module data is scoped to the selected account and workspace. Inventory details
require current workspace access, and unavailable modules show no stored-data
inventory. Removing a module's data clears only its scoped namespace resources,
preserving every queued write and other module/account/workspace snapshot. Cache
removal in Offline preferences also uses the selected scope; the cache quota
remains device-wide and can be changed by a signed-in user without a selected
workspace. Scoped usage and clearing require a workspace; no cross-workspace
usage is shown when none is selected. Scope changes cancel open cache preference
sheets. Eviction and quota controls disable reactively while an explicit download
is running. Stored corrupt JSON payloads still count toward storage and can be
cleared, while they never count as available offline items.

Pause cancels subsequent download steps. Resume retries unfinished modules while
skipping modules verified ready in the current session. It restarts a module's
supported collection download; it does not promise byte-level continuation.
Across launches, retained timestamps are historical evidence and never alone
establish readiness. Cache removals during a download or its final retention
checks are retained until completion: affected products return to queued status,
while unrelated products can finish. Successful product downloads supersede their own reconciliation removals;
final retention checks and later removals still revoke readiness. The next
explicit retry must verify removed dependencies again. Cache removal notifications retain only scoped
identity with an event-only opaque key digest, never the removed response payload
or literal query/search parameters. Persisted cache keys remain unchanged. A corrupt stored response is treated
as missing and still attempts network revalidation; account switches and explicit
cache clearing continue to fence that response. Inventory product details permit
pending-item fallback only for typed transport failures. Invalid response bodies,
session failures, and unknown status-zero errors surface instead.
Regression coverage: `offline_preparation_coordinator_test.dart`,
`cache_revalidation_corruption_test.dart`, and `inventory_repository_test.dart`. Explicit downloads continue to use the existing bounded
Finance, Inventory, Tasks, and Calendar collections; neither these pages nor a
Ready label promise all server data or every attachment.

Timezone reads and writes both pin their authenticated account. Automatic timezone
preferences persist even if native timezone lookup fails; unresolved effective
timezone and actual load/save errors remain visible, with wrapping text and retry.
These settings use the production mobile-calendar gateway and existing Bearer
renewal/retry behavior; no backend route or production state changes are included.

Regression evidence: `test/core/cache/offline_cache_inventory_test.dart`,
`test/core/cache/offline_preparation_coordinator_test.dart`,
`test/features/settings/cubit/timezone_settings_cubit_test.dart`, and
`test/data/repositories/timezone_settings_http_contract_test.dart` under
`apps/mobile`. Widget tests are source-level evidence; native airplane-mode and
installed-client behavior require a new exact-source CI artifact and separate
runtime verification.

## Native Assistant prompt and navigation

On the mobile Assistant text-chat surface, opening the prompt collapses the
actual floating shell navigation into the right-hand hamburger toggle. The
single-row prompt occupies the remaining width: plus menu, chat field, and
microphone action. Text or attachments replace the microphone with Send. The
plus menu holds attachment previews and removal, model selection, thinking mode,
and the credit-source sheet, including its existing balance/error/retry behavior.
Model selection remains constrained by the active credit source's allowlist.

The hamburger expands the existing navigation above the prompt and dismisses
the keyboard. Closing the prompt restores normal navigation. Android back first
collapses expanded navigation, then closes the prompt. Tab changes hide the
prompt while retaining its unsent text and attachments; workspace changes and
the existing account session boundary reset the draft to prevent scope leakage.
The legacy fullscreen button is removed. Explicit Live entry, voice recording,
camera controls, permissions, and session persistence keep their existing rules.
Other shell screens retain their shared keyboard-hide navigation policy.

Regression coverage: `assistant_composer_dock_test.dart` checks the 320px layout,
large text, single-row actions, attachment removal, restoring state and blank
submission; `assistant_composer_options_test.dart` checks adaptive model selection
and credit allowlists; `assistant_chrome_cubit_test.dart` covers presentation reset;
`shell_assistant_composer_test.dart` checks actual dock collapse, restoration,
back handling, mounted shell continuity, retained tab drafts and workspace reset
across the active floating dock at phone/tablet/desktop widths (the legacy compact
footer is disabled). `assistant_composer_geometry_test.dart` checks the rendered
scroll action clears the composer with safe-area insets, large text and keyboard
visibility; both exclude physical bottom padding while the keyboard is visible.
Widget coverage does not establish
physical-device microphone, provider, camera, or production behavior.

## Native onboarding and brand introduction

The first-run and replay guide introduces Tuturuuu and Mira alongside Tasks,
Calendar, Finance, and Inventory. Native gradient surfaces and brand assets provide
visual context; tool labels describe existing surfaces rather than enabling access
or promising automatic actions. Role and goal selection remain optional local
recommendation preferences, not permissions or subscription changes.

The four-page guide keeps the existing completion flag, role and goal preferences,
login destination, and replay return behavior. Skip completes the same guide.
Content scrolls independently of its primary action, including on small screens
and with enlarged text. Light and dark themes retain solid readable controls.
Reduced-motion settings remove animated page, progress, and background transitions;
there is no continuous animation. This introduction is a full-screen flow outside
the consolidated shell and does not add a nested shell navbar.

Regression evidence: `apps/mobile/test/features/onboarding/onboarding_page_test.dart`
covers progression, preferences, skip, replay, and compact enlarged-text layouts.

### Cache recovery and explicit quote refresh

Mobile cache publication journals retain prior snapshots for stale-while-revalidate
rollback. Eviction and authoritative completed-download reconciliation instead
persist a scoped deletion intent without copying removed payloads or replica rows.
After interruption, recovery completes those deletions and preserves unrelated
scopes and pending writes; it does not restore evicted or obsolete data. Journal
completion batches the entity-log flush after affected snapshot/outbox flushes.
Regression evidence: `cache_store_publication_test.dart`.

Inventory manual season-quote refresh waits for an automatic refresh, then performs
an unthrottled fresh request in the same actor/workspace/period scope. Other
concurrent callers still coalesce; a scope change cancels the queued refresh.
Regression evidence: `season_pricing_controller_test.dart`.

### Challenges and shared cached reads

Shared mobile JSON object/list reads retain the last encrypted authorized snapshot
when revalidation requires `MFA_REQUIRED` or a typed verification challenge.
The request still rejects with the challenge, allowing the owning screen to request
verification; retained cache does not authorize a write or bypass server checks.
Rate limits and server availability failures likewise leave the stored snapshot
intact. Definitive same-account 401/403 responses erase the snapshot and replica
projection durably. Purge admission rechecks the request actor, so a departed
account's delayed denial cannot erase a newer authorized publication.

Regression evidence: `offline_read_through_access_test.dart` verifies both payload
shapes, reopening encrypted storage after retention/denial, and a delayed denial
across an account change.

### Snapshot invalidation and private search

A concurrent tag invalidation rejects the new response but retains the previous
authorized snapshot as stale, including its replica rows. Account/workspace clears
and actor changes still erase it. Offline search patterns are compiled per call
once per Finance/Inventory collection scan and retained only by that caller; no application-owned global raw query cache
survives logout. A queued sale-period assignment retains its period ID when period
metadata is evicted, with unknown metadata distinct from an explicit null removal.
Regression coverage: `cache_store_publication_test.dart`, `local_search_test.dart`,
and `inventory_sale_period_projection_test.dart`.

Finance replica merging treats a newer server `[CONFIDENTIAL]` description as an
authorization barrier regardless of detail authority: older plaintext cannot
appear in offline lists/search or merged JSON. A newer authorized response may
restore that field even from a list after an older redacted detail. Amount and
category permission nulls (with their server confidentiality flags) likewise yield
to newer explicit authorized values, while ordinary detail clears and sparse-field
authority remain unchanged. Newer explicit null still clears the field. This projection rule is covered
by `cache_replica_policy_test.dart` and `finance_inventory_offline_test.dart`.

Direct transaction detail refresh also routes transport fallback through merged
replica rows rather than an older raw detail snapshot, even during awaited
revalidation. Authentication/MFA errors still propagate. Other read-through
callers retain their existing awaited transport fallback default. Covered by
`finance_review_regressions_test.dart`.

Transaction detail fallback reads merged replicas after the failed request or
offline connectivity decision, rather than returning rows captured before it.
A redaction arriving while a request waits therefore takes effect immediately;
the captured actor is checked after the fallback read. Concurrency regressions
live in `finance_review_regressions_test.dart`.

Pending Mail and workspace-secret reads fall back only for typed transport
failures; local response/session errors remain visible even with queued edits.
Tag invalidation advances stored resource revisions as well as active flights,
so completed futures in the same refresh cycle cannot replay a pre-mutation
response. Queued manual season refresh is also bound to the generation, preventing
A-to-B-to-A scope changes from resuming an old continuation. Regression coverage:
`mail_repository_test.dart`, `workspace_secrets_repository_test.dart`,
`cache_revalidation_test.dart`, and `season_pricing_controller_test.dart`.

### CMS actor-bound repository reads and edits

CMS repositories created for a signed-in actor bind cached summary, collection,
and entry reads to that actor. Pending edits are overlaid only for their owner;
an account change during queue access rejects the old read. CMS writes carry the
same actor into offline admission, and invalidation targets that actor's workspace
cache. Unbound legacy callers resolve the current actor for pending overlays and
never display anonymous or another account's pending edits. This foundation does
not grant CMS permissions or replace API authorization.

Regression evidence: `cms_actor_scope_test.dart` exercises collection and entry
overlays, delayed queue completion after account switching, and obsolete reads
and writes. The native CMS screen and device verification remain separate work.

### CMS native library and editing

The mobile CMS surface owns one signed-in actor and workspace. Its library uses
lazy rows, collection/status filters, and local search published into the single
shell dock. Search covers the loaded CMS collection/entry response; it does not
claim server pagination or full-text search beyond that response. Re-entry
publishes stored scoped content and awaits background revalidation; explicit
refresh waits for the current cycle. Same-actor temporary failures and MFA
challenges retain content, while definitive denial clears it. Switching actor or
workspace discards the previous surface and closes its owned editing routes.
Editors keep drafts and inline errors until a save succeeds, permitting explicit
retry without silently replaying an uncertain write.

Regression coverage: `cms_workspace_test.dart` exercises lazy 500-row rendering,
shared dock search, stale-scope responses, denied versus challenged refreshes,
retained failed-save drafts, and actor-owned editor dismissal beneath an
unrelated modal. Cleanup schedules a frame even when the covered route is
settled; it removes that editor alone and preserves the covering modal.

Timer also remounts its native host for each authentication transition, including batched logout and login to the same account. A preference read owned by the disposed host cannot prevent the new host from loading or resume its previous request. The actual-host deferred preference regression covers this liveness boundary independently of Timer load-publication fences.

### Native Chat account lifetime

The native Chat root owns a new host and cubit for each signed-in actor, even
when the workspace ID stays unchanged. An actor-transition generation also
replaces the host when logout and same-account login occur before a frame
renders. Search, selected conversations, drafts,
and retained messages belong to that host. Closing invalidates asynchronous
callbacks before subscription cancellation finishes; actor and cache-resource
lifetime checks also fence delayed results. This preserves the existing shared
shell dock and API-backed workspace chat behavior. The actual host account-switch
and delayed-cancellation regressions are in `chat_actor_lifetime_test.dart`.

Chat rejects retained-cubit API dispatch after its actor lifetime ends. A send waiting for previous stream cancellation rechecks actor, workspace and selected conversation before starting a new request; stale conversation creation results do not trigger selection reads or return a navigable result. Already dispatched server writes are not cancelled by this client boundary. Deferred cancellation and creation regressions cover these rules.

### Delivered inbox identity foundation

Standard persisted notification pushes carry a versioned `inboxIdentity` capsule
from the recipient account, actual inbox workspace column (explicit null for
personal), and notification row ID. Android receives the same full identity as
its notification tag. This is an encoded identity, not encryption or an action
authorization token. Display/navigation metadata cannot change its owner or scope;
a personal inbox invite can still navigate to a shared workspace.

Custom/MFA pushes strip the reserved `inboxIdentity` data field and receive no
owned inbox tag; other custom metadata remains unchanged. Legacy rows
without valid recipient/workspace/notification identity remain unqualified; they
must not be bulk dismissed by guessing their owner. Existing Mail navigation is
preserved without promoting its legacy metadata into trusted inbox identity.
`push-inbox-identity.test.ts` covers the actual payload constructor and outgoing
transport with a fake Firebase client, including same-ID foreign scopes,
personal/navigation separation and legacy/custom exclusions.

This packet provides identity only. Mobile delivered-only removal and read-action
integration remain separate; it does not clear an OS tray or cancel future task
and calendar reminders. Source tests are not device proof. A future delivery
receipt must record the actual TestFlight version/build and verify foreground
and background single/all-read dismissal while foreign scopes, later arrivals,
and pending reminders survive. The reported 0.23.4 build number remains unknown.

### Delivered-only native bridge

The mobile bridge binds to the current account session, snapshots delivered inbox
notifications, and removes only still-matching captured deliveries. A null inbox
workspace selector means all inbox scopes available to that actor, matching the
existing bulk-read API; an explicit workspace selector is narrower. Missing or
malformed ownership capsules remain untouched. Foreground and data-only background
local notifications preserve the same capsule as standard remote pushes.

Android uses app-owned active notification tag/ID/post time; iOS uses delivered
request identifier/delivery date and remote or local capsule metadata. Account
session changes invalidate outstanding snapshots, including logout/relogin ABA.
Enumeration beyond 512 delivered records or eight retained snapshots fails closed.
A discard operation releases a snapshot without removing notifications. Neither
platform bridge calls pending-notification or alarm cancellation APIs.

The native platforms offer no atomic timestamp-conditioned removal. Rechecking
captured identity and delivery time protects replacements already visible during
the recheck, but a replacement racing between recheck and OS removal remains a
platform limitation. Returned counts mean matched removal requests submitted,
not verified tray disappearance. Read-action integration is a separate packet;
this bridge alone does not dismiss notifications when marking them read.

Dart MethodChannel tests cover actor/session ABA, held callbacks, strict receipts,
scope selection, malformed capsules and metadata round trips using fake native
transport. Native compilation and actual TestFlight foreground/background tray
behavior remain separate required evidence. Future scheduled task/calendar
reminders must survive single/all-read cleanup. Record the actual version and
build number for device feedback; source tests do not identify a delivered build.

Push-service session start/stop/dispose also invalidate a sticky lifetime epoch.
A start held in native binding, initialization, token lookup or device-ID lookup
cannot continue into registration or pending-navigation dispatch after departure,
including a same-account logout/relogin. The registration helper rechecks its
captured lifetime before writing, and disposal closes initialization/navigation
admission. Already dispatched transport writes cannot be undone by this boundary.
`push_service_session_lifetime_test.dart` exercises actual service methods and the
actual registration helper with injected platform/token/device transport.

### Calendar viewport and adjacent timed-card geometry

Mobile Day, Three-day and Week timelines keep isolated back-to-back events at
full available width. Half-open timestamp components identify genuine overlap;
an isolated card's readable minimum is capped at the next disjoint start, and
paint and column assignment use that same extent. Tiny capped cards clip their
visual content, retain full title/time button semantics and do not extend their
hit area into the next event. Genuine simultaneous/transitive overlap clusters
retain readable minimum heights and physical conflict columns; a timestamp-
disjoint successor can still share columns with that readable cluster.

Shared Day, Three-day and Week strips size spans intersecting the viewport.
Chip insets and offscreen events reserve no rows or expand control.
Row and control heights transition together over 180ms and retarget from their
current geometry. Whole rows and controls appear only when they fit, preserving
scaled text and viewport-clamped labels. The header stays fixed; the timed grid
moves with the strip while keeping its minute offset. Reduced motion places
geometry immediately, including interruptions. A scope change resets the
transition. Data refreshes retain current authorized content and date anchors.
The all-day scroller retains its identity and attaches at the grid offset.
Recentring updates dates and horizontal offsets before paint; scoped civil-date
keys retain day cells. Pixel scroll rebuilds only the strip. Initial time
positioning, week-start and date reselect keep their existing behavior.

`calendar_three_day_geometry_test.dart` and `calendar_all_day_transition_test.dart`
cover painted drags, data updates, retargets, text scale, themes, taps and scopes.
Existing overlap tests remain. CI and installed-device checks remain separate;
widget geometry does not establish TestFlight identity or frame-time impact.

### Reading inbox notifications and the system tray

Mobile reads capture a bounded snapshot of actual delivered notifications before
accepting the read. Single reads match the current actor and notification ID;
workspace bulk reads match that workspace, while the personal/all-workspaces
inbox follows the existing API's actor-wide bulk scope. This is independent of
the visible 20-row feed. Unread transitions never dismiss notifications.

Only the captured, still-current session can request delivered-item removal.
Mounted read controls suppress stale cleanup and refresh after account/workspace
changes or route disposal. The opened-item helper follows its actor-bound ID
across intentional navigation and rechecks that actor/native lifetime before
publishing a refresh; logout/relogin invalidates both paths. Captured native
tags/identifiers and delivery timestamps
retain later arrivals and replacements. Pending scheduled reminders are never
cancelled. Legacy deliveries without trusted identity remain untouched.

A repository read may be a durable offline intent, rather than a confirmed server
write. Cleanup failure preserves that acceptance and shows a localized warning;
it does not retry the read. Failed reads discard their snapshot without removing
OS items. A later inbox or badge refresh failure similarly preserves accepted
read state and shows the localized refresh warning. Mutation refreshes consume
explicit per-operation success receipts, including ordinary transport exceptions;
background badge/feed helpers retain their nonthrowing behavior and badge calls
still share one in-flight request. When cleanup and refresh both fail, the tray
cleanup warning takes precedence; the accepted read is never resubmitted.
The delivered-only bridge is applicable to native Android and iOS. Web, Windows,
Linux and macOS retain actor/session fencing but do not attempt this unregistered
channel or show an unavailable-cleanup warning solely for its absence. Failed
binding or a missing channel on Android/iOS still produces that warning. Web
capability-policy tests are not browser compilation or OS runtime evidence.
The platform APIs still cannot atomically compare and delete an OS item; the
previously documented last-moment replacement race remains.

Regression evidence uses actual mounted inbox actions, the real Cubit and opened
notification helper with fake repository/platform transports, including scope
ABA and rejection controls. It is not device evidence. Delivery requires exact
native CI and a recorded TestFlight version/build/source SHA: foreground and
background single/bulk reads must clear only matching delivered tray items while
other actors, out-of-scope workspaces, later deliveries and future reminders
survive.

### Notification post-write feed refresh

Notification read actions invalidate any pre-write feed response before awaiting
its completion, then request a fresh feed after the accepted write. Loading is
not treated as a failed refresh. Queued continuations retain actor/workspace
lifecycle admission. Held pre-write pagination is fenced by the same tab
generation on both success and error, so it cannot restore captured unread items.
An abandoned scope cannot publish or start a replacement
request. Ordinary background requests coalesce without throwing; a failed fresh
request reports the existing safe refresh warning and can be retried without
resubmitting the accepted read. Regression coverage: `notification_read_held_feed_test.dart`.

### Assistant Settings Above the Shell

The central Assistant settings entry and Mira quick settings open the same framed
editor above the shell. Its single heading and Back action cover the underlying
shell chrome; other scoped settings routes retain their existing routing. Captured
account/workspace providers and sticky scope invalidation remain in force, so a
held preference load cannot restore an editor after an account/workspace switch,
including switching away and back. Large-text content scrolls above the frame's
Back action. Real shell regressions cover English/Vietnamese, narrow screens,
large text, Back restoration, actionable switch clearance and held-load scope
transitions. Both current-route cancellation and removal below an unrelated
covering route are exercised, with sticky rejection after account/workspace ABA
and after the held preference completes. Regression coverage:
`settings_assistant_shell_checks.dart`, registered by
`settings_compact_navigation_test.dart`. This source fix
does not claim native TestFlight delivery or establish the original screenshot's
exact installed build.

### Workspace Secrets Settings Heading

The mobile workspace Secrets detail uses the shared shell title and Back action.
Its summary panel retains the workspace description, icon, status counts and
explicit create action without repeating the page heading. Permission checks and
content/dock padding are unchanged. Actual-shell regression coverage in
`settings_secrets_shell_checks.dart` checks English/Vietnamese, narrow layouts and
large text, including denial visibility and dock Back. This scoped correction
does not establish the cause of the reported Assistant Settings TestFlight issue.

# Native Calendar preferences
Source: https://docs.tuturuuu.com/platform/features/native-calendar-preferences

Web ownership, authorization and protection for native timezone settings.

Personal calendar preferences are scoped to the authenticated user. Settings
updates accept supported IANA timezone names or `auto` inheritance; invalid
names and fixed-offset strings are rejected before storage. Workspace
calendar settings are readable by members, but updates require
`manage_workspace_settings`. Check that permission explicitly on the owning
PATCH route: a verified signed app session can use an admin-backed database
client, so membership and table RLS alone do not enforce editing rights.

Native personal/workspace preference GET/PATCH requests default to Web at
`tuturuuu.com` for `/api/v1/users/calendar-settings` and
`/api/v1/workspaces/:wsId/calendar-settings`. This product decision applies to
mobile Settings > Calendar & timezone and all native consumers of those
preferences. Web serves these routes locally with no Calendar rewrite; Calendar
and Web use shared settings logic with identity injected by each adapter.
Supabase Bearer verification, MFA, membership, `manage_workspace_settings`, value
validation, dedicated preference quotas, IP blocks and diagnostic headers remain
required. Existing environment origin overrides remain supported.

Intentional exceptions: existing Calendar browser/app-session clients retain
Calendar's routes, published older mobile builds retain Infrastructure's gateway
allowlist, and other native Calendar APIs keep their gateway routing. Retaining
the gateway requires its private-credential hosting exception until those builds
are retired. New mobile preferences do not require Turnstile or a WebView by default.
Optional Apple App Attest and Android Play Integrity use a server mode defaulting
to `off`. `monitor` verifies available proofs and records scalar verdicts without
blocking existing auth/MFA/quota/permission controls. Turnstile is a bot-abuse
speed bump, not native attestation; it is separately disabled by default and
requires operator-owned unsupported-actor eligibility. Live Apple or verified
Play capability bars that downgrade while native proofs remain valid across an
actor's devices. Headers and User-Agent claims cannot grant eligibility.

`enforce` stays inactive pending provider/device/fallback and older-client
acceptance. The guard also covers existing Web browser/server consumers without
proofs; their proof coverage or a separately reviewed trusted-browser policy is
mandatory before activation. Missing headers never grant an exemption. Proofs
never replace workspace authorization or hosting clearance. See the
[native integrity rollout](/build/devops/calendar-native-api-protection#native-integrity-rollout-default-off)
for exact configuration, capacity, retention/deletion and rollback gates.
The [regression inventory](/build/devops/calendar-native-api-protection#regression-evidence)
links shared-domain, Web auth/guard/header, rewrite ownership and Flutter origin
coverage for this decision; provider configuration and device acceptance are
separate release evidence.

Native preference GETs and PATCHes use the actor already verified by the shared MFA guard, without another authentication request. Their quota must not depend on a warm session
trust cache: a cold/rotated credential previously fell into the shared anonymous IP bucket
and could receive 429 before Calendar authenticated it. Actor keys also survive token rotation. The exact preference routes use a dedicated bucket, separate from unrelated gateway traffic. Personal/workspace GETs share 600/minute, 6,000/hour, 40,000/day by default; saves share
60/minute, 300/hour, 2,000/day. Anonymous IP limits and existing overrides remain unchanged.
MFA, IP blocks, downstream authentication and workspace permissions remain enforced.
`api-proxy-calendar-preference-reads.test.ts` covers a cold-cache Settings open after shared-IP
exhaustion, forged credentials, MFA rejection, actor isolation and rotation; the mutation
regression covers independent bounded save budgets. Fixtures use the real shared guard/MFA
adapter with synthetic provider/quota boundaries. `preference-guard.test.ts` checks route
boundaries; `gateway.test.ts` checks upstream diagnostics. Mobile makes one personal and one
workspace GET on scope mount; tile rebuilds do not load. `timezone_resolution_scope_test.dart`
covers request counts, rebuilds and cooldown. English/Vietnamese notices retain Retry-After
and known safe limiter details, without private bodies or arbitrary headers. Retry is explicit
and preserves the timezone/endpoint (`timezone_settings_http_widget_test.dart`).
See [Native Calendar API protection](/build/devops/calendar-native-api-protection) for the full limiter inventory,
read-only WAF policy audit, exact operator items and native attestation design. An unclassified device 429 does not prove the cold-cache mechanism.
Correlate owning host/path and safe metadata; never log credentials, bodies, actor/workspace IDs or IPs here.

## Mira assistant timezone

Mira's date-aware tools (tasks, calendar, scheduling, time tracking) resolve the
user's timezone in this order:

1. A valid IANA timezone sent by the client with the request.
2. The saved personal preference.
3. The workspace preference.

`auto`, invalid names, and failed preference reads fall through to the next
step. If nothing resolves, the executors keep their existing UTC fallback. The
order applies to Web chat and to mobile chat through the native
`/chat/conversations/:id/messages` route, which accepts an optional `timezone`
and forwards it to the shared AI chat route.

Mobile sends the verified device timezone only for Mira sends. An unverified
lookup is omitted instead of being sent as `UTC`, so the saved preference still
applies. Previously the native route dropped the timezone, so mobile Mira
treated "today" and "9am" as UTC.

Regression coverage: `packages/ai/src/chat/google/mira-timezone.test.ts`,
`route-mira-runtime.test.ts`, the native messages `route.test.ts`, and
`apps/mobile/test/features/chat/data/chat_mira_timezone_test.dart`.

# Native recurring Calendar events
Source: https://docs.tuturuuu.com/platform/features/native-calendar-recurrence

Create and edit canonical recurring events with explicit scopes.

Calendar and the integrated Tasks Calendar offer **Recurring event** in Create.
It saves to canonical Tuturuuu Calendar. Daily, weekly, monthly and yearly rules
support an interval and no end, an occurrence count, or an inclusive end date.
Monthly and yearly rules offer an absolute day or the first, second, third, fourth
or last selected weekdays; yearly rules also select a month. Absolute month days
can skip missing dates or use the month's last day. Choose a named time zone: local
wall-clock times remain stable across DST.
Nonexistent spring-forward slots are skipped; repeated fall-back times use the
earlier instant. All-day end dates are exclusive midnight boundaries.

Expansion visits at most 36,600 local dates from the anchor, including history
needed to preserve counts and exception identities. Uncounted rules reject an
oversized effective range before generating occurrences; an inclusive end date
caps that range, while count rules may finish earlier and keep the same scan
limit. Far-away original exception slots also contribute to the effective range.
`calendar-recurrence.test.ts` covers early rejection and count/end-date behavior.

Generated occurrences open a dedicated editor. **Only this occurrence**,
**Entire series**, and **This and following occurrences** are explicit choices,
defaulting to this occurrence. Requests preserve its immutable original slot and
use the loaded series revision. Concurrent changes require an explicit reload.
Whole-series editing uses the original anchor; future count rules retain remaining
slots. Relative-weekday patterns can be edited, while details-only edits preserve
imported week boundaries and month-end behavior. The anchor must remain an actual
first occurrence; invalid changes are rejected rather than silently shifting it.

Virtual occurrences never use ordinary event CRUD or drag mutation APIs. Dragging
and resizing are disabled; use the scoped editor to move an occurrence. Native
ranges revalidate in the background, retaining same-actor data through transport,
throttling and temporary failures. Definitive access denial clears retained data.
Reads and writes use verified actor lifetimes and separate workspace cache keys.
Unchanged failed write intents reuse idempotency keys. Reopening or changing the
workspace/account resets form state.

Native Create defaults to canonical Tuturuuu Calendar. The connected-calendar
editor below remains gated by provider admission and verified source capabilities;
production admission is disabled until authenticated provider parity is proven.

Regression evidence: `native-recurrence-model.test.ts` covers DST, validation,
all-day boundaries, original identities, remaining counts and retry intent IDs;
`native-recurrence-dialog.test.tsx` covers forms, permission and reset behavior;
`native-recurrence-pattern-model.test.ts` and
`native-recurrence-pattern-fields.test.tsx` cover relative weekday, yearly month,
month-end and imported-rule preservation against Google and Outlook serializers;
`use-native-calendar-occurrences.test.tsx` covers SWR and actor/permission fences;
`use-calendar-readonly.test.tsx` proves virtual mutations cannot reach ordinary
write APIs.

## Unsupported provider rules

When the provider recurrence pilot is enabled, a complete, stable Google or
Outlook snapshot with an unsupported rule becomes **read-only**. The exact raw
master and exceptions are retained in an actor/source-bound encrypted journal;
no approximate native rule is created. Calendar and integrated Tasks Calendar
show a read-only badge and direct the user to the original calendar. Ordinary
writes and scoped provider writes check authoritative private state, including
when a delayed import loses its visible metadata marker.

A previously supported canonical series is hidden rather than left visible with
outdated dates. A subsequent supported snapshot restores the same series identity
and removes verified legacy duplicates atomically. Publication compares both the captured master ETag and observation hash, so
separately edited exceptions cannot overwrite a newer observation. Pending
canonical or ordinary provider operations defer this transition; database admission rejects new legacy
operations after the read-only state is published. Other calendars and unmatched
provider identities remain untouched.

The provider mutation pilot remains disabled by default. These checks do not
establish authenticated Google/Outlook write parity or enable provider editing in
the native creation dialog. Rollout still requires provider runtime verification.
Regression evidence: `calendar-provider-readonly.sql`, provider inbound snapshot
and service tests, `readonly.test.ts`, and `calendar-provider-readonly.test.ts`.

## Recoverable connected-calendar editor

The shared Calendar recurrence editor checks actor-scoped provider capabilities
before offering Google or Outlook calendars. Admission remains disabled by
production default. An offered connection must belong to the current actor,
have active credentials and outbound sync, an explicit writable provider role,
and an enabled linked workspace calendar. These configuration capabilities do
not prove provider access; each mutation still rechecks credentials and the
fresh provider master.

Imported provider series always use the provider operation API, including
this-occurrence, entire-series and future changes. They never fall back to native
series writes. Disabled admission, missing ownership or uncertain capabilities
makes the imported series read-only. Native Tuturuuu series retain the native API.

Pending provider changes keep fields frozen and expose a continue-synchronization
action. The actor/workspace-scoped query cache retains the original intent; only
its operation UUID is written to tab-scoped session storage before dispatch.
No event content, tokens or account details are persisted there. Refreshing or
reopening the dialog resumes that same UUID, and only an applied receipt closes
the dialog and invalidates Calendar data. Applied provider receipts also revalidate
the affected workspace’s database and provider event projections, including
a creation resumed after a reload; pending receipts leave those views intact. If session storage is unavailable,
new provider writes fail before dispatch. Cross-device operation history is not
provided by this editor. Provider write admission still requires authenticated
Google and Outlook parity evidence before production enablement.

Regression coverage: provider `capabilities.test.ts`, operation-route tests,
`native-recurrence-provider-routing.test.tsx` and
`use-provider-recurrence-operation.test.tsx` cover source permissions, native
fallback exclusion, ambiguous responses, dialog dismissal, tab reload recovery
and actor separation.

### Fresh conferences on future splits

New Google/Outlook future-update plans create the replacement series before
trimming the original. Provider creation is checkpointed only after a fresh
conference identity is available. Original join links and Google conference
signatures are never cloned into the replacement: Google Meet uses a stable
operation-derived `createRequest`; Outlook selects the original supported meeting
provider only when the destination calendar explicitly permits it. Pending or
failed conference generation preserves the untrimmed original and remains in the
recoverable operation flow. Google regeneration uses at most two additional
request identities on the same replacement event; an exhausted budget remains
blocked for support, with no original-series trim.

The database binds checkpoint roles atomically: the created replacement receipt
belongs to the new canonical series, and the trim receipt advances the original
binding. Older persisted trim-first plans retain their original order and receipt
selection. New unsupported provider metadata, including Outlook attachments, remains rejected before reservation. A copied body or description
that embeds the original meeting link is also rejected; generated meeting HTML
blobs are not stripped or copied with stale credentials. Preflight detects raw,
HTML character-reference and percent-encoded prior join identities; unrelated
malformed percent escapes cannot suppress detection. Raw string values and parsed
URL comparison also cover browser-normalized control characters, backslashes,
protocol-relative links and dot segments. This follows the
[URL parsing contract](https://url.spec.whatwg.org/#concept-basic-url-parser). The original body remains
unchanged, including benign encoded content; detection rejects the operation
rather than sanitizing it. `conference.test.ts` and `future-admission.test.ts`
cover encoded-link rejection before any plan reservation. Character references
follow the [HTML syntax contract](https://html.spec.whatwg.org/multipage/syntax.html#character-references). Production provider mutation
admission stays disabled until authenticated provider and deployment evidence is
complete; these tests do not constitute that evidence.

Coverage: `conference.test.ts`, `writer.test.ts`, `plan.test.ts`, and
`apps/database/supabase/tests/calendar-provider-series.sql`. Provider contracts:
[Google conference creation](https://developers.google.com/workspace/calendar/api/guides/create-events)
and [Outlook calendar online meetings](https://learn.microsoft.com/en-us/graph/outlook-calendar-online-meetings).

### Calendar settings workspace identity

Calendar settings resolves route aliases such as `personal` before mounting
integration sync or hours/timezone consumers. These consumers and their caches use
the resolved workspace ID; resolution failures do not dispatch alias requests to
UUID-only Calendar APIs. This applies to the standalone Calendar settings shell.
Regression coverage: `apps/calendar/src/components/settings/settings-dialog.test.tsx`.

### Truthful storage hints

The shared recurrence editor shows its native-storage hint only for canonical
native events and native creation. Connected Google/Outlook editing or selected
provider creation suppresses that hint, including when provider capabilities are
unavailable. This display decision does not change source permissions, admission
or the prohibition on native write fallback for provider events. Coverage:
`native-recurrence-provider-routing.test.tsx` renders the actual recurrence fields
for native, Google, Outlook and disabled-provider cases.

### Outlook attendee privacy on future tails

For a verified organizing source, future splits retain the source's explicit
`hideAttendees` setting only when the fresh master supplies its attendee list.
The encrypted plan carries this field without attendee
response statuses. Creation and retained-event recovery both require an
authoritative matching privacy receipt before trimming the original series.
Non-organizers, malformed privacy settings and unsupported attachments remain
blocked. This is source parity, with production admission still disabled; it does
not prove invitation delivery or authenticated Outlook behavior.

Graph v1 reference attachments expose read/delete metadata without a documented
reference-creation/source-URL contract. Tuturuuu therefore does not copy attachment
bytes or invent attachment references when splitting an Outlook series.
Regression coverage: provider `create-metadata.test.ts` and `writer.test.ts`.
Contract: [Graph event attendee privacy](https://learn.microsoft.com/en-us/graph/api/resources/event?view=graph-rest-1.0)
and [Graph reference attachments](https://learn.microsoft.com/en-us/graph/api/resources/referenceattachment?view=graph-rest-1.0).

### Future edit resets

Editing this and following occurrences starts a replacement tail and resets its
previous moved, edited and cancelled exceptions. Native and connected-calendar
editors show this consequence before Save. Selecting the first occurrence
normalizes to a whole-series edit and does not show the tail-reset notice;
single-occurrence and whole-series edits also omit it. The existing transaction preserves earlier
exceptions. This notice changes no provider admission or write behavior.
Regression coverage: `native-recurrence-dialog.test.tsx` checks notice visibility
and preserves the original scope/revision/boundary submission assertions.

### Single Calendar settings host

One dashboard-owned host mounts Calendar settings with the verified workspace ID.
Responsive account menus forward their query intent without mounting their own
settings providers. This prevents stacked inaccessible dialogs and duplicate
connection checks while preserving settings from collapsed, expanded and mobile
layouts. Settings content mounts only while the dialog is open. Provider accounts,
synchronization and mutation admission are unchanged. Coverage:
`settings-dialog-host.test.tsx` checks query intent, shortcut, close cleanup and
workspace scoping; existing `settings-dialog.test.tsx` retains alias resolution.

## Provider admission evidence

Production provider editing remains disabled by default. Source capabilities and
mocked provider receipts are configuration and regression evidence, not proof that
Google or Outlook accepted an operation or delivered invitations. Before admission,
record the exact deployed source and migration results, then verify each provider
with an authorized account and a dedicated test calendar:

* Create and reload a series through Tuturuuu and the provider; inspect provider
  master identity, timezone, all-day boundaries and the recurring dates.
* Edit and delete this occurrence, the whole series, and future occurrences;
  verify moved/cancelled original-slot identities, remaining counts, earlier
  exceptions, and the visible tail-reset warning.
* Change the provider series externally and reconcile it back without duplicates;
  verify a richer unsupported rule stays read-only rather than being approximated.
* Interrupt and resume an operation with the same persisted UUID; verify one
  provider result, correct source-bound receipt, and refreshed Calendar projections.
* For supported conference splits, verify a fresh meeting identity and preserved
  attendee/privacy metadata before the original tail is trimmed. Check organizer
  and recipient behavior separately; a mutation response does not prove delivery.
* Verify expired credentials, read-only calendars, revoked access and actor or
  workspace changes fail closed, with no native-write fallback or cross-actor data.

These checks have not been established by the focused source tests. Admission
must not imply unrestricted provider parity: Outlook attachment-bearing future
splits and bodies containing the prior conference's join credentials remain
unsupported and rejected before reservation. Tuturuuu neither clones attachment
bytes nor strips generated meeting HTML to bypass these limits. Special Google
event types and incomplete attendee snapshots also retain their explicit
preflight restrictions. Native Tuturuuu recurrence remains independently usable.

# Notes voice analysis
Source: https://docs.tuturuuu.com/platform/features/notes-voice-analysis

Private, metered voice transcripts and proposals with explicit retry controls.

The Notes voice API accepts a short native recording and returns an actor-owned
job. Native Notes exposes recording from its list, using the existing persistent
shell dock rather than mounting another navbar. Recording remains local until the
user pauses and explicitly chooses transcription/analysis, with a personal-credit
notice. Pause, resume, retake and cancel remain in the same dock; backgrounding
pauses recording, and account/workspace changes or leaving Notes discard unsent
recording bytes. Existing Notes editing and locking remain unchanged.

Completed results, including recordings with no detected speech, can open the
review sheet. A silent result explains that no speech was detected and offers no
saveable Note; Save remains disabled and no analysis is replayed automatically.

Completed results use a compact review sheet with transcript, summary, decisions,
proposed actions, recommendations and evidence. A successful transcript can also
be reviewed/saved if the later analysis has a known failure. **Save note to this
workspace** is explicit: private results become an ordinary workspace Note, which
may be visible to team members. Saving creates no task or event. The voice job UUID
is the stable Note ID, so retrying a save does not duplicate the note or overwrite
later user edits. Users can edit the saved note through the existing editor.

Only the stable job intent is persisted before dispatch, so navigation can recover
a submitted job without persisting its audio. The latest authorized job is cached
under its actor/workspace, shown immediately on return and revalidated even when
fresh. Transport, 429/5xx and MFA challenges
retain that scoped result; definitive access loss/not-found removes it. Old async
responses are fenced across account/workspace away-and-back transitions. Deleting a job disables new capture until the request completes. Definitive
DELETE access loss/not-found clears the scoped result; MFA and temporary failures
retain it. Cached result deletion rechecks ownership after initialization and queue admission; once
admitted, the serialized snapshot and index purge completes before new publication. Temporary
status failures offer explicit retry; ongoing successful status requests poll only
while Notes is active. In-memory recording bytes permit explicit safe preflight
retries using the same request ID/revision. After navigation discards those bytes,
users can retain a successful transcript or record again; paid uncertain jobs
never automatically restart.

Input is mono 16 kHz PCM16 WAV, at most 120 seconds. The server verifies actual
frames and bounds streamed multipart bytes rather than trusting a claimed duration.
Audio bytes are transient and are not stored in job rows or billing metadata.

Transcription and structured analysis use the requesting user's personal AI
credits. Results include a transcript, summary, supported decisions, action items,
recommendations with evidence, and open questions. These are proposals for review;
the API creates no Notes documents, tasks, Calendar events, or room-shared artifacts.
Transcripts are untrusted input, including spoken instructions. Unknown owners and
deadlines remain unspecified. Silence does not trigger a second analysis request.

Jobs and artifacts are private to the requesting actor, even in team workspaces.
Every status read, creation, retry, and deletion verifies current workspace access.
Definitive loss of access denies retained artifacts. Workspace/account deletion
cascades job deletion; completed or stopped jobs can be explicitly deleted through
the job endpoint. Processing jobs must finish or enter review before deletion.

A stable request ID plus audio/time-zone digest deduplicates creation. Changed
payloads conflict. Atomic revision claims prevent duplicate provider execution.
Known preflight failures require an explicit retry against the current revision;
a successful transcript is reused when only analysis needs retry. Provider or
settlement outcomes without reliable accounting enter **review required** rather
than being automatically replayed or assigned an invented charge/refund.

Processing runs in a bounded Next response-tail callback. Persisted status is
recoverable after client navigation; the callback is not a durable execution queue.
Interrupted or abandoned work is marked for review after its execution window.
Clients must not automatically resubmit review-required jobs.

Regression coverage: `notes-voice/audio.test.ts`, `jobs.test.ts`, `provider.test.ts`,
`request.test.ts`, the internal API client tests, and `note-voice-jobs.sql` cover
input limits, metering, actor isolation, revision/retry behavior and RLS. API routes
are first-class Next handlers tracked as Rust migration backlog. Native cubit,
repository and widget regressions cover owner transitions, retry intents, retained
snapshots, denied access, real recording controls, enlarged-text review and explicit
stable-ID saves. `notes_voice_host_review_test.dart` verifies that a silent
completed result reaches review through the actual host action while Save remains
disabled, and that uncertain jobs cannot enter review. `cache_store_scoped_removal_test.dart` covers obsolete deletions
waiting for initialization/admission and durable denied-history erasure. Device
microphone/provider execution and production deployment
remain separate runtime verification gates.

Definitive Notes voice access denials write a separate secure-storage revocation
marker before attempting encrypted-cache deletion. An unreadable or denied marker
blocks cached reads after restart even when the snapshot could not be erased.
Only a validated server response whose snapshot and replica index were durably
published can clear this marker; a local pending intent cannot authorize access.
MFA challenges retain the last authorized snapshot. If both independent storage
paths fail, the current process remains blocked and reports the original denial,
but durable revocation cannot be guaranteed while all persistence is unavailable.
Regression coverage: `notes_voice_revocation_test.dart` exercises real encrypted
cache failures/restart, failed publication, scoped ordering, and MFA retention.

## On-device text summaries

An open, unencrypted note can explicitly generate a short text summary using an
already installed Mira model. Notes verifies the catalog digest and device
capability before loading its own local inference session. This flow does not
download models, send note text to an AI service, or replace the server voice
transcription flow. It provides no offline speech recognition.

Generated text is a volatile preview. Appending requires explicit review and a
current actor, workspace, note selection and editor revision. Editing, navigation,
auth changes, locking or backgrounding invalidates the preview. Appending preserves
existing rich text and uses the ordinary Notes save queue. Offline acceptance means
local queue persistence, not server synchronization. The editor guard is not a
cross-device database compare-and-set. Unaccepted previews are not persisted.

Source and mocked widget tests do not establish real supported-device inference,
model quality, memory behavior or offline network isolation. Validate those on an
actual supported device with the pinned model digest before claiming device runtime
readiness.

# Notification access
Source: https://docs.tuturuuu.com/platform/features/notification-access

Who can see a notification, when email-addressed invitations are claimed, and what happens on account deletion.

Notifications are server-owned. Web, satellite and mobile clients read and update
them only through the notification API routes, which use the service role after
resolving the signed-in user. The `anon` and `authenticated` API roles hold no
privileges on `public.notifications`. The row-level policies are kept as defence
in depth.

## Who sees a notification

* A notification with a recipient account (`user_id`) is visible only to that
  account. Email is never matched on such rows, so later address changes or
  reuse of the address by another account do not expose it. New and updated
  rows do not keep a copy of the recipient's address; copies stored before this
  rule are inert and left for a separate batched cleanup.
* A row is addressed by email only while it is an **unclaimed workspace
  invitation** (`type = 'workspace_invite'` with no `user_id`). It is shown to
  the account whose **confirmed** address matches. Unconfirmed addresses never
  match.
* Addresses are stored trimmed and lowercased, and compared the same way.

## Claiming invitations

An unclaimed invitation is assigned to an account when:

* the account is created with an already-confirmed address (for example OAuth),
* the account confirms its address, or
* a confirmed account changes to a new confirmed address.

Only unclaimed invitation rows are claimed; rows that belong to another account
are never reassigned. `sync_my_notifications()` applies the same rule on demand
for the caller's confirmed address.

## Account deletion

Deleting a `public.users` row deletes that account's notifications instead of
leaving them without a recipient. The rollout migration removed rows left behind
by deleted accounts: recipient-less rows that were not invitations, and
recipient-less invitations with no pending email invite for that workspace and
address.

## Scope and exceptions

* Applies to every app that shows the notification inbox: web, satellites through
  the shared notification popover, and mobile through the API.
* The account email helper used by these checks, `public.get_current_user_email()`,
  resolves only the caller's own confirmed address.
* Delivery (email and push batches) is unchanged; batch rows keep the delivery
  address they need.
* Notifications are no longer published to Supabase Realtime; clients refresh
  through the API.

Regression coverage: `apps/database/supabase/tests/security-notification-email-access.sql`
and `apps/database/supabase/tests/security-user-email-helper.sql`, run by the
security database contract job (`apps/database/scripts/verify-security-egress-contract.mjs`).

# Living pitch deck
Source: https://docs.tuturuuu.com/platform/features/pitch-deck

Maintain the ecosystem vision, workforce prototype narrative, and public presentation.

The localized `/pitch` page is a 32-slide presentation about Tuturuuu's ecosystem,
workforce decision support, and long-term intelligent-partner vision. It is excluded
from search indexing. Existing product foundations, proposed pilot work, and
long-term research are explicitly distinguished; product availability varies.

## Present

Use arrows or previous/next controls to navigate. Home and End jump to the first
and final slides. Space toggles twelve-second autoplay. Playback pauses when the
browser tab is hidden, notes open, or the presenter navigates manually. The overview
lists every slide. Fullscreen shows a translated error when unavailable. Motion
and optional closing-slide confetti respect reduced-motion preferences.

Stable hashes such as `/pitch#workforce`, `/pitch#simulation`, and
`/vi/pitch#pricing` support sharing. Existing slide hashes remain valid after
reordering. Print renders every slide with landscape page breaks. Presenter notes
are included in the public payload: they are not a private channel. Never include
confidential opportunities, private partner briefs, or unpublished commitments.

The capacity sandbox is a deterministic, synthetic illustration. It multiplies
team size by available hours and compares that result with estimated weekly work.
It does not run an AI model, persist inputs, collect telemetry, or recommend staff
allocation. Its limitations and baseline are visible. Interaction tracking in the
pilot narrative describes proposed development, not tracking performed by this page.

## Evolve

Edit the `pitch` namespace in `apps/web/messages/en.json` and `vi.json`, then run
`bun i18n:sort` and format the owned locale files. Keep locale shapes aligned with
`PitchCopy`. Each slide has a chapter, headline, narrative, public presenter note,
maturity label, and visual panels. Stable identifiers live in `pitch-model.ts`.
The presentation uses official branding tokens through `pitch-brand.ts`; specialized
art and the synthetic simulation live in the adjacent components and CSS modules.

The pricing slide and subscription calculator use the same public catalog API as
the pricing page. They refresh every five minutes and show an unavailable state
instead of a fabricated fallback. Distinguish current prices from proposed
allowances, annual charges from monthly equivalents, and subscriptions from custom
prototype scope. The engagement slide presents a budget structure, not a quote.

Do not republish legacy traction, fundraising amounts, partner endorsements,
certifications, savings, or delivery dates without current supporting evidence.
Pilot timelines are indicative, require scoping, and are not delivery commitments.
Workforce decision support must retain transparent assumptions and human review;
it is not a promise of autonomous employment decisions.

## Verify

Run focused pitch tests, `bun validate`, and the real web build through
`ttr resources run`. Inspect both locales at desktop and mobile sizes, keyboard
navigation, deep links, overview, notes, simulation, reduced motion, and print.
Keep `/pitch` public in `apps/web/src/constants/public_paths.ts`. Route ownership
changes also require updating the TanStack migration manifest.

## Product scenes and company portfolio

The `/portfolio` route is the public company capability profile. It includes
interactive product illustrations, the shared application registry, engineering
capabilities, and open research collaboration directions. Both English and
Vietnamese content live in the `portfolio` and `capabilities` message namespaces.

Keep the app directory derived from `LAUNCHABLE_APPS`; every registered slug
requires a translated description. The directory test catches missing descriptions.
A registry entry does not imply every integration is complete or publicly accessible.

Pitch slides use labeled product flows, decision diagrams, and journey diagrams
in `product-diagrams.tsx`, `decision-diagrams.tsx`, and `journey-diagrams.tsx`.
The remaining editorial illustrations live in the geometry modules. The Tasks and Meet scenes
are shared with the portfolio. They are local, synthetic illustrations: they do
not call AI, create tasks, join meetings, or process real participant data.

Research and grant-funded collaboration can be described in general terms on
the portfolio. Keep confidential opportunities and unpublished partner details
out of both public pages and presenter notes. Do not claim awarded funding,
validated outcomes, or institutional endorsements without published evidence.

The portfolio and deck also cover smart Chat, Mail, Calendar, realtime whiteboards,
collaborative documents, multi-agent simulation research, and Tuturuuu product
ownership. Keep Mira mail action extraction labeled as a development direction
until the underlying product supports that full workflow.

The 32-slide story is organized into six chapters: why now, product foundations,
connected intelligence, trust and validation, sustainable delivery, and user
ownership. External statistics link to primary sources from Stanford HAI,
Microsoft, WEF, and OECD, with dates and sample limitations on the reference
slide. Update source details when changing a statistic. Full independence remains
a roadmap; do not imply external infrastructure or model dependencies are gone.

The ecosystem strategy slide explains the investment in shared architecture, ongoing engineering, and operations as AI-assisted app creation becomes more accessible. This is presented as a strategic thesis, with expansion tied to customer value and reuse rather than breadth alone.

## Diagram and product-mark maintenance

Keep diagram labels, icons, and connectors in the same SVG coordinate system.
Use explicit unfilled paths for line art, route connectors to node boundaries,
and draw opaque node surfaces over connection paths. Scope responsive SVG rules
to the outer `data-pitch-diagram` element, never embedded product icons.

`product-mark.tsx` uses approved local brand assets for Tuturuuu, Mira, Tasks
(TuDo), Nova, and Rewise, with application icons for other products. It is shared
by the deck, product illustrations, and portfolio directory. Short diagram labels
live in both locales under `pitch.visuals`; do not position separate HTML labels
over a scaled SVG. Workload and skills figures are explicitly synthetic, and
evaluation cells stay empty until a real pilot provides measured results.

## Editorial imagery and responsive storytelling

The portfolio uses two optimized AI-generated concept illustrations under `apps/web/public/media/story`: a Vietnam-to-starward panorama and an imagined research observatory. Captions explicitly identify concept art; neither represents an existing facility or geographic footprint. Keep text in HTML, retain image alt text in both locales, and preserve mobile cropping. Generation prompts are recorded beside the assets.

The pitch consolidates overlapping topics into 32 slides. Historical fragments redirect through `CONSOLIDATED_SLIDES` in `pitch-model.ts` so shared links survive editorial changes. The portfolio catalog chart derives its counts from the same app list as the directory; it never represents adoption or revenue. Its selectable workflow is a conceptual walkthrough, not a live AI action.

### Motion and the innovation story

The portfolio's innovation explorer uses shared `@tuturuuu/ui` tabs and buttons,
with icons from `@tuturuuu/icons`. Its three chapters connect useful products,
maintained foundations, and long-term intelligence research. The Google comparison
is explicitly an ambition, not a claim of equivalent scale or market position.

`StoryMotion` provides a reader-controlled motion switch. Use a single short
opacity transition per scene; do not animate full sections, stack parent and child
entrances, or run decorative loops. Chapter panels share a grid cell to reserve
the tallest panel, with inactive content inert and hidden from assistive technology.
Use SVG icons from `@tuturuuu/icons` for every button icon, never emoji or text glyphs. Reduced-motion preferences disable scene animation; print removes motion
and keeps all pitch slides visible. Essential content is rendered without waiting
for an animation or observer. Check keyboard tab navigation, the pause control,
EN/VI mobile layouts, and print whenever these compositions change.

# Programming playgrounds
Source: https://docs.tuturuuu.com/platform/features/programming-playgrounds

Hosted projects, personal Drive saves and collaborative programming in Learn and Meet.

## Product decisions

Learn exposes hosted playgrounds inside Programming. The first version uses
platform-managed runners explicitly enabled by Infrastructure operators.
Registered customer devboxes are not selected automatically. Supported language
templates are Python, JavaScript, TypeScript, C, C++, Java, Rust, Go, Ruby, PHP and
shell. Creation only offers languages reported ready by the managed pool.

Normal access requires a paid personal-workspace subscription or the active
`feature.learn.playgrounds` account benefit. Workspace membership or somebody
else's paid team subscription does not confer personal playground access.
Owners may invite named accounts as editors or viewers. Invited accounts must
also have playground access. Only owners manage collaborators.

Meet is an intentional exception: a current, confirmed `@tuturuuu.com` room
admin elevates programming and playground access for all admitted participants
in that room. The server checks the host's auth identity. This does not grant a
permanent benefit, expose workspace archives or bypass the waiting room. Closing
the meeting prevents fresh coding tickets; outstanding tickets expire shortly.
The host selects a Learn problem or owner-controlled playground for the room.
Learn problem execution uses public tests; hidden test data is never shared.

## Files and environments

Project files live in the owner's **personal workspace Tuturuuu Drive**, including
when the project is opened from an organization education workspace or meeting.
Server metadata points to immutable file objects. Each successful checkpoint
advances an optimistic revision. Unchanged file objects are reused; stale writers
must retry after reconciling their state.

Editing is collaborative through Yjs documents. Remote cursors identify the
active file and position; pointers are normalized to the coding pane. Presence
is transient and never written to Drive. Learn and Meet reuse the same workbench
and realtime protocol.

Background saves coalesce changes and send changed text plus a path inventory.
No-change snapshots and ticket refreshes avoid file transfers. Runner-created
files are exported at bounded intervals and after commands complete. Dependencies
and caches are kept in the warm isolated environment, not copied to Drive.
Only regular UTF-8 text files are saved: at most 128 files, 256 KiB per file and
2 MiB per project. Symlinks, binary files, `node_modules`, `.git`, `__pycache__`,
`target` and `.venv` are excluded. Oversized files report a save failure.

Managed containers use gVisor, pinned images, non-root users, resource limits and
no host mounts or credentials. Warm environments retain installed dependencies
until they sleep after 15 minutes idle or reach a two-hour lifetime. Drive files
persist across sleeps; templates and project commands rebuild dependencies when
needed. Network access is disabled unless operators configure a dedicated,
restricted managed network.

## Previews and recovery

Private app previews require current project or admitted meeting authorization.
The preview document executes in a sandboxed iframe with an opaque origin. It
cannot read Tuturuuu cookies or expose a public runner port. Web module and CSS
assets use a 60-second capability limited to one project and port; native assets
use a separate loopback capability and authenticated proxy. Reload the preview
after capability expiry. GET documents, modules, stylesheets and binary assets
are supported; runtime API requests, WebSockets and form submission are disabled.
Unsupported preview
behaviors must remain explicit rather than weakening the application origin.

Offline programming rooms reserve at most three automatic checkpoint attempts
within two minutes of the first offline attempt, at least 30 seconds apart. The
reservation is persisted before the provider call, so duplicate alarms and object
restarts cannot replenish it. At exhaustion or expiry, the room retains its unsaved
document and revision without scheduling more offline retries. A current authorized
owner may explicitly checkpoint the retained document; a confirmed save clears
the retry budget. Viewer requests cannot recover or overwrite it. Active signed
connections retain their existing checkpoint and ticket-expiry behavior; this
offline bound is not a platform spending cap.

Regression coverage: `collaboration-retry-budget.test.ts` counts provider/storage
operations through failures, duplicates, restarts, deadlines and owner recovery.
The isolated Worker/SQLite fixture reconstructs handlers against real persistence
and invokes alarm logic explicitly; hosted alarm delivery and Drive remain separate
acceptance evidence.

Keep the room open when Drive reports a save failure. Durable room state and
Drive confirmation are distinct. A busy project or conflicting revision must
not be silently overwritten. Stopping an environment terminates its processes;
only files already checkpointed to Drive survive.

Regression evidence belongs in `apps/database/supabase/tests/hosted-playgrounds.sql`,
`packages/realtime/src/collaboration`, Meet admission tests and SDK sandbox tests.
See [the runbook](/build/devops/programming-realtime-runbook) for rollout gates
and operational diagnostics.

### Runner exports and collaborative edits

Runner exports first commit against the current database run lease and Drive
revision, then join the durable Yjs document and participant broadcasts. A
previously issued runner ticket cannot admit files after cancellation or a newer
run takes over; a rejected commit leaves the live room unchanged. Ordinary room
edits may clear terminal run metadata and continue saving after a run finishes.
If an editor changes a runner-touched file while its Drive commit is awaiting a
response, the newer editor content or deletion is preserved in the room and
checkpointed separately. A lost HTTP acknowledgement after a successful database
commit can leave the room's revision behind Drive; later saves fail with a
conflict rather than overwriting it. Automatic lost-response reconciliation is
not implemented, and reconnecting alone is not a recovery guarantee. The same
fail-closed revision conflict can occur if the committed candidate and newer
editor changes exceed the combined room budget; valid peer edits stay in the
room, while the committed Drive revision remains authoritative.

The runner sends its complete path inventory and only changed bytes. A file changed only in the editor
is retained; files created by the runner appear in every participant's editor.
If both sides change the same file, or the runner deletes a file edited by a
participant, the export is rejected with a visible save conflict. Retrying an
acknowledged export does not upload unchanged bytes. This applies to personal
Learn projects and admitted Meet programming rooms. Failed initial template saves
release only an unpublished project's quota; existing projects are retained.

Regression evidence: `runner-files.test.ts`, the local programming Worker probe,
`playground-service.test.ts`, `programming-collaboration.test.ts`, and the
hosted-playgrounds pgTAP suite.

The framework-independent `@tuturuuu/realtime/core/retry-budget` planner owns
finite attempt/deadline decisions; the Worker persists reservations before I/O
and retains authorization and recovery. Invalid durable retry state stops without
resetting the job or deleting documents. See
`apps/docs/build/devops/programming-realtime-runbook.mdx#portable-offline-retry-planning`
for the adapter contract and planner, counted-handler and SQLite regressions.

# Progress, Goals & Leaderboards
Source: https://docs.tuturuuu.com/platform/features/progress-goals-leaderboards

TrackBear-style progress tracking for tasks: flexible metrics, target/habit goals, activity heatmaps, leaderboards, and gamification.

## TL;DR

The Tasks app turns everyday work into a motivating, glanceable progress system. Progress is
derived **automatically** from completed tasks and focus sessions, and can also be **logged
manually** in any unit — including writing units like words, pages, and chapters. Goals, an
activity heatmap, leaderboards, and a full achievement/XP layer keep momentum visible.

## Metrics

Every workspace tracks a few automatic metrics (completed tasks, estimate points, focus time,
focus sessions). Teams that write can enable a one-click **Writing pack** that adds Words, Pages,
Chapters, Scenes, and Lines. Metrics support two aggregation styles — summed deltas or a running
total — so you can log either "+500 words today" or "project total is now 12,000".

## Logging progress

* **Automatic**: completing a task or finishing a focus session feeds the relevant metric with no
  manual step.
* **Quick log**: a persistent button (and a mobile floating action button) opens a dialog to record
  an amount for any metric, on any date, with a note and tags. Zero and negative values are allowed
  so a "showed up but wrote nothing" day is distinct from an untracked one, and corrections are easy.

## Goals

Two goal types, mirroring TrackBear:

* **Target** — accumulate toward a total by an optional end date. Shows a progress bar, the expected
  pace ("par"), a projected finish, and an on-track / needs-attention chip.
* **Habit** — write regularly at a chosen cadence (per day / week / month) with an optional
  per-period threshold. Shows a gauge that turns gold when the period is met, plus current, longest,
  and typical streak length and the percentage of periods hit.

## Visualizations

* **Activity heatmap** — a year-long contribution grid; darker cells mean more progress that day.
* **Cumulative chart** — accumulated progress over time, with an optional par line for dated targets.
* **Analytics dashboard** — KPI strip, daily bars, weekday distribution, tag breakdown, best day,
  consistency, and a momentum recommendation.

## Leaderboards

Anyone can create a leaderboard for a metric and period. Members **join by code**, appear on a
podium (top three) with a ranked overflow list, and can be organized into teams. Automatic weekly
leaderboards are synthesized from task activity so a workspace always has something live.

## Gamification

Logging progress unlocks **achievements** (streaks, volume, consistency, milestones, social) across
bronze → platinum tiers, awards **XP**, and raises your **level**. Streak freezes are earned as
streaks grow. Unlocks surface as celebratory toasts and in an achievements card on the Progress and
Analytics views.

## Under the hood

Progress data lives in the `task_progress_*` and `task_leaderboard*` tables, with the gamification
layer in `task_progress_achievements`, `task_progress_user_achievements`, and
`task_progress_user_stats`. XP and achievement evaluation is deterministic and idempotent — it is
recomputed from current activity on every progress write, so it never drifts or double-counts.

# Search indexing and private routes
Source: https://docs.tuturuuu.com/platform/features/search-indexing

Explicit public discovery, private-route defaults, shared links, storefront transactions, and inactive runtimes.

## Product decision

Search indexing is opt-in at the app route boundary. The maintained Next.js apps
use the shared policy in `packages/utils/src/seo-policy.json` and the header
builder in `packages/utils/src/seo.ts`. Private routes receive
`X-Robots-Tag: noindex, nofollow, nosnippet` even when an inherited layout has
public metadata. Authentication, authorization, RLS, and private storage still
control access; search directives do not protect data from a caller.

This applies across Web, satellites, internal example apps, and redirect hosts.
Private app metadata continues to use `NO_INDEX_ROBOTS`. The Flutter browser bootstrap is noindex. The paused TanStack Start runtime
is not deployed or refreshed by this policy. Before any explicitly authorized
resumption, establish preview noindex and canonical ownership; do not expose an
indexed duplicate of the live Next.js platform.

## Public exceptions

| Surface | Eligible content | Private or unlisted content |
| - | - | - |
| Web | Generated public page manifest and published changelog entries | Workspaces, documents/shares, AI chats, invites, auth, onboarding, pitch, and utility/internal routes |
| Apps | Public directory | App redirect aliases and private targets |
| Tools | `/`, `/qr`, `/random` | API and undeclared utility paths |
| Learn/Teach | Product landing page | Workspaces, courses, assignments, marks, parent records, and auth |
| Nova | Declared marketing/learning routes | Challenges, submissions, sessions, profile/admin/dashboard routes |
| Git | Public repository browser | `/-/` workspace integration routes, auth, and API |
| Tulletin | Landing, spaces, explorer, published worlds, and public creators | Workspace studio, drafts, invitations, and moderation |
| Forms | Landing page and `/f/{shareCode}`, subject to author and access-aware page metadata | Studio, responses, protected/unavailable pages, and embed wrappers |
| Storefront | Published store and product pages, subject to availability metadata | Cart, checkout, success/cancel, order lists/tokens, and legacy aliases |
| Other Next apps | No application routes by default | Private workspace products, rooms, share codes, admin, developer examples, and short redirects |

Forms retains its existing author-controlled indexing opt-out: this policy does
not force every public form to noindex or reverse an author's `noIndex` choice.
Eligible does not mean included in a sitemap. Dynamic forms, shops, worlds, and
repository pages are not crawled from privileged workspace tables merely to
populate discovery feeds.

## Crawling, canonical URLs, and previews

`robots.txt` permits crawlers to observe redirects and noindex responses.
Blocking a URL in robots.txt can prevent a crawler from seeing its noindex
instruction. Public pages use page-specific canonicals and social metadata.
Language alternates are emitted only when distinct stable language URLs exist;
apps with `localePrefix: never` do not invent indexed locale duplicates.

Preview and development Next deployments are excluded by the HTTP policy when
`VERCEL_ENV` is `preview`/`development` or `NODE_ENV` is `development`.
Set `TUTURUUU_NOINDEX=1` for a non-Vercel staging host and rebuild/redeploy its
configuration. Production public routes remain eligible unless that explicit
flag is set. A production-domain canonical is not a replacement for preview
noindex.

## Regression evidence

`packages/utils/src/seo.test.ts` verifies parsed Next header patterns against
private workspaces, auth/API routes, form/embed boundaries, buyer transactions,
public education/tool pages, Git integration paths, Tulletin drafts, the generated
Web allowlist, and preview behavior. `scripts/generate-app-seo.test.js` checks
sitemap host ownership, truthful locale alternates, and the absence of private
sitemaps. Deployment HTML/header inspection and Search Console URL Inspection
remain required to establish the served/indexed result.

References: [Google noindex guidance](https://developers.google.com/search/docs/crawling-indexing/block-indexing)
and [content access controls](https://developers.google.com/search/docs/crawling-indexing/control-what-you-share).
The [SEO runbook](/build/development-tools/public-seo) explains maintenance.

Public Forms metadata explicitly overrides its private root layout for accessible
anonymous snapshots when `noIndex` is false. Protected, unavailable, and opted-out
forms retain noindex; embeds and workspace pages always do. Regression coverage:
`apps/forms/src/features/forms/shared-form-data.test.ts` and
`shared-form-loader.test.ts`. This changes discovery metadata, not response access.

# Settings dialog
Source: https://docs.tuturuuu.com/platform/features/settings-dialog

Shared account tabs, settings deep links, URL state and history behavior across apps/web and satellites.

Every app opens account and app settings in one fullscreen settings dialog. Its
open state and active tab live in the URL, so links can be shared, the page can
be refreshed, and browser Back works.

## URL contract

Scope: apps/web and every satellite that renders a settings dialog (the shared
satellite user menu, plus the dedicated Calendar and Tasks hosts).

* A bare `settingsTab` is enough to open the dialog. Before 2026-10-23, the
  dialog opened only when `settingsDialog=open` was also present, so links such
  as `/personal?settingsTab=security` silently stayed closed.
* Tab ids are lowercase `[a-z0-9_-]`, at most 64 characters. Malformed values
  are ignored.
* An unknown or unavailable tab falls back to the app's first enabled tab. The
  URL is not rewritten, so a tab that registers later (for example after a
  permission check resolves) still opens.
* Host-specific params travel with the dialog and are cleared with it:
  `settingsBoardId` (Tasks/web board settings) and `settingsLinkedProvider`
  (web identity-link callback).
* When the signed-in web root (`/` or `/<locale>`) redirects to the default
  workspace, settings params are carried over. Other root query params are still
  dropped, as before.

## History

* Opening a closed dialog pushes a history entry, so Back closes it and Forward
  reopens it.
* Switching tabs and closing replace the current entry, so tab browsing does not
  fill the history stack.
* All updates are shallow (no server round-trip) and keep the scroll position.
* apps/web shows the dialog optimistically on an open intent, before the URL
  updates. That optimistic state is dropped as soon as the URL acknowledges the
  open, even if the lazy dialog bundle is still loading. Back always closes the
  dialog.

## Identity-link callback

`settingsLinkedProvider` is set on the return URL whether the provider flow
succeeded, failed or was cancelled. apps/web shows the "linked" success message
only after a fresh identities read contains that provider. Otherwise it shows a
neutral "couldn't confirm" message.

## Tabs every app has

Scope: every satellite that renders the shared satellite user menu. Default:
every such app shows one **Account** group with the same tab ids as apps/web,
so `?settingsTab=<tab>` means the same thing in every app.

Apps with their own dialog (ai, calendar, cms, contacts, drive, finance, forms,
git, infrastructure, inventory, rewise, tasks, track) add the Account group with
`createAccountSettingsNavGroup` and render `SatelliteAccountSettingsPanel`, next
to their app tabs. Apps without one (chat, learn, lettin, mail, meet, mind,
parley, storefront, teach) get `SatelliteDefaultSettingsDialog`: the Account
group, appearance and the onboarding guide. The satellite user menu has a
**Settings** item (Cmd/Ctrl+,) that opens the same dialog.

App-specific tabs stay pluggable. An app adds its own nav groups and panels, and
`SatelliteAccountSettingsPanel` renders nothing for tabs it does not own.

### Security-sensitive tabs stay in apps/web

Satellites do not reimplement password change, 2FA, passkeys, identity linking
or session revocation, and they do not proxy those mutations. apps/web owns
re-authentication, the WebAuthn relying party and session revocation. The
satellite `accounts`, `security` and `sessions` tabs link to
`<web origin>/personal?settingsDialog=open&settingsTab=<tab>` in a new tab
(`rel="noopener noreferrer"`), which opens the web dialog on the same tab.

Satellites edit only display name, full name and avatar upload, through the
existing web profile endpoints (`/api/v1/users/me/*`) in
`@tuturuuu/internal-api`, using the satellite session and the `/api` proxy
contract.

* **Email is a link-out.** A satellite session's admin client has no provider
  session and cannot change the auth email. Satellites show the email read-only
  and link to `?settingsTab=profile` in apps/web, which owns verification. They
  never call `PATCH /api/v1/users/me/email`.
* **Avatar removal is off in satellites**
  (`SATELLITE_AVATAR_REMOVE_ENABLED`) until the web avatar route fix is merged.
  Users remove avatars in apps/web.

### Exceptions

* apps/web keeps its own dialog with the full tab set.
* nova keeps its own single-page profile dialog. It does not use the satellite
  user menu.
* hive, pay, apps, tools, external, playground and shortener have no user
  settings dialog.
* Personal timezone and notification preferences are only in apps/web.
* Calendar keeps workspace timezone under its own calendar tabs.

## Implementation

`packages/ui/src/hooks/settings-dialog-url.ts` is the single source of truth: the
param names, tab-id sanitizing, parse/serialize, fallback resolution, href
building and history mode. `useSettingsDialogUrlState`
(`packages/ui/src/hooks/use-settings-dialog-url-state.ts`) is the only way a host
reads or writes the dialog URL state. Build links with `buildSettingsDialogHref`
instead of hand-writing query strings.

## Regression coverage

* `packages/ui/src/hooks/settings-dialog-url.test.ts`: parse/serialize, the bare
  `settingsTab` deep link, sanitizing, unknown-tab fallback, history mode.
* `packages/ui/src/hooks/use-settings-dialog-url-state.test.tsx`: push on open,
  replace on tab switch, every param cleared on close.
* `packages/ui/src/components/ui/custom/__tests__/settings-dialog-shell.test.tsx`:
  URL-restored tab and unknown-tab fallback without a URL rewrite.
* `packages/satellite/src/components/user-nav-client-deep-link.test.tsx`: the
  shared satellite menu host.
* `apps/calendar/src/components/settings/settings-dialog-host.test.tsx` and
  `apps/tasks/src/components/settings/settings-dialog-host.test.tsx`: dedicated
  satellite hosts.
* `apps/web/src/components/settings/settings-dialog-shortcuts.test.tsx`: web
  dashboard and user-menu hosts.
* `apps/web/src/components/settings/settings-dialog-host-lazy.test.tsx`: Back
  while the lazy dialog import is pending keeps the dialog closed, including
  after a repeated open (Cmd/Ctrl+, twice on a task board).
* `apps/web/src/components/settings/account/use-linked-provider-confirmation.test.tsx`:
  link success only after confirmation.
* `apps/web/src/components/settings/account/linked-identities-card.test.tsx`:
  the real card shows no toast while identities are pending, neutral wording
  for an unlinked provider, and success only when the provider is present.
* `packages/satellite/src/components/account-settings/account-settings.test.tsx`:
  shared Account group tab ids and the web link-out URL.
* `packages/satellite/src/components/user-nav-client-settings.test.tsx`: the
  default dialog for apps without their own, and the menu Settings item.
* `packages/ui/src/components/ui/custom/satellite-user-menu-items.test.tsx`: the
  Settings menu item.
* `packages/satellite/src/components/profile-settings/profile-sensitive-actions.test.tsx`:
  the email link-out sends no email PATCH, and avatar removal is not offered.
* `apps/calendar/src/components/settings/settings-dialog.test.tsx`: an
  app-specific dialog includes the shared account tabs.
* `apps/web/src/__tests__/proxy.test.ts`: settings params survive the root
  redirect.

# Shared-secret password reset
Source: https://docs.tuturuuu.com/platform/features/shared-secret-password-reset

Required reset and owner recovery for retired Nova challenge and Meet guest credentials.

## Scope and default

Under the 25 October 2026 reset policy, every non-empty stored hash outside the
accepted scrypt format is a reset marker, including older short digests and malformed
scrypt values. These markers are never verified or upgraded using a submitted
password. The shared verifier returns `resetRequired: true` and `valid: false`,
without computing a SHA-256 digest. All new credentials use scrypt. Empty or
absent values are not reset markers.

This decision covers two credential domains and three app surfaces:

These are application shared secrets, not Supabase account passwords. Account
sign-in, email password reset, account sessions and MFA are unchanged. Meet guests
have no email recovery identity. Anonymous callers cannot reset a guest by name.

The existing hash format is the durable marker. No extra flag, schema migration,
bulk database update, automatic password clearing or record deletion is needed.
The actual number of legacy rows cannot be inferred from source. Potential scope
is every row with an unsupported non-empty hash in these two tables, with no finite
row-count bound in the schema; zero provider account-password rows are affected. No production query is
part of this decision.

## User recovery

Nova returns HTTP 409 with `code: PASSWORD_RESET_REQUIRED`; the confirmation form
shows the reset instruction in English or Vietnamese instead of “wrong password”.
A challenge manager opens **Edit challenge**, enters a new password under the
password setting, and saves. The existing authorized update writes scrypt. The
manager shares the new challenge password privately with participants. Managers
may instead deliberately remove challenge password protection using the existing
setting; normal unprotected-challenge access rules then apply.

Meet returns the same reset code and a localized instruction to contact the plan
creator. On the plan page, the signed-in creator uses **Reset a guest password**,
enters the guest name exactly as used to sign in and sets a new password. For a workspace plan, the creator must also retain the same MEMBER access
required to open the plan. The server rechecks plan ownership,
scopes the guest to that plan, and conditionally replaces only the legacy hash.
The creator chooses the guest's new password and can therefore sign in as that guest.
A concurrent credential change is never overwritten. Current scrypt credentials
are outside this recovery action. The guest signs in with the new password;
reset itself issues no session. Guest identity, availability and votes are kept.

If a Meet plan has no available authenticated creator, the legacy guest identity
stays blocked. A participant can use their Tuturuuu account or a new guest name. New passwordless guests still use scrypt for the empty password;
legacy passwordless identities cannot be distinguished safely and also require reset.
Existing data is retained; there is no unauthenticated takeover or email reset.

## Existing grants and rollout

Nova challenge grants and Meet guest tokens now use versioned purpose names.
Tokens issued under the retired verifier are rejected, including after the owner
resets a row. This deliberately requires one-time password re-entry for holders
of older grants, including scrypt credentials; their existing scrypt password
continues to work. Account sessions and MFA are not revoked. The new policy also
checks the backing row so even a correctly signed new token cannot authorize a
row that still requires reset.

Ship the shared verifier, owner recovery, localized forms and token consumers
across Web, Nova and Meet together. Require exact-commit app CI/build and independent
security review. Do not roll back to the former verifier while legacy rows remain.

## Regression evidence

* `packages/utils/src/__tests__/legacy-password-reset.test.ts`: long/short legacy and malformed-hash rejection,
  no SHA-256 computation or legacy writer, valid scrypt, retired-token rejection.
* `apps/nova/src/app/api/auth/challenges/verify-password/route.test.ts`: reset
  response without a grant, valid scrypt, wrong-password and user-binding controls.
* `apps/nova/src/lib/challenge-password-error.test.ts` and the shared Meet
  `plan-login-reset.test.tsx`: actual English/Vietnamese reset copy.
* `packages/apis/src/meet/guest-password-reset.test.ts`: creator-only recovery,
  foreign-plan denial, conditional update, data retention and held-row session denial.
* Meet native `guest-password-reset.test.ts` and `legacy-action-ports.test.ts`:
  app-session actor injection, argument validation and unsigned-request rejection.

# API Reference
Source: https://docs.tuturuuu.com/platform/features/smart-scheduling/api-reference

REST API endpoints for Smart Scheduling

# Smart Scheduling API

The Smart Scheduling API allows you to programmatically trigger scheduling and retrieve scheduling status.

## Endpoints

### Trigger Scheduling

Triggers the unified scheduler for a workspace, scheduling both habits and tasks.

#### Path Parameters

**wsId** `string` *required*

The workspace ID (UUID format)

#### Request Body

**windowDays** `number` (default: 30)

How many days into the future to schedule events (7-90)

**forceReschedule** `boolean` (default: false)

If true, deletes existing auto-generated events and creates new ones

#### Response

```json theme={null}
{
  "success": true,
  "summary": {
    "habitsScheduled": 5,
    "tasksScheduled": 3,
    "eventsCreated": 12,
    "bumpedHabits": 1,
    "rescheduledHabits": 1,
    "windowDays": 30
  },
  "habits": {
    "events": [
      {
        "habitId": "uuid",
        "habitName": "Morning Meditation",
        "occurrence": "2024-01-15",
        "duration": 20,
        "event": {
          "id": "uuid",
          "start_at": "2024-01-15T07:00:00Z",
          "end_at": "2024-01-15T07:20:00Z"
        }
      }
    ],
    "warnings": []
  },
  "tasks": {
    "events": [
      {
        "taskId": "uuid",
        "taskName": "Complete report",
        "scheduledMinutes": 120,
        "warning": null,
        "events": [
          {
            "id": "uuid",
            "start_at": "2024-01-15T09:00:00Z",
            "end_at": "2024-01-15T11:00:00Z",
            "scheduled_minutes": 120
          }
        ]
      }
    ],
    "bumpedHabits": [
      {
        "habitId": "uuid",
        "habitName": "Reading",
        "occurrence": "2024-01-15",
        "originalEventId": "uuid"
      }
    ],
    "warnings": []
  },
  "rescheduledHabits": [
    {
      "habitId": "uuid",
      "habitName": "Reading",
      "occurrence": "2024-01-15",
      "duration": 30,
      "event": {
        "id": "uuid",
        "start_at": "2024-01-15T19:00:00Z",
        "end_at": "2024-01-15T19:30:00Z"
      }
    }
  ],
  "warnings": []
}
```

#### Example

```bash cURL theme={null}
curl -X POST "https://tuturuuu.com/api/v1/workspaces/{wsId}/calendar/schedule" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{"windowDays": 30, "forceReschedule": false}'
```

```typescript TypeScript theme={null}
const response = await fetch(
  `/api/v1/workspaces/${wsId}/calendar/schedule`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ windowDays: 30, forceReschedule: false }),
  }
);

const result = await response.json();
console.log(`Created ${result.summary.eventsCreated} events`);
```

***

### Get Scheduling Status

Retrieves the current scheduling status and statistics for a workspace.

#### Path Parameters

**wsId** `string` *required*

The workspace ID (UUID format)

#### Response

```json theme={null}
{
  "lastScheduledAt": "2024-01-15T10:30:00Z",
  "lastStatus": "success",
  "lastMessage": "Scheduled 5 habits and 3 tasks",
  "statistics": {
    "habitsScheduled": 5,
    "tasksScheduled": 3,
    "eventsCreated": 12,
    "bumpedHabits": 1,
    "windowDays": 30
  },
  "schedulableItems": {
    "activeHabits": 7,
    "autoScheduleTasks": 4
  }
}
```

#### Example

```bash cURL theme={null}
curl "https://tuturuuu.com/api/v1/workspaces/{wsId}/calendar/schedule" \
  -H "Cookie: your-session-cookie"
```

```typescript TypeScript theme={null}
const response = await fetch(
  `/api/v1/workspaces/${wsId}/calendar/schedule`
);

const status = await response.json();
console.log(`Last scheduled: ${status.lastScheduledAt}`);
```

***

## Authentication

### User Authentication

Standard user authentication via session cookie. The user must be a member of the workspace.

### Cron Authentication

For background jobs, the API accepts a Bearer token with the cron secret:

```http theme={null}
Authorization: Bearer {CRON_SECRET}
```

This is used by the Vercel cron job that runs scheduling every 6 hours.

The cron secret is read from `process.env.CRON_SECRET ?? process.env.VERCEL_CRON_SECRET`.

## Error Responses

| Status | Description |
| - | - |
| 400 | Invalid workspace ID |
| 401 | Not authenticated |
| 403 | Not a workspace member |
| 409 | Safe apply blocked because the schedule still has unresolved warnings |
| 422 | Workspace timezone is not set, or is set to `auto` |
| 500 | Internal server error |

## Rate Limiting

The scheduling endpoint is rate-limited to prevent abuse:

* **Manual triggers**: Limited by standard API rate limits
* **Cron triggers**: A single global cron runs every 6 hours and fans out to eligible workspaces (not per-workspace at the cron level)

## Cron Job

Smart Scheduling runs automatically every 6 hours via Vercel Cron:

```json theme={null}
{
  "path": "/api/cron/calendar/smart-schedule",
  "schedule": "0 */6 * * *"
}
```

The cron job:

1. Finds all workspaces with auto-schedule enabled habits or tasks
2. Calls the scheduling API for each workspace
3. Logs results and any errors

> [!NOTE]
>
> The cron job uses `forceReschedule: false` to avoid disrupting existing schedules. Only new items are scheduled.

## Calendar link preview for Mail

`GET /api/v1/workspaces/{wsId}/calendar/events/{eventId}/link-preview` returns
a sanitized read-only target for an explicit Mail association. The default
Calendar/Tasks authentication boundary is preserved; this endpoint also accepts
a validated Mail app session and mobile bearer authentication. Workspace
membership and `manage_calendar` remain required. A provider target additionally
requires one enabled, active connected account owned by the actor, with both the
stored workspace source and external calendar IDs matching exactly. Read-only
provider roles are eligible; ambiguous or incomplete legacy identities, disabled
accounts, missing targets, and cancelled events suppress the preview.

The response preserves internal IDs, connected-account row and connection IDs,
provider calendar and immutable event IDs, actual provider UID, and original
occurrence identity when available. Microsoft occurrence UIDs are returned as
provided and must not be assumed to equal a series UID. Native events report
unknown account, organizer, UID, recurrence and attendee ownership.

Provider fields come from an exact authorized GET, after the local encrypted
storage boundary. Missing keys, malformed ciphertext and authentication failures
suppress both native previews and provider GETs; the preview never treats the
legacy decryption fallback or an encryption flag as proof of plaintext. Hidden
attendees are omitted; conferencing fields only yield
validated HTTPS Teams/Meet links, separately from the structured location. Raw
bodies, account credentials and provider errors are never returned. This endpoint
does not save associations, alter either event, respond to invitations, copy
events or grant permission to merge a private hold into an organizer's request.

The shared wire contract is exported from `@tuturuuu/internal-api/calendar`.
Mail owns actor-scoped association metadata and must recheck this preview on
confirm/open. No Calendar table or provider mutation is part of this seam.

# Duration Optimization
Source: https://docs.tuturuuu.com/platform/features/smart-scheduling/duration-optimization

How Smart Scheduling optimizes habit duration based on time slot characteristics

# Duration Optimization

Duration optimization is a key feature that makes habit scheduling intelligent. Instead of always using a fixed duration, the system adapts based on the available time slot and your preferences.

## Flexible Duration Bounds

Each habit can have three duration settings:

> [!NOTE]
>
> If you only set the preferred duration, the system calculates sensible defaults for min and max.

## Optimization Strategy

The duration optimizer chooses the optimal duration based on slot characteristics:

### 1. Ideal Time Match

When the slot contains your specified `ideal_time` (e.g., "07:00"):

```
Duration = Maximum
```

The system maximizes duration because you're getting your most valuable time slot. This is when you'll get the most benefit from the habit.

### 2. Time Preference Match

When the slot falls within your preferred time-of-day:

```
Duration = Preferred
```

The system uses your standard preferred duration since this is still a good time for the habit.

### 3. Constrained Slot

When the available slot is smaller than your preferred duration:

```
Duration = max(Minimum, Available)
```

The system shrinks to fit while ensuring you still get value from the habit.

### 4. No Special Conditions

When no preferences match:

```
Duration = Preferred
```

Falls back to your standard preferred duration.

## Slot Scoring

When multiple time slots are available, the system scores each one to find the best:

```typescript theme={null}
function scoreSlotForHabit(habit, slot, timezone?, weights?): number {
  const characteristics = getSlotCharacteristics(habit, slot, timezone);
  let score = 0;

// Ideal time match is best (default +1000, overridable via weights)
  if (characteristics.matchesIdealTime) {
    score += weights?.habitIdealTimeBonus ?? 1000;
  }

// Time preference match is second best (default +500, overridable)
  if (characteristics.matchesPreference) {
    score += weights?.habitPreferenceBonus ?? 500;
  }

// Prefer slots that fit preferred duration (+200), else minimum (+100)
  const { preferred, min } = getEffectiveDurationBounds(habit);
  if (slot.maxAvailable >= preferred) {
    score += 200;
  } else if (slot.maxAvailable >= min) {
    score += 100;
  }

// Tiebreaker (timezone-aware hour):
  // - With a preference set, slightly prefer earlier slots
  // - With no preference, prefer slots closer to noon to spread habits out
  const slotHour = getLocalHour(slot.start, timezone);
  if (habit.time_preference || habit.ideal_time) {
    score -= slotHour * 0.1;
  } else {
    score -= Math.abs(slotHour - 12) * 0.5;
  }

return score;
}
```

## Examples

### Morning Meditation

```
Habit: Morning Meditation
Preferred: 20 minutes
Minimum: 10 minutes
Maximum: 30 minutes
Ideal Time: 06:30
Preference: Morning
```

### Evening Workout

```
Habit: Evening Workout
Preferred: 60 minutes
Minimum: 30 minutes
Maximum: 90 minutes
Ideal Time: null
Preference: Evening
```

## Implementation Details

The duration optimizer is implemented in `packages/ai/src/scheduling/duration-optimizer.ts`:

```typescript theme={null}
// Key exports (signatures simplified; optional params shown where they matter)
export function getEffectiveDurationBounds(habit): { preferred, min, max };
export function calculateOptimalDuration(habit, slot, characteristics): number;
export function timeMatchesSlot(idealTime: string, slot, timezone?): boolean;
export function slotMatchesPreference(preference: TimeOfDayPreference, slot, timezone?): boolean;
export function getSlotCharacteristics(habit, slot, timezone?): SlotCharacteristics;
export function scoreSlotForHabit(habit, slot, timezone?, weights?): number;
export function findBestSlotForHabit(habit, slots, timezone?, weights?): TimeSlotInfo | null;
```

> [!NOTE]
>
> Most matching and scoring functions accept an optional `timezone` so that
> `ideal_time` and time-of-day preferences are interpreted in the user's local
> time rather than the server's. `scoreSlotForHabit` and `findBestSlotForHabit`
> also accept optional `SchedulingWeights` to override the default ideal-time and
> preference bonuses.

## Configuration in Habit Form

When creating or editing a habit, you can configure duration optimization:

**1. Set Preferred Duration**

The standard duration for this habit (required)

**2. Enable Flexible Duration**

Toggle to allow min/max bounds

**3. Set Minimum Duration**

Shortest acceptable duration (optional)

**4. Set Maximum Duration**

Longest beneficial duration (optional)

**5. Set Ideal Time**

Specific time of day (optional, format: HH:MM)

**6. Set Time Preference**

Morning, Afternoon, Evening, or Night (optional)

## Testing

The duration optimizer ships with an extensive unit-test suite (currently 127
cases) covering:

* Duration bounds calculation
* Time matching and preference detection (including timezone-aware extraction)
* Slot scoring and selection
* Integration scenarios for real-world habits

Run tests with:

```bash theme={null}
npx vitest run src/scheduling/duration-optimizer.test.ts
```

# Smart Scheduling Overview
Source: https://docs.tuturuuu.com/platform/features/smart-scheduling/overview

Intelligent, unified scheduling for habits and tasks with priority-aware event placement

# Smart Scheduling

Smart Scheduling is an intelligent system that automatically schedules your habits and tasks on your calendar, respecting priorities, deadlines, and your preferences.

## Key Features

> **Unified Scheduling**
>
> Habits and tasks are scheduled together in a coordinated manner, ensuring they don't conflict

> **Priority-Aware**
>
> Items are scheduled based on priority, with urgent tasks able to bump lower-priority habits

> **Deadline Intelligence**
>
> Automatically infers priority from deadlines - items due soon get scheduled first

> **Flexible Duration**
>
> Habits can have min/max duration bounds, optimizing time based on slot availability

## How It Works

### 1. Priority Calculation

Every habit and task has an **effective priority** that determines scheduling order:

| Priority | Weight | Deadline Inference |
| - | - | - |
| Critical | 4 | Overdue or due within 24 hours |
| High | 3 | Due within 24-48 hours |
| Normal | 2 | Due beyond 48 hours |
| Low | 1 | No deadline set |

> [!NOTE]
>
> Explicit priorities always take precedence over inferred priorities. If you manually set a task as "Critical", it stays critical regardless of deadline.

### 2. Scheduling Order

Smart Scheduling processes items in this order:

1. **Habits First** - Sorted by priority, then by ideal time preference
2. **Tasks Second** - Sorted by priority, then by deadline proximity
3. **Bumping** - Urgent (critical) tasks can bump lower-priority habit events
4. **Rescheduling** - Bumped habits are rescheduled to the next available slot

### 3. Duration Optimization

For habits with flexible duration (min/max bounds), the system optimizes duration based on slot characteristics:

```
Ideal Time Match → Maximum duration (get most value from preferred time)
Preference Match → Preferred duration (morning/afternoon/evening/night)
Constrained Slot → Minimum viable duration (still complete the habit)
No Match → Preferred duration (default behavior)
```

## Using Smart Schedule

### From the Calendar

Click the **Smart Schedule** button in the calendar toolbar to run scheduling for your workspace:

**1. Click Smart Schedule**

Find the button in the calendar toolbar with the sparkle icon

**2. Wait for Processing**

The system analyzes your habits, tasks, and existing events

**3. View Results**

New calendar events appear automatically, with a toast notification showing the summary

### Automatic Scheduling

Smart Scheduling runs automatically every 6 hours via a background cron job (`/api/cron/calendar/smart-schedule`, scheduled `0 */6 * * *`). This keeps your calendar up to date as you add new habits and tasks. You can always trigger an on-demand run from the calendar toolbar in between cron cycles.

> [!NOTE]
>
> The cron job only schedules items with `auto_schedule` enabled. You can enable/disable auto-scheduling per habit or task.

## Configuration Options

### Window Days

Controls how far into the future to schedule events (default: 30 days, clamped to a 7-90 day range).

### Force Reschedule

When enabled, existing scheduled events are deleted and recreated. Use this to completely refresh your schedule.

> [!WARNING]
>
> Force reschedule will delete all auto-generated calendar events and create new ones. Manual events are not affected.

## Best Practices

> **Set Explicit Priorities for Important Items**
>
> While the system infers priority from deadlines, setting explicit priorities ensures your most important work is scheduled first.

> **Use Flexible Duration for Habits**
>
> Set min/max duration bounds instead of fixed durations. This allows the system to optimize scheduling - using more time in ideal slots and less in constrained ones.

> **Set Ideal Times for Habits**
>
> Specify your preferred time (e.g., "07:00" for morning meditation). The system will prioritize these slots and allocate maximum duration when they're available.

> **Keep Deadlines Updated**
>
> The system uses deadlines to infer priority. Keep your task deadlines accurate for optimal scheduling.

## API Reference

Smart Scheduling is available via the REST API:

```bash theme={null}
# Trigger scheduling for a workspace
POST /api/v1/workspaces/{wsId}/calendar/schedule
Content-Type: application/json

{
  "windowDays": 30,
  "forceReschedule": false
}
```

The `windowDays` value is clamped server-side to a minimum of 7 and a maximum of 90 days (default 30). See [API Reference](/platform/features/smart-scheduling/api-reference) for full details.

# Priority System
Source: https://docs.tuturuuu.com/platform/features/smart-scheduling/priority-system

How Smart Scheduling calculates and uses priority for scheduling decisions

# Priority System

The priority system is the foundation of Smart Scheduling. It determines which items get scheduled first and which items can bump others.

## Priority Levels

Smart Scheduling uses four priority levels:

| Level | Weight | Description |
| - | - | - |
| **Critical** | 4 | Must be done immediately, can bump other events |
| **High** | 3 | Important, scheduled before normal items |
| **Normal** | 2 | Standard priority, default for most items |
| **Low** | 1 | Can be deferred, scheduled when convenient |

## Priority Inference

When an item doesn't have an explicit priority set, the system infers it from the deadline:

```typescript theme={null}
function inferPriority(deadline: Date | null): Priority {
  if (!deadline) return 'low';

const hoursUntilDeadline = (deadline - now) / (1000 * 60 * 60);

if (hoursUntilDeadline <= 0) return 'critical';  // Overdue
  if (hoursUntilDeadline <= 24) return 'critical'; // Due today
  if (hoursUntilDeadline <= 48) return 'high';     // Due tomorrow
  return 'normal';                                  // Due later
}
```

> [!NOTE]
>
> Explicit priorities always override inferred priorities. If you set a task as "Low" priority, it stays low even if it's overdue.

## Priority Score Calculation

For more granular sorting, the system calculates a numeric priority score:

```typescript theme={null}
// Base score from priority level
const baseScores = {
  critical: 4000,
  high: 3000,
  normal: 2000,
  low: 1000
};

// Urgency bonus from deadline proximity (added to the base score)
function getUrgencyBonus(deadline: Date | null): number {
  if (!deadline) return 0;

const hoursUntil = (deadline - now) / (1000 * 60 * 60);

if (hoursUntil < 0) return 5000;    // Overdue - highest urgency
  if (hoursUntil < 24) return 2000;   // Due within 24h
  if (hoursUntil < 48) return 1000;   // Due within 48h
  if (hoursUntil < 72) return 500;    // Due within 3 days
  if (hoursUntil < 168) return 200;   // Due within 7 days
  return 0;                            // Due later
}
```

This scoring system ensures that:

* Overdue items are scheduled first (score up to 9000)
* Items due soon are prioritized even within the same priority level
* Low priority items with urgent deadlines can outrank high priority items due later

## Sorting Algorithm

Items are sorted using a multi-level comparison:

**1. Primary: Priority**

Higher priority items come first (critical > high > normal > low)

**2. Secondary: Deadline**

Among same priority, earlier deadlines come first

**3. Tertiary: Creation Date**

Among same priority and deadline, older items come first (FIFO)

## Bumping Rules

Only **critical priority** items can bump other events:

> [!WARNING]
>
> Critical items cannot bump other critical items. This prevents infinite bumping loops and ensures all critical work gets done.

### Bumping Process

When a critical task needs a time slot occupied by a lower-priority habit:

1. The habit event is marked for rescheduling
2. The task is scheduled in the freed slot
3. The bumped habit is rescheduled to the next available slot
4. If no suitable slot exists, a warning is generated

## Implementation Details

The priority calculator is implemented in `packages/ai/src/scheduling/priority-calculator.ts`:

```typescript theme={null}
// Key exports
export const PRIORITY_WEIGHTS = {
  critical: 4,
  high: 3,
  normal: 2,
  low: 1,
};

export function getEffectivePriority(item: PrioritizableItem): Priority;
export function comparePriority(a: Priority, b: Priority): number;
export function isHigherPriority(a: Priority, b: Priority): boolean;
export function canBump(bumper: PrioritizableItem, target: PrioritizableItem): boolean;
export function sortByPriority<T extends PrioritizableItem>(items: T[]): T[];
export function calculatePriorityScore(item: PrioritizableItem): number;
```

## Testing

The priority system is thoroughly tested with a comprehensive suite (60 test cases as of this writing) covering:

* Priority weight ordering
* Explicit priority handling
* Deadline-based inference
* Priority comparison functions
* Bumping rules
* Multi-level sorting
* Score calculation with urgency bonuses

Run tests with:

```bash theme={null}
npx vitest run src/scheduling/priority-calculator.test.ts
```

# Outbound SSO to Claude
Source: https://docs.tuturuuu.com/platform/features/sso

SAML identity-provider architecture, pilot decisions, and delivery boundaries

Tuturuuu is the proposed SAML 2.0 identity provider: an invited Claude organization
member signs into Claude through WorkOS using a Tuturuuu account. This is distinct
from inbound enterprise sign-in to Tuturuuu and from internal cross-app sessions.
No Supabase bearer token is shared with Claude.

## Pilot decisions

The pilot is SP-initiated and defaults to denied access. A future enabled client
selects exactly one active nonpersonal workspace. Each user needs current MEMBER
status, an explicit client assignment, a confirmed email in an approved domain,
fresh verified MFA no older than ten minutes, and identity-sharing approval on
every login. Guests, invitations and email-domain matches alone confer no access.
No workspace or test population has been selected by the protocol fixture.

Share only a stable random pairwise NameID/`id`, confirmed `email`, `firstName`
and `lastName`. Persist subjects per client/Auth account; do not derive them from
email or recycle them. An email change requires fresh verification and operator
review of Claude linking behavior before restoring SSO. Names are presentation,
never authorization. Claude owns roles, seats and invite-only provisioning.

The pilot excludes OIDC, SCIM, groups, IdP-initiated login and single logout.
Tuturuuu logout does not imply termination of an existing Claude session.
These decisions apply to future outbound SSO Web/consent/management surfaces;
ordinary Tuturuuu sign-in and cross-app session policy retain their own rules.

## Phase 1 protocol boundary

`packages/sso` provides strict Zod configuration/request/identity/assurance
contracts, bounded Redirect and POST AuthnRequest decoding, pinned request
signatures when required, signed response/assertion construction and public IdP
metadata without SLO. Clock, signer and ID generation are injected. Portable
entrypoints have no framework imports; the implementation targets Node crypto
and zlib for the future Next.js Node runtime on Vercel.

The selected libraries are `xml-crypto` 6.4.0 and `@xmldom/xmldom` 0.9.12.
RSA-SHA256 signatures, SHA256 digests and exclusive canonicalization are supplied
by the library. Request admission rejects unknown SPs, exact-URL mismatches,
stale requests, unsupported NameID/authentication contexts, passive interactions,
duplicate IDs/parameters, DTDs and oversized compressed/expanded XML. Unsigned
requests require an explicitly unsigned profile and do not authenticate the SP.

Assertions expire after two minutes and bind Audience, Recipient, Destination
and InResponseTo. The only supported NameID format is persistent; the connection's
actual requirements must be confirmed before enabling it. For both request
bindings, NameIDPolicy or AllowCreate omission means false, including signed
requests. Only explicit true/1 permits the future caller to allocate a subject;
otherwise it must find an existing mapping or deny. These defaults apply to the
portable protocol and future outbound SSO adapters, with no unsigned-request
exception. See `packages/sso/src/__tests__/security-review.test.ts` for omission
and invalid-boolean regression coverage. REFEDS MFA context
requires a future adapter to prove primary authentication and current TOTP MFA;
the package cannot establish assurance from a supplied timestamp alone.

Phase 1 adds no routes, UI, migrations, live clients or hosted configuration.
Metadata generation is a library function, not a published metadata endpoint.
Do not expose the protocol functions as an issuance API without the later gates.

## Phase 2 persistence boundary

Six additive migrations (`20261022100000` through `20261022100005`) introduce
`manage_sso_clients` and eight RLS-enabled private tables: `sso_clients`,
`sso_saml_clients`, `sso_assignments`, `sso_subjects`, `sso_disclosure_grants`,
`sso_transactions`, `sso_signing_keys` and `sso_audit_events`. All children carry
`ws_id` and composite tenant foreign keys. Creation always starts disabled;
client changes require an expected policy revision. The initial profile supports
only persistent NameID and one to eight exact HTTPS ACS destinations, without
credentials, fragments or custom ports. Configuration stores approved email
domains; authoritative email/domain enforcement belongs to phase 3.

Browser roles and `service_role` have no direct table privileges. Management is
through service-only `sso_manage_client` and `sso_set_assignment` RPCs. Both require
a current MEMBER in an active nonpersonal workspace with effective
`manage_sso_clients` permission (including the existing creator/admin semantics).
The server must resolve the authenticated actor before calling them; an actor ID
is a trusted server input, never a browser authorization claim.

Service-only `sso_create_transaction` reserves a request hash uniquely per client,
stores InResponseTo and an exact configured ACS, and caps expiry at five minutes.
Opaque handles, browser/session bindings and RelayState are hashes; raw RelayState
and assertions are absent. `sso_record_consent` records one immutable per-login
approval or denial for the fixed identity attribute list, binding actor, policy,
browser and session. Denial burns the transaction. `sso_consume_transaction` takes
row locks, rejects expired/used transactions, rechecks enabled client, policy,
current MEMBER and active assignment, and requires the matching approval and
bindings. The validated request's `allow_create` is persisted with default false;
allocation requires explicit true, while false can reuse an existing mapping.
Consumption, random 256-bit pairwise subject allocation and audit append
commit together. Concurrent consumers yield one winner and a replay error.

`authenticated` users can call `sso_read_own_disclosures(ws_id)` to read up to 100
of their own receipts. Its actor comes exclusively from `auth.uid()`. Other users
and anonymous callers cannot read those receipts. Disclosure receipts and audit
rows reject updates and deletes; audit appends expose only bounded event codes
and correlation IDs. `sso_append_audit` is service-only and requires a consumed,
approved transaction for issuance events. A signed event records the issuer's
observation; it does not prove Claude accepted the response.

Signing-key rows contain only a public certificate, kid, status, revision and
validity/rotation timestamps. A partial unique index permits at most one active
key per client. Certificate syntax constraints reject private-key PEM; the future
signer must validate the actual X.509 certificate and key match. No private key,
secret reference, key import/rotation RPC or signer route is added by this phase.
Subjects reference `auth.users`, so actual Auth deletion clears their user link
while reserving the random value. Auth deletion also clears client/assignment
creator attribution and deletes assignments and actor-bound transactions, even
though the public user row remains. Membership deletion cascades assignments;
MEMBER-to-GUEST demotion deletes them too. Rejoining or later promotion requires
an explicit new assignment. This rule applies to every phase 2 SSO client.

Workspace hard deletion cascades clients, protocol profiles, assignments, subjects,
transactions and public signing-key metadata, including disabled clients. Immutable
disclosure receipts and audit events retain denormalized workspace/client/actor/
transaction UUIDs without parent foreign keys. These historical receipts cannot
authorize a login without a live transaction and current membership/assignment.
Cleanup never disables or bypasses their append-only triggers. All eight tables
force RLS; approved definer RPCs retain their PostgreSQL BYPASSRLS owner, while a
non-BYPASSRLS table owner is subject to the policies.
Receipt/audit actors are UUID-only correlation values without deletion-blocking
user foreign keys; retention and pseudonymization require the phase 5 operating
policy. There is no automatic retention job in this phase.

### Database verification

From the repository root, run:

```sh theme={null}
ttr resources run -- node apps/database/scripts/verify-sso-persistence.mjs
```

The runner stages the complete migration history into an owned disposable
Supabase project, applies it with `supabase start` and `supabase db reset`, runs
`sso-persistence.sql` with strict pgTAP parsing, and drives a real two-connection
consume race. It generates `packages/types/src/supabase.ts` from that same applied
`public,private,storage` schema, then stops only the owned database without backup.
Synthetic race rows are committed only inside the disposable database and vanish
with its teardown; immutable audit rows are never bypassed for fixture cleanup.
Each race uses fresh UUIDs so repeat runs preserve retained user/workspace history.
The pgTAP packet covers membership removal/rejoin, demotion/promotion, real Auth
deletion (including retained public users), creator and workspace deletion,
byte-identical retained history, and a non-BYPASSRLS table owner. The separate race
requires one winner, one replay rejection, one subject and one consume audit.
It also races membership deletion and assignment deactivation against consume in
both orders. The holder observes its own PID blocking the competitor before it
commits: revocation first must deny consume without a subject or consume audit;
consume first must commit before revocation can commit. Both orders deny a later
consume. Assignment deactivation uses direct SQL so the management RPC's client
lock cannot mask missing authorization-row locks. Keep lock-removal negative
controls confined to a disposable database; never alter production migrations
to make the harness pass.

When the committed base type snapshot already lags its applied schema, generate
both the clean base and candidate using the same CLI and formatter. Apply their
generated delta to the committed base with a three-way merge, failing on conflicts;
exclude unrelated baseline drift rather than manually editing generated objects.
The SSO-only committed type delta intentionally excludes existing employee-profile
objects absent from the base snapshot. The workflow artifact still contains the
complete applied schema. Check `packages/users-core` as well as the types package
after generation because new FK relationships affect nested select inference.

The runner prints a schema snapshot digest and recovery directory for a failed
cleanup. Use the existing isolated lifecycle cleanup procedure for that directory.
The `SSO persistence database contract` CI workflow repeats this on the exact PR
head. No application stack or build is needed for this check.

These primitives do not establish Auth account status, confirmed email, MFA,
request XML validation, key selection or an issuance permit. Phase 3 must provide
those checks, recheck current key/policy state after signing, and burn the original
transaction on an unknown signing outcome. Never interpret a consumed database
row as permission to retry or emit an assertion without those service gates.

## Verification and remaining work

`packages/sso/src/__tests__` drives generated signatures through Node-SAML's SP
consumer with disposable in-memory keys. Negative coverage includes wrapping,
tampered claims, unsigned assertions, wrong audience/ACS, expiration, replayed
InResponseTo, unknown SPs and deflate bombs. Node-SAML uses the same underlying
signature library; independent SAML parsing is not independent crypto validation.
Parser and XML-signature library failures expose fixed protocol error messages
without request-derived diagnostics. Wrapping regressions retain an intact signed
assertion beside a distinct unsigned attacker assertion, verify both original
assertion and renewed outer signatures, and assert semantic rejection.
The harness adds exact Destination/Recipient checks because Node-SAML 5.1.0 does
not enforce them for login responses. See `packages/sso/README.md` for dependency
advisories, limits, reproduction commands and the samlify evaluation.

Phase 2 supplies the private database primitives described above. Phase 3 adds
authoritative Auth/MFA/eligibility reads, disclosure enforcement, key/policy
revision fences, durable audit, disabled Web routes and a minimal bilingual
per-login consent page. Phase 4 supplies workspace management UI.
Phase 5 supplies rotation, compromise/disable procedures, an explicitly selected
test workspace and connection, exact-commit CI/runtime acceptance and real Claude
SSO tests. Runtime profile verification and actual Claude login remain unrun.

Run focused tests through `ttr resources run -- bun run --cwd packages/sso test`
and the package's `type-check` script. Require applicable exact-commit CI before
integration; no local release builds or production configuration changes are
part of this phase.

## Disabled issuance adapters (phase 3)

All endpoints return 404 unless the server-only `SSO_SAML_ENABLED` is exactly
`true`. No enabled client or production configuration is included in source.
The adapter additionally requires explicit server configuration, the applied
schema, an enabled nonpersonal-workspace client, active current public signing-key
metadata, and matching private signing material. Missing dependencies fail closed.
The initial adapter supports one pinned client, one exact ACS, persistent NameID
and TOTP MFA. Other MFA methods and multiple ACS profiles remain unqualified.

| Endpoint | Purpose |
| - | - |
| `GET /api/v1/sso/saml/[clientId]/metadata` | Public metadata, subject to the flag and key/config checks |
| `GET /api/v1/sso/saml/[clientId]/sso` | HTTP-Redirect request admission |
| `POST /api/v1/sso/saml/[clientId]/sso` | HTTP-POST request admission, including browsers without ambient cookies |
| `/{locale}/sso/consent?transaction={handle}` | English/Vietnamese account, destination and attribute disclosure |
| `POST /api/v1/sso/transactions/[transactionId]/decision` | Same-origin, account/session-bound CSRF approval or denial; the path parameter is an opaque handle |

Admission validates the request against the registered SP and reserves its unique
request ID through `sso_create_transaction`. An encrypted Secure, HttpOnly,
host-only cookie preserves the exact validated request and RelayState. Navigation
URLs contain only the opaque handle. Parallel transactions have separate cookies;
oversized state is rejected rather than truncated. The transaction lasts 290
seconds, leaving transit margin below the database's five-minute maximum.
A verified account/session present at admission is hashed into an immutable starter
binding. Signed-out and cross-site POST admission remain supported: the first
authenticated continuation atomically claims the unbound transaction before any
consent form or decision. Consent reloads and decision POSTs must match that
user/session pair. Switching accounts or signing in again with a new session burns
and audits the pending transaction; restart SSO from the SP. Refreshing tokens
within the same provider session preserves the binding. This rule applies to all
outbound SAML clients, including optional-MFA accounts, with no account-switch
exception. Route/page regressions are in `apps/web/src/app/api/v1/sso/routes.test.ts`;
SQL binding and invalidation coverage is in `supabase/tests/sso-persistence.sql`.

Before approval and after signing, the adapter revalidates the provider cookie's
account, fresh Auth email and server-owned recovery policy. It reuses
`checkRequiredAccountMfa`, verified claims, `bindCurrentMfaFactor` and the existing
primary-authentication policy. Optional-MFA accounts still need a current
factor-bound TOTP proof at most ten minutes old. Refresh `iat` is not MFA evidence.
ForceAuthn additionally requires primary authentication and MFA after the SP
request. The consent page links to the existing login/MFA flow with a local
return path. For an already authenticated account needing fresh MFA it reuses the
existing required-MFA enrollment surface and Supabase challenge/verify service;
an explicit sign-in-again action supplies ForceAuthn/recovery primary login.

Current MEMBER status and explicit assignment are checked in both portable policy
and transactional RPCs. Names must be explicit `given_name` and `family_name`
profile fields; the adapter does not split display names. Only fresh confirmed
Auth email is shared. Names confer no access. Phase-2 random 64-character hex
subjects are accepted as pairwise persistent NameID and `id`; earlier UUID
protocol fixtures remain supported.

Every admitted decision records immutable per-login consent or a browser-bound
rejection. Consent and consumption retain phase-2 atomic auditing.
Rejected decisions can burn only an actor-unbound pending transaction; a losing
concurrent decision cannot cancel another decision's committed consent. After consume,
failures append `issuance.failed` through the audit RPC. The new
`sso_finalize_issuance` locks and rechecks the client, MEMBER, assignment, active
key revision, expiry and five-second issuance window, then invokes the same
append-only audit RPC for `issuance.signed`. Finalization cannot be replayed. No
response is emitted on audit/finalization failure, disable or elapsed budget.
After the finalization RPC, the service checks the verified final principal's MFA
age again before releasing the signed response. The inclusive ten-minute cutoff
also covers RPC transit time; stale assurance burns issuance and requires SP
restart after reauthentication. `packages/sso/src/__tests__/service.test.ts` covers
finalization crossing that cutoff within the five-second budget and a valid
boundary control.
Unknown outcomes are never retried; restart at the SP. Invalid requests without a
validated transaction have no client/actor audit attribution.

The adapter signs assertion and response, then returns an auto-submitting form
to the exact stored ACS, with a localized submit fallback. Its CSP permits only
that form destination and a nonce-bound script. It uses no external assets and
sets `no-store`, `no-referrer` and framing denial. Consent pages also deny caching
and framing. The finalized permit has a bounded emission window; it cannot
revoke an assertion or Claude session already delivered.

The existing Redis limiter is used with fail-closed behavior: 20 starts/minute
per IP/client, 10 decisions/minute per account/client, and 100 starts or
decisions/minute per client. Metadata is limited to 20 reads per IP/client/minute.
Deployment must sanitize the forwarded IP header. The per-client ceiling applies
independently of IP attribution.

### Server configuration

These variables are server-only. Never use `NEXT_PUBLIC_` prefixes, print secret
values, store private keys in the database, or reuse internal session signing keys.

Existing server Supabase configuration supplies Auth and service-only RPC access.
`sso_issuance_snapshot`, `sso_finalize_issuance` and `sso_reject_transaction` grant
no direct table privileges or browser execution rights. Their key projection
contains public certificates only.

### Runbook for a later pilot

1. Keep server flag and client disabled. Require exact-commit Web build, lint,
   type-check, protocol/route and database-contract CI. Apply migrations through
   authorized staging/production workflows and verify their separate results;
   never manually push schema changes.
2. Obtain separate authorization for one nonpersonal workspace, named MEMBERs,
   company domains and Claude parent connection. Confirm the actual WorkOS
   entity ID, ACS, request-signature mode, NameID policy and attribute mapping.
   Keep Claude enforcement/JIT off and preserve an Owner recovery path.
3. Through the trusted operator boundary, provision a dedicated RSA secret,
   install only its public certificate/current revision in key metadata, and
   configure the independent transaction secret and limiter. Key management UI
   remains a later phase; this PR provides no provisioning bypass or enabled
   client. Verify names, email, assignment and current MFA for each invited user.
4. Enable only the authorized pilot configuration after these gates. Fetch
   metadata from the canonical host and verify issuer, endpoint and certificate
   fingerprint. Upload it in Claude's actual setup portal. Run Test SSO and
   normal sign-in, then denial, stale/removed MFA, unassigned/guest/removed-member,
   expired/replayed request and disable cases. Retain private redacted correlation
   evidence; do not publish raw assertions.
5. To stop issuance, set `SSO_SAML_ENABLED` off and disable the client through the
   revision-checked management boundary. Confirm new starts/decisions deny.
   Retain consent and audit history. Handle existing Claude sessions through
   Claude's own controls; Tuturuuu logout is not SLO.
6. For rotation or compromise recovery, disable issuance, replace the secret and
   active public-key metadata with a new revision, update SP trust, and rerun
   real acceptance before enabling. Overlapping metadata certificates/seamless
   rotation require later qualification; this adapter publishes one active key.

### Regression evidence and remaining gates

`packages/sso/src/__tests__/policy.test.ts` and `service.test.ts` exercise actual
portable policy/orchestration, including a response consumed by the phase-1
Node-SAML SP. `apps/web/src/app/api/v1/sso/routes.test.ts` calls real route exports,
parser, policy, encrypted cookies and signer, with mocked Supabase Auth/RPC and
limiter transport. `rate-limit-sso.test.ts` covers unavailable limiter storage.
The applied-schema pgTAP fixture covers the service-only snapshot, finalization
and rejection contracts and retains the real consume/revocation races. These
fixtures do not establish hosted Auth/cookies/PostgREST or Claude behavior.
Browser accessibility/layout, actual login/MFA return, hosted custody, rotation
and real WorkOS acceptance remain pilot gates.

## Workspace administration (phase 4)

Open **Single sign-on** in the workspace navigation, or follow its link from
workspace settings (`/{locale}/{wsId}/sso`). This is outbound SSO application
management, separate from incoming enterprise sign-in. Only current MEMBERs of
an active nonpersonal workspace with `manage_sso_clients` can open it. The same
permission and MEMBER checks apply to every management API and service RPC.

1. Select **Add SSO application**. Give it the Claude organization name, the
   exact SP entity ID and canonical HTTPS ACS from that WorkOS connection, and
   comma-separated lowercase approved email domains. The current pilot supports
   one exact ACS and persistent pairwise NameID. Choose the actual request-signing
   policy explicitly; required signatures need the SP's RSA public certificate.
   Unsigned requests are a deliberate configuration choice. No remote metadata or
   certificate URL is fetched.
2. Complete current factor-bound TOTP verification when prompted. All trust,
   enable/disable and assignment writes require a verified proof no older than
   ten minutes, including optional-MFA accounts. Verification does not replay a
   failed mutation: submit again after checking its current state.
3. Save the application. Creation is always disabled. Saving edited trust also
   disables the application in the UI; review and enable it as a separate action.
   Legacy applications retain the deployment-pinned request-signature policy
   until saved with an explicit policy. They can always be disabled without
   resubmitting trust settings. Revisions prevent stale edits from overwriting
   concurrent administrator changes. On a conflict or unknown result, refresh
   before making another change; mutations are never retried automatically.
   While editing, Refresh explicitly discards unsaved edits, reloads
   the latest revision and trust fields, and confirms that values were reloaded.
   Ordinary background refreshes preserve editor values. Both ordinary editor
   refresh and conflict-refresh-save regressions in `sso-management.test.tsx`
   verify the next intentional save uses the refreshed revision and trust values.
4. Select the application and assign named test MEMBERs. Guests and invitations
   do not appear. The assignment RPC rechecks current membership atomically;
   stale roster entries cannot assign a demoted member. Revocation prevents future
   issuance but does not end existing Claude sessions, invite a user to Claude,
   purchase seats or change Claude roles.
5. Copy the IdP entity ID, SSO URL and active **public** certificate into the
   Claude custom SAML provider setup, or use its metadata URL if the portal
   supports import. Setup URLs come only from `SSO_SAML_ORIGIN`, never the request
   Host. A missing canonical origin is shown explicitly. The deployment-selected
   client, global flag and provisioned active key remain separate requirements;
   metadata itself remains unavailable while the global/client gate is off.
6. After separately authorized pilot verification, select **Enable** and confirm
   in the application dialog. The UI shows the current server-side
   `SSO_SAML_ENABLED` state and has no control that can change it. A client enabled
   while the flag is off remains inert. The phase-3 deployment still selects one
   client through `SSO_SAML_CLIENT_ID`; other configured clients cannot issue.

The public-key panel shows kid, status, public certificate, validity and creation,
activation, retirement and revocation timestamps. It offers no private-key import,
creation or rotation control. Dedicated private-key provisioning and SP trust
rotation remain trusted operator operations. The latest 50 audit events expose
only event id/type, policy revision and time, excluding raw assertions, email,
actor/session/transaction identifiers and private material. A prepared signed
response is not a successful Claude-login receipt.

### Management transport and regression boundaries

`@tuturuuu/internal-api/sso` owns the typed browser transport; the Web UI uses
TanStack Query with workspace/client query keys and no automatic write retries.
All new handlers live in `apps/web/src/app/api/v1/workspaces/[wsId]/sso/`:

| Method and path (relative to `/api/v1/workspaces/{wsId}/sso`) | Behavior |
| - | - |
| `GET /clients` | Authorized clients and current server global flag |
| `POST /clients` | Validated, disabled application creation |
| `GET /clients/{clientId}` | MEMBER assignment roster, public keys, 50 sanitized audit events and canonical setup URLs |
| `PATCH /clients/{clientId}` | Revision-checked SP trust update; explicit confirmation required if enabled |
| `PUT /clients/{clientId}/activation` | Revision-checked enable or disable; enable requires explicit confirmation |
| `PUT /clients/{clientId}/assignments` | Revision-checked MEMBER assignment or revocation |

The additive migration keeps private table access revoked. New read projections
and trust/activation writes are service-only definers with an empty search path,
canonical workspace/client predicates and the phase-2 manager assertion. The
trust writer composes the existing client RPC in one transaction so policy
revision, SP settings and audit either all commit or all roll back. New clients
persist their signature policy; issuance uses it, while unchanged legacy profiles
retain the deployment setting as a compatibility boundary. Server configuration
still needs the phase-3 deployment variables above.

`management.test.ts` calls the real HTTP exports against mocked Auth/RPC transport
for unauthenticated, non-manager, guest and foreign-workspace denial, confirmation,
MFA age, exact ACS validation and sanitized disclosure. Guest mutation authority
is independently covered in the applied-schema `sso-persistence.sql` fixture.
`sso-management.test.tsx` drives creation, disabled trust edits, confirmation,
assignment/revocation and public copy controls using the shared dialog components.
`packages/internal-api/src/sso.test.ts` verifies the actual transport contract.
These checks do not establish hosted Auth/PostgREST, browser layout, production
configuration or real Claude/WorkOS acceptance; those remain pilot gates.

# Task reminder delivery
Source: https://docs.tuturuuu.com/platform/features/task-reminder-delivery

Current-task revision and cancellation checks before deadline reminder dispatch

## Queued deadline reminder cancellation

Web dispatch rechecks deadline reminders against the current task before email
or push delivery, including reminders for changes made in Tasks and Calendar.
The default is to skip a reminder when its due-date instant has changed, its due
date was removed, the task was completed, closed or deleted, its list became
review/done/closed, or the recipient stopped watching it. Equivalent timezone
representations of the same instant retain the reminder revision.

The lookup binds the task, workspace and recipient. Unknown bindings, malformed
current state and failed lookups remain errors rather than confirmed cancellation.
Lifecycle cancellation applies before a send; a task edit after a provider timeout
cannot turn unknown provider acceptance into a confirmed skipped delivery.
Skipped delivery logs retain their reason; existing inbox records and reminder
history are preserved. Ordinary task activity notifications retain their existing
rules. Email preferences, recipient suppression and the one-day overdue cutoff
still apply.

This dispatch check does not lock concurrent task edits across a provider send,
deduplicate concurrent reminder producers, or add persisted snooze, quiet hours,
digests or configuration UI. Those capabilities require separate implementation
and runtime evidence. No scheduler configuration changes accompany this rule.

Regression coverage uses `packages/utils/src/__tests__/task-reminder-lifecycle.test.ts`,
`apps/web/src/lib/notifications/task-reminder-lifecycle.test.ts` and
`apps/web/src/lib/notifications/cron-helpers.test.ts` for revision, cancellation,
timezone, recipient and tenant boundaries. Provider delivery and deployed
behavior remain separate acceptance gates.

# Usage accounting safety guards
Source: https://docs.tuturuuu.com/platform/features/usage-accounting-guards

Failure behavior for AI budgets, storage capacity and subscription seats.

## Fail closed for new consumption

Unknown usage is not zero usage. AI credit lookups reject malformed allowance
rows; generation output budgets reject missing model prices and use the highest
applicable output-token price. The technical output ceiling is 65,536 tokens,
independent of available credits. Existing atomic AI reservation paths remain
responsible for their full request budget and settlement; an output cap is not
a substitute for input, tool, retry or media accounting.

Workspace storage rejects missing object sizes, invalid limits and unsafe byte
arithmetic. App-managed artifacts count toward upload capacity even when hidden
from ordinary Drive browsing. Infrastructure delegates to the same shared storage implementation.
If object sizes cannot be verified, the usage overview reports an accounting
failure rather than a misleading zero. File listing and download paths remain
separate and do not call the quota overview. When diagnosing a denied upload, verify object metadata and the quota RPC instead
of adding an unlimited override. Capacity checks do not yet atomically reserve
all concurrent signed uploads; final-object verification and provider reconciliation
remain required before selling new storage/egress add-ons.

Subscription provider lookup failure does not authorize creation of a duplicate
Free subscription. Seat availability rejects failed counts, missing products and
invalid purchased quantities. Active, trialing and past-due subscriptions use the
existing seat policy. Readable existing data is preserved; new capacity changes
must wait for accounting recovery. The Rust billing port mirrors these semantics
but does not serve production traffic. Invitation acceptance assigns a Polar seat
before exposing membership and stops when assignment fails. Polar rejects seat
reductions below pending plus claimed assignments, so that provider operation
protects in-flight assigned invitations beyond the local member-count check.
See [Polar seat management](https://polar.sh/docs/guides/seat-based-pricing).
Other membership paths and provider reconciliation still require coverage; this
is not a claim of a shared database/provider transaction.

## Provider catalog safety

Legacy product normalization recognizes one active fixed, Free or flat seat price.
New paid self-serve purchases require a supported flat seat price; recognizing a
legacy fixed product does not make it eligible for a new self-serve purchase.
Ambiguous, graduated, invalid or non-USD subscription prices cannot be flattened
into a misleading amount. Archived products can still be marked archived when
they have no active price. Product IDs, intervals and pricing model must be
explicitly bound before a catalog update; display names are not identifiers.

These controls do not activate new prices, reduce existing AI grants, or implement
a complete cross-product billing ledger. Use the commercial rollout runbook for
versioned allowance changes, provider reconciliation and existing-customer notice.

## Meeting lifecycle accounting

New rooms retain their first-admission deadline. Admitted legacy snapshots without
a stored deadline end on observation because departed participants make their
original start time unrecoverable. Legacy
participant time before observation remains unknown and is marked as incomplete
in the usage response and UI; it is never backfilled as a fabricated zero-cost history.
Lobby approvals carry the room deadline. Successful provider publications that
cannot be committed after a leave or room end are queued for durable cleanup.
Cleanup completion removes only confirmed obligations and preserves newer usage
counters and cleanup requests. The local server stops its sweep when stopped.

Cleanup reads Cloudflare session state to recover missing legacy provider mids by
local track name, and settles mixed close responses per mid. Unidentifiable tracks
remain pending for investigation; they cannot prevent later sessions from closing.
Room termination resets prior cleanup backoff. The lobby remains independently
bounded while active capacity is full; host approval still enforces active limits.
Provider contract: [Cloudflare SFU Connection API](https://developers.cloudflare.com/realtime/sfu/https-api/).

# User Management
Source: https://docs.tuturuuu.com/platform/features/user-management

A central place to manage users, groups, and information about them.

## Post Email Delivery Recovery

The post email queue now treats provider-accepted delivery as durable once it is written to `email_audit`. The `sent_emails` table is still the primary history surface for the product UI, but queue retries must not resend a post email just because the follow-up `sent_emails` insert or `user_group_post_checks.email_id` link failed.

### Recovery Rules

* `email_audit` is created before a send and updated to `sent` immediately after provider success.
* Batch processing checks both `sent_emails` and matching `email_audit` entries for the same post-recipient pair before sending.
* If an audit record proves the email was already sent, the worker marks the queue row as `sent` and backfills `sent_emails` opportunistically instead of resending.
* If provider delivery succeeds but local `sent_emails` persistence fails, the queue row still transitions to `sent` with a warning in `last_error` so the system does not retry the message.

### Claiming Strategy

* The queue worker should only claim rows that it can start in the current processing slice.
* Avoid front-claiming the whole `sendLimit`; stranded `processing` rows interact badly with stale cleanup and can create duplicate delivery attempts after requeue.
* Rejected-recipient cleanup must remain a set-wise private RPC. Scanning every rejected check and updating recipient pairs one at a time can consume the cron's runtime before approved messages are claimed.

### Operations Dashboard

* The infrastructure Post Email Queue page shows approval/delivery backlog health, age buckets, throughput, sanitized failure categories, workspace breakdowns, and recent batch summaries.
* Operators should use the page's Run Now action instead of calling the cron endpoint from the browser. The app route keeps `CRON_SECRET` server-side and invokes `/api/cron/process-post-email-queue` with diagnostic output.
* The cron defaults are tuned for production backlogs: `limit=500` and `sendLimit=200`. Query parameters may still lower those values for focused recovery runs.
* When a recipient is approved but still shown as queued in the Posts dashboard, inspect the selected-recipient delivery diagnostics before assuming approval failed. Queue age over 1 hour is a warning; queue age over 24 hours should be treated as an incident.

## Attendance Exports

The workspace attendance page now supports exporting attendance for everyone across a selected date range.

### Behavior

* The export is inclusive: records on both the start date and end date are included.
* Exports are workspace-wide and include all recorded attendance rows across groups in the selected period.
* The UI builds the file client-side, but the data source remains the authenticated internal API route at `/api/v1/workspaces/:wsId/users/attendance/export`.

### Implementation Notes

* Keep range filtering on the persisted `user_group_attendance.date` string values with `gte(startDate)` and `lte(endDate)` to avoid timezone drift.
* Attendance exports must bind both `workspace_user_groups.ws_id` and joined `workspace_users.ws_id` to the normalized route workspace before returning user names or private email fields.
* Page the API response for large exports instead of assuming a single Supabase page will return every matching row.
* Excel and CSV generation should stay in the client so the page can reuse localized column labels and progress feedback.

## Workspace Member Profiles

Workspace members can have workspace-specific display names, similar to server profiles.

### Behavior

* Member profile display names are stored on `workspace_users.display_name`, not on the global `users.display_name`.
* The workspace members settings page can edit display names for joined members and pending invites.
* Pending email invites may create a `workspace_users` row before the invited platform user joins.
* When the invited user later joins, `workspace_user_linked_users` should reuse exactly one unlinked `workspace_users` row with a matching email in the same workspace.
* If multiple matching workspace profiles exist for an email, runtime linking must not guess. Admin edit APIs should report the ambiguity so duplicate profiles can be resolved explicitly.
* The users database page includes a platform-link repair action for administrators with user-update and private-info permissions. It links only matching platform users who are already workspace members; it never creates workspace membership or merges duplicate workspace profiles.

### Implementation Notes

* Keep members-page writes narrow: update the workspace profile display name only.
* Always verify `manage_workspace_members` before writing member profiles from the members settings UI.
* Enhanced member listing should display the workspace profile name when available and fall back to the platform user display name.
* Auto-linking runs on `workspace_members` insert. If a virtual profile is created or its email is corrected after membership already exists, use the database-page repair action to reconcile the link.
* Repair is conservative: a link is inserted only when one unlinked workspace profile and one existing member platform account share the same normalized email. Missing emails, no member match, duplicate workspace profiles, duplicate platform matches, and platform accounts already linked elsewhere are reported as skipped cases.

## Attendance Manager Visibility And Counting

In Contacts workspace settings, open **Attendance → Display & Totals**, turn off **Show Managers in Attendance**, and save. The setting is shared by every group attendance-taking view. Both attendance settings default on for workspaces without an explicit value.

* `ATTENDANCE_SHOW_MANAGERS=false` hides members whose role in that group is `TEACHER` (the group manager/teacher role) from attendance-taking rosters and their on-screen totals. It applies to the Contacts attendance page, group detail attendance, the shared web attendance client, and the TanStack replacement. It does not remove a manager from the group, alter saved attendance, or erase historical records and exports.
* The setting is read for the first server render of group detail attendance. Client-only rosters wait for the setting before showing managers, so a hidden manager does not briefly appear while the setting loads or refreshes. The setting is scoped to the workspace, not an individual browser or group.
* `ATTENDANCE_COUNT_MANAGERS` controls the separate group-list attendance totals. When enabled, group managers count toward those totals. When disabled, the totals subtract group managers from the group member count.

When a product change touches attendance, check the settings UI, every roster entry point, summary counts, exports, and the live Next.js API plus the TanStack/Rust migration path. Record any intentional difference here before release so a later app port cannot reintroduce a resolved behavior.

## User Group Activity Audit Logs

User group activity is exposed from the dashboard at `/users/groups?tab=audit-log` and on each group detail page. The feed is normalized from `audit.record_version` through private service-role RPCs so UI code receives one event shape with action, resource type, group, affected user, actor, timestamp, and before/after snapshots.

The Contacts audit view must show a distinct error when the feed query fails. An unavailable feed is not evidence that no changes occurred. Investigate the server error and the `private.list_user_group_activity_logs` RPC before using an empty view to reconcile a student's history. Existing membership rows show their current join timestamp; an audit event is needed to establish a prior removal and rejoin. Neither a receipt for a different group nor membership history alone proves that tuition was transferred or credited to another class. Keep the original invoice and any explicit adjustment or transfer record when reconciling debt.

The feed reads a date range of `audit.record_version` before resolving groups and actors. Keep its partial date index aligned with the current `public` and `private` table names whenever a tracked resource moves schemas. A PostgreSQL `57014` timeout means the feed is unavailable, not empty; check the exact query plan and index validity before widening the statement timeout. The concurrent activity index migration `20260929130000_user_group_activity_current_schema_index.sql` restored schema alignment, but did not by itself resolve the Easy Center timeout. An OR-based workspace/group predicate and then an unscoped workspace-wide orphan scan also timed out after reaching production. The feed now builds indexed candidates for direct group events, workspace metadata, child records, workspace users, and metric categories. Historical group IDs retain member and attendance events after a group is deleted. The workspace-wide view retains feedback and child events that resolve through a student or category after their parent is deleted. Keep each branch's table predicate aligned with its partial index when adding an audited resource. The unfiltered workspace listing counts and sorts narrow candidate IDs, then calculates snapshots, labels, and actors for the selected page. Searches and group-scoped requests still use the full feed so filters see enriched fields. The listing RPC owns ordering; do not sort every wide feed row inside `user_group_activity_feed` as well. Compare candidate IDs and counts with the full feed, benchmark a representative 30-day range locally, and verify live response time after release. The three-argument feed delegates to the same implementation.

### Local performance verification

The fast-page migrations preserve the existing RPC signature and service-role-only
access. Only the default unfiltered workspace request uses narrow IDs; search,
resource/action filters, group scope, and ranges whose snapshots reference
multiple fallback actor links retain the enriched path. Fallback actors may belong
to another workspace; the multiplicity guard checks eligible historical snapshot
references rather than current workspace ownership. It conservatively checks all
potential actor fields, including unchanged update fields. Narrow eligibility checks supported row operations
without calculating snapshot diffs. Action labels, changed fields, names, and
snapshots are still calculated for the selected page.

The 2026-09-30 same-data benchmark used isolated local PostgreSQL, synthetic
feedback events across 28 days, equally distributed inserts/updates/deletes,
roughly 1.9 KiB content snapshots, 4 MB `work_mem`, and a 20-row page at offset 20.
Both implementations read the same rows in one session. Each had one warm-up and
five measured runs; the p95 values below are interpolated from these five samples,
not production SLA estimates.

| Events | Baseline median / sample p95 | Fast median / sample p95 | Baseline temp read / written blocks | Fast temp read / written blocks |
| - | - | - | - | - |
| 24,000 | 2,632 / 2,737 ms | 513 / 527 ms | 24,685 / 25,039 | 0 / 0 |
| 48,000 | 5,403 / 6,041 ms | 994 / 1,035 ms | 49,723 / 50,077 | 0 / 0 |
| 96,000 | 10,928 / 12,989 ms | 2,027 / 2,371 ms | 99,796 / 100,150 | 639 / 611 |

An additional 48k fixture with an unrelated virtual actor in another workspace
linked to two platform users measured baseline median/sample p95 5,651/5,842 ms
versus fast 2,379/2,701 ms. The scoped ambiguity check adds work but retains early
pagination when those actor IDs are absent from the audit snapshots. Use the
harness option `unrelated_actor_links=true` to reproduce this case.

Full-row multiset equality, including counts and snapshots, passed at every size.
The regression suite also covers all 18 resources and three operations, tied
sorting, offsets and normalized limits, date boundaries, filters, workspace
isolation, same-workspace and cross-workspace fallback actor multiplicity,
service-role execution, and actual denied
anon/authenticated calls. Restrictive MFA policies must not be counted as
permissive access grants in policy assertions; no policy or grant is changed by
this optimization.

The reproducible rollback-only harness and raw JSON samples are in
`apps/database/supabase/benchmarks/user-group-activity-fast-page.sql` and
`user-group-activity-fast-page-results.json`. Use a disposable database named
`audit_benchmark_*` or `audit_takeover_*`; the harness rejects other names. Install
the previous listing from migration
`20260929153000_scope_user_group_activity_before_enrichment.sql` under the test-only
name `private.list_user_group_activity_logs_baseline`, then apply the three
fast-page migrations. Run through the resource queue with `psql` variables
`size=48000` and `baseline_rpc=list_user_group_activity_logs_baseline`. Benchmark
rows roll back. Never run this synthetic fixture against shared or production data.

Candidate resolution extracts the snapshot anchor fields together before parent
joins. Repeated `->>` calls on large TOASTed JSON can fetch the same snapshot
for each join even when the required partial indexes are valid. Preserve
`try_parse_uuid`, current/old fallback, and workspace precedence when changing
anchor extraction; malformed non-object snapshots retain null-field behavior.
Use `user-group-activity-anchor-extraction.sql` to compare the deployed candidate
helper with this follow-up on the same synthetic mixed-operation history. It
includes representative parent cardinality and both inline (`toast_snapshots=false`)
and TOASTed (`toast_snapshots=true`) snapshots. Keep production timeout settings
unchanged while diagnosing; a warm fixed-window success does not prove the
default rolling 30-day request is stable.

The anchor-extraction benchmark adds 72,000 mixed-operation activity snapshots
and 570,000 unrelated older audit rows, with representative user/group/post/report
cardinality. Alternating implementations on the same data (one warm-up and five
measured runs) produced:

| Snapshot storage | Before median / sample p95 | After median / sample p95 | Before / after median shared buffer hits |
| - | - | - | - |
| Inline | 1,163 / 1,426 ms | 1,175 / 1,411 ms | 118,303 / 85,306 |
| TOASTed | 2,972 / 3,727 ms | 2,373 / 2,503 ms | 3,561,903 / 1,411,338 |

Candidate and full-page multiset parity passed in both scenarios. Raw samples
and exact source hashes are in `user-group-activity-anchor-extraction-results.json`.
These local measurements do not establish production latency or an SLA. Confirm
the default rolling 30-day UI after release; retain an unavailable state for a
timeout rather than displaying an empty history.

Broad tests on the schema-only local fixture reproduced 43 failing suites on the
original HEAD. Two stale audit policy assertions are repaired here; the remaining
41 unrelated failures have identical baseline failure records. This fixture omits
scheduler setup and migration-seeded reference catalogs. A separate fresh
Supabase bootstrap applies the migrations and passes the 24-case parity suite;
its full test run has 35 failing suites before the change and 33 afterwards,
with no new failures and identical existing failure summaries. Type generation
from that fresh schema and a non-emitting type check pass. The full suite is
therefore still blocked by unrelated failures. Require green exact-commit CI,
plus a read-only live 30-day workspace/group/filter check after
production rollout before declaring the original timeout fixed.

### Tracked Resources

* Group metadata and status: `workspace_user_groups`.
* Membership and manager role changes: `workspace_user_groups_users`.
* Group tags and default included groups: `workspace_user_group_tag_groups`, `workspace_default_included_user_groups`.
* Posts, post logs, and post checks: `user_group_posts`, `user_group_post_logs`, `user_group_post_checks`.
* Attendance, linked products, metrics, categories, category links, and student metric values: `user_group_attendance`, `user_group_linked_products`, `user_group_metrics`, `user_group_metric_categories`, `user_group_metric_category_links`, `user_indicators`.
* Reports and feedback: `external_user_monthly_reports`, `external_user_monthly_report_logs`, `user_feedbacks`.
* Course content: `workspace_course_modules`, `workspace_course_module_groups`.

### Actor Attribution

* Core group, member, metric, student metric value, and attendance mutations should use the private actor-aware RPCs so service-role writes set `audit.override_auth_uid` before changing rows.
* Other tracked tables still appear when raw audit rows exist. If a route writes with a service-role client and the table does not preserve actor intent in columns such as `creator_id` or `updated_by`, add a focused actor-aware private RPC or route-level activity insert before expanding the UI around that resource.
* Bulk reorder operations are normalized as `reordered` events when the persisted `sort_key` changes.

### Workspace Validation

* Before any admin write, normalize the route `wsId` and verify the target group belongs to that workspace.
* Member writes must also verify every affected `workspace_users.id` belongs to the same normalized workspace before inserting, updating, or deleting membership rows.
* Attendance writes must additionally verify every affected user is already a member of the target `workspace_user_groups_users` row before inserting or deleting `user_group_attendance`.
* Child resource writes should validate their parent group or parent module group before the admin mutation. Do not rely on a raw `group_id` from the URL without checking ownership.

## Topic Announcements

Topic Announcements live under Users and are gated by the workspace secret `ENABLE_TOPIC_ANNOUNCEMENTS=true`.

### Behavior

* Contacts are workspace-scoped and may be raw email contacts or linked to an existing workspace virtual user profile. The linker UI searches workspace users with avatar and email affordances.
* Announcements may optionally reference a real `workspace_user_groups` row through `group_id` for scheduling and reporting context.
* A contact cannot receive announcements until its email is verified through the Tuturuuu internal SES verification flow or through a linked Tuturuuu platform account with a confirmed matching email **and membership in the same workspace**. Platform-wide confirmed accounts must not auto-confirm a contact for another workspace.
* Announcements can include image and PDF attachments. The composer and API enforce the shared email limits: up to 5 files and 10 MB total per announcement.
* Verification emails are sent by the root Tuturuuu sender with normal protected delivery checks, not the rate-limit-bypassing system path.
* Verification links resolve to the public platform origin by default (`https://tuturuuu.com`) so listener hosts such as `0.0.0.0:7803` never leak into recipient inboxes. Set `TOPIC_ANNOUNCEMENT_VERIFICATION_ORIGIN` only when an explicit alternate public origin is required.
* Verification sends enforce a short pending-link cooldown before creating another token, and email delivery applies workspace, user, IP, and recipient limits. The recipient limit is global across workspaces, so one workspace or many workspaces cannot repeatedly send verification links to the same inbox.
* Actual announcements are sent by the enabled workspace sender and are written to `email_audit`.
* The composer and table send flow preview the same server-rendered HTML and text payload that delivery uses. Operators should review that rendered preview before sending or scheduling announcements.
* The first import preset supports foreign-teacher schedule rows with day/date, class, room, time, teacher/contact, email, place, and topic fields. The import UI now uses an editable Excel-like table as the review surface; uploaded spreadsheets, CSV, and direct paste all load into that table so operators can correct every email field before creating drafts or sending valid rows in bulk.
* Workspace-shared **announcement templates** store reusable title, topic starter text, class metadata, optional default group, and default recipient ids. Operators apply a template in the composer, then edit the topic field before sending.
* Operators can fork an existing sent or draft announcement into a new draft. The fork copies title, topic, class context, recipients, and attachment references, but never copies sent, queued, scheduled, or email audit state.
* **Scheduled send** sets `status = queued` and `scheduled_send_at` using the workspace's fixed IANA timezone from calendar settings. Scheduling is blocked while the workspace timezone is still `auto` or unset; use the same calendar timezone gate as the main calendar product.
* The `process-topic-announcement-queue` cron job (every 15 minutes) loads due queued rows and reuses the same `sendTopicAnnouncement` path as manual send. Failed sends keep the existing `failed` / `last_error` handling without infinite retries.
* Announcement list APIs enrich recipient rows with the same `verificationStatus` contract as the contacts list so the table does not treat missing status as unverified.

### Implementation Notes

* Client UI must call `@tuturuuu/internal-api` Topic Announcements helpers; do not add direct client-side fetches.
* Email preview must go through the Topic Announcements preview API and shared renderer instead of a client-only template so previews cannot drift from actual delivery.
* Bulk create/send must keep using the import API plus `send-bulk` helper from `@tuturuuu/internal-api`; do not bypass the shared renderer, recipient verification, or delivery gates for spreadsheet rows.
* Delivery APIs must check the workspace secret, `manage_users`, `send_user_group_post_emails`, recipient verification, and workspace ownership before sending.
* If a contact email changes, previous verification records for the old email must no longer satisfy delivery checks.
* Linked-account auto-confirm checks must join through `workspace_members` for the contact workspace. Do not treat a confirmed Tuturuuu account as sufficient unless that platform user belongs to the same workspace as the linked virtual user.
* Attachment uploads must prepare signed upload URLs through the central workspace storage route, then upload bytes directly to the active storage provider. Do not stream attachment bytes through Topic Announcement-specific Next.js routes.
* User group and course storage uploads are quota-sensitive and must use the server-mediated `uploadWorkspaceUserGroupStorageFile` / group storage multipart route. Do not mint signed upload URLs from this route because the app server cannot verify the final object size after a direct provider upload.
* Attachment rows keep workspace, announcement, storage path, content type, and size metadata. Email delivery downloads the stored files and switches to raw MIME only when attachments exist; regular no-attachment messages should keep the standard SES `SendEmailCommand` path.

### Mobile profile image optimization

Mobile avatars use a square crop; choose 512–1024 pixels per side. Banners use
web's 3:1 display aspect, for example 2400 by 800 pixels. The mobile optimizer
preserves aspect and never enlarges small images, fitting avatars within 1024 by
1024 and banners within the server's 2560 by 1440 canvas.

Camera/gallery selection uses the native picker with bounded dimensions and
quality conversion, including HEIC/HEIF to JPEG on iOS, followed by a native
JPEG crop. The shared optimizer runs decoding and encoding off the UI isolate,
bakes EXIF orientation, takes the first animation frame, and strips metadata.
Opaque photos and screenshots use JPEG quality steps (90, 82, 72, 60), then
progressively smaller dimensions until they fit. Transparent input retains PNG
when it fits at the current size; otherwise it is flattened onto white for JPEG.
The same optimizer handles offline replay and workspace avatars; there is no
second codec policy. Workspace avatar authorization and its separate storage
upload protocol retain their existing limits.

The source allowance is 20 MiB with a separate 20-megapixel decode ceiling,
bounding memory use on mobile devices. Input beyond these safety limits is
rejected before full pixel decoding, and oversized files before reading their
bytes. Upload targets remain 1,000,000 bytes for avatars and 2,000,000 for banners,
below the server's authoritative 2 MiB and 5 MiB caps. Only the exact profile PUT
paths with a nonempty `token` query parameter receive those proxy limits;
requests without one retain the generic 512 KiB cap. The handler still validates
the ticket. Unrelated API payloads retain their normal limit.
Actual streamed bytes, one-use tickets, upload budgets and server-side
WebP re-encoding remain authoritative; client sizes do not grant permission.
Proxy consumers import the dependency-free
`@tuturuuu/storage-core/profile-upload-limits` module. The server-only budget
module re-exports the same limits for existing handler callers.
Empty/corrupt images and native decode failures use invalid-image guidance,
rather than size guidance. Recovery uses a compact design-system alert and
retains fresh selection, dismissal and authorized sanitized diagnostics.

![Profile image recovery with a fresh selection and dismissal](https://mintcdn.com/tuturuuu/3Ywt5c_8lO9FcIox/images/mobile-profile-media-recovery-synthetic.png?fit=max\&auto=format\&n=3Ywt5c_8lO9FcIox\&q=85\&s=ff91867a44724696415e6697f69eb629)

Regression coverage: `profile_media_optimizer_test.dart` exercises phone JPEG,
PNG, tiny and panoramic images, orientation/metadata, transparency, the exact
20 MiB source boundary and rejection above it. `profile_native_media_options_test.dart`
covers picker/crop conversion options (real HEIC selection still needs device
acceptance). `profile_media_failure_mapping_test.dart` and the existing actor,
delivery and recovery suites cover errors and ownership.
`apps/web/src/lib/profile-media-proxy.test.ts` exercises the real proxy guard
and route exports, including valid ticketed images above the old 512 KiB proxy
ceiling and the generic cap for missing or empty tickets.

### Mobile profile banners

Mobile profile headers reserve a 3:1 banner area, including an empty placeholder,
image loading indicator and image-error fallback. Banner selection uses the native
camera/gallery chooser and a locked 3:1 crop, then the shared optimizer. Upload
and replacement reuse `POST /api/v1/users/me/banner/upload-url`, the signed PUT,
and `POST /api/v1/users/me/banner` with `action: finalize`; removal uses the latter
with `action: remove`. Each mutation retains its operation UUID and reloads the
actor's profile. These controls do not change shell navigation or account access.

Permission denial, size rejection, connection failure and invalid/expired upload
tickets have scoped English and Vietnamese guidance. Ticket failure asks for a
new selection; it does not bypass signature checks. Avatar upload authorization
continues to use its existing error mapping. Regression coverage lives in
`profile_banner_lifecycle_test.dart`, `profile_banner_states_test.dart`,
`profile_banner_picker_test.dart` and `profile_media_failure_contract_test.dart`.

### Browser profile capability uploads

The central avatar and banner upload endpoints expose credential-free CORS for
literal registered internal app origins, including Lettin and approved Portless
origins and ports, and exact configured external app origins. External matching
uses the configured protocol, host and port; it does not query database
registration or enabled state. Production HTTPS registrations do not admit HTTP
downgrades. Arbitrary host suffixes, localhost ports and forwarded hosts do not
grant access.

Explicit OPTIONS permits only PUT and Content-Type. It does not verify or consume
the upload capability, read a body or access Auth, lifecycle, optimizer or storage
services. Responses are not cached and vary on Origin and preflight method/header
names. Trusted-origin PUT success and errors expose the exact requesting origin
and retain existing Vary values. No credentials, Authorization or private network
access grant is added.

CORS controls browser response visibility. Upload authority still comes from the
short-lived, atomically consumed capability and its actor, kind and scope checks.
Untrusted origins receive no CORS grant; native requests without Origin retain
existing behavior. Banner issued-state checks, immutable storage and separate
finalization/replay rules remain in force. Transport unit regressions live in
`apps/web/src/lib/profile-media-upload-cors.test.ts` and
`apps/web/src/lib/profile-media-upload-put.test.ts`. These source checks do not
prove deployed browser preflight, persistence or finalization behavior.

## Public platform profiles

`tuturuuu.com/u/[username]` resolves the current canonical username and renders
only the user's avatar, banner, display name, and biography. The route supports
English and Vietnamese and anonymous access. Unknown or invalid usernames have no profile.
Public profiles are request-time reads and are not advertised for search indexing.
The storage projection and returned object independently allowlist the four
fields; email, account IDs, timestamps, workspace membership, and
activity are never selected or returned. HTTPS images reject embedded credentials.

Other profile information remains private unless the owner explicitly shares it
on an owning app surface. Workspace access and saving private identity fields do
not imply public-sharing consent. This initial platform page has no additional
field-sharing controls. Lettin provides an explicit saved opt-in for its About
section; canonical biography is public by default, while workspace data stays
private.
Public creator names link to the canonical platform profile when a username exists.
Regression evidence: `apps/web/src/lib/public-user-profile.test.ts` checks the
query and response allowlists, invalid/unknown usernames, failures, and artwork;
`public-paths.test.ts` checks anonymous localized access.

### Profile discovery across apps

The platform account menu and the shared Next satellite account menu offer Public
profile for signed-in accounts with a canonical username. The destination is the
central `/u/[username]` page, using the satellite's configured central origin.
Links open in a new tab so the current task and unsaved work remain available.
Accounts without a username have no public-profile link; private profile settings
remain available. No profile content or workspace data is copied across apps.
Framework adapters without a canonical username omit the optional menu item.
Regression coverage: `public-profile-url.test.ts` checks legacy usernames,
configured origins, and rejected paths; `satellite-user-menu-items.test.tsx`
checks signed-in, signed-out, and missing-profile menu behavior.

### Explicit public link copying

The public `/u/[username]` page offers an explicit copy-link control using the
canonical `https://tuturuuu.com/u/[username]` address. It copies only that routing
URL, never biography text, account metadata, private fields, workspace identifiers
or tracking query values. Default public fields remain avatar, banner, display
name and biography; additional details still require explicit owner sharing.
The control is an action for a visitor, not a new profile data field or a grant.
It does not send messages, create notifications or publish anything automatically.

The shared `PublicLinkButton` accepts only the canonical public-profile and
published-notebook route shapes. The owning surface must first provide an
already-public projection; URL validation is not authorization. It writes to the
clipboard only after a click, announces success, and offers a read-only selectable
URL after clipboard denial/unavailability. Duplicate clicks are fenced and old
completion is suppressed when the destination changes or the control unmounts.
App-provided English/Vietnamese labels keep the shared component free of implicit
translation namespace requirements. Regression coverage: `public-content-link.test.ts`,
`public-link-button.test.tsx` and profile page/projection tests. Hosted clipboard
permissions and exact-head app/shared-package CI remain separate evidence gates.

## Workspace User Avatar Paths

Web and Contacts user-avatar reads authorize the workspace through the existing
permission helper, then use its resolved lowercase UUID. Aliases such as
`personal` remain supported only when authorization resolves them to that UUID.
The shared read handler signs only `<workspace UUID>/users/<filename>` in the
`workspaces` bucket. It accepts exactly three original segments; it never repairs
or decodes a submitted object path. Full URLs, other workspaces, nested paths,
percent encodings, backslashes and control characters are rejected.

The shared upload handler requires `manage_users`, a PNG, JPEG, WebP or GIF
content type, and one filename of at most 255 ASCII letters, digits, dots,
underscores or hyphens starting with a letter or digit. It preserves the filename
and issues its `avatars` ticket only after charging the verified actor's upload
budget. These rules apply to shared handler callers; canonical Web and Contacts
POST routes retain their existing optimized media-ticket flow. There is no
DELETE handler in the shared user-avatar module.

Regression coverage lives in
`packages/users-core/src/routes/users/avatar.test.ts`. It exercises read and upload
traversal, foreign workspaces, invalid resolved IDs, alias resolution, authorization
and budget ordering with synthetic storage fixtures. Hosted Storage behavior is
a separate acceptance boundary.

# Get started with a workspace
Source: https://docs.tuturuuu.com/platform/guides/getting-started

Accounts, app selection, workspace identity, permissions, and safe first steps.

## Sign in and choose the right workspace

1. Open the [platform](https://tuturuuu.com) or a product from the
   [Apps gateway](https://apps.tuturuuu.com).
2. Complete central sign-in. Satellite apps use a coordinated session handoff;
   their login and verification URLs are not public content pages.
3. Choose your personal or team workspace. If you have a pending invitation,
   accept it through the app's invitation flow before expecting team access.
4. Open the product you need and check its access state. An app tile does not
   override membership, product flags, or a role's permissions.

A workspace is the boundary for team data and permissions. Browser routes can
use `personal`, `internal`, a UUID, or an accepted workspace handle. Persistent
records and server authorization use the resolved workspace UUID. Do not copy a
workspace slug into a database field that expects an ID.

See [Workspaces and permissions](/platform/architecture/workspaces-permissions)
for the full model and [Routing](/platform/architecture/routing) for redirects.

## Start with a small workflow

* Create a task in [Tasks](/platform/applications/tasks) and choose its board,
  status, assignee, and scheduling fields where available.
* Put a fixed appointment in [Calendar](/platform/applications/calendar).
  Scheduling suggestions and provider synchronization have their own state;
  saving a task is not proof that a provider calendar has synchronized.
* Track a work session in [Track](/platform/applications/track), then review
  its history instead of estimating completion from a running timer.
* Upload a file through [Drive](/platform/applications/drive) or start a
  [Chat](/platform/applications/chat) discussion with the right audience.

## Configure the experience

Theme and language controls are documented under
[Themes](/platform/personalization/themes) and
[Language](/platform/personalization/language). Sidebar customization is in
[Sidebar navigation](/platform/personalization/sidebar-navigation). Mobile
modules follow their own [default and experiment rules](/platform/features/mobile-workspace-tools).

A configured root destination applies when opening the app root; visiting a
workspace home directly keeps that home destination. Hidden workspaces can be
restored without deleting them: see [Hidden workspaces](/platform/features/hidden-workspaces).

## Understand sharing before publishing

Workspace membership, a shared link, a public form, a published storefront, and
an external app token are different access mechanisms. Share only through the
owning product's supported flow. A URL's presence in a browser or docs inventory
is not proof that its data is public. Search exclusion also does not replace
access controls. Read [Search indexing](/platform/features/search-indexing)
and the product's publishing guide.

If a module is unavailable, use [Troubleshooting](/platform/guides/troubleshooting)
before recreating an account or changing workspace data.

# Troubleshooting and glossary
Source: https://docs.tuturuuu.com/platform/guides/troubleshooting

Resolve access, stale data, scheduling, publication, and payment questions using the owning product.

## Troubleshoot by symptom

| Symptom | What to check | Detailed guide |
| - | - | - |
| Login loops or expired handoff | Central account session, intended app audience, local origin mapping, and MFA continuation | [Authentication](/platform/architecture/authentication), [Satellite apps](/platform/architecture/satellite-apps) |
| Workspace or module missing | Membership, hidden workspace state, product enablement, role permissions, and account eligibility | [Permissions](/platform/architecture/workspaces-permissions), [Contacts modules](/platform/applications/contacts-modules) |
| Calendar data looks old | Owning Infrastructure schedule, gateway result, and provider sync timestamp with clients closed | [Active runtime](/build/devops/active-runtime), [Calendar](/platform/applications/calendar) |
| AI request unavailable | Model policy, provider setup, whitelist/entitlement, credits, and request error | [Model catalog](/platform/ai/model-catalog), [Usage guards](/platform/features/usage-accounting-guards) |
| Shared form inaccessible | Publication/access mode, share code, author controls, and session requirements | [Forms](/platform/applications/forms) |
| A world update is not public | Whether the new draft revision was explicitly published | [Tulletin](/platform/features/lettin) |
| Checkout returned but order is pending | Provider confirmation/webhook and order audit state | [Storefront](/platform/applications/storefront), [Inventory](/platform/applications/inventory) |
| Search does not show a page | Public eligibility, noindex, canonical, sitemap, response status, and Search Console evidence | [SEO runbook](/build/development-tools/public-seo) |
| Old Docker cron status is stale | The Docker runner is retired; inspect the owning hosted scheduler | [Active runtime](/build/devops/active-runtime) |
| Rust/TanStack setup fails | These runtimes are not in use; use the maintained Next.js path | [Without Docker](/build/development-tools/without-docker) |

A useful bug report includes the app, relevant route pattern, locale, workspace
alias, expected behavior, actual error/status, and build version or commit where
available. Keep private content, tokens, raw credentials, and personal records
out of public issues and documentation.

## Glossary

## Evidence levels

A source file proves an implementation exists. A passing test proves the checked
behavior in its fixture. A successful build proves compilation for that commit.
A deployment marker identifies delivery. A recent processor result proves a job
ran. Keep these distinct when reporting product readiness or incident recovery.

# Daily workflows
Source: https://docs.tuturuuu.com/platform/guides/workflows

Connect planning, meetings, writing, forms, CRM, commerce, and learning without assuming automatic actions.

## Plan and execute a day

Use the [Command Center](/platform/features/command-center-dashboard) to review
priorities. Organize actionable work in [Tasks](/platform/applications/tasks),
fixed events in [Calendar](/platform/applications/calendar), and actual work
sessions in [Track](/platform/applications/track). Smart scheduling has explicit
[priority](/platform/features/smart-scheduling/priority-system) and
[duration](/platform/features/smart-scheduling/duration-optimization) rules;
calendar provider synchronization is separate from the local planning view.

Review [progress and goals](/platform/features/progress-goals-leaderboards) after
updating source work. A dashboard summary is a view over records, not a second
place to maintain the same task manually.

## Turn a meeting into reviewed work

[Meet](/platform/applications/meet) separates planning, participating, recording,
transcription, and follow-up proposals. Review the generated evidence before
creating a task or calendar event. See
[Follow-ups](/platform/features/meet-followups),
[Live assistants](/platform/features/meet-live-assistants), and
[Solo mode](/platform/features/meet-solo-mode). Provider connectivity, access,
and consent affect which tools are available; opening a room is not evidence
that transcription or an external provider is working.

## Capture ideas and knowledge

Workspace Notes, documents, whiteboards, habits, readings, and planning surfaces
remain in Web where they have not been assigned to another app. Use
[Mind](/platform/applications/mind) for mindboards and nested ideas,
[Drive](/platform/applications/drive) for files, and
[Tulletin](/platform/features/lettin) for creative worlds and published wiki
revisions. These are separate content models; following an app link does not
copy or synchronize every record.

[Notes voice analysis](/platform/features/notes-voice-analysis) records locally
until the user explicitly submits transcription/analysis. Saving the reviewed
result creates a workspace Note; it does not automatically create tasks or
events. A partial transcript can be useful even when analysis fails, and retries
must preserve the actor/workspace scope.

## Collect information and follow up

Build and share a [Form](/platform/applications/forms), then review responses
and analytics in its studio. Manage the people and groups who participate in
[Contacts](/platform/applications/contacts). Forms responses and CRM membership
are separate: do not assume a response creates a user, group enrollment, or
outreach message unless an explicitly configured product workflow does so.

## Run a sales workflow

Use [Inventory](/platform/applications/inventory) for catalog, stock, costing,
bundles, and checkout readiness. Publish a
[Storefront](/platform/applications/storefront) for buyers. Review provider
payment evidence and audit trails before treating an order as paid. Browser
success return URLs are navigation signals, not an independent payment proof.
[Finance](/platform/applications/finance) handles financial records;
[Pay](/platform/applications/pay) handles workspace subscription billing.
These three products have different responsibilities.

## Run a learning workflow

[Teach](/platform/applications/teach) serves educators;
[Learn](/platform/applications/learn) serves eligible learners and linked
parents. Education access and parent visibility are explicit. Programming runs
use the configured Judge/Devbox boundary: local editor diagnostics do not prove
a submission verdict. [Nova](/platform/applications/nova) has separate
prompt-learning and challenge experiences.

## Integrate rather than duplicate

Developers should use [shared internal API contracts](/platform/architecture/data-fetching)
and the [SDK](/reference/packages/sdk). The
[route catalog](/reference/repository/catalog) helps locate an owner, but private
internal handlers are not automatically supported third-party APIs. AI recall
is context, not permission to send messages, publish, or mutate a workspace.

# Platform Overview
Source: https://docs.tuturuuu.com/platform/overview

How Tuturuuu products, AI systems, and personalization layers fit together.

# Tuturuuu Platform Overview

The Tuturuuu platform combines proactive AI, unified applications, and automation tooling to help every visionary move from ambition to execution. Use this section to understand how each layer works and where to dive deeper.

## Explore the Platform

* **Applications** – Tuturuuu ships as a catalog of standalone web apps that each run on their own host, may serve product APIs locally, and can fall back to `apps/web` for unmatched or explicitly central route families. Browse the [Applications catalog](/platform/applications/overview) covering [Calendar](/platform/applications/calendar), [Finance](/platform/applications/finance), [Drive](/platform/applications/drive), [Chat](/platform/applications/chat), [CMS](/platform/applications/cms), [Inventory](/platform/applications/inventory), [Storefront](/platform/applications/storefront), and the [Apps gateway](/platform/applications/apps).
* **Experience Apps** – See how Tuturuuu Calendar, Tuturuuu Tasks, Tuturuuu Meet, and the Command Center Dashboard deliver daily flow. Start with the [Command Center Dashboard](/platform/features/command-center-dashboard), or turn Meet notes into [reviewed calendar and task follow-ups](/platform/features/meet-followups).
* **AI & Automation** – Learn how Mira, Nova, and Rewise support intelligent workflows in the [AI Overview](/platform/ai/structured-data).
* **Shared Components** – Reuse building blocks from the [Component Library](/platform/components/overview).
* **Personalization** – Tailor the workspace using [Themes](/platform/personalization/themes) and [Language settings](/platform/personalization/language).

## Satellite Apps And Central API Ownership

Beyond the experience surfaces, Tuturuuu is organized as a fleet of
**satellite apps** under `apps/` — `calendar`, `finance`, `drive`, `chat`,
`cms`, `inventory`, `storefront`, and more. Each runs as its own standalone host
on its own canonical domain. Satellites may own their product APIs locally;
unmatched or explicitly central route families can fall back to the live
`apps/web` platform. `apps/web` remains authoritative only where a route family
has not been hard-cut over to a satellite or another approved owner.

Use the [satellite app ownership guide](/platform/architecture/satellite-apps)
for local route, proxy, and auth boundaries. The
[TanStack and Rust migration guide](/platform/architecture/tanstack-rust-migration)
retains historical designs; both runtimes are paused and not in use.

The [Apps gateway](/platform/applications/apps) (`apps.tuturuuu.com`) sits in
front of the routable apps as a launcher and redirect layer — it surfaces app
cards and redirects to each app's canonical domain rather than reverse-proxying
them.

## Offline Runtime Ownership

Tuturuuu owns service-worker registration, precache-manifest generation,
worker compilation, navigation fallback, and runtime cache strategies in
`packages/offline`. Applications consume `OfflineProvider`; the live Web app
builds the worker through `createOfflineRoute` and
`getOfflineTurbopackConfig`.

The worker continues to use `/serwist/sw.js` as a compatibility URL so existing
browser registrations upgrade in place. Do not add Serwist packages to an app
or depend on that project's release schedule. Extend the shared internal
runtime and its focused tests instead.

## How it fits together

The Apps gateway links to standalone Next.js products. Each product owns its
publications, permissions, and local route handlers; central API families remain
in Web. Shared packages provide UI, internal API clients, authentication, and
storage helpers. Supabase, Trigger.dev, and product-specific Cloudflare services
support these apps according to their owning runbooks.

Use the [complete product directory](/platform/applications/overview) and
[repository catalog](/reference/repository/catalog) to locate products and
supporting services. [Versions](/reference/repository/versions) are derived from
maintained source manifests and lockfiles; a source entry is not a deployment or
entitlement guarantee. Private workspace pages remain authenticated and
[excluded from search indexing](/platform/features/search-indexing).

## Next Steps

1. Walk through the [Platform Features](/platform/features/command-center-dashboard) to see how the GTD-aligned dashboard works.
2. Review the [AI Structured Data guide](/platform/ai/structured-data) to understand how we interact with models.
3. Explore [Component docs](/platform/components/overview) when you need reusable UI patterns.

Looking for development workflows? Jump to the [Build](/build/overview) section. Ready to level up your skills? Explore [Learn](/learn/overview).

# Personal journal
Source: https://docs.tuturuuu.com/platform/personal-journal

Private original journal entries, self-reported mood, and a timezone-aware life and work timeline.

## Scope and delivery state

The first source slice adds a personal-workspace web journal at
`/[wsId]/personal-journal`. It preserves original words, event time, the entry's
chosen IANA timezone, an optional self-reported mood and context, life/work domain,
and reflection/good moment/challenge/milestone category. No mood is inferred and
no diagnostic interpretation is made. Existing Notes, mobile profile activity,
calendar attribution, public profiles, and shared activity consent are unchanged.
Mobile editing, search, deletion/reopening, source-linked AI reflections, finance,
social context, and proactive actions remain separate delivery units.

The live storage provider is deliberately unavailable until the migration has
been applied in ROOT's isolated environment and fresh generated Supabase types
support the real provider. The API returns `503`, never a simulated save or an
empty history. Source tests and setup do not prove SQL application or runtime
acceptance. Relevant exact-commit app build, type, lint, tests, SQL assertions, and
authenticated runtime evidence are required before delivery is complete.

## Privacy and original source

Journal entries and revision receipts are in separate `private` tables. No
anonymous or authenticated table/RPC grant exists. Session authorization revalidates
the current actor with Supabase Auth, accepts the `personal` alias or a UUID
without privileged handle fallback, verifies MEMBER membership, and
checks that the workspace is personal, undeleted, and created by that actor before
storage access. The private service RPC repeats the personal-workspace check.
Every read and write remains bound to actor, workspace and entry. A disabled
navigation item is only presentation, never an authorization boundary.

Workspace Notes is unsuitable as unchanged journal storage: its current database
read policies permit workspace members, and its editor rewrites its document.
The legacy private per-user notes table is retained without repurposing it.
Journal original body and self-reported mood never enter public profile or shared
workspace activity reads.

## Saves, conflicts and history

A create has a stable client UUID. Its UUID is also its initial operation ID.
Replaying exactly the same original document returns the original receipt.
Reusing that ID with different content conflicts. An edit has a distinct stable
operation UUID and expected revision. The private writer serializes an entry,
checks the revision, then updates the current entry and inserts an immutable
revision receipt in one transaction. An exact retry returns its receipt even if a
later independent edit exists. It does not rewrite history or add a revision.

The editor serializes saves and waits for a receipt matching actor, workspace,
entry ID, revision and original document. It autosaves valid drafts after 700 ms.
An unsuccessful or ambiguous response retains the immutable attempt and draft on
this page. Retry sends that same attempt. A `409` stops retries and preserves the
draft. The user can reread the current saved source, compare it with the draft,
and explicitly save that draft with a fresh operation and expected revision.
Another concurrent edit still conflicts. It never silently overwrites the newer entry. During pending,
unconfirmed or conflicted edits, changing entries is disabled. The current web
slice has no durable offline outbox: leaving or reloading can lose an unsaved draft,
and the UI explicitly says so. It never labels an unconfirmed write as saved.

## Timeline and accessibility

The timeline displays original source text and explicit self-reported mood.
Day/month/year grouping uses the user-selected display timezone. Weeks start on
Monday in that timezone, including weeks spanning a year boundary. The entry's
original UTC instant and captured timezone remain intact. The initial display
zone comes from the device and is editable; team timezone is not assumed.

Lists use keyset continuation, with at most 100 entries per page. The interface
labels partial history while more pages remain; a failed read does not become an
empty-history claim. All controls have labels, status changes use a live region,
invalid timestamp/timezone/body fields have associated accessible errors,
text wraps, and every journal string is provided in English and Vietnamese.

## Metadata references and future consented context

A portable journal source reference contains only kind, actor ID, verified
personal workspace ID, source UUID, exact source revision, UTC observation/expiry,
and authoritative consent/deletion/revocation versions. It contains no title,
body or mood. Missing authority, disabled consent, deletion, revocation, scope or
revision mismatch, stale observation or expiry produces an unqualified result.
The current projection requires an observation no older than 60 seconds and a
lifetime at most five minutes. It is an injected source contract, not a qualified
production consent provider or permission to start a scheduler.

Future journal/goals context must use the existing product memory service and
separate explicit journal consent. References preserve source provenance and
revision. Inspection/correction/forgetting and index invalidation must honor
source deletion and consent revocation. Existing successful missing-row memory
defaults cannot be treated as explicit journal consent. Dreaming cannot silently
copy private original journal content into another consent store.

## Regression evidence

`packages/internal-api/src/personal-journal.test.ts` checks original-source
validation, timezone boundaries and malformed success payloads.
`apps/web/src/lib/personal-journal/` tests cover actor/workspace guards and denied
unqualified storage. Draft and metadata tests cover exact receipt matching and
consent/scope/version fences. `apps/database/supabase/tests/personal-journal.sql`
uses transactional synthetic actors to exercise actual SQL replay, stale-edit
conflict, immutable original history, private grants and workspace-scope revocation;
it still must run against the applied schema before being reported as passing.

# MIRA proactive work core
Source: https://docs.tuturuuu.com/platform/personal-proactive-execution

Inactive consented due events, reviewable plans and selected dry-run actions.

MIRA helps people review consented work context and get things done through
bounded plans and selected actions. This source milestone is **inactive**. It
creates synthetic metadata plans and dry-run receipts only. Missing or
unqualified authority denies admission. No Worker exports the new class, and no
production binding, ingress, model, private-content reader or provider is added.

## Scope and product decisions

The portable contracts, due-job engine, review engine and SQLite adapter live in
`apps/coordination/src/proactive/`. Future web/mobile MIRA surfaces may use them
after their adapters are qualified. Paid membership does not grant autonomy.
Default enablement is off. Execution rechecks personal creator/actor ownership,
paid status, explicit consent, cadence, timezone/quiet hours, pause, budgets,
source revisions, permission and revocation. A due occurrence is event-driven;
there is no per-user idle heartbeat or new global Cron.

The initial synthetic policy permits one daily occurrence per authoritative
cadence, one due-job run and two plan revisions. Cross-occurrence anti-spam and
budgets require an authoritative atomic adapter before activation. Local job
counters alone are not an account-wide spend cap.

Journal sources stay private. Plans are separate source-linked suggestions, not
changes to user journals or inferred mood records. Being away may authorize
specifically consented read-only research/planning. Calendar/task/finance/email
mutations, purchases and sends need distinct authority. This implementation only
supports the selected action `record-dry-run`, which calls no provider.

## Existing infrastructure census

| Existing source | Reuse boundary |
| - | - |
| Coordination SQLite DO | Transactional leases, with its own expiry-cleanup alarm. Do not reuse that single alarm or identity for due jobs. |
| Cron-control Worker | Five-minute immediate-notification batch recovery through a private RPC and web processor; not a personal scheduler. |
| Devbox-control RunnerWake | Hibernating runner wake sockets; operational infrastructure, not a product scheduler. |
| Meet realtime/Colab Workers | Room/session objects and provider contracts stay scoped to their products. |
| `packages/utils/src/meet-duration.ts` | Server-side personal creator, active subscription and private tier lookup. Next/Supabase imports make it an entitlement reuse candidate, not a qualified Worker adapter. Free subscriptions do not prove payment. |

The existing product memory service is `packages/ai/src/memory/index.ts`, with
scope/settings, context/search, edit/forget and ingest operations. Its settings
code fails closed on lookup errors; successful missing settings retain existing
enabled defaults, which cannot prove explicit proactive consent. `packages/internal-api/src/ai-memory.ts`
already exposes product settings and edit revisions. Reuse those consented
services at a qualified adapter; do not build a second memory store. Current
memory revisions are opaque strings, so they cannot be fabricated as the
journal proposal's numeric revision. Task reminder lifecycle checks already
cover cancellation, revision and recipient watching in
`packages/utils/src/task-reminder-lifecycle.ts`; calendar payloads already carry
explicit provider/source and recoverable create identifiers. None of those
existing interfaces grants this slice external mutation permission.

The active source scan found no Cloudflare Workflow entrypoint or Agents SDK
scheduler for this product. Hive workflow logic is not Cloudflare Workflows.
A bounded deployment-workflow query found a successful coordination production
run; production-filtered cron-control/devbox-control queries returned no runs.
This is workflow metadata, not current hosted namespace health or measured cost.

## Functional loop and contracts

`Authority.read(identity, now)` returns untrusted adapter output, parsed into a
strict fresh snapshot before every admission, approval and execution.
`unavailableAuthority` denies by default. Read errors deny. The due engine pins
an immutable occurrence, reserves a durable lease/run and computes private
metadata only. Duplicate wakes return existing state. Expired leases become
unknown outcomes without another alarm or automatic replay. Accepted-unresolved
and dead-letter states remain inspectable. Provider acceptance is represented in
synthetic recovery tests, not a qualified real provider protocol.

A failed second authority read during plan preparation persists an inspectable
blocked record without retry or another wake. A completed due receipt plus fresh
scoped context creates an evidence-linked
reviewable plan. Selected approval binds its revision, the only permitted action
and expiry. Rejection preserves a feedback category; revision refreshes evidence
and invalidates older approval scopes, within a two-revision cap. Approval and
execution recheck authority and current evidence. Changed source, deletion,
revocation, consent or permission versions revoke selected action. Completed
dry-run activity receipts are durable and idempotent.

The journal reference proposal has exactly `kind`, UUID `actorId`, UUID
`personalWorkspaceId`, UUID `sourceId`, positive safe-integer `sourceRevision`,
strict UTC ISO `observedAt`/`expiresAt`, and required safe-integer deletion,
revocation and consent versions. Expiry follows observation. Missing versions
never default. No body, title or mood is accepted. Adoption of the actual journal
parser requires the journal owner's reviewed file SHA and root binding. Other
memory/goals/task/calendar/notification interfaces remain injected synthetic
contracts with opaque string revisions, discriminated from numeric journal
revisions. No unpublished internal-api module or broad admin read is imported.

`journal-reference.ts` independently validates the reviewed canonical metadata
contract, preserving numeric `sourceVersion`, GUID identifiers, exact millisecond
UTC timestamps and positive consent versions. A root-injected parser descriptor
must carry the reviewed parser SHA and return the same strict metadata. The
explicit `sourceVersion` to internal `sourceRevision` alias does not coerce or
default a value. Canonical GUIDs that fail the stricter internal UUID union are
denied. Missing parser qualification denies even valid-looking fixtures. Returned
references are synthetic-only with runtime admission denied; there is no import
of the journal branch, provider or private content. An actual parser binding and
union qualification remain separate root-owned work.

After a confirmed authoritative correction/forget, the owning adapter must
invalidate derived indices and persist the review invalidation fence before
reuse. Failed deletion cannot be reported as success. This core cannot delete
original journals or build a private memory index.

SQLite state writes are transactional; alarm reconciliation is a separate
awaited operation. Resubmitting the same immutable occurrence repairs an
interrupted alarm write. Atomic state/alarm crash qualification and authenticated
recovery ingress are held activation gates. Terminal fences prevent late alarms
from executing work, even after cancellation or restart.

## Bounded cost assumptions

Official documentation was checked on 2026-10-12. These are illustrative
assumptions, not observed usage, account spend or latency. Shared allowances,
actual retries, retention overhead, logs, database and provider costs are unknown.

Assume 1,000 opted-in paid users, one daily due event, 30 days: `30,000`
occurrences. Disabled users emit no events. Assume five DO invocations, one
active second, 10 SQLite writes, 20 reads and 2 KB retained metadata per
occurrence. These counts must be measured against a qualified native runtime.

| Candidate | Assumed monthly work |
| - | - |
| SQLite DO wake-on-due | 150,000 requests; 3,840 GB-s at 128 MB; 300,000 row writes; 600,000 reads; at most 0.06 GB metadata before overhead |
| Workflows, six steps/occurrence | 30,000 invocations; 180,000 steps; 3 million CPU ms at 100 ms/occurrence; at most 0.12 GB assuming 4 KB state/instance |
| Per-user five-minute heartbeat | 8,640,000 alarm invocations, 288 times the due wake count; 110,592 GB-s assuming 100 ms active/wake. Not selected. |
| One global five-minute Cron | 8,640 Worker invocations and 8.64 million candidate checks if each wake scans 1,000 users. Not added. |

[Workflows pricing](https://developers.cloudflare.com/workflows/reference/pricing/)
uses Workers request/CPU rates plus steps and storage. Steps/storage billing
started August 10, 2026. Paid allowances are 10 million requests, 30 million CPU
ms, 500,000 steps and 1 GB-month. Overage rates are $0.30/million requests,
$0.02/million CPU ms, $0.80/100,000 steps and $0.20/GB-month. Idle waits use no CPU;
retained state still counts. With shared allowances exhausted, raw-rate scenario
amounts are `$0.009 + $0.06 + $1.44 + $0.024 = $1.533` before billing granularity,
account minimum or other services. With all allowances available, these modeled
dimensions fit within them; that does not make the account or providers free.

[DO pricing](https://developers.cloudflare.com/durable-objects/platform/pricing/)
includes 1 million requests, 400,000 GB-s, 25 billion row reads, 50 million writes
and 5 GB-month monthly on Paid. Excess rates are $0.15/million requests,
$12.50/million GB-s, $0.001/million reads, $1/million writes and $0.20/GB-month.
Compute excess rounds up to the next billable unit. With exhausted compute
allowances, 150,000 extra requests round to one million, or $0.15, and 3,840
extra GB-s round to one million GB-s, or $12.50. Raw SQL rate products are $0.30
writes, $0.0006 reads and $0.012 storage before SKU rounding. Alarm scheduling
counts as a row write; deletes count as writes and KV methods bill SQLite rows.
Waiting on network I/O can keep a DO active and billed. The synthetic one-second
assumption cannot be extrapolated to model calls.

[Workers pricing](https://developers.cloudflare.com/workers/platform/pricing/)
has a \$5 paid-account monthly minimum and shared request/CPU allowances.
[Cron](https://developers.cloudflare.com/workers/configuration/cron-triggers/)
uses UTC schedules; it supplies neither consent nor a total spend fence.
[DO alarms](https://developers.cloudflare.com/durable-objects/api/alarms/)
have one slot per object, at-least-once execution and up to six automatic retries
starting at two seconds. Deleting an alarm cannot replace a terminal fence.

[Agents schedules](https://developers.cloudflare.com/agents/runtime/execution/schedule-tasks/)
use SQLite and DO alarms. Count their underlying costs; the attempted standalone
Agents pricing URL was unavailable, so no separate free-price claim is made.
[Agents limits](https://developers.cloudflare.com/agents/platform/limits/)
include 30 seconds default CPU/event and 1 GB state/agent.
[Workflows limits](https://developers.cloudflare.com/workflows/reference/limits/)
include 1 MiB event/result payloads, 300 creations/second/account and
100/second/workflow on Paid. Scheduling is not authority to spend or retry
external effects indefinitely.

## Verification and activation gates

```sh theme={null}
cd apps/coordination
ttr resources run -- bun x --no-install vitest run --config vitest.config.ts src/proactive --maxWorkers=1
```

Tests use fake clocks, synthetic authority and actual local SQLite. The storage
seam test replaces the Cloudflare base class, so it is not native workerd/hosted
DO proof. Coverage binds due admission, cancellation/replay/recovery, rollback,
evidence/approval fences, bounded feedback revisions and idempotent receipts.

Before activation, root must bind actual paid/personal identity, consent,
permission, revocation/deletion, source and atomic budget adapters. Qualify native
alarm/crash/restart behavior, operation counts and durable terminal stop fences.
Require bounded strict ingress with signed tenant/audience/expiry/replay checks
or scoped service-binding identity and narrow secret references. This milestone
installs no endpoint or shared admin credential.

Require exact-commit tests/type/lint/build CI, staging acceptance and a finite
canary cost budget. Provider acceptance/unknown-outcome tests are required if a
real provider is added. Root alone authorizes promotion/rollback. Rollback stops
admission, persists cancellation/revocation and removes future alarms; retain and
inspect unknown outcomes before replay. A rate limit, CPU cap, billing alert or
redeploy alone is not a total-spend stop mechanism.

# Language
Source: https://docs.tuturuuu.com/platform/personalization/language

View Tuturuuu in your preferred language.

## Usage

Language helps you view everything on [Tuturuuu](https://tuturuuu.com) in your preferred language.

### Supported Languages

Currently, we provide first-class support for the following languages:

* **English**
* **Vietnamese**

### How to Change Language

[Tuturuuu](https://tuturuuu.com) will automatically detect your browser's language and set the language accordingly. If you want to change the language, you can do so by clicking on the language switcher in your profile avatar (located at the top right corner of the page).

> [!NOTE]
>
> The language switcher is only available after you have logged in.

### Contribute

If you want to help us translate [Tuturuuu](https://tuturuuu.com) into your language, feel free to open a pull request on our [GitHub repository](https://github.com/tutur3u/platform).

Each supported locale lives in a single message bundle under `apps/web/messages/`:

* `apps/web/messages/en.json` for English
* `apps/web/messages/vi.json` for Vietnamese

When you add or change a key, update it in **both** `en.json` and `vi.json` so the bundles stay in sync, then run `bun i18n:sort` to keep the keys ordered consistently before committing.

# Sidebar Navigation
Source: https://docs.tuturuuu.com/platform/personalization/sidebar-navigation

How dashboard sidebar layout preferences work in apps/web.

## Default layout

The dashboard sidebar always keeps **Dashboard** in the root navigation. By default, the root navigation then shows **Tasks**, **Calendar**, and **Finance**.

All other eligible top-level tools are placed under **More tools**. More tools is grouped into durable sections:

* **Work tools**: Habits, Whiteboards, Track, Drive, Forms, Documents
* **AI**: Mind, Hive, Chat, AI Lab
* **Operations**: Workforce, Users, Inventory
* **Utilities**: QR Generator, Google Workspace, Meet, Polls, Mail, Education, Link Shortener

Dashboard is separated from the main root tools. **Settings** is pinned to the bottom of the sidebar, below More tools and Archived (including when Archived is promoted to the root sidebar).

## Managing layout

Users manage start-page navigation, sidebar behavior, sidebar layout, and recent-history visibility from **Settings → Preferences → Navigation & Sidebar**.

## Preference precedence

Sidebar layout preferences use a hybrid model:

1. Workspace override: `user_workspace_configs.SIDEBAR_NAVIGATION_LAYOUT`
2. Account default: `user_configs.SIDEBAR_NAVIGATION_LAYOUT`
3. Authored default layout

The saved layout stores three ordered id lists:

* `root`: first-level tools shown directly in the sidebar
* `more`: first-level tools shown inside More tools
* `hidden`: first-level tools archived from normal sidebar rendering

Unknown or stale ids are ignored when the layout is applied and are dropped the next time the user saves preferences.

## Quick actions

First-level navigation items expose compact hover actions in the sidebar:

* **Pin** moves an item from More tools to the root sidebar.
* **Unpin** moves an item from the root sidebar to More tools.
* **Archive** hides an item from normal sidebar rendering.

Pin, unpin, and archive also appear on tier-gated items that render grayed out in the sidebar. Saving layout preferences does not grant access to unavailable tools.

Dashboard and Settings are locked and cannot be pinned, unpinned, or archived.

Archived items appear in a compact **Archived** dropdown at the bottom of **More tools**. More tools remains visible when archived items exist alongside other visible More tools children.

When every normal More tools child is hidden or unavailable and **Archived** is the only remaining visible child, structure promotion lifts **Archived** to the root sidebar instead of leaving an empty More tools wrapper. Selecting an archived item from that dropdown (or the root Archived entry) restores it to its previous root or More tools placement.

## Visibility rules

Preferences never bypass authorization, feature flags, production gates, root-workspace restrictions, or tier visibility. If a tool is unavailable for the current user or workspace, placing it in root navigation does not make it appear.

Hidden tools remain directly routable. When the current route matches a hidden tool or one of its descendants, the sidebar reveals that item only for the current route and marks it as an active hidden item. This contextual reveal is not saved back into the preference config.

## Recent history

Recent sidebar navigation history is controlled by `user_configs.SIDEBAR_RECENT_NAVIGATION_ENABLED`.

The default is **off**. When disabled, the sidebar does not render recent navigation history and does not record recent visits.

# Themes
Source: https://docs.tuturuuu.com/platform/personalization/themes

Enhance your experience with themes.

## Usage

Themes are a way to customize the look and feel of your experience on [Tuturuuu](https://tuturuuu.com). You can choose from a variety of themes to suit your preferences.

### Modes

Modes are how the entire website looks. You can choose between **light mode**, **dark mode**, and **system mode** (which follows your system settings).

### Basic theme switcher

When you are not logged in, a basic theme switcher will be available which will allow you to switch between standard **dark mode** and **light mode** by clicking on the theme switcher in the top right corner of our website.

### Advanced theme switcher

You can switch between a variety of themes by tapping on your profile picture in the top right corner of our website and selecting the **Theme** option.

> [!TIP]
>
> This switcher is will available when you are logged in.

#### Variants

When using **Advanced theme switcher**, you can also choose a variant of the selected mode.

> [!NOTE]
>
> For example, you can choose dark mode with a blue accent.

Available variants:

* **Standard** (Default)
* **Pink**
* **Purple**
* **Yellow**
* **Orange**
* **Green**
* **Blue**

## Mobile app

In the mobile app, open **Settings → Appearance** to pick a mode (System, Light
or Dark), a theme (Classic, Aurora, Sunset, Ocean, Forest, Ember, Blossom or Mono),
an accent colour and a background style (Solid, Gradient or Blobs). For gradient
and blob backgrounds, you can tune intensity, blob softness and card opacity, and
optionally animate blobs. Animation stays off when your device's Reduce Motion
setting is on. Changes apply across the app immediately. **Reset to default**
restores Classic with the system mode. See
[Mobile settings shell](/platform/features/mobile-settings-shell#settings-overview-and-appearance)
for defaults and behaviour.

# AI Studio API
Source: https://docs.tuturuuu.com/reference/api-reference/ai-studio

OpenAI-compatible Tuturuuu AI endpoints, bearer authentication, streaming, and native extensions.

The AI Studio API is served from `https://ai.tuturuuu.com` and accepts
workspace-scoped `ttr_ai_` credentials through the standard bearer header:

```http theme={null}
Authorization: Bearer ttr_ai_...
```

The plaintext credential is shown once. Store it in a secret manager and never
place it in browser bundles, URLs, logs, or source control.

> [!TIP]
>
> For a workspace-aware quickstart with copyable cURL and server-side TypeScript
> examples, open [AI Studio](https://ai.tuturuuu.com), select a workspace, and
> choose **Developer docs**. That module links directly to the same workspace's
> keys, Playground, credits, and run observability.

Creating or rotating a credential requires both the workspace
`manage_ai_keys` permission and a standing platform-admin approval for that
workspace. Listing and revoking existing credentials remain available without
issuance approval. Removing approval does not invalidate existing credentials.

Registered external apps may instead use a short-lived `ttr_app_` access token.
The app registration and issued token must both include `workspace:session` and
`ai:use`; speech requests require `tts:use`. These requests must also send the
normalized workspace ID returned by the app-token exchange:

```http theme={null}
Authorization: Bearer ttr_app_...
X-Tuturuuu-Workspace-Id: 00000000-0000-0000-0000-000000000000
```

The external-app path is temporarily exempt from workspace credit deductions.
It is not unrestricted access: registration status, linked workspace, current
user membership, model policy, payload bounds, workspace request rate, stable
request IDs, and usage auditing remain enforced. Browser sessions, internal
satellite sessions, ordinary Studio keys, and unrecognized callers never
receive this exemption.

## OpenAI-compatible endpoints

| Method | Path | Purpose |
| - | - | - |
| `GET` | `/v1/models` | List models visible to the key |
| `POST` | `/v1/responses` | Generate text or structured output |
| `POST` | `/v1/chat/completions` | OpenAI chat-completions compatibility |
| `POST` | `/v1/embeddings` | Generate embeddings |
| `POST` | `/v1/images/generations` | Generate images |
| `POST` | `/v1/audio/speech` | Generate downloadable WAV or PCM speech |
| `POST` | `/v1/agents/{agentId}/responses` | Run a versioned workspace agent |

Requests support stable `x-request-id` values and the `idempotency-key` header.
Streaming responses use server-sent events. Errors use an OpenAI-compatible
`error` object and include the stable request ID for support correlation.

Model access is the intersection of the globally enabled catalog, global Studio
defaults, workspace policy, plan or root grants, and the key's own model
restrictions. A model visible elsewhere in Tuturuuu is not necessarily
available to a Studio key.

The legacy global/workspace Studio enablement switches no longer gate model
execution. Credit availability, model policy, credential status, budgets, rate
limits, and abuse controls remain authoritative.

## Structured output and audit attribution

Chat completions preserve `response_format` values `text`, `json_object`, and
`json_schema` through to the model. For schema output, include `json_schema.name`
and `json_schema.schema`; schemas are bounded to 100,000 characters. Set an
explicit `max_completion_tokens` budget for large structured results. The default
is 2,048 tokens and the maximum is 32,768; a truncated response still incurs
provider usage even when the calling application cannot parse it.

Applications may attach `X-Tuturuuu-Operation` and `X-Tuturuuu-Entity-Id` headers
for audit correlation. A valid operation is also shown as the run feature in
AI Studio, so operators can distinguish analysis, classification, and drafting.
Values are limited to 128 ASCII letters, digits, periods,
underscores, colons, and hyphens. These labels do not change workspace, actor, or
application attribution, which comes from the authenticated credential. Keep
personal data, secrets, and prompt text out of these labels. The response ID and
`x-request-id` identify the gateway run.

Provider-reported tokens remain recorded when structured output validation fails.
Monetary values use the configured model pricing, rather than provider invoices.
The original output-token total includes reasoning tokens; pricing counts each
reasoning token once, while retaining the breakdown for audit. Optional content-capture failures cannot overwrite settled
usage. When a provider supplies no usage on failure, audit metadata marks it
`unavailable`; known completed steps without a final total are marked
`provider_partial`. Interrupted streams without final usage are labeled
`estimated_partial`. Such records are not proof of zero provider spend and need
provider-billing reconciliation for a complete accounting close. AI Studio run
details show a warning for these incomplete records.

## Native extensions

Tuturuuu-native response metadata reports billed workspace credits, provider
cost when permitted, run and trace IDs, token or media units, and timing
information. These fields extend the compatible response without changing the
standard OpenAI fields.

Text endpoints accept an optional bounded tool-loop extension:

```json theme={null}
{
  "tuturuuu": {
    "max_steps": 4,
    "tools": ["calculator", "current_time"]
  }
}
```

`max_steps` must be between 1 and 8. The listed tools are deterministic,
server-owned demonstration tools; arbitrary HTTP requests and code execution
are not accepted. Non-streaming responses include
`tuturuuu.steps` with only the ordered step number, type, name, status, and
latency. Streaming responses emit the same sanitized trace in the final
`response.completed` event before `[DONE]`.

Workspace Studio dashboards combine settled `ai_studio_runs` with unmatched
deductions from `ai_credit_transactions`. This includes ordinary workspace
deductions and the signed-in member's personal deductions when a free workspace
uses a personal credit balance, without double-counting ledger rows linked to a
Studio run. Billed credits and settled provider cost are shown separately;
registered external-app runs therefore report provider cost while showing zero
billed workspace credits.

The usage and run-log responses include identifiers, model, feature, credential
source, status, token or media units, settled credits and cost, and timing
metadata. They never include raw prompts, model outputs, tool payloads, ledger
metadata, or unsanitized provider errors.

The legacy `/api/ai/generate` endpoint remains available as a compatibility
adapter. New integrations should use the `/v1` Studio endpoints.

### Speech

`POST /v1/audio/speech` accepts `input`, optional `voice`, optional
`response_format` (`wav` or `pcm`), and the
`google/gemini-3.1-flash-tts-preview` model. The response is downloadable audio
and is never cached. Google currently prices the model by text input tokens and
audio output tokens; Tuturuuu records both provider cost and generated audio
duration-derived token usage.

## Retention and content capture

Metadata logging is enabled by default. Prompt, output, and tool content is
captured only when the workspace enables content capture. Use the Studio
retention controls to review the active policy before submitting sensitive
data.

## External provider costs

`POST /v1/provider-costs` imports one provider-reported USD run expense. Use a
registered external-app session or an AI Studio key bound to that app, with
`X-Tuturuuu-Workspace-Id` matching its workspace. Unbound keys cannot import costs.
The existing `ai:use` app scope and registration checks apply. This endpoint does
not execute AI, reserve credits, or debit the workspace.

```json theme={null}
{
  "provider": "apify",
  "externalRunId": "run_123",
  "service": "apify_facebook_posts",
  "amountUsd": 0.126,
  "currency": "USD",
  "source": "provider_api",
  "occurredAt": "2026-07-01T12:00:00Z",
  "observedAt": "2026-09-01T12:00:00Z"
}
```

Bodies are limited to 8 KiB. Workspace/app identity comes from authentication,
never the body. Each workspace/app/provider/account/run has one record; newer observation
timestamps can correct it and stale retries cannot overwrite it. A successful
write returns `{ "accepted": true, "externalRunId": "run_123" }`. Retry unavailable
writes with the same run ID. Import provider totals only once: do not add event
charges to an Apify `usageTotalUsd` total or import the same account invoice as
additional run usage.

The AI Studio Usage page has a **Provider costs** section using the selected date
range, original run dates, and UTC months. Only imported records are included;
unknown costs and expired runs are not zero-cost records. The workspace read API
is `GET /api/v1/workspaces/{wsId}/ai/provider-costs?from=...&to=...`, authorized with
`use_ai_studio` and a joined satellite session.

Apply migration `20260906100000_external_provider_costs.sql` before enabling import
clients. During a schema-first rollout, unavailable storage returns `503` and the
client must retain its pending records. The Supabase production migration remains
an operator action.

For an account exclusively dedicated to the sending app, import daily account
usage with `granularity: "account_day"`, `accountId`, a stable account/day
`externalRunId`, and `occurredAt` at midnight UTC. These daily records replace
covered run amounts in aggregates; run records remain for audit. Run imports
may include `accountId` to distinguish multiple accounts. Never use account-day
imports for a shared provider account without explicit attribution. Daily totals
must reconcile with the provider's post-discount billing-cycle total; do not
silently allocate discounts or add current list-price surcharges. Apify's reported
usage includes applicable date-order/pay-per-event charges, storage and transfer.

When IDs are only unique within a provider account, supply `accountId` on every
record. Account-day totals include the complete UTC day whenever it overlaps
the requested range; hourly costs cannot be inferred from a daily total.

## External app usage reports

`GET /v1/usage` accepts an app-bound machine key or external-app session credential
and `X-Tuturuuu-Workspace-Id`. It returns only AI metering attributed to the
authenticated app in the matched workspace. Unbound keys and workspace mismatches
receive `403`.

The response includes `currency: "USD"`, `source: "tuturuuu_ai_metering"`,
`workspaceId`, `appId`, `from`, `to`, and daily `rows`: `day`, `model`, `feature`,
`executionMode`, `amountUsd`, `requests`, `failed`, `inputTokens`, `outputTokens`,
`billedCredits`, and `unmeteredCredits`. All retained app-attributed history is
paginated in adjacent windows of at most 365 days. Reads neither debit credits
nor create metering events. Reporting failures return `503`, not a partial total.

Combine `amountUsd` with provider-reported expenses without adding credit
valuations again: credits are a separate accounting dimension of the same calls.
These are recorded consumption costs, not proof of a paid invoice. Unconnected
provider bills must remain explicit coverage gaps. Cache reports privately and
keep machine credentials on the server.

Validate with `bun run --cwd apps/ai test src/app/v1/usage/route.test.ts`.

## Reviewed provider invoices

`POST /v1/provider-invoices` accepts an immutable, manually reviewed paid invoice
snapshot. Use the same workspace-matched external-app credential as provider
cost ingestion. Workspace, app and actor attribution come from the credential.

```json theme={null}
{
  "provider": "neon",
  "accountId": "dedicated-account",
  "reference": "example-invoice",
  "issuedOn": "2026-01-01",
  "reviewedOn": "2026-01-02",
  "amountUsd": 1.25,
  "currency": "USD",
  "status": "paid",
  "source": "reviewed_provider_invoice"
}
```

Success returns `{ "accepted": true, "reference": "example-invoice" }`.
Identical retries retain one receipt per workspace/app/provider/account/reference.
Conflicting snapshots return `409`; review the evidence rather than generating a
new reference to bypass the conflict. Unknown fields, negative amounts, future
reviews and reviews before issuance are rejected. Keep real invoice details and
credentials in private configuration, never source control.

AI Studio **Integrations** shows retained invoices separately from measured
provider usage. Its workspace-authorized read API is
`GET /api/v1/workspaces/{wsId}/ai/provider-invoices` and requires `use_ai_studio`.
It paginates storage reads to avoid silently truncating all-time invoice totals.
Invoice periods use issue dates; they do not establish consumption dates. Original
amounts stay in USD and display conversion does not change the ledger. Do not add
invoice and usage totals when they cover the same expenses. Neither invoice
imports nor provider costs debit AI credits.

Apply migration `20260907110000_external_provider_invoices.sql` through the normal
production migration workflow before enabling invoice delivery. This endpoint
stores reviewed evidence; it does not fetch future provider invoices. A receipt's
sync time confirms persistence, not connection health or complete cost coverage.

# Generate AI Completion
Source: https://docs.tuturuuu.com/reference/api-reference/endpoint/generate

Public Tuturuuu endpoint for generating text completions with supported Gemini models using a workspace API key.

# POST /api/ai/generate

This public API endpoint allows you to generate text completions using supported AI models (e.g., Gemini). You must provide a valid access key for authentication.

## Endpoint

```
POST https://tuturuuu.com/api/ai/generate
```

## Request Body

Send a JSON object with the following fields:

### `accessKey` object

| Field | Type | Required | Description |
| - | - | - | - |
| `id` | string | Yes | Your API access ID. |
| `value` | string | Yes | Your API access key. |

### `configs` object

## Supported Models

* `gemini-2.0-flash`
* `gemini-2.0-flash-lite`
* `gemini-2.5-flash`
* `gemini-2.5-flash-lite`
* `gemini-2.5-pro`

## Example Request

```json theme={null}
{
  "prompt": "The Swedish buyout firm has sold its remaining 22.4 percent stake, almost eighteen months after taking the company public in Finland.",
  "accessKey": {
    "id": "00000000-0000-0000-0000-000000000000",
    "value": "00000000-0000-0000-0000-000000000000"
  },
  "configs": {
    "model": "gemini-2.5-pro",
    "systemPrompt": "Analyze the sentiment of the text and return a JSON object with the following format: {\"sentiment\": positive|negative|neutral,\"confidence_scores\":{\"positive\": <float between 0.0 and 1.0>, \"negative\": <float between 0.0 and 1.0>, \"neutral\": <float between 0.0 and 1.0>}, \"explanation\": \"<brief explanation of the sentiment>\"}.\n\nEnsure no extra text outside the JSON."
  }
}
```

## Example Response

```json theme={null}
{
  "input": "The Swedish buyout firm has sold its remaining 22.4 percent stake, almost eighteen months after taking the company public in Finland.",
  "output": "{\"sentiment\":\"neutral\",\"confidence_scores\":{\"positive\":0.12,\"negative\":0.10,\"neutral\":0.78},\"explanation\":\"The text is factual and does not express a clear positive or negative sentiment.\"}",
  "usage": {
    "inputTokens": 45,
    "outputTokens": 60,
    "reasoningTokens": 10,
    "totalTokens": 115
  },
  "finishReason": "stop",
  "cost": {
    "inputCost": "$0.00005625",
    "outputCost": "$0.00060000",
    "reasoningCost": "$0.00010000",
    "totalCost": "$0.00075625"
  }
}
```

## Errors

* `400 Missing accessKey` — You must provide both `id` and `value` in the accessKey object.
* `400 Invalid model` — The model is not allowed for your key.
* `400 Invalid accessKey` — The credentials are invalid.
* `400 Missing prompt` — The prompt field is required.
* `400 Missing API key` — Internal error, contact support.

## Notes

* You must have a valid access key with the required model scope.
* The response includes the original input, the model output, token usage, cost breakdown, and the finish reason.

# API Reference
Source: https://docs.tuturuuu.com/reference/api-reference/introduction

Overview of the public Tuturuuu HTTP API, authentication, and where the canonical OpenAPI contract lives.

# API Reference

This section documents the public Tuturuuu HTTP API. It is reference material for
integrators calling Tuturuuu endpoints from outside the platform.

## What this API covers

This section documents the OpenAI-compatible **AI Studio API**, including
responses, chat completions, embeddings, images, and versioned agents. See
[AI Studio API](/reference/api-reference/ai-studio). The older
[Generate AI Completion](/reference/api-reference/endpoint/generate) endpoint
remains available as a compatibility adapter.

The [source route inventory](/reference/repository/catalog) locates active
Next.js handlers and their owners. Internal routes are not automatically public
integration contracts; use the product-specific API/SDK guide for supported use.

## Authentication

Authentication depends on the endpoint:

* **AI-only bearer keys.** AI Studio endpoints authenticate with a hash-only
  `ttr_ai_` workspace credential in the `Authorization: Bearer` header. These
  keys can call only AI Studio endpoints and are restricted by workspace,
  model, expiry, rate, and optional credit-budget policy.
* **Legacy workspace API keys.** The compatibility AI generate endpoint still
  accepts its existing request-body `accessKey` contract while integrations
  migrate to AI Studio.
* **App sessions / session cookies.** First-party Next.js routes resolve actors
  through their owning application boundary and check workspace permissions.
  Supported bearer authentication is endpoint-specific. Internal routes are not
  general-purpose public endpoints merely because they exist in source.

Never commit API keys or tokens. Reference credentials by environment variable
name and supply them at request time.

## Active contracts and retained migration specification

The inactive Rust migration retains its specification at:

```
apps/backend/api/openapi.yaml
```

It describes retained migration work, not the deployed API. Rust and TanStack
Start are not in use and are not refreshed by ordinary Next.js changes. Active
HTTP behavior lives in the owning Next.js app, and shared first-party contracts
live in `packages/internal-api`. Use the [AI Studio API](/reference/api-reference/ai-studio),
[SDK](/reference/packages/sdk), and [active runtime map](/build/devops/active-runtime)
for current integration and operating guidance.

# Database Migrations Guide
Source: https://docs.tuturuuu.com/reference/database/migrations-guide

Best practices for creating, testing, and deploying Supabase migrations

The Tuturuuu platform uses Supabase migrations to manage database schema changes with version control and reproducibility.

## Declarative adoption preparation

Declarative schemas are opt-in preparation. Existing migrations remain the
source of truth; this foundation does not enable an engine, export a baseline,
change deployment gates, or regenerate database types.

```sh theme={null}
node apps/database/scripts/declarative-schema-readiness.js --json
```

Run after workspace dependency setup. The checker prints migration/schema
filename and byte-hash inventories, config/lock identities, the PostgreSQL major,
and bounded help probes of the installed bundled Supabase CLI. It installs
nothing and makes no database connections. It rejects linked targets, database
URLs, apply/overwrite/experimental flags, and unknown arguments before inspection.
Exit 2 means adoption is held; exit 1 means inspection failed; `--help` exits 0.
A schema tree plus supported commands cannot produce a ready result. Keep the
report in ignored task evidence.

The [current Supabase guide](https://supabase.com/docs/guides/local-development/declarative-database-schemas)
distinguishes pg-delta `db schema declarative generate`/`sync` from legacy migra
`db diff` and ordered `schema_paths`. Check exact installed help first. Root owns
any CLI upgrade choice. Do not use a pg-delta export with legacy diffing, add a
partial tree, or silently change the engine/config or existing `sb:diff` command.

Baseline approval requires a fresh source/config/lock/version binding, explicit
reconciliation of pending migration owners, complete disposable Linux replay,
and full ledger comparison. Export DDL only from that task-owned database,
review for embedded secrets, then prove a no-op declarative diff against the
complete history and catalog/security parity from a second disposable replay.
A production dump can omit pending migrations and is not an approved baseline.
Never reset foreign databases or rewrite deployed history.

Keep DML/backfills, environment operations, and diff-engine unsupported objects
in reviewed imperative migrations with an explicit exception inventory. Verify
RLS, public/private grants and default privileges, service-role functions,
security-definer search paths, extension versions, Storage policies, and
application customizations of managed auth/storage/realtime schemas separately.
A no-op diff cannot prove objects the engine excludes. Keep declarations below
the authored 700-LOC ceiling, use the shared resource queue, and prove closure of
all task-owned containers, volumes, ports, and scopes.

The detailed repository procedure is
`plugins/tuturuuu/skills/tuturuuu-database/references/declarative-schema-adoption.md`.
Until those independently reviewed receipts exist, adoption remains preparation.
After approval, use the qualified engine to propose forward migrations, review
all generated SQL, replay and test security, then run typegen on the applied
schema. Production application remains separately authorized.

## Migration Workflow

```
┌─────────────────────────────────────────────────────┐
│  1. Make schema changes locally                      │
│     ├─ Edit tables in Supabase Studio               │
│     ├─ OR write SQL migration manually              │
│     └─ Test changes                                  │
└─────────────────┬───────────────────────────────────┘
                  │
┌─────────────────▼───────────────────────────────────┐
│  2. Generate migration                               │
│     ├─ bun sb:diff (from Studio changes)            │
│     ├─ OR bun sb:new (blank migration)              │
│     └─ Review generated SQL                          │
└─────────────────┬───────────────────────────────────┘
                  │
┌─────────────────▼───────────────────────────────────┐
│  3. Test migration locally                           │
│     ├─ bun sb:reset (fresh DB)                      │
│     ├─ Verify schema                                │
│     └─ Test RLS policies                            │
└─────────────────┬───────────────────────────────────┘
                  │
┌─────────────────▼───────────────────────────────────┐
│  4. Commit migration                                 │
│     ├─ git add apps/database/supabase/migrations/          │
│     ├─ git commit                                    │
│     └─ Push to repository                           │
└─────────────────┬───────────────────────────────────┘
                  │
┌─────────────────▼───────────────────────────────────┐
│  5. Deploy (USER ONLY - AGENTS NEVER)               │
│     ├─ bun sb:push (production)                     │
│     ├─ OR apply via CI/CD                           │
│     └─ Verify in production                         │
└─────────────────────────────────────────────────────┘
```

## Creating Migrations

### Method 1: Generate from Studio Changes

**Best for:** Visual schema editing, quick table creation

1. **Make changes in Supabase Studio:**
   ```bash theme={null}
   bun sb:start
   # Open http://localhost:8003
   # Make changes in Table Editor
   ```

2. **Generate migration:**
   ```bash theme={null}
   bun sb:diff
   ```

3. **Review generated file:**
   ```bash theme={null}
   # apps/database/supabase/migrations/20250101120000_add_new_table.sql
   ```

### Method 2: Manual SQL Migration

**Best for:** Complex changes, custom functions, data migrations

1. **Create blank migration:**
   ```bash theme={null}
   bun sb:new add_custom_function
   ```

2. **Edit migration file:**
   ```sql theme={null}
   -- apps/database/supabase/migrations/20250101120000_add_custom_function.sql

-- Create custom function
   CREATE OR REPLACE FUNCTION get_user_task_count(user_uuid uuid)
   RETURNS integer AS $$
     SELECT COUNT(*)::integer
     FROM workspace_tasks
     WHERE created_by = user_uuid;
   $$ LANGUAGE sql SECURITY DEFINER;
   ```

## Migration File Structure

### Naming Convention

```
[timestamp]_[descriptive_name].sql
```

Examples:

```
20250101120000_create_tasks_table.sql
20250101130000_add_task_priority_column.sql
20250101140000_update_task_rls_policies.sql
```

Keep new migration timestamps ahead of the latest migration already on `main`,
`staging`, and `production`. Supabase refuses to apply a local migration that
sorts before the last remote migration unless the operator passes
`--include-all`. Staging and production CI intentionally run
`supabase db push --include-all` so each project can converge after migration
history changes, but ordinary forward deploys should still keep timestamps
monotonic. After a rebase, merge, or hotfix, re-list
`apps/database/supabase/migrations` and rename any still-unapplied local
migration forward instead of treating `--include-all` as permission to edit or
replay old migration history.

### File Template

```sql theme={null}
-- Migration: [Description]
-- Created: [Date]
-- Author: [Name]

-- Create table
CREATE TABLE IF NOT EXISTS table_name (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  created_at timestamptz DEFAULT now()
);

-- Add indexes
CREATE INDEX idx_table_name_column ON table_name(column);

-- Enable RLS
ALTER TABLE table_name ENABLE ROW LEVEL SECURITY;

-- Add RLS policies
CREATE POLICY "policy_name"
ON table_name
FOR SELECT
USING (true);

-- Add comments
COMMENT ON TABLE table_name IS 'Description of table';
COMMENT ON COLUMN table_name.column IS 'Description of column';
```

## Common Migration Patterns

### Creating Tables

```sql theme={null}
-- Create workspace-scoped table
CREATE TABLE workspace_resources (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  ws_id text NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
  name text NOT NULL,
  description text,
  created_by uuid REFERENCES workspace_users(id) ON DELETE SET NULL,
  created_at timestamptz DEFAULT now(),
  updated_at timestamptz DEFAULT now()
);

-- Add indexes
CREATE INDEX idx_workspace_resources_ws_id ON workspace_resources(ws_id);
CREATE INDEX idx_workspace_resources_created_by ON workspace_resources(created_by);

-- Enable RLS
ALTER TABLE workspace_resources ENABLE ROW LEVEL SECURITY;

-- Add policies
CREATE POLICY "workspace_members_can_view"
ON workspace_resources FOR SELECT
USING (
  ws_id IN (
    SELECT ws_id FROM workspace_members WHERE user_id = auth.uid()
  )
);

CREATE POLICY "permission_required_to_modify"
ON workspace_resources FOR ALL
USING (
  ws_id IN (
    SELECT wm.ws_id FROM workspace_members wm
    JOIN workspace_role_permissions wrp
      ON wrp.ws_id = wm.ws_id AND wrp.role_id = wm.role
    WHERE wm.user_id = auth.uid()
      AND wrp.permission = 'manage_resources'
  )
);
```

### Adding Columns

```sql theme={null}
-- Add nullable column
ALTER TABLE workspace_tasks
ADD COLUMN priority integer;

-- Add column with default
ALTER TABLE workspace_tasks
ADD COLUMN status text DEFAULT 'pending';

-- Add NOT NULL column (requires default or backfill)
ALTER TABLE workspace_tasks
ADD COLUMN category text DEFAULT 'general' NOT NULL;

-- Update existing rows (if needed)
UPDATE workspace_tasks
SET category = 'important'
WHERE priority >= 4;
```

### Modifying Columns

```sql theme={null}
-- Rename column
ALTER TABLE workspace_tasks
RENAME COLUMN old_name TO new_name;

-- Change column type
ALTER TABLE workspace_tasks
ALTER COLUMN priority TYPE smallint USING priority::smallint;

-- Add constraint
ALTER TABLE workspace_tasks
ADD CONSTRAINT priority_range CHECK (priority BETWEEN 0 AND 5);

-- Drop constraint
ALTER TABLE workspace_tasks
DROP CONSTRAINT priority_range;
```

### Creating Indexes

```sql theme={null}
-- Standard index
CREATE INDEX idx_tasks_ws_id ON workspace_tasks(ws_id);

-- Composite index
CREATE INDEX idx_tasks_ws_list ON workspace_tasks(ws_id, list_id);

-- Partial index
CREATE INDEX idx_incomplete_tasks
ON workspace_tasks(ws_id)
WHERE completed = false;

-- Unique index
CREATE UNIQUE INDEX idx_unique_task_name
ON workspace_tasks(ws_id, name);

-- GIN index for JSONB
CREATE INDEX idx_metadata_gin ON workspace_tasks USING GIN (metadata);

-- Text search index
CREATE INDEX idx_tasks_search
ON workspace_tasks USING GIN (to_tsvector('english', name || ' ' || COALESCE(description, '')));
```

### Creating Functions

```sql theme={null}
-- Simple function
CREATE OR REPLACE FUNCTION get_workspace_task_count(workspace_id text)
RETURNS integer AS $$
  SELECT COUNT(*)::integer
  FROM workspace_tasks
  WHERE ws_id = workspace_id;
$$ LANGUAGE sql SECURITY DEFINER;

-- Function with complex logic
CREATE OR REPLACE FUNCTION complete_task_with_notification(task_uuid uuid)
RETURNS void AS $$
DECLARE
  task_name text;
  task_ws_id text;
BEGIN
  -- Update task
  UPDATE workspace_tasks
  SET completed = true, completed_at = now()
  WHERE id = task_uuid
  RETURNING name, ws_id INTO task_name, task_ws_id;

-- Create notification (example)
  INSERT INTO notifications (ws_id, message, type)
  VALUES (task_ws_id, format('Task "%s" completed', task_name), 'success');
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;
```

### Creating Triggers

```sql theme={null}
-- Update updated_at timestamp trigger
CREATE OR REPLACE FUNCTION update_updated_at()
RETURNS trigger AS $$
BEGIN
  NEW.updated_at = now();
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER trigger_update_workspace_tasks_updated_at
  BEFORE UPDATE ON workspace_tasks
  FOR EACH ROW
  EXECUTE FUNCTION update_updated_at();
```

### Creating Enums

```sql theme={null}
-- Create enum
CREATE TYPE task_status AS ENUM ('pending', 'in_progress', 'completed', 'cancelled');

-- Add enum column
ALTER TABLE workspace_tasks
ADD COLUMN status task_status DEFAULT 'pending';

-- Modify enum (add value)
ALTER TYPE task_status ADD VALUE 'on_hold';

-- Cannot remove enum values - requires recreation
```

## Data Migrations

### Safe Data Migration Pattern

```sql theme={null}
-- 1. Add new column
ALTER TABLE workspace_tasks
ADD COLUMN new_priority integer;

-- 2. Backfill data
UPDATE workspace_tasks
SET new_priority = CASE
  WHEN old_priority = 'high' THEN 5
  WHEN old_priority = 'medium' THEN 3
  WHEN old_priority = 'low' THEN 1
  ELSE 0
END;

-- 3. Make NOT NULL (if needed)
ALTER TABLE workspace_tasks
ALTER COLUMN new_priority SET NOT NULL;

-- 4. Drop old column (in separate migration after verification)
-- ALTER TABLE workspace_tasks DROP COLUMN old_priority;
```

### Batch Processing Large Migrations

```sql theme={null}
-- For tables with millions of rows, batch the updates
DO $$
DECLARE
  batch_size integer := 1000;
  rows_updated integer;
BEGIN
  LOOP
    UPDATE workspace_tasks
    SET new_column = calculate_value(old_column)
    WHERE id IN (
      SELECT id FROM workspace_tasks
      WHERE new_column IS NULL
      LIMIT batch_size
    );

GET DIAGNOSTICS rows_updated = ROW_COUNT;
    EXIT WHEN rows_updated = 0;

-- Commit after each batch
    COMMIT;
  END LOOP;
END $$;
```

## Testing Migrations

### Local Testing

```bash theme={null}
# Reset to clean state
bun sb:reset

# Verify schema
bun sb:status

# Check migration list
ls apps/database/supabase/migrations/

# Test specific queries
psql -h localhost -U postgres -d postgres -c "SELECT * FROM workspace_tasks LIMIT 5;"
```

### Test RLS Policies

```sql theme={null}
-- Set user context for testing
SET request.jwt.claim.sub = 'user-uuid-here';

-- Test query with RLS
SELECT * FROM workspace_tasks WHERE ws_id = 'workspace-123';

-- Reset context
RESET request.jwt.claim.sub;
```

### Verify Indexes

```sql theme={null}
-- Check if index is being used
EXPLAIN ANALYZE
SELECT * FROM workspace_tasks WHERE ws_id = 'workspace-123';

-- List all indexes on table
SELECT indexname, indexdef
FROM pg_indexes
WHERE tablename = 'workspace_tasks';
```

## Migration Checklist

Before committing a migration:

* [ ] Migration file has descriptive name
* [ ] All tables have RLS enabled
* [ ] RLS policies are tested
* [ ] Indexes added for foreign keys
* [ ] Indexes added for frequently queried columns
* [ ] Comments added for complex logic
* [ ] Data migration is idempotent
* [ ] Migration tested with `bun sb:reset`
* [ ] Type generation updated (`bun sb:typegen`)
* [ ] Breaking changes documented

## Deploying Migrations

### ⚠️ AGENTS: NEVER RUN THESE COMMANDS

Agents should prepare migrations but NEVER deploy them. Only users should run:

```bash theme={null}
# Link to remote project (one-time setup)
bun sb:link

# Push migrations to production
bun sb:push
```

### Agent Workflow

**Agents should:**

1. Create migration file
2. Test locally with `bun sb:reset`
3. Run `bun sb:typegen`
4. Commit files
5. **Instruct user to run `bun sb:push`**

**Agents should NEVER:**

* Run `bun sb:push`
* Run `bun sb:linkpush`
* Deploy to production

## Rollback Strategy

### Simple Rollback

```sql theme={null}
-- Create reverse migration
-- apps/database/supabase/migrations/20250101150000_rollback_add_priority.sql

ALTER TABLE workspace_tasks DROP COLUMN priority;
```

### Complex Rollback

```sql theme={null}
-- apps/database/supabase/migrations/20250101150000_rollback_task_status_enum.sql

-- 1. Add back old column
ALTER TABLE workspace_tasks ADD COLUMN old_status text;

-- 2. Convert data
UPDATE workspace_tasks
SET old_status = CASE
  WHEN status = 'pending' THEN 'todo'
  WHEN status = 'in_progress' THEN 'doing'
  WHEN status = 'completed' THEN 'done'
END;

-- 3. Drop new column
ALTER TABLE workspace_tasks DROP COLUMN status;

-- 4. Rename old column
ALTER TABLE workspace_tasks RENAME COLUMN old_status TO status;

-- 5. Drop enum type
DROP TYPE task_status;
```

## Common Issues

### Issue: Migration Fails on Production

**Cause:** Local Supabase version differs from production

**Solution:**

```bash theme={null}
# Check Supabase version
bun sb:status

# Update Supabase CLI
bun add -g supabase

# Recreate local instance
bun sb:stop
bun sb:start
```

### Issue: Type Generation Fails

**Cause:** Migration has syntax errors

**Solution:**

```bash theme={null}
# Reset database
bun sb:reset

# Check migration syntax
cat apps/database/supabase/migrations/[migration-file].sql

# Fix errors and retry
bun sb:typegen
```

### Issue: RLS Policy Conflicts

**Cause:** Multiple policies on same table/operation

**Solution:**

```sql theme={null}
-- List all policies
SELECT policyname, permissive, roles, cmd, qual
FROM pg_policies
WHERE tablename = 'workspace_tasks';

-- Drop conflicting policy
DROP POLICY "old_policy" ON workspace_tasks;
```

## Best Practices

### ✅ DO

1. **Use descriptive names**
   ```sql theme={null}
   20250101_add_task_priority_with_validation.sql
   ```

2. **Add indexes for foreign keys**
   ```sql theme={null}
   CREATE INDEX idx_tasks_ws_id ON workspace_tasks(ws_id);
   ```

3. **Enable RLS on all tables**
   ```sql theme={null}
   ALTER TABLE table_name ENABLE ROW LEVEL SECURITY;
   ```

4. **Add comments for clarity**
   ```sql theme={null}
   COMMENT ON TABLE workspace_tasks IS 'User tasks within workspaces';
   ```

5. **Test migrations locally first**
   ```bash theme={null}
   bun sb:reset
   ```

6. **Materialize replacement-table rows before rewiring child foreign keys**
   ```sql theme={null}
   -- When replacing a parent table, copy or upsert the source rows first.
   INSERT INTO workspace_user_groups (id, ws_id, name)
   SELECT id, ws_id, name
   FROM workspace_courses
   ON CONFLICT (id) DO UPDATE
   SET name = EXCLUDED.name;

-- Then backfill the child FK, validate it, and only afterwards drop the legacy column/table.
   ALTER TABLE workspace_course_modules ADD COLUMN group_id uuid;

UPDATE workspace_course_modules
   SET group_id = course_id
   WHERE group_id IS NULL;

-- Verify the backfill before dropping or rewiring the legacy FK in a follow-up migration.
   -- SELECT COUNT(*) FILTER (WHERE group_id IS NULL) AS unmigrated
   -- FROM workspace_course_modules;
   ```

### ❌ DON'T

1. **Don't skip RLS**
   ```sql theme={null}
   -- ❌ Bad: No RLS
   CREATE TABLE table_name (...);
   ```

2. **Don't use DROP without backup**
   ```sql theme={null}
   -- ❌ Dangerous
   DROP TABLE important_data;
   ```

3. **Don't modify old migrations**
   ```sql theme={null}
   -- ❌ Bad: Modifying committed migration
   ```

4. **Don't deploy without testing**
   ```bash theme={null}
   # ❌ Bad: Skip local testing
   bun sb:push
   ```

## Related Documentation

* [Database Schema Overview](/reference/database/schema-overview)
* [RLS Policies](/reference/database/rls-policies)
* [Supabase Client](/reference/packages/supabase)

## External Resources

* [Supabase Migrations](https://supabase.com/docs/guides/cli/local-development#database-migrations)
* [PostgreSQL ALTER TABLE](https://www.postgresql.org/docs/current/sql-altertable.html)

# Row-Level Security (RLS) Policies
Source: https://docs.tuturuuu.com/reference/database/rls-policies

Security model and RLS policy patterns in the Tuturuuu platform

The Tuturuuu platform implements comprehensive Row-Level Security (RLS) policies to enforce workspace-based multi-tenancy and granular permission controls.

## Security Model Overview

### Core Principles

1. **Workspace Isolation**: All workspace-scoped resources are isolated via RLS policies
2. **Permission-Based Access**: Actions require specific workspace role permissions
3. **User Ownership**: Users can only access resources they own or have permission to view
4. **Fail-Secure Default**: No access unless explicitly granted by policy

### Architecture

```
┌─────────────────────────────────────────┐
│         PostgreSQL Database             │
│  ┌───────────────────────────────────┐  │
│  │   RLS Policies (113+ policies)     │  │
│  ├───────────────────────────────────┤  │
│  │  1. Workspace Membership Check     │  │
│  │  2. Permission Verification        │  │
│  │  3. Ownership Validation           │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘
```

## Policy Patterns

### Pattern 1: Workspace Membership Check

**Use Case:** User must be a member of the workspace to access resources.

**Example:** `workspace_tasks` SELECT policy

```sql theme={null}
CREATE POLICY "Users can view tasks in their workspaces"
ON workspace_tasks
FOR SELECT
USING (
  ws_id IN (
    SELECT ws_id
    FROM workspace_members
    WHERE user_id = (select auth.uid())
      AND type = 'MEMBER'
  )
);
```

**Key Components:**

* `auth.uid()`: Gets the authenticated user's ID
* Subquery checks `workspace_members` table
* Returns only rows matching user's workspaces

### Pattern 2: Permission-Based Access

**Use Case:** User needs specific workspace permission to perform action.

**Example:** Task UPDATE policy

```sql theme={null}
CREATE POLICY "Users can update tasks with manage_projects permission"
ON workspace_tasks
FOR UPDATE
USING (
  EXISTS (
    SELECT 1
    FROM workspace_members wm
    WHERE wm.ws_id = workspace_tasks.ws_id
      AND wm.user_id = (select auth.uid())
      AND wm.type = 'MEMBER'
  )
  AND public.has_workspace_permission(
    workspace_tasks.ws_id,
    (select auth.uid()),
    'manage_projects'
  )
)
WITH CHECK (
  EXISTS (
    SELECT 1
    FROM workspace_members wm
    WHERE wm.ws_id = workspace_tasks.ws_id
      AND wm.user_id = (select auth.uid())
      AND wm.type = 'MEMBER'
  )
  AND public.has_workspace_permission(
    workspace_tasks.ws_id,
    (select auth.uid()),
    'manage_projects'
  )
);
```

**Permission Enum Values:**

Permissions come from the `workspace_role_permission` enum. The generated list
is the single source of truth — see the `workspace_role_permission` array in
`packages/types/src/supabase.ts` (regenerated by `bun sb:typegen`) rather than
hard-coding values, since the set evolves with new features. A representative
subset at the time of writing:

* `manage_workspace_settings`
* `manage_workspace_roles`
* `manage_workspace_members`
* `manage_workspace_security`
* `manage_workspace_audit_logs`
* `manage_projects`
* `manage_calendar`
* `manage_documents`
* `manage_drive`
* `manage_users`
* `manage_finance`
* `manage_inventory`
* `ai_chat`
* `ai_lab`

> [!NOTE]
>
> Task and project access is governed by `manage_projects`; there is no
> `manage_tasks` permission. Several values that older docs referenced
> (`manage_infrastructure_settings`, `manage_user_groups`, `manage_user_roles`,
> `ai_lab_assistant`, `view_disabled_users`, `disable_user`) are no longer part
> of the enum. Always confirm a permission string against the generated enum
> before using it in a policy — a typo or removed value will fail the
> `permission::workspace_role_permission` cast at runtime.

### Pattern 3: User Ownership

**Use Case:** User can only access resources they created.

**Example:** `notes` policies

```sql theme={null}
-- SELECT
CREATE POLICY "Users can view their own notes"
ON notes
FOR SELECT
USING (created_by = auth.uid());

-- INSERT
CREATE POLICY "Users can create their own notes"
ON notes
FOR INSERT
WITH CHECK (created_by = auth.uid());

-- UPDATE
CREATE POLICY "Users can update their own notes"
ON notes
FOR UPDATE
USING (created_by = auth.uid());

-- DELETE
CREATE POLICY "Users can delete their own notes"
ON notes
FOR DELETE
USING (created_by = auth.uid());
```

### Pattern 4: Combined Workspace + Permission

**Use Case:** Workspace membership AND specific permission required.

**Example:** Calendar event management

```sql theme={null}
CREATE POLICY "Users can manage calendar events with permission"
ON workspace_calendar_events
FOR ALL
USING (
  EXISTS (
    SELECT 1
    FROM workspace_members wm
    WHERE wm.ws_id = workspace_calendar_events.ws_id
      AND wm.user_id = (select auth.uid())
      AND wm.type = 'MEMBER'
  )
  AND (
    public.has_workspace_permission(
      workspace_calendar_events.ws_id,
      (select auth.uid()),
      'manage_calendar'
    )
    OR public.has_workspace_permission(
      workspace_calendar_events.ws_id,
      (select auth.uid()),
      'manage_workspace_settings'
    )
  )
)
WITH CHECK (
  EXISTS (
    SELECT 1
    FROM workspace_members wm
    WHERE wm.ws_id = workspace_calendar_events.ws_id
      AND wm.user_id = (select auth.uid())
      AND wm.type = 'MEMBER'
  )
  AND (
    public.has_workspace_permission(
      workspace_calendar_events.ws_id,
      (select auth.uid()),
      'manage_calendar'
    )
    OR public.has_workspace_permission(
      workspace_calendar_events.ws_id,
      (select auth.uid()),
      'manage_workspace_settings'
    )
  )
);
```

### Pattern 5: Public Read, Restricted Write

**Use Case:** All workspace members can view, only privileged users can modify.

**Example:** Workspace settings

```sql theme={null}
-- Read: any workspace member
CREATE POLICY "Members can view workspace settings"
ON workspaces
FOR SELECT
USING (
  EXISTS (
    SELECT 1 FROM workspace_members wm
    WHERE wm.ws_id = workspaces.id
      AND wm.user_id = (select auth.uid())
  )
);

-- Write: requires permission
CREATE POLICY "Users can update workspace with permission"
ON workspaces
FOR UPDATE
USING (
  EXISTS (
    SELECT 1
    FROM workspace_members wm
    WHERE wm.ws_id = workspaces.id
      AND wm.user_id = (select auth.uid())
      AND wm.type = 'MEMBER'
  )
  AND public.has_workspace_permission(
    workspaces.id,
    (select auth.uid()),
    'manage_workspace_settings'
  )
)
WITH CHECK (
  EXISTS (
    SELECT 1
    FROM workspace_members wm
    WHERE wm.ws_id = workspaces.id
      AND wm.user_id = (select auth.uid())
      AND wm.type = 'MEMBER'
  )
  AND public.has_workspace_permission(
    workspaces.id,
    (select auth.uid()),
    'manage_workspace_settings'
  )
);
```

### Pattern 6: Cross-Table Permission Inheritance

**Use Case:** Permission check depends on related table's policies.

**Example:** Task project members inherit from project permissions

```sql theme={null}
CREATE POLICY "Project members can view project tasks"
ON task_project_tasks
FOR SELECT
USING (
  project_id IN (
    SELECT id FROM task_projects
    -- task_projects has its own RLS policy checking workspace membership
  )
);
```

### Pattern 7: Platform User Profile Visibility

**Use Case:** Platform profile rows are useful for names and avatars, but the
Data API must not let any authenticated user enumerate every account.

`public.users` is not a globally readable directory. Authenticated callers can
read their own row and rows for users who share at least one workspace with
them. Private account fields such as email and full name belong in
`public.user_private_details`. Account state and preferences such as
`services`, `timezone`, `first_day_of_week`, `time_format`, and `deleted` also
belong there instead of on the public profile row.

`public.user_private_details` may be used for self-profile and shared-workspace
profile lookups, but the policy must correlate the target user to the current
requesting user. Do not use an uncorrelated `EXISTS` check that only proves the
target user belongs to some workspace.

Use a `SECURITY DEFINER` helper for the shared-workspace check so the profile
policy does not recurse through `workspace_members` RLS under the caller's
permissions.

Do not restore a policy equivalent to `USING (true)` on `public.users`. If a
feature needs a global user directory or public profile page, expose only the
intended columns through an application route or a purpose-built API contract
instead of widening the table policy.

```sql theme={null}
CREATE POLICY "Enable read access for current user and workspace members"
ON public.users
FOR SELECT
TO authenticated
USING (
  (select auth.uid()) is not null
  and (
    id = (select auth.uid())
    or public.current_user_shares_workspace_with(users.id)
  )
);
```

### Pattern 8: Client-Facing Public Views

**Use Case:** A view in the exposed `public` schema is granted to `anon` or
`authenticated`.

Postgres views are security definer by default when created by privileged
owners. In Supabase, that means a public view can bypass RLS on the underlying
tables even when every base table has RLS enabled. Any public-schema view that
is directly selectable by `anon` or `authenticated` must be created or altered
with `security_invoker = true`.

Do not use a public view as a shortcut around table policies. If a view needs
privileged data such as audit records or private profile details, revoke direct
client-role `SELECT` and expose the data through a permission-checked API route
or RPC instead.

```sql theme={null}
CREATE OR REPLACE VIEW public.workspace_safe_summary
WITH (security_invoker = true) AS
SELECT ...
FROM public.workspace_scoped_table;

REVOKE SELECT ON public.audit_logs FROM anon, authenticated;
```

New public views should be covered by `public-view-security.sql`, which fails
when a Data API-exposed view is missing `security_invoker`.

### Pattern 9: Workspace-Scoped Security Definer RPCs

**Use Case:** An RPC must run with elevated database privileges to read audit,
private, or RLS-protected tables.

Every workspace-scoped `SECURITY DEFINER` RPC that is reachable through the
Supabase Data API must enforce authorization inside the database function. Page,
route, or server action permission checks are not sufficient because clients can
call exposed RPCs directly.

Required controls:

* Read the caller with `auth.uid()` and deny missing callers unless the JWT role
  is `service_role`.
* Verify workspace membership and the workspace permission in the function
  before reading sensitive rows. Do not rely on permission helpers alone when a
  default permission could be enabled workspace-wide.
* For identity-linking flows, resolve candidate identity inside the function
  from the current verified `auth.users` row. Gate privileged lookups with the
  workspace feature config before returning candidate IDs, and do not accept
  caller-supplied emails or user-editable profile fields as proof of identity.
* Revoke direct execution from `public` and `anon`.
* Avoid exposing lower-level privileged helper functions to `authenticated` when
  they do not perform their own permission check.
* Cover the grant matrix and allowed/denied calls with pgTAP when practical.

```sql theme={null}
create or replace function public.authorize_workspace_sensitive_rpc(
  p_ws_id uuid
)
returns void
language plpgsql
security definer
set search_path = ''
as $$
begin
  if auth.role() = 'service_role' then
    return;
  end if;

if auth.uid() is null then
    raise exception 'auth_required' using errcode = '42501';
  end if;

if not exists (
    select 1
    from public.workspace_members workspace_member
    where workspace_member.ws_id = p_ws_id
      and workspace_member.user_id = auth.uid()
  ) then
    raise exception 'permission_denied' using errcode = '42501';
  end if;

if not public.has_workspace_permission(
    p_ws_id,
    auth.uid(),
    'manage_workspace_audit_logs'
  ) then
    raise exception 'permission_denied' using errcode = '42501';
  end if;
end;
$$;

revoke execute on function public.authorize_workspace_sensitive_rpc(uuid) from public;
revoke execute on function public.authorize_workspace_sensitive_rpc(uuid) from anon;
revoke execute on function public.authorize_workspace_sensitive_rpc(uuid) from authenticated;
```

### Pattern 10: API-Only Workspace Tables

**Use Case:** The `apps/web` API performs stricter permission checks than a
plain workspace membership policy can express safely, then reads or writes with
`createAdminClient()`.

For these tables, do not grant `anon` or `authenticated` direct Data API access
and do not leave member-only RLS policies in place. A browser or REST client can
call exposed Supabase tables directly with the publishable key, bypassing route
checks such as `manage_users` or `send_user_group_post_emails`.

Required controls:

* Revoke table privileges from `public`, `anon`, and `authenticated`.
* Keep table access behind service-role API routes that perform the workspace
  permission check first.
* Keep service-role grants explicit. The proxy route is the public contract; the
  table is not a browser, mobile, REST, or GraphQL contract.
* Drop permissive member-only RLS policies on the underlying tables; use
  service-role-only policies when an explicit policy is useful for review.
* Add the tables to `PROXY_ONLY_PUBLIC_TABLES` in
  `packages/supabase/src/next/protected-tables.ts` so deprecated direct clients
  fail loudly during app development.
* Revoke direct `EXECUTE` from exposed helper RPCs unless the function performs
  its own caller authorization.

The migration `20260522172925_harden_proxy_only_public_tables.sql` applies this
transition guardrail to the current `PROXY_ONLY_PUBLIC_TABLES` set and also
revokes automatic grants for future `public` tables, functions, and sequences.
New migrations that intentionally expose a public Data API surface must now add
the matching explicit `GRANT` statements in the same migration.

```sql theme={null}
revoke all privileges on table public.sensitive_workspace_table
from public, anon, authenticated;

drop policy if exists "Allow workspace members to manage sensitive workspace table"
  on public.sensitive_workspace_table;

create policy "Allow service role to manage sensitive workspace table"
  on public.sensitive_workspace_table
  for all
  to service_role
  using (true)
  with check (true);
```

### Pattern 11: Private Schema Server-Owned Tables

**Use Case:** A table, helper function, or protected query surface is only
needed by cron jobs, service-role routes, Tuturuuu API routes, or database
internals and should not be exposed through Supabase's generated REST API at
all.

Default new protected database access to the existing `private` schema unless
the data is intentionally public. Do not add `private` to the Supabase Data API
exposed schemas or extra search path. New migrations should prefer direct
server-owned access from `apps/web`: call private RPCs through the server-side
Supabase admin client with `schema('private').rpc(...)`, and use
`getPlatformSql()` only for private table access that is not modeled as an RPC.
This keeps browser and mobile consumers on centralized `apps/web` API routes
while avoiding new Supabase REST endpoints for private data.

Legacy `public` bridging RPCs may exist while older code is migrated, but do
not add new public RPCs for tables or protected helper queries that can be
reached through the server-side database connection.

If a public table has no app/package consumers and is not part of an active
database contract, prefer dropping it in a forward migration instead of moving
dead schema surface into `private`.

Notification delivery queue internals follow this pattern:
`private.notification_batches` and `private.notification_delivery_log` are
processed only by the server-owned batch cron, immediate-send route, and
service-role notification helper functions.

Required controls:

* Keep `anon` and `authenticated` without `USAGE` on `private`.
* Revoke direct table privileges from `public`, `anon`, and `authenticated`.
* Keep RLS enabled with service-role-only policies for reviewability.
* Keep private table reads and writes inside server-only modules used by
  `apps/web` routes, server actions, or server components.
* Cover private placement, table privileges, and schema usage with pgTAP tests.

```sql theme={null}
create schema if not exists private;

revoke all on schema private from public, anon, authenticated;
grant usage on schema private to service_role;

alter table if exists public.server_owned_table
  set schema private;

revoke all on table private.server_owned_table
from public, anon, authenticated;

alter table private.server_owned_table enable row level security;

create policy "Service role can manage server-owned table"
  on private.server_owned_table
  for all
  to service_role
  using (true)
  with check (true);
```

## Common RLS Helpers

### Get User Workspaces

```sql theme={null}
CREATE FUNCTION get_user_workspaces(user_uuid uuid)
RETURNS TABLE(ws_id text) AS $$
  SELECT ws_id
  FROM workspace_members
  WHERE user_id = user_uuid
    AND pending = false;
$$ LANGUAGE sql SECURITY DEFINER;
```

### Check Workspace Permission

The deployed helper is `public.has_workspace_permission(p_ws_id, p_user_id, p_permission)`.
The workspace id comes first, the user id second, and the permission is passed as
`text` (cast inside the function to `workspace_role_permission`). It checks both
role-based grants (`workspace_role_members` → `workspace_role_permissions`) and
workspace-wide default permissions (`workspace_default_permissions`), and only
counts rows where `enabled = true`. Match this signature when calling it from
policies or RPCs (see Pattern 9).

```sql theme={null}
-- Mirrors apps/database/.../add_has_workspace_permission.sql
CREATE OR REPLACE FUNCTION public.has_workspace_permission(
  p_ws_id uuid,
  p_user_id uuid,
  p_permission text
)
RETURNS boolean
LANGUAGE plpgsql
SECURITY DEFINER
STABLE
AS $$
BEGIN
  RETURN EXISTS (
    -- Role-based grant
    SELECT 1
    FROM workspace_role_members wrm
    JOIN workspace_role_permissions wrp
      ON wrp.role_id = wrm.role_id
      AND wrp.ws_id = p_ws_id
    WHERE wrm.user_id = p_user_id
      AND wrp.permission = p_permission::public.workspace_role_permission
      AND wrp.enabled = true

UNION

-- Workspace-wide default grant
    SELECT 1
    FROM workspace_default_permissions wdp
    WHERE wdp.ws_id = p_ws_id
      AND wdp.permission = p_permission::public.workspace_role_permission
      AND wdp.enabled = true
  );
END;
$$;
```

> [!NOTE]
>
> Call it as `public.has_workspace_permission(ws_id, auth.uid(), 'manage_projects')`.
> Argument order matters: `(p_ws_id, p_user_id, p_permission)`. Passing the user
> id and workspace id in the wrong order silently checks the wrong workspace.

## Policy Testing

### Enable RLS (Always Required)

```sql theme={null}
ALTER TABLE table_name ENABLE ROW LEVEL SECURITY;
```

### Test Policy as User

```sql theme={null}
-- Impersonate user for testing
SET request.jwt.claim.sub = 'user-uuid-here';

-- Run queries to verify policy
SELECT * FROM workspace_tasks WHERE ws_id = 'workspace-123';

-- Reset
RESET request.jwt.claim.sub;
```

### Verify Policy Coverage

```sql theme={null}
-- Check if all tables have RLS enabled
SELECT tablename
FROM pg_tables
WHERE schemaname = 'public'
  AND tablename NOT IN (
    SELECT tablename
    FROM pg_tables t
    JOIN pg_class c ON c.relname = t.tablename
    WHERE c.relrowsecurity = true
  );
```

## Security Best Practices

### 1. Always Enable RLS

```sql theme={null}
-- ✅ Good
CREATE TABLE my_table (...);
ALTER TABLE my_table ENABLE ROW LEVEL SECURITY;

-- ❌ Bad
CREATE TABLE my_table (...);
-- Forgot to enable RLS!
```

### 2. Use SECURITY DEFINER Carefully

Only use `SECURITY DEFINER` for helper functions that need elevated privileges:

```sql theme={null}
-- ✅ Good: Helper needs admin access
CREATE FUNCTION admin_helper() ... SECURITY DEFINER;

-- ❌ Bad: Bypasses RLS unnecessarily
CREATE FUNCTION simple_query() ... SECURITY DEFINER;
```

### 3. Test Policies Thoroughly

Always test:

* ✅ Users can access their own data
* ✅ Users cannot access other workspaces' data
* ✅ Permission checks work correctly
* ✅ Edge cases (pending invites, disabled users)

### 4. Avoid Policy Conflicts

```sql theme={null}
-- ❌ Bad: Multiple policies may conflict
CREATE POLICY "policy_1" ON table FOR SELECT USING (...);
CREATE POLICY "policy_2" ON table FOR SELECT USING (...);
-- Which one applies?

-- ✅ Good: One comprehensive policy per operation
CREATE POLICY "select_policy" ON table FOR SELECT USING (
  condition_1 OR condition_2
);
```

### 5. Performance Considerations

```sql theme={null}
-- ❌ Bad: Subquery runs for every row
CREATE POLICY "slow_policy" ON table FOR SELECT USING (
  column IN (SELECT id FROM expensive_query)
);

-- ✅ Good: Use indexed foreign keys
CREATE POLICY "fast_policy" ON table FOR SELECT USING (
  ws_id = (SELECT ws_id FROM workspace_members WHERE user_id = auth.uid() LIMIT 1)
);
```

## Common Policy Patterns by Table Type

### Workspace-Scoped Resources

```sql theme={null}
ALTER TABLE resource ENABLE ROW LEVEL SECURITY;

CREATE POLICY "workspace_members_can_view"
ON resource FOR SELECT
USING (ws_id IN (SELECT ws_id FROM workspace_members WHERE user_id = auth.uid()));

CREATE POLICY "permission_required_to_modify"
ON resource FOR ALL
USING (
  EXISTS (
    SELECT 1 FROM workspace_members wm
    WHERE wm.ws_id = resource.ws_id
      AND wm.user_id = (select auth.uid())
      AND wm.type = 'MEMBER'
  )
  AND public.has_workspace_permission(
    resource.ws_id,
    (select auth.uid()),
    'manage_projects'
  )
)
WITH CHECK (
  EXISTS (
    SELECT 1 FROM workspace_members wm
    WHERE wm.ws_id = resource.ws_id
      AND wm.user_id = (select auth.uid())
      AND wm.type = 'MEMBER'
  )
  AND public.has_workspace_permission(
    resource.ws_id,
    (select auth.uid()),
    'manage_projects'
  )
);
```

### User-Owned Resources

```sql theme={null}
ALTER TABLE user_resource ENABLE ROW LEVEL SECURITY;

CREATE POLICY "users_can_manage_own"
ON user_resource FOR ALL
USING (user_id = auth.uid());
```

### Public Read Resources

```sql theme={null}
ALTER TABLE public_resource ENABLE ROW LEVEL SECURITY;

CREATE POLICY "anyone_can_read"
ON public_resource FOR SELECT
USING (true);

CREATE POLICY "admin_can_write"
ON public_resource FOR ALL
USING (
  EXISTS (
    SELECT 1 FROM workspace_members wm
    WHERE wm.ws_id = public_resource.ws_id
      AND wm.user_id = (select auth.uid())
      AND wm.type = 'MEMBER'
  )
  AND public.has_workspace_permission(
    public_resource.ws_id,
    (select auth.uid()),
    'manage_workspace_settings'
  )
)
WITH CHECK (
  EXISTS (
    SELECT 1 FROM workspace_members wm
    WHERE wm.ws_id = public_resource.ws_id
      AND wm.user_id = (select auth.uid())
      AND wm.type = 'MEMBER'
  )
  AND public.has_workspace_permission(
    public_resource.ws_id,
    (select auth.uid()),
    'manage_workspace_settings'
  )
);
```

## Debugging RLS Issues

### Check Active Policies

```sql theme={null}
SELECT schemaname, tablename, policyname, permissive, roles, cmd, qual
FROM pg_policies
WHERE tablename = 'your_table_name';
```

### Test as Specific User

```sql theme={null}
-- In Supabase SQL Editor
SELECT set_config('request.jwt.claim.sub', 'user-uuid', false);
SELECT * FROM workspace_tasks; -- Runs with RLS as that user
```

### Bypass RLS for Admin Operations

Use `createAdminClient()` from `@tuturuuu/supabase` in server-side code:

```typescript theme={null}
import { createAdminClient } from '@tuturuuu/supabase/next/server';

const sbAdmin = createAdminClient(); // synchronous - do not await
// This client bypasses RLS - use carefully!
```

Always name `createAdminClient()` locals `sbAdmin`, not `supabase`, so service-role access is visually distinct from request-scoped clients during review.

## Migration Example

When adding a new table, always include RLS:

```sql theme={null}
-- Create table
CREATE TABLE new_feature (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  ws_id uuid REFERENCES workspaces(id) ON DELETE CASCADE,
  name text NOT NULL,
  created_by uuid REFERENCES workspace_users(id),
  created_at timestamptz DEFAULT now()
);

-- Enable RLS
ALTER TABLE new_feature ENABLE ROW LEVEL SECURITY;

-- Add policies
CREATE POLICY "workspace_members_can_view"
ON new_feature FOR SELECT
USING (ws_id IN (
  SELECT ws_id FROM workspace_members
  WHERE user_id = (select auth.uid())
    AND type = 'MEMBER'
));

CREATE POLICY "permission_required_to_modify"
ON new_feature FOR ALL
USING (
  EXISTS (
    SELECT 1 FROM workspace_members wm
    WHERE wm.ws_id = new_feature.ws_id
      AND wm.user_id = (select auth.uid())
      AND wm.type = 'MEMBER'
  )
  AND public.has_workspace_permission(
    new_feature.ws_id,
    (select auth.uid()),
    'manage_projects'
  )
)
WITH CHECK (
  EXISTS (
    SELECT 1 FROM workspace_members wm
    WHERE wm.ws_id = new_feature.ws_id
      AND wm.user_id = (select auth.uid())
      AND wm.type = 'MEMBER'
  )
  AND public.has_workspace_permission(
    new_feature.ws_id,
    (select auth.uid()),
    'manage_projects'
  )
);

-- Add indexes for policy performance
CREATE INDEX idx_new_feature_ws_id ON new_feature(ws_id);
CREATE INDEX idx_new_feature_created_by ON new_feature(created_by);
```

## Privilege Grants vs RLS Scope

RLS policies only apply after SQL privileges have already allowed the role to
touch a table. For sensitive workspace configuration tables, avoid granting
`insert`, `update`, or `delete` to the broad `authenticated` role when the
matching RLS policies only check workspace membership.

Keep `authenticated` grants read-only unless the table policy itself enforces
the same granular permission that the application route requires. Route
privileged writes through permission-gated API handlers using elevated
service-role access.

## Related Documentation

* [Database Schema Overview](/reference/database/schema-overview)
* [Permission System](/platform/architecture/authorization)
* [Supabase Client Usage](/reference/packages/supabase)

# Database Schema Overview
Source: https://docs.tuturuuu.com/reference/database/schema-overview

Complete reference for the Tuturuuu platform database schema

The Tuturuuu platform uses Supabase (PostgreSQL) with a comprehensive multi-tenant architecture. This document provides an overview of the database schema, organized by domain.

## Core Architecture

### Multi-Tenancy Model

The database implements **workspace-based multi-tenancy** where:

* Each workspace is isolated via Row-Level Security (RLS) policies
* Users can belong to multiple workspaces
* Resources are scoped to workspaces using `ws_id` foreign keys
* Permissions are managed through workspace roles and granular permissions

### Key Design Principles

1. **Security First**: All tables have RLS policies enforcing workspace isolation
2. **Audit Trails**: Many tables include `created_at` and `updated_at` timestamps
3. **Soft Deletes**: Critical tables support soft deletion patterns
4. **Hierarchical Structures**: Support for nested organizational structures (tasks, calendars, etc.)

### Private Schema Operations

Private tables and RPCs used by `apps/web` are exposed to server-side Supabase
clients through PostgREST's configured private schema. After production
migrations add private tables, RPC signatures, or columns that the app reads
through `.schema('private')`, reload the PostgREST schema cache:

```sql theme={null}
notify pgrst, 'reload schema';
```

Local Supabase restarts usually refresh this cache automatically, so stale-cache
failures can appear only in production after otherwise successful migrations.

## Schema Domains

### User & Workspace Management

#### `workspace_users`

Primary user table with workspace association.

**Key Fields:**

* `id` (uuid, PK)
* `display_name` (text)
* `email` (text)
* `phone` (text)
* `avatar_url` (text)

#### `workspaces`

Workspace container for multi-tenant organization.

**Key Fields:**

* `id` (text, PK)
* `name` (text)
* `logo_url` (text)
* `created_at` (timestamptz)

#### `workspace_members`

Links users to workspaces with roles.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (text, FK → workspaces)
* `user_id` (uuid, FK → workspace\_users)
* `role` (text)
* `pending` (boolean) - invitation status

#### `workspace_role_permissions`

Granular permission system for workspace roles.

**Key Fields:**

* `ws_id` (text, FK → workspaces)
* `role_id` (text)
* `permission` (workspace\_role\_permission enum)
* `created_at` (timestamptz)

**Available Permissions:**

> [!WARNING]
>
> The `workspace_role_permission` enum is large (100+ values) and evolves
> frequently as new product surfaces ship. The generated TypeScript union is the
> single source of truth — do **not** hand-copy permission names from this page
> into RLS policies, role seeds, or app code. Read the live union instead:
>
> ```typescript theme={null}
> import type { Database } from '@tuturuuu/types';
>
> type WorkspacePermission =
>   Database['public']['Enums']['workspace_role_permission'];
> ```
>
> In SQL, the canonical definition lives in the `workspace_role_permission` enum
> type (defined by the migrations under `apps/database/supabase/migrations/`).

The values below are a representative snapshot grouped by domain (accurate as of
this page's `updatedAt`, but treat the generated type as authoritative):

* **Workspace administration**: `manage_workspace_settings`,
  `manage_workspace_roles`, `manage_workspace_members`,
  `manage_workspace_security`, `manage_workspace_integrations`,
  `manage_workspace_billing`, `manage_workspace_audit_logs`,
  `manage_workspace_secrets`, `manage_subscription`, `manage_api_keys`,
  `manage_e2ee`, `admin`
* **Infrastructure**: `view_infrastructure`, `manage_external_migrations`,
  `manage_infrastructure_stress_tests`, `manage_mobile_deployment_vault`
* **Users & groups**: `manage_users`, `create_users`, `update_users`,
  `delete_users`, `export_users_data`, `view_users_public_info`,
  `view_users_private_info`, `view_user_groups`, `create_user_groups`,
  `update_user_groups`, `delete_user_groups`, `send_user_group_post_emails`,
  `manage_user_report_templates`, `manage_user_profile_links`
* **Finance**: `manage_finance`, `export_finance_data`, `view_finance_stats`,
  `view_transactions`, `create_transactions`, `update_transactions`,
  `delete_transactions`, `view_invoices`, `view_expenses`, `view_incomes`,
  `create_wallets`, `update_wallets`, `delete_wallets`, `change_finance_wallets`,
  `view_confidential_amount`, `view_confidential_description`
* **Inventory**: `manage_inventory`, `view_inventory`, `create_inventory`,
  `update_inventory`, `delete_inventory`, `view_inventory_catalog`,
  `manage_inventory_catalog`, `view_inventory_stock`, `adjust_inventory_stock`,
  `view_inventory_sales`, `view_inventory_analytics`
* **AI**: `ai_chat`, `ai_lab`
* **Chat**: `view_chat`, `create_chat`, `manage_chat`, `moderate_chat`
* **Projects, docs & drive**: `manage_projects`, `manage_documents`,
  `manage_drive`, `view_drive`, `manage_drive_tasks_directory`,
  `manage_external_projects`, `publish_external_projects`
* **Calendar & time tracking**: `manage_calendar`,
  `manage_time_tracking_requests`, `bypass_time_tracking_request_approval`
* **Workforce & payroll**: `manage_workforce`, `view_workforce`,
  `manage_payroll`, `view_payroll`, `check_user_attendance`,
  `update_user_attendance`
* **Forms & changelog**: `manage_forms`, `view_form_analytics`,
  `manage_changelog`

The previously documented permissions `manage_infrastructure_settings`,
`ai_lab_assistant`, `manage_user_groups`, `manage_user_roles`,
`manage_external_users`, `view_disabled_users`, and `disable_user` have been
**removed or renamed** in the current enum — do not reference them in new policies.

### Authentication & Credential Handoffs

#### `private.cross_app_tokens`

Private short-lived tokens for cross-app authentication handoffs. Client and
satellite apps should use the existing public RPC helpers or central
`apps/web` verification route; do not read or write the table through public
Supabase REST access.

**Key Fields:**

* `id` (uuid, PK)
* `user_id` (uuid, FK → users)
* `token` (text, unique)
* `origin_app` (text)
* `target_app` (text)
* `expires_at` (timestamptz)
* `used_at` (timestamptz)
* `session_data` (jsonb)

#### `private.internal_email_api_keys`

Private API credentials for the internal mail send route. The
`apps/web` route reads these keys with the server-side admin client and keeps
credential validation behind the application proxy.

**Key Fields:**

* `id` (uuid, PK)
* `creator_id` (uuid, FK → users)
* `user_id` (uuid, FK → users)
* `value` (text)
* `allowed_emails` (text\[])
* `created_at` (timestamptz)

### Notification Delivery Internals

#### `private.notification_batches`

Private operational queue rows for email and push notification delivery.
Server-owned `apps/web` cron and immediate-send routes read and update these
rows through the service-role client; browser, mobile, and satellite apps should
not query them directly.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (uuid, FK → workspaces, nullable for pending-email flows)
* `user_id` (uuid, FK → users, nullable for pending-email flows)
* `email` (text)
* `channel` (text)
* `delivery_mode` (notification\_delivery\_mode)
* `status` (text)
* `window_start` / `window_end` (timestamptz)

#### `private.notification_delivery_log`

Private delivery-attempt records linked to persisted notifications and optional
batches. The table is intentionally excluded from public Data API and Realtime
access; inspect or mutate it through centralized notification APIs only.

**Key Fields:**

* `id` (uuid, PK)
* `notification_id` (uuid, FK → notifications)
* `batch_id` (uuid, FK → private.notification\_batches)
* `channel` (text)
* `status` (text)
* `retry_count` (integer)
* `sent_at` (timestamptz)

### Task Management Hierarchy

The platform implements a 6-level hierarchical task management system:

```
Workspaces (top-level)
└── Task Initiatives (strategic grouping)
    └── Task Projects (cross-board coordination)
        └── Workspace Boards (kanban boards)
            └── Task Lists (columns)
                └── Workspace Tasks (work items)
```

#### `notes`

Unstructured notes that can be converted to tasks or projects (Bucket Dump feature).

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (text, FK → workspaces)
* `title` (text)
* `content` (text)
* `created_by` (uuid, FK → workspace\_users)

#### `task_initiatives`

Strategic initiatives grouping multiple projects.

**Key Fields:**

* `id` (text, PK)
* `ws_id` (text, FK → workspaces)
* `name` (text)
* `description` (text)
* `start_date` (date)
* `end_date` (date)

#### `task_projects`

Cross-functional projects coordinating tasks across boards.

**Key Fields:**

* `id` (text, PK)
* `ws_id` (text, FK → workspaces)
* `name` (text)
* `description` (text)

**Relationships:**

* `task_project_initiatives` - links projects to initiatives
* `task_project_tasks` - links tasks to projects

#### `workspace_boards`

Kanban-style task boards.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (text, FK → workspaces)
* `name` (text)
* `description` (text)
* `created_at` (timestamptz)

#### `task_lists`

Columns within boards (e.g., "To Do", "In Progress", "Done").

**Key Fields:**

* `id` (text, PK)
* `board_id` (uuid, FK → workspace\_boards)
* `name` (text)
* `position` (integer) - display order

#### `workspace_tasks`

Individual work items.

**Key Fields:**

* `id` (text, PK)
* `ws_id` (text, FK → workspaces)
* `list_id` (text, FK → task\_lists)
* `name` (text)
* `description` (text)
* `priority` (integer)
* `completed` (boolean)
* `start_date` (date)
* `due_date` (date)
* `created_by` (uuid, FK → workspace\_users)

**Related Tables:**

* `task_cycles` - sprint/iteration grouping
* `task_labels` - categorization tags
* `task_estimates` - effort estimation (fibonacci, exponential, linear, t-shirt)
* `task_statuses` - custom status definitions per board

### AI Features

#### `private.ai_providers`

Legacy supported AI providers retained for historical foreign-key compatibility.
Active model catalog APIs should use `private.ai_gateway_models` through centralized
`apps/web` routes instead of Supabase REST/PostgREST.

**Key Fields:**

* `id` (text, PK)
* `name` (text)
* `created_at` (timestamptz)

#### `private.ai_models`

Legacy AI models per provider retained for historical foreign-key compatibility.
Active model catalog APIs should use `private.ai_gateway_models` through centralized
`apps/web` routes instead of Supabase REST/PostgREST.

**Key Fields:**

* `id` (text, PK)
* `provider` (text, FK → private.ai\_providers)
* `name` (text)
* `enabled` (boolean)

#### `ai_chats`

Persistent chat sessions.

**Key Fields:**

* `id` (uuid, PK)
* `title` (text)
* `model` (text) - free-text AI Gateway model id in `provider/model` form
  (e.g. `google/gemini-2.5-flash`). No longer a foreign key — the legacy
  `ai_chats.model → private.ai_models` constraint was dropped, and
  `private.ai_gateway_models` is now the single source of truth for the active
  model catalog.
* `creator_id` (uuid, FK → workspace\_users)

#### `ai_chat_messages`

Individual messages within chat sessions.

**Key Fields:**

* `id` (uuid, PK)
* `chat_id` (uuid, FK → ai\_chats)
* `role` (text) - user, assistant, system
* `content` (text)
* `created_at` (timestamptz)

#### `workspace_ai_executions`

Token usage tracking for billing.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (text, FK → workspaces)
* `model_id` (text, FK → private.ai\_models) - retains the legacy `ai_models`
  reference for historical executions; the active model catalog now lives in
  `private.ai_gateway_models`, and pricing helpers map identifiers accordingly
* `input_tokens` (integer)
* `output_tokens` (integer)
* `total_tokens` (integer)

#### `private.ai_whitelisted_emails`

Server-owned email whitelist for AI feature access. This table is kept outside
the Supabase REST-exposed `public` schema; apps should check or manage access
through centralized `apps/web` APIs.

### Private Reference Tables

#### `private.currencies`

Finance reference data retained for foreign-key compatibility with
`private.workspace_wallets` and `currency_exchange_rates`. Runtime consumers should use
centralized app APIs or package currency constants instead of Supabase REST.

#### `private.field_types`

Workspace user-field reference data retained for historical foreign keys.
Management should go through centralized app APIs instead of direct public table
access.

#### `private.healthcare_diagnoses`

Legacy healthcare diagnosis records retained for historical checkup foreign keys.
Server-side helpers own access; the public count RPC is restricted to
`service_role` and reads from the private schema.

#### `private.personal_notes`

Legacy per-user notes retained for historical compatibility. Active personal
task-note behavior should stay behind centralized app flows instead of Supabase
REST table access.

#### `private.team_members`

Legacy team membership data retained for historical foreign-key compatibility.
Active membership flows should use workspace or Nova team tables.

#### `private.timezones`

Timezone synchronization records for infrastructure management. The dashboard
continues to source canonical timezone data from package constants and reaches
stored records only through `apps/web` APIs.

### Calendar System

#### `workspace_calendar_events`

Calendar events with Google Calendar sync support.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (text, FK → workspaces)
* `title` (text)
* `description` (text)
* `start_at` (timestamptz)
* `end_at` (timestamptz)
* `location` (text)
* `google_event_id` (text) - for sync
* `creator_id` (uuid, FK → workspace\_users)

#### `private.calendar_event_participants`

Legacy event-attendee projection retained for historical compatibility and
service-role workflows. Current application code does not query this legacy
participant model directly.

**Key Fields:**

* `event_id` (uuid, FK → workspace\_calendar\_events)
* `participant_id` (uuid, FK → users, workspace\_users, or workspace\_user\_groups)
* `going` (boolean, nullable for participant groups)

#### `calendar_sync_states`

Tracks synchronization state with Google Calendar.

**Key Fields:**

* `ws_id` (text, PK, FK → workspaces)
* `sync_token` (text) - Google sync token
* `last_synced_at` (timestamptz)
* `is_syncing` (boolean) - prevents concurrent syncs

#### `calendar_auth_tokens`

OAuth tokens for Google Calendar integration.

**Key Fields:**

* `user_id` (uuid, PK, FK → workspace\_users)
* `access_token` (text, encrypted)
* `refresh_token` (text, encrypted)
* `expires_at` (timestamptz)

#### `private.workspace_calendar_sync_log`

Private operational audit trail for calendar sync jobs. Access this table
through service-role infrastructure routes instead of Supabase REST table
access.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (uuid, FK → workspaces)
* `google_account_email` (text)
* `sync_started_at` (timestamptz)
* `sync_ended_at` (timestamptz)
* `status` (text) - success, failed, in\_progress, cancelled, partial\_success
* `error_message` (text)
* `event_snapshot_before` (jsonb)

### Finance Management

#### `private.workspace_wallets`

Primary wallet for workspace financial tracking. Wallet rows are owned by
server-side finance APIs that verify workspace permissions before using
service-role private schema access.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (text, FK → workspaces)
* `name` (text)
* `balance` (numeric)
* `currency` (text)

#### `credit_wallets`

Credit-based wallet system.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (text, FK → workspaces)
* `balance` (numeric) - credit amount
* `currency` (text)

#### `wallet_transactions`

Financial transaction history.

**Key Fields:**

* `id` (uuid, PK)
* `wallet_id` (uuid, FK → private.workspace\_wallets)
* `amount` (numeric)
* `description` (text)
* `type` (text) - income, expense, transfer
* `category_id` (uuid, FK → transaction\_categories)
* `created_at` (timestamptz)

#### `workspace_role_wallet_whitelist`

Role-based wallet access control with time-bounded viewing windows.

**Purpose:** Controls which workspace roles can access specific wallets and defines the historical data viewing window for each role-wallet pairing.

**Key Fields:**

* `id` (uuid, PK)
* `role_id` (uuid, FK → workspace\_roles) - the role granted access
* `wallet_id` (uuid, FK → private.workspace\_wallets) - the wallet being accessed
* `viewing_window` (text) - allowed values: `1_day`, `3_days`, `7_days`, `2_weeks`, `1_month`, `1_quarter`, `1_year`, `custom`
* `custom_days` (integer) - required when `viewing_window = 'custom'`; must be > 0; must be NULL otherwise
* `created_at` (timestamptz)

**Constraints:**

* Unique constraint on `(role_id, wallet_id)` - one whitelist entry per role-wallet pair
* CHECK constraint on `viewing_window` - enforces allowed literal values
* CHECK constraint on `custom_days` - ensures presence/positivity when `viewing_window = 'custom'` and NULL otherwise

**Access Control:**

* RLS policies restrict access to users with `manage_workspace_roles` permission
* INSERT policy validates wallet belongs to the same workspace as the role
* UPDATE policy enforces wallet-workspace consistency via WITH CHECK clause

### Meeting Management

#### `meeting_plans`

Scheduled meetings with metadata.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (text, FK → workspaces)
* `title` (text)
* `description` (text)
* `start_time` (timestamptz)
* `end_time` (timestamptz)

#### `meeting_plan_timeblocks`

Time allocations within meetings.

**Key Fields:**

* `id` (uuid, PK)
* `meeting_id` (uuid, FK → meeting\_plans)
* `title` (text)
* `duration` (integer) - minutes
* `position` (integer)

#### `meeting_guest_accounts`

External participant management.

**Key Fields:**

* `id` (uuid, PK)
* `email` (text)
* `display_name` (text)
* `ws_id` (text, FK → workspaces)

#### `meeting_recordings`

Meeting transcription and recording storage.

**Key Fields:**

* `id` (uuid, PK)
* `meeting_id` (uuid, FK → meeting\_plans)
* `transcription` (text)
* `summary` (text) - AI-generated
* `recording_url` (text)

### Nova Platform (Prompt Engineering)

#### `nova_problems`

Prompt engineering challenge problems.

**Key Fields:**

* `id` (uuid, PK)
* `title` (text)
* `description` (text)
* `difficulty` (text) - easy, medium, hard
* `created_by` (uuid, FK → workspace\_users)

#### `nova_challenges`

Specific challenge instances.

**Key Fields:**

* `id` (uuid, PK)
* `problem_id` (uuid, FK → nova\_problems)
* `title` (text)
* `start_time` (timestamptz)
* `end_time` (timestamptz)

#### `nova_test_cases`

Test cases for validating prompt submissions.

**Key Fields:**

* `id` (uuid, PK)
* `problem_id` (uuid, FK → nova\_problems)
* `input` (jsonb)
* `expected_output` (jsonb)
* `is_hidden` (boolean) - public vs private tests

#### `nova_submissions`

User prompt submissions.

**Key Fields:**

* `id` (uuid, PK)
* `challenge_id` (uuid, FK → nova\_challenges)
* `user_id` (uuid, FK → workspace\_users)
* `prompt` (text)
* `score` (numeric)
* `submitted_at` (timestamptz)

#### `nova_sessions`

Active problem-solving sessions.

**Key Fields:**

* `id` (uuid, PK)
* `user_id` (uuid, FK → workspace\_users)
* `problem_id` (uuid, FK → nova\_problems)
* `started_at` (timestamptz)
* `completed_at` (timestamptz)

### Education System

#### `courses`

Educational course catalog.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (text, FK → workspaces)
* `title` (text)
* `description` (text)
* `instructor_id` (uuid, FK → workspace\_users)

#### `course_modules`

Course content structure.

**Key Fields:**

* `id` (uuid, PK)
* `course_id` (uuid, FK → courses)
* `title` (text)
* `content` (text)
* `position` (integer)

#### `course_module_completion_status`

Student progress tracking.

**Key Fields:**

* `user_id` (uuid, FK → workspace\_users)
* `module_id` (uuid, FK → course\_modules)
* `completed_at` (timestamptz)

#### `course_certificates`

Achievement certificates.

**Key Fields:**

* `id` (uuid, PK)
* `user_id` (uuid, FK → workspace\_users)
* `course_id` (uuid, FK → courses)
* `template` (text) - elegant, modern, original
* `issued_at` (timestamptz)

#### `quiz_sets`

Quiz collections.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (text, FK → workspaces)
* `title` (text)
* `questions` (jsonb)

#### `quiz_attempts`

User quiz submissions.

**Key Fields:**

* `id` (uuid, PK)
* `quiz_id` (uuid, FK → quiz\_sets)
* `user_id` (uuid, FK → workspace\_users)
* `score` (numeric)
* `answers` (jsonb)
* `completed_at` (timestamptz)

#### `flashcard_sets`

Flashcard study materials.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (text, FK → workspaces)
* `title` (text)
* `cards` (jsonb) - array of `{front, back}`

### Time Tracking

#### `time_tracking_sessions`

Hierarchical time tracking with daily structure.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (text, FK → workspaces)
* `user_id` (uuid, FK → workspace\_users)
* `task_id` (text, FK → workspace\_tasks)
* `start_time` (timestamptz)
* `end_time` (timestamptz)
* `duration` (integer) - seconds
* `date` (date) - for daily hierarchy

**Related Tables:**

* `workspace_calendar_hour_settings` - categorizes hours (work, meeting, personal)

### URL Shortener

#### `shortened_links`

Short URL mappings.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (text, FK → workspaces)
* `short_code` (text, unique)
* `original_url` (text)
* `created_by` (uuid, FK → workspace\_users)
* `expires_at` (timestamptz)

#### `shortened_link_analytics`

Click tracking.

**Key Fields:**

* `id` (uuid, PK)
* `link_id` (uuid, FK → shortened\_links)
* `clicked_at` (timestamptz)
* `ip_address` (inet)
* `user_agent` (text)
* `referrer` (text)

### Subscriptions & Billing

#### `workspace_subscriptions`

Workspace subscription status.

**Key Fields:**

* `ws_id` (text, PK, FK → workspaces)
* `product_id` (text, FK → private.workspace\_subscription\_products)
* `status` (text) - active, canceled, expired
* `started_at` (timestamptz)
* `expires_at` (timestamptz)

#### `private.workspace_subscription_products`

Private subscription tiers managed through billing and Polar server helpers.

**Key Fields:**

* `id` (text, PK)
* `name` (text)
* `price` (numeric)
* `currency` (text)
* `features` (jsonb)

#### `private.workspace_subscription_errors`

Private subscription failure state used by billing overview RPCs and
service-role repair helpers.

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (uuid, FK → workspaces)
* `error_message` (text)
* `error_source` (text)
* `created_at` (timestamptz)
* `resolved_at` (timestamptz)

### Additional Features

#### `user_referrals`

Referral tracking system (added September 2025).

**Key Fields:**

* `id` (uuid, PK)
* `referrer_id` (uuid, FK → workspace\_users)
* `referred_id` (uuid, FK → workspace\_users)
* `created_at` (timestamptz)

#### `whiteboards`

Real-time collaborative whiteboard (added June 2025).

**Key Fields:**

* `id` (uuid, PK)
* `ws_id` (text, FK → workspaces)
* `title` (text)
* `content` (jsonb) - whiteboard state

#### `support_inquiries`

Support ticket system.

**Key Fields:**

* `id` (uuid, PK)
* `type` (text) - bug, feature-request, job-application, support
* `subject` (text)
* `description` (text)
* `status` (text) - open, in-progress, resolved
* `created_by` (uuid, FK → workspace\_users)

#### `discord_guild_integrations`

Discord server integration metadata.

**Key Fields:**

* `guild_id` (text, PK)
* `ws_id` (text, FK → workspaces)
* `enabled` (boolean)

## Database Functions

The schema includes several PostgreSQL functions for complex operations:

### `atomic_sync_token_operation`

Atomically updates calendar sync tokens to prevent race conditions.

**Usage:** Calendar synchronization coordination

### `get_wallet_viewing_window_days`

Converts viewing window literals to day counts for wallet access control.

**Signature:**

```sql theme={null}
public.get_wallet_viewing_window_days(
  p_viewing_window TEXT,
  p_custom_days INTEGER DEFAULT NULL
) RETURNS INTEGER
```

**Return Type:** INTEGER - number of days in the viewing window

**Semantics:**

* Maps viewing window literals (`1_day`, `3_days`, `7_days`, `2_weeks`, `1_month`, `1_quarter`, `1_year`) to day counts
* For `viewing_window = 'custom'`, returns `p_custom_days` value (defaults to 30 if invalid)
* Defaults to 30 days for unknown `viewing_window` values
* Function is `IMMUTABLE` - safe for indexing and optimization

**Example:**

```sql theme={null}
SELECT public.get_wallet_viewing_window_days('1_month', NULL); -- Returns 30
SELECT public.get_wallet_viewing_window_days('custom', 45);    -- Returns 45
SELECT public.get_wallet_viewing_window_days('1_year', NULL);  -- Returns 365
```

### `user_has_wallet_access_via_role`

Checks if a user has wallet access through role whitelisting and returns viewing window details.

**Signature:**

```sql theme={null}
public.user_has_wallet_access_via_role(
  p_user_id UUID,
  p_wallet_id UUID,
  p_ws_id UUID
) RETURNS TABLE (
  has_access BOOLEAN,
  viewing_window TEXT,
  custom_days INTEGER,
  window_start_date TIMESTAMPTZ
)
```

**Parameters:**

* `p_user_id` - the user to check (caller can only query their own ID unless they are a workspace admin)
* `p_wallet_id` - the wallet to check access for
* `p_ws_id` - the workspace context

**Return Columns:**

* `has_access` - `TRUE` if user has access via any role whitelist, `FALSE` otherwise
* `viewing_window` - the viewing window setting from the whitelist (e.g., `1_month`, `custom`)
* `custom_days` - the custom day count (NULL if not using `custom` window)
* `window_start_date` - calculated start of the viewing window (rolling from current timestamp)

**Security:**

* Function is `SECURITY DEFINER` - runs with elevated privileges
* **Authorization gate:** Callers can only query their own `user_id` OR must be a workspace admin (ADMIN/OWNER role)
* Raises exception `Permission denied` if caller attempts to query another user without admin privileges

**Access Logic:**

* When multiple roles grant access to the same wallet, selects the **widest access window** (most days)
* Tie-breaking: uses highest `custom_days` value, then `id` for deterministic ordering
* Calculates rolling window start date by subtracting window days from current timestamp

**Example Usage:**

```sql theme={null}
-- Check if current user has access to a specific wallet
SELECT * FROM public.user_has_wallet_access_via_role(
  auth.uid(),
  '550e8400-e29b-41d4-a716-446655440000'::uuid,
  'workspace-123'::text
);

-- Admin checking access for another user
SELECT * FROM public.user_has_wallet_access_via_role(
  '123e4567-e89b-12d3-a456-426614174000'::uuid,  -- another user
  '550e8400-e29b-41d4-a716-446655440000'::uuid,  -- wallet
  'workspace-123'::text
);

-- Filter transactions by viewing window
WITH access AS (
  SELECT * FROM public.user_has_wallet_access_via_role(
    auth.uid(),
    '550e8400-e29b-41d4-a716-446655440000'::uuid,
    'workspace-123'::text
  )
)
SELECT t.*
FROM wallet_transactions t
CROSS JOIN access a
WHERE t.wallet_id = '550e8400-e29b-41d4-a716-446655440000'::uuid
  AND a.has_access = TRUE
  AND t.created_at >= a.window_start_date;
```

### User Creation Triggers

Automatically create related records when new users are added.

### Task Board Member Management

Helper functions for managing board access permissions.

### AI Pricing Helpers

Calculate AI model costs based on token usage.

## Migration Management

Migrations are stored in `/apps/database/supabase/migrations/` with timestamp prefixes:

```
20250929042000_add_notes.sql
20250929060000_add_task_cycles.sql
20250911083732_add_task_labels_and_estimates.sql
...
```

See [Migration Guide](/reference/database/migrations-guide) for workflow details.

## Related Documentation

* [RLS Policies](/reference/database/rls-policies) - Security model and policy patterns
* [Migration Guide](/reference/database/migrations-guide) - Migration workflow

## Type Generation

After schema changes, regenerate TypeScript types:

```bash theme={null}
bun sb:typegen
```

Generated types are exported from `@tuturuuu/types`:

```typescript theme={null}
import type { Database } from '@tuturuuu/types';

type Task = Database['public']['Tables']['workspace_tasks']['Row'];
type PrivateConfig = Database['private']['Tables']['notification_email_config']['Row'];
type StorageObject = Database['storage']['Tables']['objects']['Row'];
```

# Reference
Source: https://docs.tuturuuu.com/reference/overview

Authoritative references for APIs and contracts.

# Reference

This section collects stable contracts—APIs, schemas, database internals, and package integration guides.

## Database

* **[Schema Overview](/reference/database/schema-overview)** – Core tables, relationships, and conventions across the Tuturuuu platform database.
* **[Row-Level Security Policies](/reference/database/rls-policies)** – The security model and RLS patterns that gate workspace data access.
* **[Migrations Guide](/reference/database/migrations-guide)** – Creating, testing, and deploying Supabase migrations safely.

## Packages

* **[`tuturuuu` SDK](/reference/packages/sdk)** – Official TypeScript/JavaScript SDK for the platform.
* **[`@tuturuuu/masonry`](/reference/packages/masonry)** – High-performance, responsive masonry grid component for React.
* **[`@tuturuuu/utils/effect`](/reference/packages/utils-effect)** – Curated Effect entrypoint and Tuturuuu error helpers for typed server orchestration.
* **[`@tuturuuu/supabase`](/reference/packages/supabase)** – Supabase client creation patterns and utilities.
* **[`@tuturuuu/trigger`](/reference/packages/trigger)** – Calendar provider-sync and scheduling helpers used by Vercel Cron routes.

## API Reference

* **[Generate API](/reference/api-reference/endpoint/generate)** – Request and response schemas for the AI generate endpoint.

If you need implementation guides, jump to [Build](/build/overview); for product tours, explore [Platform](/platform/overview).

# Local operational state
Source: https://docs.tuturuuu.com/reference/packages/cli-operational-state

Offline backlog and operational notes with retained legacy history and explicit conflicts

## Scope and defaults

`ttr backlog` manages local program requests. `ttr operational-memory` stores
explicit operational lessons in a separate SQLite database. Both groups run before
CLI authentication, platform clients and update checks. They require no login or
network access. They never import personal conversation archives, product/customer
memory or CLI credentials. Nothing in a record authorizes a tool action.

Backlog defaults to
`~/.local/share/tuturuuu/orchestration/programs/platform/backlog.sqlite`.
Operational memory defaults to `operational-memory.sqlite` in that directory.
Reads fail when the store is missing. Initialization requires an explicit `--db`
and refuses existing destinations. Use canonical paths without symlinks, including
parent directories. On macOS, use `/private/tmp` rather than `/tmp` for fixtures.
Writable stores require a private parent directory and file permissions of 0700
and 0600. Commands never change existing permissions automatically.

`--json` emits one JSON object, including failures. Validation, conflicts and store
errors exit with code 2. A valid but incomplete evidence board exits with code 1,
matching the Python checker. Help supports `--lang en|vi`. Human command results also
use JSON so recorded output has one stable representation.

Tiếng Việt: Hai nhóm lệnh quản lý dữ liệu vận hành ngoại tuyến, không yêu cầu đăng
nhập hoặc kết nối mạng. Lệnh đọc không tự tạo kho. Lệnh ghi yêu cầu phiên bản dự
kiến và mã thao tác duy nhất. Nhập dữ liệu mặc định chỉ kiểm tra, không ghi đè
lịch sử hoặc tự xác nhận triển khai.

## Explicit initialization and legacy adoption

Use a disposable store while evaluating these commands:

```sh theme={null}
mkdir -m 700 /private/tmp/my-operational-fixture
ttr backlog init --db /private/tmp/my-operational-fixture/backlog.sqlite --json
ttr backlog snapshot --db /private/tmp/my-operational-fixture/backlog.sqlite --json
ttr backlog help --lang vi --json
```

The existing Python ledger remains authoritative. Native reads support its exact
`items` and `events` tables, stable IDs and complete original event payloads. Native
writes require an explicit additive migration, not a migration during a read.
Migration locks the writer transaction, checks the current event revision,
validates a complete beforeimage and creates an exclusive private backup before
adding metadata and native operation receipts. Existing event rows are untouched.

```sh theme={null}
ttr backlog migrate --db /private/path/backlog.sqlite \
  --file /private/path/legacy-beforeimage.json \
  --expected-revision 862 --operation-id 00000000-0000-4000-8000-000000000001 --json
```

Replace the example revision and UUID with the inspected revision and a new
operation ID. Do not migrate a live program ledger as an implementation test.
The Python tool can continue reading and writing migrated stores. Its writes
advance `MAX(events.seq)`, so they invalidate stale native expected revisions.
Migration failures retain any created beforeimage; they do not promise backup
cleanup or automatic recovery of a failed explicit initialization.

## Intake, progress and evidence

Intake is a nonempty JSON array. Each item has a stable lowercase slug `id`,
`title`, `kind`, `source`, `acceptance` and unique nonempty `requiredEvidence`.
Kinds are `bug`, `feature`, `improvement`, `idea` and `delivery`. Optional
`priority` is an integer from 0 through 3, default 2. Optional `dependencies`
contains unique existing or same-batch IDs and must remain acyclic. Unknown fields
are rejected. New intake starts `captured`, with empty owner, note and links.
Identical repeated intake retains progressed state; conflicting intake rejects
the entire batch. Amend priority through an audited update.

```sh theme={null}
ttr backlog intake --db /private/path/backlog.sqlite --file /private/path/intake.json \
  --expected-revision 0 --operation-id 00000000-0000-4000-8000-000000000002 --json
ttr backlog update request-id --db /private/path/backlog.sqlite --status active \
  --owner local-worker --expected-revision 1 \
  --operation-id 00000000-0000-4000-8000-000000000003 --json
ttr backlog history request-id --db /private/path/backlog.sqlite --json
ttr backlog evidence-check --file /private/path/evidence.json --json
```

Updates accept `--status`, `--owner`, `--note`, `--link`, `--priority` and
`--evidence`. States are `captured`, `ready`, `active`, `blocked`, `implemented`,
`verified` and `deferred`. Ready, active and verified transitions require verified
prerequisites. Active needs a nonempty owner. Verification requires exactly one
matching unit in a version 1 program board, matching required gates and a current
full lowercase commit SHA. Every gate must have one current-head `pass` receipt
and a locator. Only `merged` or `delivered` units qualify. Stale receipts,
`pending`, `fail` and `skipped` never qualify. A delivered claim with missing PASS
fails validation. Reopening a verified prerequisite recursively returns verified
dependents to `implemented`; all old receipts remain in history. Re-verifying the
parent does not re-verify its dependents. Existing ready/active dependents retain
the legacy reopening behavior.

Every mutation requires `--expected-revision N` and `--operation-id UUID`.
Revision is the maximum event sequence read after `BEGIN IMMEDIATE`. Native operations
also capture their operation ID, validated request and exact original event interval
in the additive `operational_operation_proofs` table. Proof rows and response
receipts commit in the same writer transaction. Legacy item/event columns and
payloads remain unchanged. Replay validates the original interval, not the latest
projection, so later legitimate edits do not invalidate an earlier receipt.
The same
operation ID with identical input returns its original receipt, even after later
writes. Reusing it with different input fails. A stale revision fails without
writing. Inspect the new snapshot and reconcile deliberately; do not retry blindly
with a new revision. SQLite contention waits at most one second per lock attempt.

## Operational notes and deletion fences

```sh theme={null}
ttr operational-memory init --db /private/path/notes.sqlite --json
ttr operational-memory put --db /private/path/notes.sqlite --file /private/path/note.json \
  --expected-revision 0 --operation-id 00000000-0000-4000-8000-000000000004 --json
ttr operational-memory list --db /private/path/notes.sqlite --json
ttr operational-memory get lesson-id --db /private/path/notes.sqlite --json
ttr operational-memory history lesson-id --db /private/path/notes.sqlite --json
```

A note explicitly declares `id`, `scope`, `project`, `source`, `summary`, `evidence`
and `status`. Its status is `active`, `superseded` or `tombstone`. Scope and project
are immutable for an ID. Put a tombstone to revoke a note without removing its
history. Later writes cannot resurrect it. Notes have independent event revisions
and never appear in backlog exports. Conflicts leave the proposed input file and
existing store intact; no last-writer-wins or inferred consent is implemented.

## Immutable export and explicit import

```sh theme={null}
ttr backlog export --db /private/path/backlog.sqlite --file /private/path/snapshot.json --json
ttr backlog import --db /private/path/new-store.sqlite --file /private/path/snapshot.json --dry-run --json
ttr backlog import --db /private/path/new-store.sqlite --file /private/path/snapshot.json --apply \
  --expected-revision 0 --operation-id 00000000-0000-4000-8000-000000000005 --json
```

The same export/import commands exist under `operational-memory`. Exports refuse
existing files and symlink paths. Version 1 bundles retain source database identity,
complete original event history, projections and native dedupe receipts with
captured request/event proofs. Imported responses must agree with their recorded
operation IDs, request hashes, event payloads and revision intervals. Rehashing an
envelope does not make a forged receipt valid. SHA-256
covers canonical JSON. Hashes establish integrity, not authentication. Input is
bounded to 32 MiB, 10,000 records and 100,000 events/receipts; oversized exports
fail rather than truncate history. Unknown fields, missing sequences, divergent
projections, scope changes and tombstone resurrection fail validation.

Import defaults to dry-run and requires an explicit `--db`. A new restore retains
the bundle identity. Existing stores must have the same identity and an exact
history prefix; divergence is an explicit conflict. Original sequences and payload
strings are never renumbered or rewritten. Legacy beforeimages have no native
identity and must be restored with legacy tooling before explicit adoption.
Never silently merge unrelated ledgers. Old native receipts without original
request/event proofs cannot be replayed or imported/exported as qualified receipts.
Their stores remain readable through snapshot/history. Retain the original SQLite
store and receipts; do not invent a backfill, reset the ledger or discard its
operation log to make a write succeed. Adoption requires a separately reviewed
recovery procedure when the original request evidence is unavailable. Review the selected operational content
before transferring a bundle. No arbitrary referenced file bodies are included.

## Read-only outcome projection

The SDK source adapter in `operational-graph/reader.ts` reads an existing backlog
through `readOutcomeProjectionPageFromPath({ path, limit, cursor })`. It does not
initialize, migrate or export the store. The injected
`buildOutcomeProjectionPage({ snapshot, limit, cursor })` accepts validated
existing records and their complete event history for isolated fixtures.

Projection version 1 returns each canonical root's existing stable ID and all
contributing IDs, with members containing the complete original item and
event provenance. Acceptance, notes, links, dependencies, required evidence and
recorded verification remain separate member fields. Records without duplicate
relationships remain self-canonical. This reader does not perform graph mutations
or semantic search.

Identity, revision, items and events come from one SQLite read transaction.
Continuation cursors bind the projection version, source database UUID, event
revision and snapshot hash. A changed snapshot raises a conflict; consumers must
restart their read. Any identity, revision or projection-version change requires
derived-cache invalidation. Legacy stores retain a null identity and explicitly
deny semantic caching until separately authorized adoption. Reads never adopt a
legacy store. The reader bounds input to 10,000 items, 100,000 events and 32 MiB,
with pages of at most 500 records.

Bun 1.4.1 cannot open a read-only WAL database immediately after its journal mode
changes while its WAL sidecars are absent. A populated WAL fixture works. The
reader fails rather than creating sidecars or making a write to repair that
runtime limitation; use an already compatible runtime or store state.

Regression coverage is in `operational-graph/projection.test.ts` and
`operational-graph/reader.test.ts`, using synthetic records and real disposable
SQLite stores, including a concurrent writer during a consistent read.

## Native outcome relationships

`ttr backlog graph` adds explicit parent, dependency, related and duplicate
relationships to existing offline records. It keeps their original IDs, acceptance,
evidence requirements, notes, links, dependencies and full event history. Reads
never adopt a legacy ledger. Writes use the same native revision CAS and original
request/event receipt proofs as `backlog update`.

```sh theme={null}
ttr backlog graph help --lang en --json
ttr backlog graph show outcome-id --db /private/path/backlog.sqlite --json
ttr backlog graph readiness outcome-id --db /private/path/backlog.sqlite --json
ttr backlog graph merge --db /private/path/backlog.sqlite --file /private/path/merge.json \
  --expected-revision 12 --operation-id 00000000-0000-4000-8000-000000000012 --json
```

A merge command file contains `kind: "merge"`, `canonicalId`, nonempty unique
`memberIds`, a reason and `confirmation: "equivalent"`. Explicit equivalence is
required; similarity and related links never authorize closure. Every contributing
member remains individually available through canonical navigation and in the
lossless projection. Recanonicalizing a group requires selecting its complete
membership. Dependency collapse into a self dependency, hierarchy cycles and
canonical chains are conflicts, never silently removed obligations.

Parent organization does not create a blocking dependency. Dependency commands
use `kind: "dependency"`, `id`, `dependencyId` and `action: "add" | "remove"`.
Parent commands use `kind: "parent"`, `id` and a nullable `parentId`; related
commands use `kind: "related"`, `id`, `relatedId` and the same add/remove action.
Related links are symmetric and do not grant readiness or equivalence.

Duplicate closure is separate from verified delivery. Canonical readiness includes
all members' unmet prerequisites; a dependency on any alias resolves to the
complete group. Each member retains its own acceptance and evidence gates. An
explicit `close` requires `confirmation: "user-confirmed"`, a reason and current
verification for every unique member obligation. Reopen clears affected current
verdicts, including verified dependents, while retaining old receipts in history.
Re-verification never happens automatically.

`unmerge` requires the member ID, its current `mergeOperationId` and a reason.
It reopens that member without restoring a stale beforeimage or replacing later
notes, links or evidence history. Reopening a duplicate uses this explicit unmerge
path. Ordinary reopen uses `kind: "reopen"`, `id` and a reason. All mutation files
must match the selected CLI action and require the native write flags.

Regression coverage is in `operational-graph/store.test.ts` and
`cli/operational-graph.test.ts`, alongside the retained receipt/projection suites.
The source-only peer protocol remains separate; these local relationships do not
activate authentication, networking, leases or a server.

## Verification and delivery boundaries

All output records `liveVerificationPerformed: false`. Evidence checking validates
recorded consistency only; it does not query GitHub, a device, a provider or a
production service. Local offline commands do not implement authenticated
cross-machine synchronization, grants, leases or machine resource admission.
Those require a separate reviewed transport and runtime qualification.

Regression coverage lives in `packages/sdk/src/cli/operational-state.test.ts` and
exercises real isolated SQLite stores and unchanged Python reads/writes. Run the
focused suite through the canonical resource queue. Release qualification requires
Node 24 and Bun 1.4.1 compatibility plus exact-commit CI test/type/lint/SDK build
gates. SDK publication, integration and production delivery are separate actions.

# @tuturuuu/masonry
Source: https://docs.tuturuuu.com/reference/packages/masonry

A high-performance, responsive masonry grid component for React applications

## Overview

The `@tuturuuu/masonry` package provides a Pinterest-style masonry grid component for React with modern ResizeObserver-based measurement. The current release (0.4.3) ships only CI/release-pipeline fixes on top of 0.3.10 — the public component API is unchanged. Version 0.3.10 introduced ultra-aggressive optimization for near-perfect visual balance with 50 passes and 0.5%/5px tolerance. Version 0.3.2 brought rock-solid stability with aggressive debouncing and auto-stop mechanisms. Version 0.3.0 brought major performance improvements (50-70% CPU reduction), fixed the columns prop bug, and added advanced configuration options. It offers two distribution strategies: a fast count-based approach for uniform content, and an intelligent height-based balancing algorithm with event-driven measurement, ultra-aggressive exhaustive optimization, and memoized calculations.

## Installation

```bash npm theme={null}
npm install @tuturuuu/masonry
```

```bash yarn theme={null}
yarn add @tuturuuu/masonry
```

```bash pnpm theme={null}
pnpm add @tuturuuu/masonry
```

```bash bun theme={null}
bun add @tuturuuu/masonry
```

## Features

* 🎨 **Pinterest-style Layout**: Creates beautiful masonry grids with balanced columns
* 📱 **Responsive Design**: Optional responsive behavior with customizable breakpoints
* ⚖️ **Smart Distribution**: Two strategies - fast count-based or height-balanced
* 🖼️ **Modern Measurement**: ResizeObserver-based event-driven updates (50-70% faster)
* 💾 **Memoized Calculations**: Optimized performance with React memoization
* 🛡️ **Robust Validation**: Validates measurements with intelligent fallbacks
* 🎯 **TypeScript Support**: Fully typed with TypeScript
* ⚡ **Lightweight**: Zero external dependencies besides React
* 🔧 **Highly Customizable**: Flexible column, gap, breakpoint, and balance threshold configuration
* ✨ **Smooth Transitions**: Optional CSS transitions during redistribution
* 🐛 **Fixed Columns Prop**: Works correctly without requiring breakpoints (v0.3.0)
* 🔄 **Auto-cleanup**: Proper ResizeObserver disconnection on unmount

## Basic Usage

```tsx theme={null}
import { Masonry } from '@tuturuuu/masonry';

export function Gallery() {
  return (
    <Masonry columns={3} gap={16}>
      <div>Item 1</div>
      <div>Item 2</div>
      <div>Item 3</div>
      <div>Item 4</div>
    </Masonry>
  );
}
```

> [!NOTE]
>
> **v0.3.0+ Change**: The `columns` prop now works as expected without requiring breakpoints. Previously, default breakpoints would override the columns setting based on screen width.
>
> **v0.3.10 Improvement**: Ultra-aggressive optimization - 50 passes (vs 20) with ultra-tight 0.5%/5px tolerance (vs 1%/10px) ensures near-perfect balance. Column heights differ by ≤5px for professional appearance.
>
> **v0.3.2 Improvement**: Aggressive stability controls (500ms debounce, 10px threshold, max 10 redistributions, auto-stop after images load) ensure rock-solid layouts that settle and stay settled.

## API Reference

### Props

**children** `ReactNode[]` *required*

Array of React elements to display in the masonry grid. Each child will be distributed across columns using the shortest-column algorithm.

**columns** `number` (default: 3)

Number of columns to display. In v0.3.0+, this works as expected without requiring breakpoints configuration. Will be overridden by breakpoint configurations only if the `breakpoints` prop is explicitly provided.

**gap** `number` (default: 16)

Gap between items in pixels. This applies both horizontally (between columns) and vertically (between items within a column).

**breakpoints** `object` (default: undefined)

**Optional** responsive breakpoint configuration. Keys are viewport widths in pixels, values are the number of columns to display at or above that width.

**v0.3.0 Breaking Change**: Now optional (default: `undefined`). When not provided, uses fixed `columns` value.

Example configuration:

* `640px`: 1 column (mobile)
* `768px`: 2 columns (tablet)
* `1024px`: 3 columns (desktop)
* `1280px`: 4 columns (large desktop)

**className** `string`

Additional CSS classes to apply to the masonry container element.

**strategy** `'balanced' | 'count'` (default: count)

Strategy for distributing items across columns:

* `'count'` (default): Distributes items based on item count. Fastest with no measurement overhead and no layout shift.
* `'balanced'`: Distributes items based on actual measured heights using modern ResizeObserver API. Provides better visual balance with event-driven updates.

Use `'balanced'` when visual balance is critical (e.g., image galleries with varying aspect ratios). Use `'count'` for best performance.

**balanceThreshold** `number` (default: 0.05)

**New in v0.3.0**: Variance threshold (0-1) for redistribution in balanced mode. Only redistributes when column height variance exceeds this threshold.

* Lower values (e.g., `0.01`): Stricter balance, more redistributions
* Higher values (e.g., `0.1`): More lenient, fewer redistributions
* Default: `0.05` (5% variance tolerance)

**smoothTransitions** `boolean` (default: false)

**New in v0.3.0**: Enable smooth CSS transitions during redistribution. Adds \~300ms animation duration for visual smoothness. Disable for instant updates.

## Examples

### Image Gallery

```tsx theme={null}
import { Masonry } from '@tuturuuu/masonry';

interface Image {
  id: number;
  url: string;
  title: string;
}

export function ImageGallery({ images }: { images: Image[] }) {
  return (
    <Masonry
      columns={4}
      gap={12}
      breakpoints={{
        640: 1,
        768: 2,
        1024: 3,
        1280: 4,
      }}
    >
      {images.map((image) => (
        <div key={image.id} className="overflow-hidden rounded-lg">
          <img
            src={image.url}
            alt={image.title}
            className="h-auto w-full"
          />
        </div>
      ))}
    </Masonry>
  );
}
```

### Card Grid

```tsx theme={null}
import { Masonry } from '@tuturuuu/masonry';

interface CardProps {
  title: string;
  description: string;
  image?: string;
}

export function CardGrid({ cards }: { cards: CardProps[] }) {
  return (
    <Masonry columns={3} gap={20} className="my-8">
      {cards.map((card, index) => (
        <div
          key={index}
          className="rounded-lg bg-white p-6 shadow-lg dark:bg-gray-800"
        >
          {card.image && (
            <img
              src={card.image}
              alt={card.title}
              className="mb-4 h-auto w-full rounded"
            />
          )}
          <h3 className="mb-2 text-xl font-bold">{card.title}</h3>
          <p className="text-gray-600 dark:text-gray-300">
            {card.description}
          </p>
        </div>
      ))}
    </Masonry>
  );
}
```

### Custom Breakpoints

```tsx theme={null}
import { Masonry } from '@tuturuuu/masonry';

export function CustomBreakpointGallery() {
  return (
    <Masonry
      columns={5}
      gap={24}
      breakpoints={{
        480: 1,    // Extra small screens
        768: 2,    // Small screens
        1024: 3,   // Medium screens
        1440: 4,   // Large screens
        1920: 5,   // Extra large screens
      }}
    >
      {items.map((item) => (
        <div key={item.id}>{item.content}</div>
      ))}
    </Masonry>
  );
}
```

### Fixed Columns (v0.3.0+)

In v0.3.0+, the `columns` prop works without requiring breakpoints:

```tsx theme={null}
import { Masonry } from '@tuturuuu/masonry';

// This now works correctly - always shows 4 columns
export function FixedColumnGrid() {
  return (
    <Masonry columns={4} gap={16}>
      {items.map((item) => (
        <div key={item.id}>{item.content}</div>
      ))}
    </Masonry>
  );
}

// You can also explicitly pass empty breakpoints (same result)
export function AlternativeFixedGrid() {
  return (
    <Masonry columns={4} gap={16} breakpoints={{}}>
      {items.map((item) => (
        <div key={item.id}>{item.content}</div>
      ))}
    </Masonry>
  );
}
```

### Balanced vs Count Strategy

Choose between fast count-based distribution or height-based balancing:

```tsx theme={null}
import { Masonry } from '@tuturuuu/masonry';

// Count-based (default) - Fast, no layout shift
export function CountBasedGallery() {
  return (
    <Masonry columns={3} gap={16} strategy="count">
      {items.map((item) => (
        <div key={item.id} style={{ height: item.height }}>
          {item.content}
        </div>
      ))}
    </Masonry>
  );
}

// Height-based - Better visual balance for varying heights
export function BalancedGallery() {
  return (
    <Masonry columns={3} gap={16} strategy="balanced">
      {items.map((item) => (
        <div key={item.id} style={{ height: item.height }}>
          {item.content}
        </div>
      ))}
    </Masonry>
  );
}
```

The `balanced` strategy is particularly useful for image galleries where images have varying aspect ratios, while `count` works well for uniform content like cards or tiles.

### With Smooth Transitions (v0.3.0+)

Enable smooth CSS transitions for visual refinement during redistribution:

```tsx theme={null}
import { Masonry } from '@tuturuuu/masonry';

export function SmoothTransitionsExample() {
  const items = Array.from({ length: 16 }, (_, i) => ({
    id: i,
    height: [120, 180, 150, 200][i % 4],
  }));

return (
    <Masonry
      columns={4}
      gap={16}
      strategy="balanced"
      smoothTransitions={true}
      balanceThreshold={0.05}
    >
      {items.map((item) => (
        <div
          key={item.id}
          style={{ height: `${item.height}px` }}
          className="flex items-center justify-center rounded-lg bg-blue-500 text-white"
        >
          Item {item.id + 1}
        </div>
      ))}
    </Masonry>
  );
}
```

### Custom Balance Threshold (v0.3.0+)

Fine-tune distribution sensitivity:

```tsx theme={null}
import { Masonry } from '@tuturuuu/masonry';

export function CustomThresholdExample() {
  return (
    <Masonry
      columns={3}
      gap={20}
      strategy="balanced"
      balanceThreshold={0.1} // Higher = more tolerance for imbalance
    >
      {items.map((item) => (
        <div key={item.id}>{item.content}</div>
      ))}
    </Masonry>
  );
}
```

## How It Works

The masonry component uses an **optimized shortest-column algorithm** to distribute items:

### Count Strategy Algorithm

1. Creates the specified number of columns
2. Iterates through all items
3. Places each item in the column with the fewest items
4. Uses strict comparison for deterministic distribution
5. **Memoized** - only recalculates when children or columns change

### Balanced Strategy Algorithm (v0.3.0+)

1. **Immediate Multi-Column Render**: Items appear instantly in their target columns
2. **ResizeObserver Setup**: Observes all masonry items for size changes
3. **Event-Driven Measurement**: Captures height changes as they happen (images loading, etc.)
4. **Intelligent Distribution**:
   * Calculates running average for unmeasured items
   * Uses threshold-based greedy algorithm
   * Considers balance threshold for tie-breaking
   * Tracks coefficient of variation for quality
5. **Ultra-Aggressive Optimization** (v0.3.10 enhanced):
   * Phase 1: Min-Max placement (evaluates all placements)
   * Phase 2: Exhaustive search (tries moving EVERY item to EVERY column)
   * Phase 3: Best-move selection (applies single best improvement)
   * Phase 4: Build layout from optimized assignments
   * Up to **50 passes** exploring all N×M possibilities (vs previous 20)
   * Stops only when columns within **0.5% or 5px** of each other (vs previous 1% or 10px)
   * Near-perfect balance with ≤5px difference between columns
6. **Smart Redistribution** (v0.3.2 enhanced):
   * Debounced 500ms after last change for maximum stability
   * Only triggers when heights change >10px (ignores all minor fluctuations)
   * Maximum 10 redistributions to prevent endless movement
   * Stops observing after all images load
   * Stops observing after 2 seconds of stability
   * Uses `requestAnimationFrame` for smooth visual updates
   * Memoized to prevent unnecessary calculations
7. **Automatic Cleanup**: Observer disconnects on unmount or strategy change

### Responsive Behavior

* **Without breakpoints**: Uses fixed `columns` value
* **With breakpoints**: Adjusts columns based on viewport width

The height-based strategy provides better visual balance for items with varying heights, while the count-based strategy is faster with zero measurement overhead.

## Performance Considerations

### v0.3.0 Performance Improvements

### Strategy Performance

* **Count Strategy (Default)**: Fastest option. No height measurements, no layout shift, zero overhead. Ideal for most use cases and 100+ items.
* **Balanced Strategy (v0.3.10)**: Modern ResizeObserver API with ultra-aggressive exhaustive optimization and rock-solid stability controls. Event-driven with exhaustive search (tries all item×column moves in up to 50 passes) for near-perfect visual balance, 500ms debounce, 10px threshold, max 10 redistributions, and auto-stop after images load. Professional layouts with column heights differing by ≤5px and ultra-tight 0.5% tolerance.

### Memoization Benefits

* **Distribution calculation**: Only runs when dependencies change
* **Average height calculation**: Cached between renders
* **Column wrappers**: Prevents unnecessary array allocations
* **Result**: Smooth 60fps even with 100+ items

### When to Use Each Strategy

For best performance with many items or frequent updates, use the default `strategy="count"`. Use `strategy="balanced"` when visual balance is more important, knowing that v0.3.0's ResizeObserver implementation is significantly more efficient than previous versions.

## Styling

The component uses inline styles for core layout functionality and accepts a `className` prop for custom styling:

```tsx theme={null}
<Masonry
  columns={3}
  gap={16}
  className="mx-auto max-w-7xl px-4"
>
  {items.map((item) => (
    <div
      key={item.id}
      className="rounded-lg bg-linear-to-br from-blue-500 to-purple-600 p-4"
    >
      {item.content}
    </div>
  ))}
</Masonry>
```

## Best Practices

> **Use consistent item widths**
>
> For best results, ensure all items have the same width. The masonry layout handles varying heights automatically, but varying widths can break the grid.

> **Set appropriate gap values**
>
> Choose gap values that match your design system. Common values are 8px, 12px, 16px, or 24px.

> **Configure breakpoints thoughtfully**
>
> Consider your content and screen sizes. More columns work well for small items (like thumbnails), while fewer columns suit larger content cards.

> **Use keys properly**
>
> Always provide unique `key` props to direct children of Masonry to ensure proper React reconciliation.

> **Choose the right distribution strategy**
>
> * Use `strategy="count"` (default) for best performance with uniform or near-uniform content. Zero layout shift, instant rendering.
> * Use `strategy="balanced"` for image galleries or content with varying heights. Renders immediately with count-based distribution, then progressively optimizes to height-balanced layout as images load. No hidden measurement phase - content is visible from first render.

> **Optimize images for progressive loading**
>
> When using `strategy="balanced"` with images:
>
> * Items render immediately using count-based distribution
> * As images load, the layout progressively rebalances every 100ms
> * Final balanced distribution achieved once all images complete loading
> * No flash or hidden content - smooth progressive enhancement

## How Balanced Strategy Works (v0.3.0+)

The `strategy="balanced"` mode uses modern ResizeObserver API for event-driven measurement:

1. **Immediate Multi-Column Render**: Items appear instantly in their target columns (no single-column phase)
2. **ResizeObserver Setup**: Creates observer to monitor all masonry items for size changes
3. **Event-Driven Measurement**: Captures height changes automatically when they occur (images loading, dynamic content)
4. **Accurate Measurement**: Uses `entry.contentRect.height` from ResizeObserver for precision
5. **Validation & Fallbacks**: Validates measurements; uses running average for missing/invalid values
6. **Smart Change Detection** (v0.3.2): Only redistributes when heights change by >10px (completely ignores minor fluctuations)
7. **Item Migration** (v0.3.8 new):
   * Phase 1: Min-Max placement minimizes height range
   * Phase 2: Up to 10 iterative balancing passes
   * Each pass moves best item from tallest to shortest column
   * Stops when range \< max(20px, 5% of shortest)
   * Direct migration achieves excellent column equality
8. **Aggressive Debouncing** (v0.3.2): 500ms debounce + `requestAnimationFrame` ensures maximum stability
9. **Redistribution Limits** (v0.3.2): Maximum 10 redistributions prevents endless movement
10. **Image Load Tracking** (v0.3.2): Automatically stops observing once all images finish loading
11. **Stability Detection** (v0.3.2): Stops observing after 2 seconds of no changes
12. **Memoized Calculations**: Distribution only recalculates when dependencies actually change
13. **Auto-Cleanup**: Observer automatically disconnects on unmount or strategy change

This v0.3.0+ approach provides:

* ✅ **50-70% faster** - event-driven vs polling (100ms intervals in v0.2.x)
* ✅ **Instant response** - no 100ms delay for updates
* ✅ **Better battery life** - no continuous polling
* ✅ **Minimal memory** - single observer instance vs growing listeners
* ✅ **Memoized calculations** - prevents unnecessary work
* ✅ **Smooth 60fps** - even with 100+ items
* ✅ **Robust validation** - handles edge cases gracefully
* ✅ **No layout shift** - multi-column from first render
* ✅ **Item Migration** (v0.3.8) - Direct balancing moves items from tall to short columns
* ✅ **Iterative optimization** (v0.3.8) - Up to 10 passes with smart stopping for excellent balance
* ✅ **Aggressive debouncing** (v0.3.2) - 500ms wait ensures rock-solid stability
* ✅ **High thresholds** (v0.3.2) - 10px minimum change completely ignores minor adjustments
* ✅ **Auto-stop** (v0.3.2) - Stops observing after images load or 2s of stability
* ✅ **Redistribution limit** (v0.3.2) - Maximum 10 redistributions prevents endless movement

### Browser Support for ResizeObserver

* **Supported**: All modern browsers (Chrome 64+, Firefox 69+, Safari 13.1+)
* **Fallback**: Logs warning and gracefully degrades to count strategy if unavailable

## Additional Performance Notes

* The component uses React state and effects efficiently
* Resize events are properly debounced through React's rendering cycle
* Count strategy: No DOM measurements, instant rendering, zero overhead
* Balanced strategy (v0.3.3):
  * Event-driven measurement (no polling)
  * Change detection (>10px) completely ignores minor fluctuations
  * 500ms debounce ensures maximum stability
  * Maximum 10 redistributions prevents endless movement
  * Auto-stops after all images load
  * Auto-stops after 2 seconds of stability
  * Memoized distribution prevents recalculation unless dependencies change
  * Proper ResizeObserver cleanup on unmount
* Minimal re-renders when breakpoints change

## TypeScript

The package is written in TypeScript and exports all necessary types:

```tsx theme={null}
import { Masonry } from '@tuturuuu/masonry';
import type { ReactNode } from 'react';

interface MasonryProps {
  children: ReactNode[];
  columns?: number;
  gap?: number;
  breakpoints?: {
    [key: number]: number;
  };
  className?: string;
  strategy?: 'balanced' | 'count';
  balanceThreshold?: number;  // v0.3.0+
  smoothTransitions?: boolean; // v0.3.0+
}
```

## Accessibility

The masonry component renders semantic HTML and preserves the DOM order of items. Screen readers will encounter items in the order they appear in the `children` array, not in their visual column order.

For improved accessibility:

* Ensure items have proper semantic markup
* Use ARIA labels where appropriate
* Maintain logical tab order in interactive elements

## Browser Support

The package supports all modern browsers that support:

* React 19+
* CSS Flexbox
* ES2015+ JavaScript features

## Troubleshooting

> **Columns are uneven in height**
>
> With the default `strategy="count"`, this is expected behavior. The algorithm balances by item count, not pixel height.
>
> For better visual balance with varying item heights, use `strategy="balanced"` which measures actual heights and distributes items to achieve equal column heights.

> **Breakpoints not working**
>
> Ensure you're passing an object with numeric keys. The component checks `window.innerWidth`, so it won't work in SSR without hydration.

> **Items not appearing**
>
> Make sure you're passing an array of valid React elements to the `children` prop. Check console for any React warnings.

> **Unexpected column count**
>
> **Fixed in v0.3.0**: The `columns` prop now works as expected without breakpoints.
>
> If you're seeing unexpected column counts:
>
> * **v0.3.0+**: `<Masonry columns={4} />` always shows 4 columns
> * **v0.2.x and earlier**: Default breakpoints would override the columns prop
> * **Migration**: If you relied on default responsive behavior, explicitly add `breakpoints` prop

> **Columns prop not working (v0.2.x and earlier)**
>
> This was fixed in v0.3.0. Upgrade to the latest version:
>
> ```bash theme={null}
> bun add @tuturuuu/masonry@latest
> ```
>
> In v0.3.0+, the `columns` prop works correctly without requiring breakpoints configuration.

> **Images taking time to balance**
>
> **v0.3.0 Improvement**: Much faster than previous versions!
>
> The component uses modern ResizeObserver API for instant response:
>
> * Items render immediately in multi-column layout
> * Redistributes automatically as images load (event-driven, no polling)
> * Instant updates (no 100ms delay like in v0.2.x)
> * Achieves optimal balance once all images complete
>
> If instant rendering is more important than perfect balance, use `strategy="count"` (default).

> **Component stuck in single column with balanced strategy**
>
> This was fixed in v0.3.0. Items now render in multi-column layout immediately.
>
> If you're still experiencing this:
>
> * Update to the latest version (`bun add @tuturuuu/masonry@latest`)
> * Check that items have measurable height (not `display: none` or `height: 0`)
> * Ensure images have proper `src` attributes
> * Verify ResizeObserver is available in your browser (all modern browsers support it)

> **Performance concerns with balanced strategy**
>
> **v0.3.0 solved this!** Performance is dramatically improved:
>
> * **50-70% less CPU usage** compared to v0.2.x
> * Event-driven updates (no continuous polling)
> * Memoized calculations prevent unnecessary work
> * Smooth 60fps even with 100+ items
>
> If you're still experiencing performance issues:
>
> * Ensure you're on v0.3.0+ (`bun add @tuturuuu/masonry@latest`)
> * Check browser DevTools for ResizeObserver support
> * Consider using `strategy="count"` for 200+ items if balance isn't critical

## Source Code

The package is open source and available on GitHub:

* [View on GitHub](https://github.com/tutur3u/platform/tree/main/packages/masonry)
* [Report Issues](https://github.com/tutur3u/platform/issues)

## Migration Guide

### Migrating from v0.2.x to v0.3.0

**Breaking Change**: Breakpoints are now optional (default: `undefined` instead of default object).

```tsx theme={null}
// ❌ v0.2.x - Might show fewer columns than expected
<Masonry columns={4} />
// Default breakpoints override columns based on screen width

// ✅ v0.3.0 - Works as expected
<Masonry columns={4} />
// Always shows 4 columns

// If you want responsive behavior, explicitly provide breakpoints:
<Masonry 
  columns={4}
  breakpoints={{ 640: 1, 768: 2, 1024: 3, 1280: 4 }}
/>
```

**Migration Steps:**

1. **Test your layouts**: If you were relying on default breakpoints, explicitly add them
2. **Update imports**: No changes needed
3. **Check columns prop**: Should now work as expected without breakpoints
4. **Optional**: Consider using new `balanceThreshold` and `smoothTransitions` props

**No Action Needed If:**

* You were already passing explicit `breakpoints` prop
* You were passing empty breakpoints `breakpoints={{}}`
* Your layouts already work correctly

**New Features You Can Use:**

* `balanceThreshold` - Fine-tune distribution sensitivity
* `smoothTransitions` - Add CSS animations during redistribution
* Better performance with ResizeObserver (automatic)

## Changelog

For the canonical, machine-generated changelog see [`packages/masonry/CHANGELOG.md`](https://github.com/tutur3u/platform/blob/main/packages/masonry/CHANGELOG.md).

### 0.4.1 – 0.4.3 (Current - CI/Release Fixes)

These releases contain **no public API changes** — the `Masonry` component, props, and
distribution algorithms are identical to 0.3.10. They are release-pipeline and build
recovery fixes only:

* **0.4.3**: `fix(ci)` auto-recover package release dependencies
* **0.4.2**: `fix(ci)` recover releases and package `tsgo` builds
* **0.4.1**: Release-pipeline recovery (no source changes)

No migration or code changes are required when upgrading from 0.3.10 to 0.4.x.

### 0.3.10 (Near-Perfect Balance Release)

**Ultra-Aggressive Optimization:**

* 🎯 **50 optimization passes**: Thoroughly explores solution space (vs previous 20)
* 📊 **Very tight threshold**: Stops only when columns within **0.5% or 5px** (vs previous 1% or 10px)
* ⚖️ **Near-perfect balance**: Relentless optimization until near-identical column heights
* 🎨 **Professional appearance**: Column heights differ by ≤5px in most cases
* ⚡ **No compromise**: Ultra-tight tolerance for best visual quality

**Algorithm Details:**

* **Phase 1**: Min-Max greedy (initial placement)
* **Phase 2**: Ultra-aggressive optimization (up to 50 passes, 0.5% tolerance)
* **Phase 3**: Early stop when near-perfectly balanced (0.5% or 5px)
* **Phase 4**: Build final layout

**Why Ultra-Tight Tolerance Works:**

* 5px maximum difference ensures visually identical column heights
* 0.5% threshold prevents premature stopping on large layouts
* 50 passes ensure we find improvements even in edge cases
* No compromise on visual quality

**Results:**

* ✅ **Near-perfect balance**: Column heights differ by ≤5px in most cases
* ✅ **Thorough optimization**: 50 passes ensure no improvement missed
* ✅ **Professional appearance**: Visually indistinguishable column heights

### 0.3.9 (Optimal Balance Release)

**Global Optimization with Exhaustive Search:**

* 🎯 **Exhaustive search**: Tries moving EVERY item to EVERY column (not limited to tallest→shortest)
* 📊 **Best-move selection**: Always picks the single move that improves balance the most
* ⚖️ **Optimal balance**: Finds near-optimal distribution by exploring full solution space
* 🎨 **Tighter threshold**: Stops when columns within 1% or 10px (vs previous 5% or 20px)
* ⚡ **Guaranteed convergence**: Can't get stuck in local optima

**Algorithm Details:**

* **Phase 1**: Min-Max greedy (initial placement)
* **Phase 2**: Global optimization (try all possible moves, pick best)
* **Phase 3**: Early stop when perfectly balanced (1% or 10px)
* **Phase 4**: Build final layout

**Why Exhaustive Search Works Better:**

* Not limited to moves between tallest and shortest columns
* Considers the entire solution space at each step
* Finds truly optimal moves, not just locally good ones
* Can escape local optima that previous algorithms got stuck in

**Results:**

* ✅ **Near-optimal balance**: Explores all possibilities to find best distribution
* ✅ **No local optima**: Can always find improving move if one exists
* ✅ **Tighter tolerance**: Achieves balance within 1% or 10px

### 0.3.8 (Perfect Balance Release)

**Direct Balancing with Item Migration:**

* 🎯 **Item migration**: Moves items from tallest to shortest column (not just swapping)
* 📊 **Iterative optimization**: Up to 10 passes moving best item each time
* ⚖️ **Excellent balance**: Directly reduces height differences
* 🎨 **Smart stopping**: Stops when columns within 5% or 20px of each other
* ⚡ **More effective**: Migration is simpler and more direct than pair swaps

**Algorithm Details:**

* **Phase 1**: Min-Max greedy (initial placement)
* **Phase 2**: Iterative balancing (move items from tallest to shortest)
* **Phase 3**: Early stop when well-balanced
* **Phase 4**: Build final layout

**Why Migration Works Better:**

* Directly addresses the problem (move from tall to short)
* Doesn't require finding matching pairs to swap
* Can move any item that improves balance
* Converges faster to good solution

**Results:**

* ✅ **Better balance**: More direct approach reduces extremes
* ✅ **Simpler logic**: Migration is conceptually clearer than swapping
* ✅ **Faster convergence**: Gets to good solution in fewer iterations

### 0.3.7 (Perfect Balance Release)

**Best-First Optimization Enhancement:**

* 🎯 **Best-first search**: Each pass finds and applies the BEST swap, not just first improvement
* 📊 **Exhaustive optimization**: Up to 5 passes with thorough swap evaluation
* ⚖️ **Near-perfect equality**: Achieves virtually identical column heights
* 🎨 **Systematic refinement**: Guarantees finding local optimum through greedy best-first approach
* ⚡ **Smart threshold**: Accepts any improvement >0.5px for fine-grained optimization

**Algorithm Details:**

* Each optimization pass evaluates ALL possible swaps
* Picks and applies only the BEST swap per pass
* Continues for up to 5 passes or until no improvements >0.5px remain
* Lower threshold (0.5px vs 2px) catches more refinement opportunities

**Results:**

* ✅ **Excellent balance**: Systematically finds near-optimal distribution
* ✅ **Consistent quality**: Best-first guarantees good results
* ✅ **Handles edge cases**: 5 passes catch difficult distributions

### 0.3.6 (Perfect Balance Release)

**Hybrid Algorithm with Post-Optimization:**

* 🎯 **Two-phase approach**: Min-Max placement + swap-based refinement
* 📊 **Post-optimization**: Up to 2 passes swapping items to reduce variance further
* ⚖️ **Near-perfect equality**: Achieves virtually identical column heights
* 🎨 **Best of both worlds**: Global Min-Max + local swap optimization
* ⚡ **Still efficient**: Limited refinement passes maintain performance

**Algorithm Details:**

* **Phase 1**: Min-Max greedy (evaluates all placements, minimizes height range)
* **Phase 2**: Post-optimization (swaps items between columns if it improves balance ≥2px)
* **Phase 3**: Build final layout from optimized assignments

**Results:**

* ✅ **Virtually perfect balance**: Columns end at nearly identical heights
* ✅ **Hybrid superiority**: Outperforms pure Min-Max with refinement pass
* ✅ **Minimal overhead**: Only 2 optimization passes

### 0.3.5 (Perfect Balance Release)

**Major Algorithm Improvements:**

* 🎯 **Min-Max Balanced Greedy**: Advanced algorithm that minimizes height range across all columns
* 📊 **Look-ahead optimization**: Evaluates all possible placements before choosing
* ⚖️ **Superior balance**: Minimizes max column height difference, not just finds shortest column
* 🎨 **Visual perfection**: Columns end at nearly identical heights for professional galleries
* ⚡ **Smart & efficient**: O(n log n) sort + O(n·k²) placement with intelligent tie-breaking

**Algorithm Details:**

* **Phase 1**: Sort items by height in descending order (largest first)
* **Phase 2**: For each item, try placing in every column
* **Phase 3**: Calculate resulting height range (max - min) for each option
* **Phase 4**: Choose column that minimizes the range (most balanced result)
* **Phase 5**: Tie-breaker prefers shorter columns when ranges are equal

**Why Min-Max Works Better:**

* Considers the **global balance** of all columns, not just local shortest
* Actively minimizes the difference between tallest and shortest columns
* Produces significantly more even distributions than simple greedy
* Large items placed strategically to enable better balance
* Small items fill gaps optimally

**Results:**

* ✅ **Near-perfect balance**: Columns end at nearly identical heights
* ✅ **Superior to LFD**: Outperforms simple greedy by considering future balance
* ✅ **Handles any sizes**: Excellent for highly varied aspect ratios
* ✅ **Still fast**: Slightly more computation but dramatically better results

### 0.3.4 (Optimal Distribution Release)

### 0.3.3 (Multi-Pass Optimization - Superseded)

**Note**: This version implemented swap-based optimization which was replaced in v0.3.4 with the more effective Largest First Decreasing algorithm.

### 0.3.2 (Rock-Solid Stability Release)

**Critical UX Fixes:**

* 🎭 **Aggressive debouncing**: 500ms debounce ensures layout stability (up from 200ms in v0.3.1)
* 📏 **High threshold**: 10px change threshold completely ignores minor fluctuations (up from 3px in v0.3.1)
* 🛑 **Maximum redistributions**: Hard limit of 10 redistributions prevents endless movement
* 🖼️ **Image load tracking**: Automatically stops observing once all images finish loading
* ⏱️ **Stability detection**: Stops observing after 2 seconds of no changes
* ✨ **Rock-solid experience**: Layout settles quickly and stays settled permanently

**Bug Fixes:**

* ✅ **Non-stop repositioning**: Fixed items constantly moving around even after images loaded (critical UX issue)
* ✅ **Stable layout**: Layout now properly stabilizes and never changes again
* ✅ **Performance**: Stops wasting resources after layout is stable

### 0.3.1 (UX Polish Release)

**Initial UX Improvements:**

* 🎭 **Debounced updates**: 200ms debounce prevents jerky movement
* 📏 **Smart thresholds**: 3px change threshold ignores minor font rendering differences
* ✨ **Smoother experience**: Items settle into place smoothly

**Bug Fixes:**

* ✅ **Excessive redistributions**: Fixed items moving around too frequently
* ✅ **Stable layout**: Layout settles properly once images finish loading

### 0.3.0 (Major Performance & Bug Fix Release)

**Breaking Changes:**

* 🔧 **Breakpoints now optional**: Default changed from object to `undefined`. Columns prop now works without breakpoints!
* 🎯 **Migration needed**: If you relied on default responsive behavior, explicitly add breakpoints

**Major Improvements:**

* ⚡ **ResizeObserver API**: Replaced interval-based measurement with modern ResizeObserver (50-70% CPU reduction)
* 💾 **Memoization**: Distribution calculations now memoized for better performance
* 🎨 **Improved algorithm**: Better tie-breaking and variance tracking for more balanced columns
* 🚀 **No layout shift**: Items appear in target columns immediately (removed single-column initial render)
* ✨ **Smooth transitions**: New `smoothTransitions` prop for CSS-animated redistributions
* 🎯 **Balance threshold**: New `balanceThreshold` prop for fine-tuning distribution sensitivity

**Bug Fixes:**

* ✅ **Fixed columns prop**: `<Masonry columns={4} />` now correctly shows 4 columns (was showing 1-3 based on screen width)
* ✅ **Event-driven updates**: Instant response to size changes instead of 100ms polling
* ✅ **Better cleanup**: Proper ResizeObserver disconnection on unmount

**Performance:**

* 📊 50-70% reduction in CPU usage during measurement phase
* 🔋 Significantly better battery life (event-driven vs continuous polling)
* 💨 Instant update latency instead of 100ms intervals
* 🧠 Minimal memory footprint with single observer instance

### 0.2.1

Critical bug fix for initialization:

* **Fixed single column stuck issue**: Component now properly initializes multi-column layout
* **More lenient initialization**: Requires only 50% valid measurements instead of 100%
* **Faster initial render**: Switches to multi-column as soon as minimum threshold is met
* **Better edge case handling**: Won't get stuck if some items have zero height initially

### 0.2.0

Major improvements to measurement and distribution system:

* **Robust measurement validation**: Dual measurement approach with validation
* **Smart change detection**: Only updates when heights change by >1px
* **Intelligent fallbacks**: Uses average height for unmeasured items
* **Performance safety limits**: Maximum 50 measurement cycles (5 seconds)
* **Better image handling**: Proper event listeners with `naturalHeight` validation
* **Improved greedy algorithm**: Better column distribution
* **Immediate image updates**: Redistributes as each image loads

### 0.1.7

* **Fixed distribution algorithm**: Proper strict `<` comparison for better balance
* Prevents items from piling up in later columns

### 0.1.6

* **Fixed measurement tracking**: Added `data-item-index` for accurate height mapping
* Measurements now correctly correlate after redistribution

### 0.1.5

* **Fixed infinite rendering issue**: Proper cleanup of measurement intervals
* Removed problematic component remounting from key prop changes
* Improved lifecycle management with better effect dependencies
* Stable rendering once all images are loaded

### 0.1.4

* **Visible-first rendering**: Removed hidden measurement phase
* Items now appear immediately - no more delayed visibility
* Background measurement and progressive optimization
* Zero layout shift with count strategy, smooth progressive improvement with balanced

### 0.1.3

* **Optimized progressive loading**: Periodic redistribution every 100ms while images load
* Smooth, continuous layout improvements as images become available
* Final perfect distribution after all images are fully loaded
* Better visual experience with gradual optimization instead of sudden changes
* Eliminates janky single-redistribution in favor of smooth progressive refinement

### 0.1.2

* **Progressive image loading**: Distribution now recalculates as each image loads instead of waiting for all
* Smoother user experience with incremental layout improvements
* Better handling of mixed content (images and non-image items)
* Eliminates long wait times for image-heavy galleries

### 0.1.1

* **Fixed image support in balanced strategy**: Now waits for all images to load before measuring heights
* Handles both loaded and unloaded images gracefully
* Prevents measurement of images before they have dimensions
* Improved reliability for image galleries with `strategy="balanced"`

### 0.1.0

* **STABLE RELEASE**: Production-ready masonry grid component
* Fixed infinite rendering loop in balanced strategy
* Implemented proper two-phase measurement approach for balanced distribution
* Fixed column distribution to properly rotate through equal-height columns
* Improved visual balance with varying item heights (100+ items tested)
* Balanced strategy now uses hidden measurement phase for accurate height calculations
* Performance optimizations: measurement happens once, distribution is stable

### 0.0.4

* Added `strategy` prop with `'count'` and `'balanced'` modes
* `'balanced'` mode uses ResizeObserver to measure heights for better visual balance
* `'count'` mode (default) provides best performance with no layout shift

### 0.0.3

* Fixed unbalanced column distribution using shortest-column algorithm
* Improved visual balance across all column heights

### 0.0.2

* Added build configuration for proper module distribution
* Published compiled JavaScript and TypeScript declarations

### 0.0.1

* Initial release with basic masonry layout functionality

# tuturuuu
Source: https://docs.tuturuuu.com/reference/packages/sdk

Official TypeScript/JavaScript SDK for the Tuturuuu platform

# Tuturuuu SDK

Official TypeScript/JavaScript SDK for interacting with the Tuturuuu platform. Provides type-safe access to workspace storage, files, documents, and agent-friendly task workflows.

## Installation

```bash npm theme={null}
npm install tuturuuu
```

```bash yarn theme={null}
yarn add tuturuuu
```

```bash pnpm theme={null}
pnpm add tuturuuu
```

```bash bun theme={null}
bun add tuturuuu
```

## Quick Start

```typescript theme={null}
import { TuturuuuClient } from 'tuturuuu';

// Initialize the client with your API key
const client = new TuturuuuClient('ttr_your_api_key');

// List files in workspace
const files = await client.storage.list({
  path: 'documents',
  limit: 50
});

// Upload a file
const file = new File(['content'], 'example.txt');
const result = await client.storage.upload(file, {
  path: 'documents'
});

// Create a document
const doc = await client.documents.create({
  name: 'My Document',
  content: { text: 'Hello World' }
});
```

## Features

Source previews support native `ttr backlog search help --lang en|vi --json`
and `ttr backlog search model-status --json` before login. Lexical queries require
an explicit `--db`.
Model status without `--runtime-dir` loads or downloads no model. These source
commands do not establish published npm availability or model admission. See
[local operational state](/reference/packages/cli-operational-state).

Search indexing reads the full current projection and rebuilds every lexical
document with complete member content and provenance. Under the same source UUID,
projection version, and authenticated runtime fingerprint, it can reuse a vector
for an identical record ID and versioned full-record content hash. Canonical
membership, provenance, content, or runtime recipe changes invalidate affected
vectors. Deleted records are omitted. An absent or revoked runtime removes all
semantic vectors. An older content policy requires one rebuild.

Index output reports `strategy: snapshot-reconciled-vector-reuse-v1`,
`reuseEligible`, `reused`, `computed`, `removed`, and `invalidated`. `embedded`
counts committed vectors, with a maximum corpus of eight documents. `incremental`
means reuse eligibility. `projectionScan` and `lexicalRebuild` remain full-snapshot
operations; indexing does not consume an event delta feed. A newer cached revision
or equal-revision snapshot drift denies reuse.

`modelLoaded` reports a successful non-injected embedding return in this command.
A command that computes no new vectors authenticates the runtime without loading
the model. `embeddingAttemptsThisCommand` and
`successfulEmbeddingsThisCommand` also describe this command. A later
embedding failure can leave `modelLoaded: true` while the committed lexical
fallback has zero vectors. Partial semantic caches are never published.

Structural cache, projection, and source conflicts propagate as errors. Runtime
embedding failures and capacity failures use lexical fallback. Before publication,
the index rereads source UUID, revision, snapshot, version, and cache permission.
Queries require the current snapshot and exact document IDs and content keys.
An older content policy produces `stale-content-policy` and lexical fallback.
Similarity candidates remain uncertain and never authorize closure or merge.
Source tests and review qualify this reuse behavior separately from real engine
execution, installed CLI availability, and hosted SDK packaging.

SDK package qualification drains each owned process group after termination. On Darwin, a group containing only exiting or zombie members can briefly return `EPERM` to a signal-zero probe. The drain keeps polling within its existing 1500 ms budget and succeeds only after `ESRCH`; persistent permission errors remain `PROCESS_GROUP_UNDRAINED` with the last probe error as `cause`, while other probe errors are rethrown unchanged. The post-leader-close `SIGKILL` alone may continue to drain after `EPERM`; other termination failures remain errors. Regression coverage lives in `scripts/ci/sdk-package-process.test.js` and the unchanged real-descendant assertions in `qualify-sdk-package.test.js`. Apple’s [process-group implementation](https://github.com/apple-oss-distributions/xnu/blob/main/bsd/kern/kern_sig.c) filters zombies and can return `EPERM` when no eligible member remains.

> **Bun CLI**
>
> Use `ttr` for browser login, workspace discovery, and task workflows

> **Headless Login**
>
> Copy a short-lived CLI token from the browser when a local callback is not
> available

> **Storage Operations**
>
> Upload, download, list, and delete files and folders

> **Document Management**
>
> Create, read, update, and delete workspace documents

> **Signed URLs**
>
> Generate temporary shareable links for files

> **Image Resizing**
>
> Apply Supabase image transformations during share and download

> **Analytics**
>
> Track storage usage, file counts, and limits

## Type-check and declaration output

The SDK `type-check` command uses `tsconfig.typecheck.json`, which extends the
public build configuration to retain its source files and semantic checking options.
It disables emit, composite output and incremental state, so it owns no `dist`
files even when the CI task graph also schedules the SDK build. The portable
`build` remains responsible for JavaScript and public declarations; its configuration
remains separate from the no-emit check. `sdk-typecheck-boundary.test.ts` checks resolved compiler
coverage/options and exercises a disposable type error and successful check without
output files. Exact-head CI must verify both type-check and the real portable build.
This structural boundary does not identify the writer behind a historical
`ENOTEMPTY` failure.

Portable staging excludes test/spec/acceptance modules and the shared
`resources-test-fixtures.ts` helper. Test-only imports such as Vitest's fixture
hooks must not enter the public runtime closure. The actual-source control in
`packages/sdk/scripts/portable-build.test.cjs` verifies this before compilation.

## CLI

For offline request ledgers and separate operational notes, see
[Local operational state](/reference/packages/cli-operational-state). These groups
run before authentication and update checks and do not access platform data.

The SDK package includes a native Bun-powered CLI. `ttr` is the primary command,
and `tuturuuu` plus `tutur3u` are aliases for the same binary.

```bash theme={null}
ttr --help
ttr login
ttr upgrade
ttr --version
ttr whoami
ttr host current
ttr host use local --port 7803
ttr workspaces
ttr workspaces use
ttr boards
ttr boards use
ttr lists use
ttr tasks use
ttr tasks --board <board-id>
ttr tasks --compact
ttr tasks search "deadline review"
ttr tasks search "deadline review" --mode text
ttr tasks search "deadline review" --mode semantic
ttr tasks create "Add Tuturuuu CLI"
ttr tasks create --list <list-id> --name "Write release notes"
ttr tasks done <task-id>
ttr tasks close <task-id>
ttr tasks update <task-id> --json-payload '{"completed":true}'
ttr finance wallets
ttr finance wallets balance --all
ttr finance transactions --page-size 10
ttr finance transactions create --amount 150000 --wallet <wallet-id> --taken-at 2026-05-09
ttr finance transfers migrate --from-transaction <tx-id> --to-transaction <tx-id> --from-wallet <wallet-id> --to-wallet <wallet-id> --amount 150000 --taken-at 2026-05-09
ttr finance budgets status
ttr calendar events list --start 2026-06-11T00:00:00Z --end 2026-06-12T00:00:00Z
ttr calendar events create "Focus block" --start 2026-06-11T09:00:00+07:00 --duration-minutes 90
ttr calendar schedule preview --window-days 14 --timezone Asia/Ho_Chi_Minh
```

`ttr login` opens the browser and creates a Tuturuuu-managed CLI app-session
JWT pair through `apps/web`. The terminal and browser confirmation page show the
signed-in account email when the web session exposes it. The CLI stores that
session and selected workspace, board, list, task, label, and project in the OS
app config directory. `personal` is the default workspace after login and when
no workspace has been selected:

Use `ttr host use` to switch between Tuturuuu origins. `production` and `prod`
resolve to `https://tuturuuu.com`; `local` and `localhost` prefer safe local
environment URLs from `TUTURUUU_LOCAL_BASE_URL`, `PORTLESS_URL`, `WEB_APP_URL`,
`NEXT_PUBLIC_WEB_APP_URL`, or `NEXT_PUBLIC_APP_URL`, then fall back to
`https://tuturuuu.localhost`. Pass `--port <port>` for
`http://localhost:<port>`, or `--portless --port <port>` for
`https://tuturuuu.localhost:<port>`. Changing origins clears the saved session
and selected workspace context because both are origin-specific.

`ttr config set-base-url <url>` remains available for compatibility and uses the
same host normalization and context-clearing behavior. The CLI normalizes
`0.0.0.0` and unspecified IPv6 origins to `localhost` so the browser login flow
does not open a blocked address.

On Dockerized production deployments, the web auth start route also rewrites
wildcard bind origins such as `0.0.0.0:7803` to the forwarded public host or the
configured app URL (`WEB_APP_URL`, `NEXT_PUBLIC_WEB_APP_URL`,
`NEXT_PUBLIC_APP_URL`, `COOLIFY_URL`, or `COOLIFY_FQDN`) before sending users to
`/login`. If those environment values are unset and no public forwarded host is
available, `https://tuturuuu.com` is the default fallback.

* macOS: `~/Library/Application Support/Tuturuuu/config.json`
* Linux: `$XDG_CONFIG_HOME/tuturuuu/config.json` or `~/.config/tuturuuu/config.json`
* Windows: `%APPDATA%\Tuturuuu\config.json`

For headless agent environments, use copy-token mode:

```bash theme={null}
ttr login --copy
```

Open the printed URL in an authenticated browser, copy the returned CLI token,
and paste it into the terminal. Set `TUTURUUU_CONFIG` to use a custom config
file, or use `ttr host use <target>` to target a local, production, or explicit
URL origin.

The CLI checks the npm registry at most once per hour and writes a notice to
stderr when a newer `tuturuuu` version is available. JSON invocations suppress
this notice on both output streams while retaining the update check and cache.
This covers `--json` and explicit JSON format/output flags; non-JSON commands
retain the notice. The CLI entrypoint regression tests in
`packages/sdk/src/cli/update-entry.test.ts` cover JSON success, feedback JSON
errors, and non-JSON notices. Use `ttr upgrade` to run `bun i -g tuturuuu`. Use
`--no-update-check` on a single command, or set `TUTURUUU_DISABLE_UPDATE_CHECK=1`,
to disable the check.

CLI sessions are dedicated Tuturuuu gateway JWTs, separate from normal browser
and Supabase Auth sessions. The CLI stores a short-lived app-session access JWT
plus a longer-lived refresh JWT, refreshes shortly before access-token expiry,
updates the saved config with the rotated refresh token, and retries once after a
`401` response. Refresh JWTs only carry the CLI refresh scope, so they cannot be
used directly as API bearer tokens. If refresh fails because the user no longer
exists or the refresh JWT has expired, run `ttr login` again.

The SDK fetch wrapper must attach CLI bearer tokens, refresh sessions, and retry
`401` responses only for relative Tuturuuu API paths or absolute URLs whose
origin exactly matches the configured CLI base URL. Cross-origin absolute URLs
must be delegated without `Authorization` headers.

API routes used by `ttr` must accept the CLI app-session access JWT from the
`Authorization: Bearer ...` header. For `apps/web` routes, prefer
`withSessionAuth` with `targetApp: 'platform'` and
`requiredScope: 'cli:access'` when the route is CLI-only; shared user profile
routes can include the platform target alongside satellite app targets. Shared
API routes should verify the CLI app-session token before falling back to
Supabase session auth and then keep workspace membership checks explicit.
When a handler lives in `packages/apis` and is reused by multiple apps, keep
`@tuturuuu/auth` imports in the app-owned route wrapper and pass a
pre-authenticated context into the shared handler so package builds do not form
an auth/UI/API cycle.

SDK version and changelog PRs are generated by
`.github/workflows/release-please.yaml` from Conventional Commits on
`production`. Release Please tracks the SDK in `release-please-config.json` as
the `sdk` component, records the current version in
`.release-please-manifest.json`, and updates `packages/sdk/package.json` in the
combined monorepo release PR. SDK releases are then published automatically from
`.github/workflows/release-sdk-package.yaml` when that version bump lands on
`production` or when the release workflow itself changes. The same publish
workflow can be dispatched manually to catch up a version that already landed on
`production`. Manual dispatches from any other ref are rejected before
dependency installation, packaging, or npm trusted publishing can run. The
workflow runs the SDK tests, skips publication if the exact package version
already exists on npm, waits for publishable Tuturuuu workspace dependencies to
be visible on npm, prepares a tarball with `npm pack` outside the
trusted-publish job, and then publishes that tarball through
[npm trusted publishing](https://docs.npmjs.com/trusted-publishers). Only the
final `publish-npm` job requests `id-token: write`, so GitHub Actions mints the
short-lived OIDC token after dependency installation, package builds, and version
checks have already finished. That job downloads the prepared artifact, verifies
its package `name` and `version`, confirms the bundled `npm` CLI supports trusted
publishing, runs `npm publish ./<tarball> --ignore-scripts`, and polls `npm view`
until the exact SDK version is visible without using an `NPM_TOKEN`. npm treats
the downloaded artifact as a local file path. The job
targets the GitHub environment `sdk-release-production`; keep that environment
restricted to the `production` branch in repository settings, and keep the npm
trusted publisher bound to the same environment name so a branch-selected
workflow cannot mint a matching npm publish identity. Do not add `bun install`,
`npm install -g`, package builds, package lifecycle scripts, or repository
secrets to the SDK release workflow. Because the `tuturuuu` package is public
and `tutur3u/platform` is a public repository, npm also generates and attaches
build provenance attestations automatically. The package manifest inside the
tarball must keep repository metadata aligned with the provenance repository:
`repository.url` is `https://github.com/tutur3u/platform`, and
`repository.directory` points at the package directory.

`.github/workflows/sdk-version-bump.yaml` is retired and no longer generates
patch-version PRs. Do not restore checksum or package-only bump automation for
the SDK; release-please must remain the version/changelog source of truth.

The SDK imports `@tuturuuu/devbox`, `@tuturuuu/types`, and
`@tuturuuu/internal-api` through package exports that point at their git-ignored
`dist/` directories. The release workflow must build those workspace packages in
the non-OIDC build and prepare jobs before running SDK tests or creating the
`npm pack` tarball; otherwise a clean Actions checkout cannot resolve the SDK
imports. The workflow then runs
`node scripts/ci/prepare-npm-package-manifest.js packages/sdk` before
`npm pack` so the published manifest contains concrete npm versions instead of
local `workspace:` protocol ranges. Keep matching npm release workflows for the
SDK runtime workspace dependencies so consumers can install the published SDK.
When release-please bumps the SDK and one of those dependencies in the same
production push, the SDK workflow waits for the dependency versions before it
packs and publishes. If a dependency release workflow for the same SHA fails,
the SDK wait fails immediately instead of waiting for npm visibility until
timeout.

The matching npm-side trusted publisher must stay configured at
`https://www.npmjs.com/package/tuturuuu/access` with these exact values:

* **Provider**: GitHub Actions
* **Organization or user**: `tutur3u`
* **Repository**: `platform`
* **Workflow filename**: `release-sdk-package.yaml`
* **Environment name**: `sdk-release-production`

If the npm-side configuration drifts (for example after a repo rename, missing
first-publish setup, package access drift, or after moving the publish step into
another workflow file), `npm publish` can fail with `ENEEDAUTH`, `E404`, or
permission text. Update the npm package access or trusted publisher entry first;
do not paper over the failure by reintroducing a long-lived `NPM_TOKEN`. After
confirming a trusted-publisher release works end to end, the npm package
settings should keep `Require two-factor authentication and disallow tokens`
enabled so the package cannot be published with classic tokens.

### Dev channel and private previews

The stable channel remains Release Please plus the production release workflow.
The dev channel builds each SDK change on `main`, or a manual dispatch of
`release-sdk-dev.yaml` on `main`. It qualifies the portable package, publishes
`X.Y.(Z+1)-dev.<run-number>.<sha7>` under npm's `dev` tag with provenance, and uploads
the tarball, qualification receipt and `manifest.json`. It never updates `latest`.
The manifest records the version, full source SHA, SHA-256, npm integrity and
shasum. `ttr --version` prints only the bare version for machine consumers.
`ttr resources status --json` reports the installed version, channel and source SHA. Older stable packages without build metadata report an
unknown source; do not infer a source SHA from their version.

Branch Actions builds are deliberately refused. This repository is public, so
Actions artifacts are not a private distribution boundary. For premerge work,
build a clean committed checkout privately on an admitted build host, then transfer the tarball
and manifest over SSH. Do not upload unmerged previews to public Actions artifacts
or publish them to npm. Checksums establish byte identity, not code approval.

#### Cut a build

For the main channel, dispatch the workflow after its operator setup below:

```sh theme={null}
gh workflow run release-sdk-dev.yaml --ref main
```

For a private premerge preview, use a clean checkout in an admitted build root.
Use Node 24.21.0 and Bun 1.4.4, matching public package qualification. Do not build
on a workstation while a resource hold applies.

```sh theme={null}
# On the build host, inside the admitted clean checkout:
~/.bun/bin/ttr resources run -- bun sdk:dev-pack
```

The command prints JSON containing the output directory and checksum manifest.
Its default version uses a timestamp as the dev run number outside Actions.
The patch is one above the stable base, so prereleases sort above that base
and below the next stable patch.
Keep the `internalOnly: true` manifest and tarball private. The command builds the
portable SDK and dependencies, then runs the same public consumer/compiled-CLI
qualification and receipt verification as the official release. Missing registry
dependencies stop qualification; they are not replaced with workspace links.

The pack lock records its owner PID and gated child process groups atomically.
A later pack reclaims the lock after a crash or `SIGKILL` only when the owner and
every recorded process group have ended. Live builders are never evicted by age. If owner metadata is malformed or a reclaim guard
was interrupted, inspect `packages/sdk/.dev-pack.lock` and its `.reclaim/owner.json`
first. Only after confirming every recorded PID and process group has ended, remove those exact
lock/guard paths and retry. Do not delete a live owner's lock or partial package
outputs from another job. These coordination files are ignored by Git.

#### Roll out and recover

The rollout tool is a repository command, so it can update an older global CLI.
Run it outside an admitted job: its cutover needs an idle queue. Each target uses
its existing home, global Bun installation, queue, roots and limits. Hosts run
sequentially; the first failed or unknown result stops the fleet operation and
lists never-attempted hosts as skipped. SSH receives the requested drain time
plus a 30-minute operation budget. A disconnected attempt is reconciled from a
private terminal report when available; otherwise retain its `reportFile` and
staging paths for inspection. Do not replay an unknown installation.

```sh theme={null}
bun sdk:rollout --channel dev --host <host-a> --host <host-b>
bun sdk:rollout --channel latest --wait-drain 120 --host <host-a>
bun sdk:rollout --tarball /private/path/tuturuuu-preview.tgz --sha256 <manifest-sha256> --host <host-a>
```

Review the JSON report and retain its backup directory. The command verifies
bytes before installation, backs up the previous supplier and scheduler files,
previews setup, applies setup, and qualifies the global CLI and launchers. It
holds admission during cutover, never kills owners, and restores the backup on
failure. Without `--wait-drain`, an occupied queue refuses immediately. A bounded
wait does not authorize interrupting another job.

Automatic rollout targets must advertise `tuturuuuBuild.rolloutProtocol: 1`.
The existing 0.28.0 package predates that protocol and is refused before install;
use the reviewed manual drain/backup procedure for that older target, or wait for
a maintenance-capable stable release. Newly qualified dev and stable packs carry
the protocol marker. Every rollout target requires Python 3, preflighted before
installation, for its OS-released recovery lock. The tool qualifies project root/package metadata, not each
project's test suite.

Use the generated rollback command in the report to restore the saved supplier
without downloading it again. Rollback also requires an idle queue. Preserve the
backup until the host passes qualification; reconcile a failed or interrupted
rollback before attempting another rollout. Do not change `TTR_RESOURCES_HOME`,
link a workspace `dist`, or run concurrent global package-manager operations.
Global installation is required by the same-install trust fence.

A later rollback compares the current global install, configuration and launchers
with the recorded post-rollout hashes. **Rollback refuses after another global
package or a root/limit change.** Do not force a whole-install restore over newer
state; inspect and reconcile that state first. An interrupted rollback retains
its same-operation recovery fence so it can resume safely.

The automatic restore after a failed qualification compares the global package
tree with the installed-state receipt and reports `rollback: "failed"` with the
drift error instead of reverting a concurrent global install made after that
receipt. The guard does not cover a global install made before the receipt is
recorded (during install or setup), a failure before any receipt exists, or a
change between the check and the restore; those can still be reverted. Keep the
rollout's exclusive use of the global package manager for the whole run. Launcher and
configuration writes during qualification are candidate defects and are still
restored. Report `rollback` describes only
restore work. Housekeeping failures (retention pruning, report writing) set
`cleanup: "failed"` with `cleanupErrors` and leave the outcome and admission
unchanged; only a changed slot or lease owner also sets `admissionHeld: true`,
fails the report and keeps admission closed. Do not run `rollback.sh` for a
cleanup-only failure.

Candidates install from the stable content-addressed cache at
`~/.tuturuuu/resources/suppliers/<sha256>.tgz`, separate from backups. Completed
rollouts prune old completed backups, retaining five recent backups plus the
current/protected backup. Failed or unknown recovery evidence stays retained.
Cache pruning preserves archives referenced by the current installation and
retained backups.

Rollout integrity checks classify and read launcher files, supplier file contents,
and cache manifests through the same open descriptor. Directory fingerprints
compare the traversed path's device and inode with the open directory before and
after enumeration and after hashing children; a replacement aborts the check.
Cache manifests intentionally follow existing symlinks, while launcher paths
reject them. Special files fail without waiting on a FIFO.

Run `node --test scripts/sdk-rollout-descriptor.test.js scripts/sdk-rollout-race.test.js`
for deterministic check/read and directory-swap regressions. The test loader
injects filesystem hooks without changing the production functions. Set
`SDK_ROLLOUT_TEST_REF=<git-ref>` to exercise the race tests against historical
source; FIFO controls run in child processes with a two-second kill deadline.
These checks do not replace exclusive use of the global package manager during
rollout and restore.

#### Recover a stale admission fence

A dead preparation owner with no `admission/mutation.json` has not changed the
installation. Preparation has no retained reclaim fence; ordinary admission
reclaims a dead preparation owner. If a legacy or malformed fence still blocks
admission, stop new submissions and inspect
`~/.tuturuuu/resources/admission/owner.json`. Verify the recorded owner PID and
child PID/process group have ended, the token is unchanged, and `mutation.json`
is absent. Preserve the owner record and move only that confirmed stale
`admission/` directory into a private backup before admitting new work. Never
move a live owner's directory or remove slots, queue tickets or legacy locks.

When `mutation.json` exists, keep admission closed and use the backup path
recorded there to run its `rollback.sh`. A missing, malformed or ambiguous record
requires operator investigation; do not clear the fence to bypass it.

Promote code by merging the reviewed change and following the existing
production/Release Please process. Do not promote a dev tarball by moving
`latest`: stable releases are separately versioned, qualified and published.

#### Operator setup and threat model

Before enabling publication, create GitHub environment `sdk-release-dev` with
an explicit deployment branch restriction allowing only `main`. Add an additive
npm trusted publisher for `tuturuuu`: GitHub Actions, owner `tutur3u`, repository
`platform`, workflow `release-sdk-dev.yaml`, environment `sdk-release-dev`.
Keep the existing production publisher unchanged. Use GitHub-hosted publish
runners; do not add a registry token or secrets to artifacts. See
[npm trusted publishers](https://docs.npmjs.com/trusted-publishers/).

The trust boundary is reviewed main source, a nonprivileged build/qualification
job, and an isolated OIDC publish job that treats artifacts only as data. The
publish job has no checkout, builds, dependency installation or lifecycle scripts.
The environment restriction prevents a modified branch workflow from obtaining
matching publish authority. A checksum prevents corrupt or substituted bytes
when its expected value arrives through a trusted channel; it does not make
unreviewed code safe. Installing a private preview grants that code the host
user's authority. Backups may contain private scheduler configuration: keep them
on the target with private permissions and never commit or upload them.

### Devbox Setup

Use `ttr box setup` on self-hosted runner machines before offloading expensive
checks, Supabase workflows, or E2E suites. The command clones or reuses
`https://github.com/tutur3u/platform.git` at `~/Documents/tuturuuu`, runs
`bun install --frozen-lockfile`, starts the local Supabase stack with
`bun sb:start`, reads `supabase status -o json`, and upserts local Supabase
connection values into ignored `apps/*/.env.local` files with secret values
redacted from CLI output.

```bash theme={null}
ttr box doctor
ttr box setup
ttr box setup --dir .
ttr box repair --dir .
ttr box repair --dir . --dry-run
```

`ttr box doctor` stays read-only. Use `ttr box setup --yes` only when the host
should install detected missing prerequisites through its package manager.
Use `ttr box repair --dir .` after a CLI upgrade to repair an existing runner
service without registering a new runner token.

### Machine Storage

`ttr storage` reports disk headroom and ranks what fills a machine by the bytes
deleting it would actually free (APFS private bytes on macOS, allocated blocks
with hard links counted once on Linux). `prune` is a dry run until `--apply`.

```bash theme={null}
ttr storage status            # free space, pressure and inodes per volume
ttr storage analyze --json    # ranked consumers by category
ttr storage suggest           # actions with reclaimable bytes, risk and command
ttr storage prune             # dry run of the safe, bounded categories
ttr storage prune --category worktrees --apply
```

Prune never removes dirty, unmerged, locked, busy, current or held worktrees,
the primary checkout, `preserve/*` branches, or any path listed in a hold file
(`~/.t3/cleanup/holds.d/*.txt`). See
[Machine storage health](/build/development-tools/machine-storage-health) for
thresholds, categories and per-OS commands.

### Scoped Help

Use scoped help when you know the area but not the exact flags. Help commands do
not require login, do not read the saved config, and do not run the update check.

```bash theme={null}
ttr --help
ttr upgrade --help
ttr box --help
ttr calendar --help
ttr calendar events --help
ttr finance --help
ttr finance transactions --help
ttr tasks --help
ttr tasks search --help
ttr tasks create --help
ttr task-templates --help
ttr task-templates import --help
ttr task-templates export --help
ttr tasks done --help
ttr tasks close --help
ttr tasks update --help
ttr workspaces --help
ttr help tasks create
```

Global help shows the command map. Group help explains defaults and shared
flags. Action help focuses on a single operation, including required ids,
payload flags, and practical examples.

### Agent-Friendly Discovery

For autonomous engineering workflows, start by discovering the current account
and selected context:

```bash theme={null}
ttr whoami
ttr whoami --json
ttr workspaces --json --no-update-check
ttr tasks --json --no-update-check
```

`ttr whoami` shows login state, account email, current workspace, selected
board/list/task/label/project ids, base URL, config path, and the `Tuturuuu CLI`
session label. Use `--json` when another agent is going to parse stdout;
`--no-update-check` is optional and skips the registry check entirely.

The v1 task surface covers workspaces, boards, lists, tasks, labels, projects,
relationships, moves, and bulk task updates. Read-oriented groups list by
default, so `ttr tasks` and `ttr workspaces` are equivalent to their explicit
`list` forms. `ttr boards` shows active, unarchived boards by default; use
`ttr boards --archived`, `ttr boards --deleted`, or `ttr boards --all` when an
agent needs archived or deleted board inventory. Unscoped `ttr tasks` starts
from the personal workspace and lists personal tasks plus open tasks assigned to
the user in other accessible workspaces; selecting a board/list or passing
`--workspace` scopes the result back to that context. `ttr tasks` shows open
tasks by default by excluding rows with `completed_at` or `closed_at` and by
limiting task-list statuses to `not_started` and `active`. That default hides
tasks in `documents`, `review`, `done`, and `closed` lists, and tasks from
archived boards; use `--all`, `--include-archived`, `--documents`, `--review`,
`--done`, `--closed`, `--include-documents`, `--include-review`,
`--include-done`, or `--include-closed` to adjust that filter. Results are
paginated at 50 tasks by default; use
`--page`/`--page-size` or `--limit`/`--offset` to page through larger task sets.
Human-readable task lists show a footer with the total task count and current
page/max page. Add `--compact` to task lists when an agent only needs the task
title, task list name, and per-task workspace name. Task lists are ordered by
priority and due date, with prettier due dates and configured task-list colors
in table output. Human-readable tables use smooth box borders, respect the
terminal width, and wrap long cell content so task titles stay readable instead
of overflowing narrow panes. Add `--json`
when another agent or script needs machine-readable output.

Use `ttr tasks search <query>` for ranked task search. Search defaults to
`--mode hybrid`, accepts `--mode text` for PostgreSQL full-text search only and
`--mode semantic` for embedding similarity only, and supports
`--query`/`--q`, `--limit`/`--match-count`, `--threshold`/`--match-threshold`,
`--workspace`/`--ws`, `--compact`, and `--json`. Search output preserves API
relevance order and shows the score when available. Existing list filtering
with `ttr tasks --q <query>` is unchanged and remains the lightweight list text
filter.

`tasks create`, `boards create`, and `lists create` accept a quoted positional name as
a shorthand for `--name`. Task CRUD accepts either the task UUID or the board
identifier shown in the UI, such as `VHP-12`; prefixed identifiers resolve
within the selected workspace even when another list is selected, and matching
human-readable output keeps that prefixed identifier visible. Marking a task
completed stamps `completed_at` so Tuturuuu moves it to the first `done` list;
pass `--list <done-list-id>` or include `list_id` in `--json-payload` to choose
another done destination. Use `ttr tasks done [task-id]` as the quick shortcut.
Use `ttr tasks close [task-id]` to stamp `closed_at`; pass `--list <closed-list-id>` to choose a specific closed destination.

Task templates are single-task starters, separate from board templates.
Workspace templates are managed with
`ttr task-templates list/show/create/update/delete/use` and can be imported
from or exported to local markdown files. Local templates live under
`.tuturuuu/task-templates/*.md`, use YAML frontmatter for fields such as `key`,
`name`, `task_name`, `priority`, `label_ids`, `assignee_ids`, and
`project_ids`, and use the markdown body as the task description. Markdown
descriptions from `--description-format markdown` and local template bodies
support GFM pipe tables and are stored as TipTap/Yjs table content for the web
editor. `ttr tasks create --template <key-or-path>` resolves workspace keys or
local markdown paths; explicit flags such as `--name`, `--list`, `--priority`,
`--labels`, and `--projects` override template defaults.

```markdown theme={null}
---
key: qa-handoff
name: QA handoff
task_name: Verify release handoff
priority: high
---

| Field | Value |
| --- | --- |
| Owner | Platform |
| Environment | Staging |
```

### Finance CLI

Finance commands use the selected workspace and the same authenticated internal
APIs as the web app. Use `--workspace` or `--ws` to target a different
workspace, and use `--json-payload` when a script needs to send fields that do
not have dedicated flags yet. Finance list output is paginated by default; use
`--page`/`--page-size` or `--limit`/`--offset` to move through larger result
sets.

Finance API routes that back `ttr finance` should resolve access through
`getFinanceRouteContext` from `@tuturuuu/apis/finance/request-access`, with
app-owned routes passing `resolveFinanceRouteAuthContext(request)` from
`apps/web/src/lib/finance-route-auth.ts` when they need CLI app-session bearer
token support. Keep CLI token verification in the app layer so `@tuturuuu/apis`
does not depend on `@tuturuuu/auth`; `getFinanceRouteContext` still keeps the
pre-authenticated actor, browser Supabase sessions, `personal` workspace
resolution, and finance permission checks on the same path.

```bash theme={null}
# Wallet CRUD.
ttr finance wallets
ttr finance wallets --page 2 --page-size 10
ttr finance wallets get <wallet-id>
ttr finance wallets balance <wallet-id>
ttr finance wallets balance --all
ttr finance wallets create "Cash" --currency VND --balance 0 --type STANDARD
ttr finance wallets update <wallet-id> --name "Operating Cash"
ttr finance wallets delete <wallet-id>

# Transaction CRUD and reporting helpers.
ttr finance transactions --page-size 10
ttr finance transactions --limit 25 --offset 50
ttr finance transactions get <transaction-id>
ttr finance transactions create --amount 150000 --wallet <wallet-id> --taken-at 2026-05-09
ttr finance transactions update <transaction-id> --category <category-id>
ttr finance transactions delete <transaction-id>
ttr finance transactions export --wallets <wallet-id> --start 2026-05-01 --end 2026-05-31
ttr finance transactions stats --start 2026-05-01 --end 2026-05-31

# Transfer creation, update, and id-preserving migration.
ttr finance transfers create --from-wallet <wallet-id> --to-wallet <wallet-id> --amount 150000 --taken-at 2026-05-09
ttr finance transfers update --from-transaction <tx-id> --to-transaction <tx-id> --from-wallet <wallet-id> --to-wallet <wallet-id> --amount 150000 --taken-at 2026-05-09
ttr finance transfers migrate --from-transaction <tx-id> --to-transaction <tx-id> --from-wallet <wallet-id> --to-wallet <wallet-id> --amount 150000 --taken-at 2026-05-09

# Categories, budgets, and recurring transactions.
ttr finance categories create "Travel" --expense --color blue --description "Trips and commuting"
ttr finance budgets create "Marketing" --amount 1000000 --period monthly --start-date 2026-05-01
ttr finance budgets status
ttr finance recurring create "Rent" --amount 5000000 --wallet <wallet-id> --frequency monthly --start-date 2026-05-01
ttr finance recurring upcoming --days-ahead 30
```

### Calendar CLI

Calendar commands use the selected workspace and the same authenticated calendar
APIs as the web app. Use `--workspace` or `--ws` to target a different
workspace, and use `--json` when scripts need the raw structured response.
Human output renders resource-specific tables for events, calendars, categories,
accounts, provider calendars, connections, sources, and schedulable tasks.

Event time input is exact ISO datetime only. `events create` requires `--start`
and exactly one of `--end` or `--duration-minutes`; `events update --duration-minutes` also requires `--start`. Source flags map to provider
payloads: use `--source-provider tuturuuu --calendar <workspace-calendar-id>`
for workspace calendars, or `--source-provider google|microsoft --connection <connection-id>` for connected provider calendars. `calendar calendars reset`
is destructive and requires `--yes`.

```bash theme={null}
# Event CRUD.
ttr calendar events list --start 2026-06-11T00:00:00Z --end 2026-06-12T00:00:00Z
ttr calendar events get <event-id>
ttr calendar events create "Focus block" --start 2026-06-11T09:00:00+07:00 --duration-minutes 90
ttr calendar events update <event-id> --title "Focus block" --locked true
ttr calendar events delete <event-id>

# Default source and workspace calendar administration.
ttr calendar sources list
ttr calendar sources use --source-provider tuturuuu --calendar <calendar-id>
ttr calendar calendars create "Team" --color BLUE
ttr calendar calendars update <calendar-id> --name "Team Calendar"
ttr calendar calendars reset --yes

# Categories and provider connections.
ttr calendar categories create "Focus" --color BLUE
ttr calendar categories reorder --json-payload '{"categories":[{"id":"...","position":0}]}'
ttr calendar accounts list
ttr calendar auth google
ttr calendar auth microsoft
ttr calendar provider-calendars list --account <account-id>
ttr calendar connections create --calendar-id primary --calendar-name "Primary" --account <account-id>

# Scheduling.
ttr calendar schedule status
ttr calendar schedule tasks --q roadmap
ttr calendar schedule preview --window-days 14 --timezone Asia/Ho_Chi_Minh
ttr calendar schedule apply --mode safe-apply --scope impacted-only --window-days 14 --timezone Asia/Ho_Chi_Minh
```

Common task workflows:

```bash theme={null}
# List open tasks in the selected workspace.
ttr tasks

# List active boards only; pass --archived, --deleted, or --all for other states.
ttr boards

# Compact human output: task title, task list, and workspace.
ttr tasks --compact

# Machine-readable output for agents.
ttr tasks --json --no-update-check

# Ranked full-text, semantic, or hybrid search.
ttr tasks search "deadline review"
ttr tasks search "deadline review" --mode hybrid --limit 20 --threshold 0.25
ttr tasks search --query "deadline review" --mode text --json --no-update-check

# Create from the selected board/list, prompting when needed.
ttr tasks create "Add Tuturuuu CLI"

# Create directly into a known list.
ttr tasks create --list <list-id> --name "Write release notes"

# Create and use task templates.
ttr task-templates list
ttr task-templates create "Bug report" --key bug-report --title "Investigate bug" --priority high
ttr task-templates export bug-report --file .tuturuuu/task-templates/bug-report.md
ttr task-templates import .tuturuuu/task-templates/bug-report.md
ttr tiptap parse --text "| Field | Value |\n| --- | --- |\n| Owner | Platform |" --format markdown --output json
ttr tasks create --template bug-report --list <list-id> --name "Investigate checkout bug"
ttr tasks create "QA handoff" --description-file table.md --description-format markdown

# Move with the keyboard picker.
ttr tasks move

# Move directly to a done list.
ttr tasks move VHP-12 --list <done-list-id>

# Quick mark done and use the first done list on the task board when available.
ttr tasks done VHP-12

# Quick mark done with an explicit done destination.
ttr tasks done <task-id> --list <done-list-id>

# Quick mark closed and use the first closed list on the task board when available.
ttr tasks close VHP-12

# Quick mark closed with an explicit closed destination.
ttr tasks close <task-id> --list <closed-list-id>

# Mark completed and let Tuturuuu choose the default done list.
ttr tasks update VHP-12 --json-payload '{"completed":true}'

# Mark completed and choose a specific done destination.
ttr tasks update <task-id> --list <done-list-id> --json-payload '{"completed":true}'
```

For terminal workflows, omit an id from `use`, `get`, `update`, `delete`, or
`move` commands to pick a workspace, board, list, task, label, or project with
the keyboard. The interactive picker shows one-based indexes, colored badges
such as `[FREE] Tuturuuu` and `[PRO] Personal`, task-list color swatches, the
selected row, and muted metadata. Use up/down or `j`/`k` to move, space/enter to
select, and escape/`q` to cancel. Interactive selection is disabled for `--json`
output. Picker labels, descriptions, badges, and color names derived from
platform data must visibly escape terminal control characters before rendering.
Use `ttr -v` or `ttr --version` to print the installed CLI version.

## Client Initialization

### Basic Usage

```typescript theme={null}
const client = new TuturuuuClient('ttr_your_api_key');
```

### With Custom Configuration

```typescript theme={null}
const client = new TuturuuuClient({
  apiKey: 'ttr_your_api_key',
  baseUrl: 'https://tuturuuu.com/api/v1', // optional
  timeout: 30000 // optional, default 30s
});
```

## Storage API

### List Files

Lists files and folders in the workspace drive.

```typescript theme={null}
const files = await client.storage.list({
  path: 'documents', // folder path (optional)
  search: 'report', // search term (optional)
  limit: 50, // max results (optional, default 100)
  offset: 0, // pagination offset (optional)
  sortBy: 'created_at', // sort field (optional)
  sortOrder: 'desc' // sort direction (optional)
});

console.log(files.data); // Array of StorageObject
console.log(files.pagination); // Pagination info
```

### Upload File

Uploads a file to the workspace drive.

```typescript theme={null}
const file = new File(['content'], 'document.pdf');

const result = await client.storage.upload(file, {
  path: 'documents', // destination folder (optional)
  upsert: true // overwrite if exists (optional)
});

console.log(result.data.path); // Relative path
console.log(result.data.fullPath); // Full storage path
```

### Download File

Downloads a file as a Blob.

```typescript theme={null}
const blob = await client.storage.download('documents/report.pdf');

// Save to disk (Node.js)
const buffer = Buffer.from(await blob.arrayBuffer());
await fs.writeFile('report.pdf', buffer);

// Create download link (Browser)
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'report.pdf';
a.click();
```

Apply an image transform during download:

```typescript theme={null}
const blob = await client.storage.download('images/photo.png', {
  transform: {
    width: 320,
    height: 180,
    resize: 'cover',
    quality: 80
  }
});
```

### Delete Files

Deletes one or more files or folders.

```typescript theme={null}
const result = await client.storage.delete([
  'documents/old-report.pdf',
  'images/screenshot.png'
]);

console.log(result.data.deleted); // Number of files deleted
console.log(result.data.paths); // Array of deleted paths
```

### Create Folder

Creates a new folder in the workspace drive.

```typescript theme={null}
const result = await client.storage.createFolder(
  'documents', // parent path
  'reports' // folder name
);

console.log(result.data.path); // "documents/reports"
```

### Share File

Generates a signed URL for temporary file sharing.

```typescript theme={null}
const result = await client.storage.share('documents/report.pdf', {
  expiresIn: 3600 // 1 hour in seconds (default 3600, max 604800)
});

console.log(result.data.signedUrl); // Temporary URL
console.log(result.data.expiresAt); // ISO timestamp
console.log(result.data.expiresIn); // Seconds until expiration
```

Apply an image transform before generating the signed URL:

```typescript theme={null}
const result = await client.storage.share('images/photo.png', {
  expiresIn: 3600,
  transform: {
    width: 320,
    height: 180,
    resize: 'contain',
    quality: 85
  }
});
```

### Get Analytics

Retrieves storage usage statistics for the workspace.

```typescript theme={null}
const analytics = await client.storage.getAnalytics();

console.log(analytics.data.totalSize); // Total bytes used
console.log(analytics.data.fileCount); // Number of files
console.log(analytics.data.storageLimit); // Storage limit in bytes
console.log(analytics.data.usagePercentage); // Usage percentage
console.log(analytics.data.largestFile); // Largest file info
console.log(analytics.data.smallestFile); // Smallest file info
```

## Documents API

### List Documents

Lists documents in the workspace with optional filters.

```typescript theme={null}
const docs = await client.documents.list({
  search: 'meeting', // search in names (optional)
  limit: 20, // max results (optional, default 50)
  offset: 0, // pagination offset (optional)
  isPublic: false // filter by visibility (optional)
});

console.log(docs.data); // Array of Document
console.log(docs.pagination); // Pagination info
```

### Create Document

Creates a new document in the workspace.

```typescript theme={null}
const doc = await client.documents.create({
  name: 'Meeting Notes',
  content: {
    text: 'Discussion points...',
    attendees: ['Alice', 'Bob']
  },
  isPublic: false // optional, default false
});

console.log(doc.data.id); // Document ID
console.log(doc.data.name); // Document name
console.log(doc.data.content); // JSONB content
```

### Get Document

Retrieves a document by its ID.

```typescript theme={null}
const doc = await client.documents.get('document-id-123');

console.log(doc.data.name);
console.log(doc.data.content);
console.log(doc.data.created_at);
```

### Update Document

Updates an existing document.

```typescript theme={null}
const doc = await client.documents.update('document-id-123', {
  name: 'Updated Meeting Notes', // optional
  content: { text: 'New content' }, // optional
  isPublic: true // optional
});

console.log(doc.data); // Updated document
```

### Delete Document

Deletes a document permanently.

```typescript theme={null}
await client.documents.delete('document-id-123');
```

### Search Documents

Searches documents by name (alias for `list()` with search).

```typescript theme={null}
const results = await client.documents.search('meeting notes', {
  limit: 10,
  isPublic: false
});

console.log(results.data); // Matching documents
```

## CMS Delivery

The SDK also exposes the external-project delivery client that powers Tuturuuu CMS preview surfaces and branded external apps.

```typescript theme={null}
const delivery = await client.externalProjects.getDelivery('workspace-id');

if (delivery.loadingData?.adapter === 'yoola') {
  console.log(delivery.loadingData.featuredArtwork?.title);
  console.log(delivery.loadingData.singletonSections.about?.bodyMarkdown);
}

const yoolaLoadingData =
  await client.externalProjects.getYoolaLoadingData('workspace-id');
console.log(yoolaLoadingData.artworkCategories);
```

For the Yoola adapter, `artworkCategories` comes from the configured gallery taxonomy on `singleton-sections/gallery` (`profile_data.categoryOptions`) rather than being inferred from every artwork entry.

External app admin dashboards can auto-create and bind the workspace studio before their first diff/apply when the workspace ID is configured and the app token has `external-projects:*` or manage scope:

```typescript theme={null}
await client.externalProjects.sync.setup('workspace-id', { manifest });
```

Operators can use the authenticated CLI instead of app-local token scripts:

```bash theme={null}
ttr external projects summary --workspace <workspace-id> --json
ttr external projects delivery --workspace <workspace-id> --preview --out tmp/delivery.json
ttr external projects snapshot --workspace <workspace-id> --out tmp/snapshot.json
ttr external projects setup --workspace <workspace-id> --manifest external-project.json
ttr external projects diff --workspace <workspace-id> --manifest external-project.json --json
ttr external projects apply --workspace <workspace-id> --manifest external-project.json --confirm APPLY_EXTERNAL_PROJECT_SYNC
```

### Public Folder Asset Sync

### Register and configure an external site from the CLI

Root operators can manage registered apps, approve scopes, create templates,
and bind workspaces without opening Infrastructure or CMS. Existing root and
workspace permission checks remain mandatory; the CLI does not grant access.

```bash theme={null}
ttr external apps list --json
ttr external apps save --file app.json --dry-run
ttr external apps save --file app.json --confirm CONFIGURE_EXTERNAL_APP
ttr external apps scopes rennu --scopes external-projects:read,external-projects:manage,external-projects:publish --dry-run
ttr external apps scopes rennu --scopes external-projects:read,external-projects:manage,external-projects:publish --confirm APPROVE_EXTERNAL_APP_SCOPES
ttr external templates create --file template.json --confirm CREATE_SITE_TEMPLATE
ttr external binding set --workspace <workspace-id> --template rennu --confirm LINK_SITE_TEMPLATE
ttr external binding get --workspace <workspace-id> --json
```

App JSON requires `id`, `displayName`, `enabled`, `origins`, `allowedScopes`,
and `allowedWorkspaceIds` (explicit UUID allowlist). Do not include secrets or
audit fields. Save updates these fields without rotating credentials. Scope
changes replace the whole approved list; `--clear-scopes` revokes all scopes.
Custom template JSON can be
`{"id":"rennu","display_name":"Ren Everheart","adapter":"custom"}`;
the template ID must match the registered app ID. Run `projects setup`, `diff`,
and confirmed `apply` after binding to configure and populate the workspace.

```bash theme={null}
ttr external apps rotate-secret rennu --secret-out /private/secure/ren-app-secret --confirm ROTATE_EXTERNAL_APP_SECRET
```

This explicitly issues or rotates the secret and immediately invalidates the
previous value. The destination must not exist; its parent must exist. The CLI
writes an owner-only (`0600`) file, never the secret to stdout. Transfer it to
the app's server environment and securely remove the local file; never commit
it. A failed request may leave an empty file, which is not overwritten on retry.
The SDK equivalent lives at `TuturuuuUserClient.external.admin`.

External apps can keep seed media in their local `public/` folder and still publish it through Tuturuuu Drive. Mark each manifest asset with `metadata.publicPath`, `metadata.localAssetPath`, `metadata.sourcePublicPath`, or a relative `sourceUrl`.

```typescript theme={null}
import { linkExternalProjectPublicFolderAssets } from 'tuturuuu';
import { uploadExternalProjectPublicFolderAssets } from 'tuturuuu/external-projects/public-assets';

const linkedManifest = linkExternalProjectPublicFolderAssets(manifest);

const sync = await uploadExternalProjectPublicFolderAssets(
  client.externalProjects,
  'workspace-id',
  manifest,
  { publicDir: './public' }
);

console.log(sync.uploaded.length);
console.log(linkedManifest.content.entries[0]?.assets?.[0]?.storagePath);
```

The linker writes deterministic storage paths under `external-projects/{adapter}/{collectionSlug}/{entrySlug}/{filename}`. External apps can upload those assets through signed upload URLs, or through the external-project asset multipart route when they need the app server to stream the file with a server-owned bearer token. Production Supabase keys are not needed in external apps.

### TanStack Query

For React apps, keep the SDK as the delivery boundary and TanStack Query as the cache owner:

```typescript theme={null}
import { useQuery } from '@tanstack/react-query';
import {
  getEpmDeliveryQueryOptions,
  getYoolaLoadingDataQueryOptions
} from 'tuturuuu';

const deliveryQuery = useQuery({
  ...getEpmDeliveryQueryOptions(client.externalProjects, 'workspace-id'),
  staleTime: 60_000
});

const yoolaLoadingQuery = useQuery({
  ...getYoolaLoadingDataQueryOptions(client.externalProjects, 'workspace-id'),
  staleTime: 60_000
});
```

In external Next.js apps, prefer hydrating the delivery query once near the root layout and deriving page-level view models from that shared cache instead of letting each route perform its own SDK fetch.

## Error Handling

The SDK provides specific error classes for different scenarios:

```typescript theme={null}
import {
  AuthenticationError,
  AuthorizationError,
  NotFoundError,
  ConflictError,
  RateLimitError,
  NetworkError,
  ValidationError
} from 'tuturuuu';

try {
  await client.storage.upload(file);
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid or expired API key
    console.error('Authentication failed:', error.message);
  } else if (error instanceof AuthorizationError) {
    // Insufficient permissions
    console.error('Forbidden:', error.message);
  } else if (error instanceof NotFoundError) {
    // Resource not found
    console.error('Not found:', error.message);
  } else if (error instanceof ConflictError) {
    // Resource already exists
    console.error('Conflict:', error.message);
  } else if (error instanceof RateLimitError) {
    // Rate limit exceeded
    console.error('Rate limited:', error.message);
  } else if (error instanceof NetworkError) {
    // Network or timeout error
    console.error('Network error:', error.message);
  } else if (error instanceof ValidationError) {
    // Invalid input
    console.error('Validation error:', error.message);
  }
}
```

### Error Properties

All error classes include:

* `message` - Human-readable error description
* `code` - Machine-readable error code
* `statusCode` - HTTP status code
* `name` - Error class name

```typescript theme={null}
try {
  await client.storage.delete([]);
} catch (error) {
  if (error instanceof ValidationError) {
    console.log(error.message); // "At least one path is required"
    console.log(error.code); // "VALIDATION_ERROR"
    console.log(error.statusCode); // 400
    console.log(error.name); // "ValidationError"
  }
}
```

## TypeScript Support

The SDK is fully typed with TypeScript:

```typescript theme={null}
import type {
  StorageObject,
  Document,
  ListStorageOptions,
  UploadOptions,
  ShareOptions,
  CreateDocumentData,
  UpdateDocumentData,
  ListDocumentsOptions
} from 'tuturuuu';

// Type-safe options
const options: ListStorageOptions = {
  path: 'documents',
  sortBy: 'created_at',
  sortOrder: 'desc'
};

// Type-safe document data
const docData: CreateDocumentData = {
  name: 'My Doc',
  content: { text: 'Content' },
  isPublic: false
};
```

## API Key Management

### Creating an API Key

1. Log in to your Tuturuuu workspace
2. Navigate to **Settings** → **API Keys**
3. Click **"Create API Key"**
4. Set a descriptive name
5. Assign a **Workspace Role** (determines permissions)
6. Optionally set an expiration date
7. Copy the generated key (starts with `ttr_`)
8. Store securely (you won't see it again)

### Best Practices

> [!WARNING]
>
> **Never commit API keys to version control!** Use environment variables or
> secret management services.

```bash theme={null}
# .env
TUTURUUU_API_KEY=ttr_your_api_key_here
```

```typescript theme={null}
// app.ts
const client = new TuturuuuClient(process.env.TUTURUUU_API_KEY!);
```

### Permissions

API keys inherit permissions from their assigned **Workspace Role**. The role determines what operations the key can perform.

**Required Permissions:**

**Note:** Permissions are managed through workspace roles, not individual API keys. To modify what an API key can do, update its assigned role's permissions in **Settings** → **Roles**.

## Security Best Practices

> [!WARNING]
>
> **CRITICAL: Never expose API keys in client-side code!** API keys must remain
> server-side only.

### ❌ Insecure (NEVER do this)

```typescript theme={null}
// BAD: Exposes API key to browser!
'use client'; // Client component

const client = new TuturuuuClient(process.env.NEXT_PUBLIC_API_KEY);
// ❌ Anyone can inspect network requests and steal your key!
```

### ✅ Secure (Recommended patterns)

#### Next.js App Router (Recommended)

Create server-side API routes that proxy SDK calls:

```typescript theme={null}
// app/api/storage/list/route.ts (SERVER-SIDE)
import { TuturuuuClient } from 'tuturuuu';
import { NextResponse } from 'next/server';

const client = new TuturuuuClient(process.env.TUTURUUU_API_KEY);

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const path = searchParams.get('path') || '';

const files = await client.storage.list({ path, limit: 50 });
  return NextResponse.json(files);
}
```

Then call from your client component:

```typescript theme={null}
// app/components/FileList.tsx (CLIENT COMPONENT - SAFE)
'use client';

export function FileList() {
  const [files, setFiles] = useState([]);

useEffect(() => {
    fetch('/api/storage/list?path=documents')
      .then(res => res.json())
      .then(setFiles);
  }, []);

return <div>{/* Render files */}</div>;
}
```

#### Node.js/Express Backend

```typescript theme={null}
// server.js
import { TuturuuuClient } from 'tuturuuu';
import express from 'express';

const client = new TuturuuuClient(process.env.TUTURUUU_API_KEY);
const app = express();

app.get('/api/files', async (req, res) => {
  const files = await client.storage.list();
  res.json(files);
});

app.listen(3000);
```

#### Serverless Functions (Netlify, Vercel, AWS Lambda)

```typescript theme={null}
// netlify/functions/storage.ts
import { TuturuuuClient } from 'tuturuuu';

export const handler = async (event) => {
  const client = new TuturuuuClient(process.env.TUTURUUU_API_KEY);
  const files = await client.storage.list();

return {
    statusCode: 200,
    body: JSON.stringify(files)
  };
};
```

### Security Checklist

> **✅ DO: Use server-side code**
>
> Always use the SDK in server-side contexts:
>
> * Next.js API Routes (App Router or Pages Router)
> * Node.js backend servers
> * Serverless functions
> * Server Components (React Server Components)

> **✅ DO: Use environment variables**
>
> Store API keys in environment variables:
>
> ```bash theme={null}
> # .env.local (server-side only)
> TUTURUUU_API_KEY=ttr_your_key_here
> TUTURUUU_BASE_URL=https://tuturuuu.com/api/v1
> ```
>
> **Never** use `NEXT_PUBLIC_` prefix for API keys!

> **✅ DO: Add .env.local to .gitignore**
>
> Ensure secrets never get committed: `gitignore # .gitignore .env.local
>       .env*.local `

> **❌ DON'T: Use NEXT\_PUBLIC\_ prefix**
>
> This exposes the variable to the browser: `bash # BAD - Exposed to client!
>       NEXT_PUBLIC_TUTURUUU_API_KEY=ttr_key `

> **❌ DON'T: Import SDK in client components**
>
> Never import the SDK in files with `'use client'` directive.

> **❌ DON'T: Hardcode API keys**
>
> Never commit keys to version control:
>
> ```typescript theme={null}
> // BAD
> const client = new TuturuuuClient('ttr_1234567890abcdef');
> ```

### Complete Example

See the [external app example](https://github.com/tutur3u/platform/tree/main/apps/external) for a complete implementation showcasing:

* ✅ Secure server-side API routes
* ✅ File upload with progress
* ✅ Storage analytics dashboard
* ✅ Proper error handling
* ✅ Environment variable configuration

## Rate Limiting

The API enforces rate limits per API key to ensure fair usage and system stability:

### Rate Limits by Operation

### Rate Limit Headers

Every API response includes rate limit information in the headers:

* `X-RateLimit-Limit` - Maximum requests allowed in the time window
* `X-RateLimit-Remaining` - Number of requests remaining in current window
* `X-RateLimit-Reset` - Unix timestamp when the rate limit resets

```typescript theme={null}
const result = await client.storage.list();

// Access rate limit info from headers (if using direct API calls)
console.log('Limit:', result.headers.get('X-RateLimit-Limit'));
console.log('Remaining:', result.headers.get('X-RateLimit-Remaining'));
console.log(
  'Resets at:',
  new Date(Number.parseInt(result.headers.get('X-RateLimit-Reset')) * 1000)
);
```

### Handling Rate Limits

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```typescript theme={null}
try {
  await client.storage.upload(file);
} catch (error) {
  if (error instanceof RateLimitError) {
    console.error('Rate limited! Try again later.');
    console.error('Retry after:', error.retryAfter, 'seconds');

// Implement exponential backoff
    await new Promise((resolve) =>
      setTimeout(resolve, error.retryAfter * 1000)
    );
  }
}
```

### Workspace-Specific Rate Limits

Workspace administrators can configure custom rate limits for their workspace through **Workspace Secrets**. These override the default limits for all API keys in that workspace.

To set custom rate limits:

1. Navigate to **Settings** → **Workspace Settings** → **Secrets**
2. Add one or more of these secrets:

**Example Configuration:**

```
RATE_LIMIT_WINDOW_MS = 60000
RATE_LIMIT_MAX_REQUESTS = 500
```

This configuration allows 500 requests per minute for all API keys in the workspace, instead of the default 100.

> [!NOTE]
>
> Workspace-specific rate limits only apply to operations that don't have
> explicit per-operation limits. For operations like uploads and downloads, the
> operation-specific limits still apply.

### Best Practices

> [!TIP]
>
> **Implement exponential backoff** when handling rate limits to avoid hammering
> the API with retries.

```typescript theme={null}
async function uploadWithRetry(file: File, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await client.storage.upload(file);
    } catch (error) {
      if (error instanceof RateLimitError && attempt < maxRetries - 1) {
        // Exponential backoff: 1s, 2s, 4s
        const delay = Math.pow(2, attempt) * 1000;
        await new Promise((resolve) => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}
```

> [!TIP]
>
> **Monitor rate limit headers** to track your usage and avoid hitting limits:
>
> ```typescript theme={null}
> // Check remaining requests after each call
> const response = await fetch('https://tuturuuu.com/api/v1/storage/list', {
>   headers: { 'Authorization': `Bearer ${apiKey}` }
> });
>
> const remaining = response.headers.get('X-RateLimit-Remaining');
> const limit = response.headers.get('X-RateLimit-Limit');
>
> console.log(`API calls remaining: ${remaining}/${limit}`);
>
> // Slow down if close to limit
> if (Number(remaining) < Number(limit) \* 0.1) {
> await new Promise(resolve => setTimeout(resolve, 1000));
> }
>
> ```

## Examples

> **[Basic Usage](https://github.com/tutur3u/platform/blob/main/packages/sdk/examples/basic-usage.ts)**
>
> Complete example of all SDK operations

> **[Error Handling](https://github.com/tutur3u/platform/blob/main/packages/sdk/examples/error-handling.ts)**
>
> Comprehensive error handling patterns

## Support

> **[GitHub](https://github.com/tutur3u/platform)**
>
> Source code and issues

> **[Discord](https://discord.gg/tuturuuu)**
>
> Community support

> **[Docs](https://docs.tuturuuu.com)**
>
> Full documentation

## Changelog

The package version is managed by Release Please, and the full, authoritative
changelog is generated per release. For the complete history (currently shipping
the `0.10.x` line), see the maintained changelog rather than this page:

> **[CHANGELOG.md](https://github.com/tutur3u/platform/blob/main/packages/sdk/CHANGELOG.md)**
>
> Full per-release changelog (source of truth)

> **[npm](https://www.npmjs.com/package/tuturuuu)**
>
> Published versions and release tags

**Highlights since the initial release:**

* Storage operations (list, upload, download, delete, folders, share, analytics)
* Document operations (CRUD, search)
* `ttr` CLI with workspace, host switching, and session-based auth
* Finance commands (wallets, transactions, transfers, tags, wallet checkpoints)
* Calendar commands
* External projects support and remote devbox tooling
* Comprehensive error handling, full TypeScript types, and Zod validation

> [!NOTE]
>
> Do not treat any version number quoted in this page as exact — the SDK is on a
> fast release cadence. Always check the linked changelog or npm for the current
> version.

## License

MIT

## Local resource control

Use `ttr resources` to keep coding sessions responsive with bounded validation on the same machine. This opt-in feature supports macOS/Linux without login or a background daemon.

```bash theme={null}
ttr resources setup --root ~/code/project-a --root ~/code/project-b --shell zsh
ttr resources status
ttr resources run -- bun run test
ttr resources monitor --seconds 60 > resource-samples.jsonl
```

Explicit `run` requires setup-provisioned executable shims matching the current runtime and resource entry. It only reads and validates those launchers; it never installs, rewrites, chmods, or activates them. Missing, stale, malformed, or nonexecutable shims fail before queue admission and workload launch, with an explicit `ttr resources setup --shell none` instruction. Inspect occupancy and obtain installation authority before setup; a source update does not authorize replacing an installed scheduler. Resource commands dispatch before general authenticated CLI imports. This avoids those eager imports but does not establish the cause or repair of any host-specific startup hang. Regression coverage lives in `resources-provisioning.test.ts` and `entry-dispatch.test.ts`; existing lane tests retain FIFO, pressure, and owned cancellation/drain coverage.

Setup includes linked Git worktrees. One canonical per-user FIFO queue defaults to one lane; missing `validationLanes` in version-1 configurations means one. `validationLanes` is the base lane count, an integer from `1` to `8`, configured with `setup --lanes`. `--workers` sets the aggregate Vitest/Cargo total. Configurations split that total across lanes with rounding down, but every lane receives at least one worker. Turbo runs one task per lane, and explicit Vitest/Cargo flags are capped. `--dry-run` inspects changes without writing.

Admission is reentrant. An admitted job exports `TTR_RESOURCES_ADMITTED=<owner token>` (and the legacy `TTR_RESOURCE_OWNER`). A nested `ttr resources run` or shim-admitted heavy command inside that job runs immediately with the owner's caps instead of queueing behind its own ancestor. The marker counts only while it names a live owner inside that owner's process tree (an ancestor PID or the owned launcher's process group). When `ps` ancestry is unavailable, the marker cannot be verified, so it is ignored with a warning and the command queues. On Linux without a trusted `ps`, lineage falls back to the kernel's `/proc/<pid>/stat`, which is not PATH-controlled. Where no ancestry evidence exists at all, a waiter whose marker names a live owner fails after 60 seconds with an actionable error (install `ps`, or use `TTR_RESOURCES_BYPASS=1`) instead of waiting forever behind its own ancestor (`resources-ancestry.test.ts`). Ancestry and process-group liveness come only from `/bin/ps` or `/usr/bin/ps`, run with an empty environment; `ps` is never resolved through the caller's PATH, so a fake `ps` cannot fabricate ancestry. Without a trusted `ps` there is no evidence and the command queues. Stale or copied markers are likewise ignored with a warning and queue normally. Children whose environment is filtered, such as under Turbo strict env, are matched by ancestry alone. Successful ancestry snapshots are cached per process, and failed `ps` probes are retried. A waiter also rechecks ancestry about once per second, so a transient probe failure cannot deadlock it behind its own ancestor. Regression coverage lives in `resources-reentrancy.test.ts`.

Explicit `run` skips the queue only for a few read-only coreutils (`echo`, `pwd`, `true`, `false`, `whoami`, `uname`, `date`, `printenv`, `cat`, `head`, `tail`, `wc`). `ls` always queues because recursion hides in bundled flags (`-1R`) and GNU long-option abbreviations (`--rec`). The exemption is decided on the executable that would actually run: the first PATH match (or the given path) must resolve to the same-named binary directly inside `/bin`, `/usr/bin` or Ubuntu's rust-coreutils applet directory `/usr/lib/cargo/bin/coreutils` (exact directories, no subdirectories; the same basename keeps a multicall binary on the intended applet, so busybox-style targets queue), and that file and every directory above it must be root-owned and not writable by group or others, so an impostor script named `cat` or `/any/path/node` queues. On Ubuntu 26.04 (skr-linux-lan, verified 2026-10-23) `/bin` links to `usr/bin`, and `/usr/bin/{cat,echo,head,tail,wc,pwd,date,uname,printenv,whoami,false}` link to root-owned 755 applets in `/usr/lib/cargo/bin/coreutils`, with every directory up to `/` root:755. Those tools are trusted there; `true` links to `/usr/bin/gnutrue`, a different basename, so it queues. The host-gated test in `resources-trusted-path.test.ts` rechecks this on any such host. The CLI then spawns exactly that canonical path, never the original name or symlink, so swapping a symlink after classification cannot run a payload (`resources-race.test.ts`; Linux and macOS layouts in `resources-trusted-path.test.ts`). It is also refused while `LD_*`, `DYLD_*`, `GCONV_PATH` or `LOCPATH` is set. Runtimes and package managers queue even for `--version`/`--help`, because `NODE_OPTIONS=--require`, `npm_config_*` and preload settings load code before any flag is read. Every git command queues, because `status`/`ls-files` run `core.fsmonitor` (also injectable through `GIT_CONFIG_COUNT`), `branch` runs the `reference-transaction` hook and a pager, and `diff|log|show` run textconv or external diff drivers. Regression coverage lives in `resources-hardening.test.ts` and the occupied-slot dispatcher test in `resources-bypass.test.ts`. Shims already pass non-heavy commands straight through.

Node shim classification consumes known runtime option values, including `--diagnostic-dir /tmp`, before identifying a tool entrypoint. Unknown or incomplete Node options queue conservatively, even when later arguments include `--help`. Recognized Vitest entrypoints retain their worker cap after runtime options and the Node `--` separator. Arguments after an ordinary script path remain that script's arguments. The Node 26.4 bare forms of `--experimental-config-file` and `--experimental-specifier-resolution` do not consume the next argv; only their `=` forms are accepted as value options. Any separate option value that itself identifies a tool, ttr launcher, or heavy script makes classification ambiguous and queues conservatively.

The adaptive design requires a CLI release before activation. Optional `maxValidationLanes` accepts an integer from the base count through `16` and defaults to the base count. After release and a full idle drain, `ttr resources setup --max-lanes N` explicitly opts into a higher ceiling. Host capacity never changes the default automatically. Changing base lanes, maximum lanes, or aggregate worker budgets requires idle owners and zero waiters. Use `--workers` only for a justified aggregate budget. A maximum is a ceiling, not a promise of concurrent jobs.

Burst admission above the base requires a load-to-CPU ratio below `0.7` and sufficient memory. macOS requires normal memory pressure, reported as `1`. Linux requires at least 25% available memory and enough available memory for the estimated per-lane need. Missing telemetry refuses burst admission while preserving base admission behavior. Burst memory checks still apply with `--ignore-pressure`. Waiters with readable telemetry keep FIFO order; unreadable burst telemetry leaves that waiter base-only as described below. Running jobs are never interrupted to shrink occupancy.

Shims classify only the program for `node`, `bun`, `bunx` and `npx`: the first positional argument after the runtime's own flags. Its later arguments belong to that program, so `bun /path/ttr resources run -- bunx vitest` is `ttr`, not vitest. The `ttr` CLI is a `#!/usr/bin/env bun` launcher and starts through the bun shim whenever the shims are on PATH (for example from a `~/.zshenv` that adds them for every zsh, including `ssh host 'cmd'` and `zsh -c`). Shims never admit it: `ttr` performs its own admission, and a shim admitting it first would hold the only lane while `ttr run` queued behind its own parent. Inside an admitted job, nested shims (`bunx` → a `#!/usr/bin/env node` vitest entry → the node shim) pass through under the owner once ancestry is verified. `resources-shim-chain.test.ts` reproduces that chain with one lane.

The effective lane count is `max(1, min(maxValidationLanes, host lane ceiling))`, so base lanes above the host ceiling (for example a config copied from a larger machine) are capped as well, where the host lane ceiling is `max(1, min(16, floor(memory GiB / 4), CPUs - 2))` (6 on a 24 GiB / 10 CPU host). Worker totals no longer cap the lane count. Admission subtracts recorded running allocations from each budget. Once the aggregate budget is spent, each further pressure-gated burst lane receives exactly one worker, so the overcommit is bounded to one worker per burst lane. For multi-lane or adaptive configurations, the aggregate worker total is clamped with a warning to the host worker ceiling, `min(8, floor(memory GiB / 8), floor(CPUs / 2))` when that exceeds the legacy budget. Configured totals are never raised automatically.

Before replacing the installed scheduler, fully drain old brokers, shim processes, and FIFO waiters. An old scheduler encountering `slots/2` fails closed. Never rewrite tickets, remove live locks, or run mixed versions. Source tests/review do not authorize installation or activation, and this design does not change any installed scheduler. Reconcile every legacy `status.owner` consumer first. Status retains `owner`, `owners`, `laneCount`, `waiting`, and `limits`, and adds `baseLanes`, `maxLanes`, `effectiveLanes`, `occupied`, `burst: { eligible, reason }`, `ownerDetails` (PID, child PID, command, cwd, elapsed seconds, current CPU percent, cumulative CPU seconds, idle seconds), `waitingDetails` (command and wait time), and `warnings`. Brokers sample their owned process tree's cumulative CPU every 30 seconds into the slot's `activity.json`. Status warns when an owner has been idle at 0% CPU for more than 10 minutes. It never signals or kills owners. The compatibility `owner` stays populated whenever any owner exists; initializing occupancy is reported separately.

Admission publishes complete owner metadata exclusively and serializes pressure checks, FIFO selection, and atomic slot claims, re-caps the original arguments to the admitted policy, and rejects policy changes during pressure probing. A live legacy owner, surviving child group, or old waiter excludes all slots. Malformed/unknown state fails closed. Initialization has a 30-second grace followed by a state recheck; time never expires a live owner. An abandoned mutex removal marker requires operator recovery review. Cancellation removes only its own ticket/slot after its owned child group drains. Workload execution waits for a durable child-PID receipt.

Cross-machine offload goes through `ttr box`. `ttr resources run --offload auto -- <command>` offloads only when every effective local lane is occupied or local waiters exist; `--offload <runner-id>` always targets that runner and fails instead of falling back. Offload requires a `ttr login` session and a clean tree whose `HEAD` is contained in an `origin/*` remote-tracking branch (a commit only on a fork or other remote is refused). Only the SHA, the relative directory and the argv travel, inside a typed commit-run envelope; no local environment is sent. The runner fetches that exact commit into a temporary worktree and removes it afterwards. Logs stream while the run polls, paging forward by the per-run event sequence cursor so long runs are neither truncated nor refetched, and lines that commit late are never skipped, the remote exit code is propagated, and `--timeout` (default `30m`) or Ctrl-C (handled from before the run is created) requests a remote stop (exit `124` or `130`). Each create carries a fresh operation ID as `idempotencyKey`. If the acknowledgement is lost, the CLI stops the run by that key within a bounded retry, or prints the key when cancellation cannot be confirmed. Once a remote run exists, the command never falls back to a local run in either mode: if the control plane stays unreachable while following it, the CLI requests a remote stop and exits `1`. `--offload auto` queues locally only when no run was created: offload was unavailable, no runner was eligible, or the server rejected the run with a `4xx`. An ambiguous creation failure (network error or `5xx`) exits `1` instead, because the run may exist.

A runner is eligible only when its heartbeat is fresh (under 60 seconds by the server clock from the snapshot's `Date` header, never the local clock; a list `status` of `online` alone is not freshness), it is not draining, `run` is enabled, it holds no Judge or playground role, it attests `executionMode: trusted`, and it advertises `protocols.commitRun` containing the client's envelope version (`capability_missing` otherwise). Otherwise the diagnostic names a `blockedBy` reason: `local_saturated`, `no_eligible_runner`, `offline`, `stale_heartbeat`, `draining`, `capability_missing` or `trust_cap`. When no runner is eligible, the closest actionable blocker is reported first (`stale_heartbeat`, `offline`, `draining`, `capability_missing`), then `trust_cap`. Queue messages print `blockedBy=local_saturated` with an `--offload auto` hint. `ttr resources offload [--runner <id>] [--json]` shows local saturation, every runner's eligibility and the selected target. `ttr box runners --json` adds the same `trustedWork` verdict per runner. Root admins can use `ttr box feature --runner <id> --feature <name> --enable|--disable` and `ttr box drain --runner <id> [--undo]`. Regression coverage lives in `resources-box-offload.test.ts`, `resources-box-offload-safety.test.ts` and `devbox-fleet.test.ts`.

Elevated memory pressure holds new admission while existing jobs continue. Blocked waiters back off outside admission, remain cancellable, and probe pressure afresh before launch. This is cooperative scheduling; scripts can still fan out within a slot. Sequence lint, tests and browser QA when memory is limited.

For `turbo run` commands (`turbo`, `bun turbo:local`, `bunx turbo`, `bun x turbo`, `bun run turbo`), `run` and turbo shims add `--summarize=true` and print one line after the command exits, for example `turbo cache: 12/15 tasks cached (local 10, remote 2); 3 executed in 41s; saved ~4m10s`. The spawn hook snapshots `.turbo/runs/` after queueing. The report reads only a single new JSON file whose run ID matches its basename, and removes it only when this command requested it. Files present at spawn are always preserved. A user-supplied `--summarize` is reported but kept. Dry runs, `--graph`, other commands and runs without a Turbo root are untouched. Concurrent runs may share `.turbo/runs/`; their files are never selected by timestamps. If the command never spawned, or zero or multiple new JSON files exist, nothing is reported or removed. Child stdio stays inherited and completion follows process exit, so escaped background processes holding stdout cannot hold the lane. The report never changes the exit status. Regression coverage lives in `resources-turbo-summary.test.ts` and `resources-summary-lifecycle.test.ts`.

Shell setup preserves existing content and original backups through marked Zsh/Bash blocks. Open a new shell to activate hooks, or use `--shell none` for explicit queue usage. Absolute paths, custom PATH replacement and existing processes can bypass shims; wrap unrecognized scripts explicitly.

Out-of-range numeric configuration values (lanes `1`–`8`, workers and Turbo `1`–`64`, `maxValidationLanes` below the base) are clamped with a stderr warning that names the field and allowed range. Invalid JSON or wrongly typed fields produce an `Invalid resource configuration: <field> <expectation>` error that never discloses field values. Explicit `run` and `setup` fail on that error. `status` still prints its report with `config.state: invalid` and the error as a warning, then exits `1`; it also reports `disabled` admission and base lanes (or, failing that, `maxValidationLanes`) above the host lane ceiling as warnings. Shims print it and run the command without admission, so one bad value cannot brick every tool on the machine. `disable`/`enable` toggle future automatic admission. All configuration mutations, including uninstall, serialize with admission and read the latest policy inside the mutex. Disabled, out-of-scope and deliberate bypass commands retain their arguments/environment without admission-cap validation. `TTR_RESOURCES_BYPASS=1` is a deliberate one-command bypass. Once owners and waiters drain, `uninstall` removes owned hooks/shims and preserves shell content, configuration and backups. Keep the default `TTR_RESOURCES_HOME` across projects; private temporary homes are for lightweight synthetic tests, not parallel heavy work. Resource fixtures mock host capacity in Vitest parents and disposable Bun loaders/shims. Read exit diagnostics after subprocess pipes close; use a separate exit barrier when testing surviving descendants. Parent Vitest coverage is not evidence of coverage inside Bun subprocesses.

The bounded monitor emits JSONL memory-pressure, T3-tree resident-memory and top-process samples without arguments or environment values. RSS differs from Activity Monitor's footprint and can count shared pages multiple times.
Offload full validation with `ttr box run --runner <remote-id> -- <command>` only after verifying a different machine and intended checkout. Same-machine runners/containers consume local RAM; resource setup does not configure runners, transmit credentials, or restart Docker.

### Cross-project budget on a shared host

A shared host (for example skr-studio, shared by Tuturuuu and Upskii) can carry a `budget` block in `config.json`. It is a layer on the existing lane admission, not a second scheduler: tickets, owners, the resources home and the admission mutex are unchanged. The budget decides which waiter may claim the next lane, and how many worker tokens that job may fan out to.

```json theme={null}
"budget": {
  "lanes": 12, "tokens": 24, "memoryGiB": 320, "borrow": true,
  "projects": [
    { "id": "tuturuuu", "roots": ["/Users/thanh/Documents/GitHub/tuturuuu"], "lanes": 6, "tokens": 12, "memoryGiB": 160 },
    { "id": "upskii",   "roots": ["/Users/thanh/Documents/GitHub/upskii"],   "lanes": 6, "tokens": 12, "memoryGiB": 160 }
  ]
}
```

**Configuration rules**

* The ceiling is `lanes`/`tokens`/`memoryGiB`, with lanes up to 16.
* Shares must fit inside the ceiling, and `maxValidationLanes` may not exceed `budget.lanes`.
* An invalid budget makes the whole config invalid: explicit runs fail, and shims print the error and run unmanaged.
* A project is the longest matching root, checked for the working directory and for a linked worktree's main checkout (from `.git` → `gitdir` → `commondir`). So every Upskii worktree under `~/.t3/worktrees/upskii` counts against Upskii.
* Work outside every root is `other`: it has no share and only borrows idle capacity.

**Worker tokens**

* Each ticket declares tokens at enqueue. `run --tokens N` or `TTR_RESOURCES_TOKENS=N` set them explicitly; otherwise the classified tool decides:
  * `vitest` costs its `--maxWorkers` value, or `vitestWorkers`;
  * Playwright costs its numeric `--workers`/`-j` count, or at least 2 when omitted or expressed as a percentage; database suites (`supabase start|test|db reset`, `sb:*`) cost at least 2;
  * builds (`next build`, `cargo build|check|clippy`, Turbo or Bun `build` tasks) cost at least 4;
  * Turbo test and lint tasks, `tsc` and `eslint` cost at least 2;
  * anything else costs 1.
* Ambiguous runtime invocations cost at least `max(2, vitestWorkers)` rather than one token. `node --test` receives `--test-concurrency` matching its charged tokens; existing concurrency flags are replaced only in the Node option segment, preserving program arguments.
* Declared tokens are clamped to the ceiling.
* Admission then grants exactly that many workers (`VITEST_MAX_WORKERS`, `CARGO_BUILD_JOBS`, and rewritten `--maxWorkers`/`--jobs`/`--workers`). Turbo stays at one task per lane, so a job's internal fan-out is what it paid for.
* Playwright always receives an explicit numeric `--workers` cap. It overrides both CLI values and config defaults; percentage values fall back to the charged default rather than expanding with host CPU count.
* Memory is declared with `--memory-gib` / `TTR_RESOURCES_MEMORY_GIB`, and defaults to `tokens × memoryGiB / tokens` of the ceiling (about 13.3 GiB per token on Studio).

**Fairness, borrowing and reclaim**

* Each project keeps FIFO order, and only its oldest ticket competes.
* With `borrow: false`, demand and worker caps clamp to the project share as well as the host ceiling. A request outside configured project roots, or with no positive lane/token/memory share, fails before enqueueing with guidance to use a configured root or enable borrowing. It cannot block the FIFO forever.
* In-share heads reclaim capacity first, least-used share first. Ordinary borrowers yield to reclaim.
* A head that cannot fit even its empty project share gets age priority over younger in-share heads. If necessary, it reserves capacity and waits for running work to drain; younger small requests cannot refill that reservation. Older in-share heads retain reclaim priority. This includes unassigned `other` borrowers when borrowing is enabled.
* If a reclaiming head fits its project share but cannot yet fit the host, new admissions stop until enough capacity drains. Smaller borrowers cannot continually refill its reserved capacity.
* Running jobs, borrowers included, are never preempted.
* Nested commands inside an admitted job still run under its owner (verified ancestry), so reentrancy is unaffected.

Change budget ceilings and shares only while idle. Tickets that exceed a subsequently reduced host ceiling must be cancelled and requeued. Owners without explicit demand are charged the maximum of their recorded Vitest/build worker limits (at least one token), plus memory proportional to the host memory-per-token ratio. This is an estimate, not an RSS measurement.

**Status.** `ttr resources status --json` adds `budget`:

* `ceiling`, `used` and `borrow`;
* per project: `share`, `used`, `borrowing` (use above share) and `waiting`.

The text status prints the same per project. Regression coverage is in `resources-budget.test.ts` (fairness, borrowing, reclaim, token and memory caps, project identity for worktrees, and a sustained mixed-load simulation) and `resources-budget-admission.test.ts` (real processes).

Process identity recovery remains tracked in [#6561](https://github.com/tutur3u/platform/issues/6561). PID/PGID liveness alone can retain a stale lease after PID reuse. Fix #6561 before enabling budgets on long-uptime Studio hosts: a reused PID can retain a dead owner's reservation and stall every project. The budget fixes do not resolve that prerequisite.

#### Studio rollout: 0.28.0 single slot to the budget release

Run this only when Mastermind and Upskii have agreed a quiet window. The preparing agent does not change Studio's live config. Use the single [budget protocol rollout and rollback procedure](#budget-scheduler-rollout-and-rollback) below; install through the owning Bun global path, preserving existing roots and shell settings. A separate npm-prefix install is a different owner and cannot refresh the global launchers.

After upgrading every client and launcher, write the proposed config atomically while idle (temporary file plus rename, mode 0600), keeping its backup:

* preserve both projects' `roots` and `repositories`;
* `turboConcurrency: 1`, `vitestWorkers: 2`, `buildJobs: 4`;
* start at `validationLanes: 2`, with `maxValidationLanes: 12`;
* use the budget above: 12 lanes / 24 tokens / 320 GiB, with 6/12/160 shares and `borrow: true`.

Confirm each project's identity from a worktree with a trivial `~/.bun/bin/ttr resources run --tokens 1 -- true`, then inspect `resources status --json`. Decide how runner work is counted: explicit admission or the shim directory on its service PATH. Direct SSH work and other unmanaged fan-out are invisible to the budget; inspect them separately. Preserve the saved shell policy: `.zshenv` also runs in noninteractive zsh, so it must be neutralised during rollback before the fence is removed.

Ramp the base 2 → 4 → 6 → 8 → 10 → 12 only through idle, atomic config updates; `setup --lanes` and `--max-lanes` accept 1 to 16 (`maxResourceLanes`). Bursts above the base still require pressure and load eligibility. Before each step, measure at least 15 minutes of normal load: normal memory pressure, one-minute load below 0.7 × CPU count, at least 30% idle CPU, budget use below its ceiling, and no regression in a fixed probe suite. Count unmanaged runner/SSH fan-out as well. More lanes are a ceiling, not a reason to start heavy work. For any downgrade, follow the canonical rollback below rather than removing the marker first.

### Burst telemetry and minimal PATH

Resource admission and status probes use trusted absolute system executables:
`/usr/sbin/sysctl` with `/sbin/sysctl` fallback, and `/bin/ps` with `/usr/bin/ps`
fallback. Probes have bounded time/output and a clean locale-only environment;
they do not resolve caller PATH binaries or inherit loader variables. Linux
pressure remains an absolute `/proc/meminfo` read. A minimal PATH can therefore
use macOS burst admission without adding `/usr/sbin`.

Unreadable load or pressure telemetry makes that ticket base-only for its
remaining wait. It retains its original owner, queue age and place for base
capacity. When only burst capacity is available, selection skips only these
base-only tickets and applies existing FIFO or project-budget ordering to the
remaining waiters. A real high-load or elevated-pressure reading still holds
the queue under the existing policy. No telemetry error grants a burst lane.
Cancellation, liveness, admission mutex and worker-cap checks are unchanged.

Regression coverage: `resources-adaptive.test.ts` reproduces the minimal-PATH
failure, retains the full-PATH control and high-load FIFO test, and exercises
an unreadable head followed by a healthy burst waiter. macOS cases execute the
real probe with deterministic pressure output and fixed host capacity/load;
Linux CI skips those OS-specific cases. `resources-system-probes.test.ts`
checks trusted paths, fallback, clean environment and bounded failure.

Mastermind applied Studio's lane change on 2026-10-25: one pool A at 6 base/8
max, physical ceiling 16; pool B was not created. Linux now has 3 lanes. This
records the operator change and does not request another drain-window raise.
The private Studio runbook is `/Users/thanh/Documents/STUDIO_LANES.md`. Read
current status for worker caps; a declared total is not proof of effective
admission caps. Future policy changes remain operator-owned and require an
idle queue, preserved roots/settings and capacity evidence.

### Multi-host weighted admission

`ttr resources run --hosts -- COMMAND` admits a job across the hosts in `<resources home>/hosts.json`. Without that file, `--hosts` refuses to run and admission stays the single-host lane FIFO. The CLI never writes or activates `hosts.json`; an operator installs it after a reviewed release. The registry decides where code runs, so it is trusted only from the canonical per-user home `~/.tuturuuu/resources`. That directory must be a real 0700 directory owned by you, `hosts.json` a real 0600 file owned by you, and every parent a non-symlink directory writable only by root or you (a root-owned sticky directory such as `/tmp` is allowed). The file is opened with `O_NOFOLLOW` and re-verified through the descriptor. A home inside an opted-in repository root (`roots`, or a `repositories` checkout) is refused too, as is an invalid `config.json`. When `TTR_RESOURCES_HOME` points anywhere else, or any check fails, the registry is ignored and `--hosts` is disabled (`resources-hosts-trust.test.ts`). `ttr resources hosts [--json]` shows each host's budget, reservations and waiters (or the proposed registry when none is installed). `ttr resources hosts --simulate [--json]` is an offline dry run of the measured queue through the same planner.

* **Classes and weights.** Explicit `--hosts` jobs are `heavy` unless `--class light` is given; trivial commands never queue. Local light work also passes the dequeue disk gate, and the CLI tells a nested `run --hosts` which reservation it runs under through `TTR_RESOURCES_HOST_RESERVATION`. That nested job then runs under the ancestor's reservation, but only while that reservation is live and its broker or owned child group is a verified process ancestor; otherwise it would deadlock behind its own ancestor. No registered host that could ever hold the job (counting `remoteOk`) means it fails fast instead of queueing. Each host has separate `slots.light` and `slots.heavy`, per-class CPU/memory `weights`, and per-class worker caps (`workers`). A job is admitted only if its class slot is free and the weighted sum fits `capacity - reserved`.
* **Reserved headroom.** `reserved.cpus`, `reserved.memoryGiB` and `reserved.diskGiB` are per host, for co-tenants such as production containers, CI runners, Judge workers and the desktop.
* **Hosts.** The single `local` host uses the lane FIFO for heavy work. Lane owners count as local heavy load, a heavy `--hosts` job takes a local lane only while no lane waiter is ahead, and light local work holds a ledger reservation. `runner` hosts dispatch the exact pushed commit through the devbox offload transport (`runBoxOffload`, unchanged). Immediately before remote creation the runner is re-validated against a fresh snapshot that carries the server's timestamp. If it is stale, draining or missing, its disk is unknown or low, or the snapshot has no server time, the reservation is released and the job requeues without dispatching. Admission also refuses runners in snapshots without a server timestamp, and runners without activity telemetry (other clients' runs would be invisible). The commit plan is recomputed at dispatch; if it changed, the job falls back to local hosts. SIGHUP is forwarded to the offload transport's cancellation as SIGTERM, so a closed terminal also stops the remote run. Runs that other clients start on that runner count as heavy load. A runner that refuses creation means no remote run exists, so the job is requeued for local hosts; an ambiguous failure is never repeated locally.
* **Admission.** Admission requires a fresh trusted runner (`evaluateTrustedRunner` plus `telemetryTtlSeconds`) and known free disk at or above `reserved.diskGiB`. Unreachable fleets, stale heartbeats, draining runners and unknown disk are never admitted. Dirty or unpushed trees are local-only.
* **Canonical reservations.** Tickets and reservations live in `<home>/hosts-state/` and are created only inside the host-wide admission mutex. Concurrent requesters on this machine therefore cannot double-assign a slot. Each reservation is tied to its broker PID (or owned child group). Cancellation (SIGINT/SIGTERM/SIGHUP) releases it, and a dead owner is pruned on the next round. A malformed entry closes admission. Only `scope: "host"` reservations claim capacity: a project-only lock never stands in for host-wide admission.
* **Preference.** An optional per-host `preference` rank in `hosts.json` (lower first) orders hosts that already passed every eligibility and capacity check; the capacity score breaks ties, and unranked hosts follow ranked ones. It is an ordering hint only: a preferred host that is stale, draining, degraded, low on or unknown disk, missing telemetry, or full is skipped, never forced, and preference never lets a dirty tree run remotely. Runners are degraded when their 1-minute load per CPU (agent telemetry `resources.loadAverage` / `resources.cpu.cores`) reaches `maxLoadPerCpu` (default 1); missing load telemetry fails closed, and the pre-dispatch revalidation re-checks it. The operator's order is skr-studio > skr-sonha > skr-linux-lan > M4; `ttr resources hosts --simulate` prints it with a scenario for today's health (skr-studio offline, skr-sonha degraded at load 27 to 32, both skipped) and one with every host healthy. skr-studio and skr-sonha capacities there are illustrative until Mastermind registers them (`resources-hosts-preference.test.ts`).
* **Fairness.** Waiters are ordered by their project's live share, then age. A project is the repository's common Git directory, so all Upskii worktrees share one identity. A waiter overtaken `fairness.maxBypass` times (default 4) holds every host that could ever fit it until it is placed. This backpressure is what prevents starvation.
* **Disk at dequeue (REV-6480-1/2).** Every lane-queued job re-checks free disk inside admission, immediately before claim and spawn, using a local `statfs` probe (`resources-disk-gate.ts`).
  * It uses Lane ST's thresholds: `TTR_STORAGE_MIN_FREE` (default 15 GiB) and `TTR_STORAGE_MIN_FREE_PERCENT` (default 5%).
  * Below the floor, or when free disk is unknown, the job keeps waiting (fail closed).
  * Block reasons name only the job volume, the free/floor figures and an errno code, never the working path or raw filesystem errors, and status labels them `blockedBy=disk`.
  * The probe runs before taking the admission mutex, only for the FIFO head. It is bounded (2 s) and never stacked on a pending probe, so a hung volume counts as unknown and stalls no other admission.
  * `TTR_RESOURCES_IGNORE_DISK=1` overrides it for one command.
  * Once Lane ST's `storage-headroom` lands, the probe can delegate to it without changing this hook.

Limits from the 2026-10-23 measurements, old to new (`proposedHostRegistry()`, not activated):

| Host | Measured | Old | New |
| - | - | - | - |
| M4 (local) | 10 CPU, 24 GiB, 20 GiB of 460 GiB disk free (4.3%); load average 9 to 12; memory pressure normal; swap 0.6 GiB; disk IO idle. 2 Upskii owners and 5 to 9 waiters. | `validationLanes` 2 for every class (light work waits behind heavy), `vitestWorkers` 2, `buildJobs` 2, Turbo 1. No disk check at dequeue. | Heavy 2 (unchanged; still the lane ceiling) at 2 CPU / 5 GiB, 2 workers each. Light 0 to 1 at 1 CPU / 1 GiB, 1 worker. Reserved 4 CPU / 8 GiB / 15 GiB disk, leaving a 6 CPU / 16 GiB budget. Disk re-checked at dequeue. |
| skr-linux-lan (runner) | 20 CPU, 31 GiB (about 23 GiB available), 398 GiB free; load average 2.5 to 9; IO PSI full 14 to 23%, iowait 12 to 17%; 8 GiB swap used. Live PKTM production, 4 Upskii runners, 4 Judge workers. No trusted-development runner is registered. | Not admitted by `ttr resources`. The early-merge validation script uses 2 heavy `flock` slots at nice 10. | Heavy 0 to 2 at 5 CPU / 6 GiB, 5 workers each (matches the existing two validation slots; IO-bound, so not raised). Light 0 to 2 at 1 CPU / 1 GiB. Reserved 8 CPU / 12 GiB / 50 GiB disk, leaving a 12 CPU / 19 GiB budget. |
| Sonha | IO degraded | Not capacity | Not registered (0/0) |
| ThanhStudio | Offline | Not capacity | Not registered (0/0) |

Only Linux gains slots. The M4 keeps its heavy ceiling and gains one light slot, because its CPU and disk are already the binding constraints. For the measured queue, the dry run cuts the makespan from 43 to 20 minutes and the maximum wait from 33 to 10 minutes, with every host within its ceiling. Raise Linux heavy slots only after IO PSI `full avg60` stays below 10%.

Before activation:

* register a trusted-development runner on skr-linux-lan that publishes `capabilities.disk.freeGiB`, because unknown runner disk fails closed;
* reclaim disk on the M4, or set the floor deliberately: at 4.3% free, the 5% floor holds heavy lane jobs.

Regression coverage:

* `resources-hosts-plan.test.ts`: ceilings, stale or unknown hosts, fairness and starvation, and project-only locks;
* `resources-hosts-ledger.test.ts`: concurrent no-double-assignment, process death, cancellation, overlap and stale-runner dispatch;
* `resources-disk-gate.test.ts`;
* `resources-hosts-sim.test.ts`.

#### Capability placement and the M4 hub

Multi-host admission is implemented but requires operator activation: a trusted
registry, eligible registered devbox runners, a pushed clean commit and fresh
telemetry. SSH reachability alone does not register a runner or admit work.
The historical simulation above is an offline example, not live fleet capacity.

Set `hubHostname` in `hosts.json` to the M4's exact OS hostname. Registries with
runner entries refuse dispatch when that field is absent or differs from the
current machine, before creating a ticket or contacting a runner. Submit fleet
jobs on the M4; remote hosts use their own canonical `ttr resources run` queue.
The transport remains the keyed devbox API; it does not SSH between hosts or
copy local credentials/environment values.

`hubHostname` controls dispatch origin only. It does not prohibit local heavy
work or inspect commands for builds. The M4 build prohibition remains an
operator/caller policy; a heavy class also includes permitted focused tests.
Configure local slots/capabilities for the intended placement policy and submit
builds only to remote hosts. Do not treat a matching hub hostname as permission
to build on the M4.

Each host can declare `platform: "darwin" | "linux"` and a `capabilities` array
containing `ios`, `macos`, `flutter`, `web`, `rust` and/or `docker`. Declared
platform must match local OS or fresh runner `capabilities.os.platform` telemetry;
unknown/mismatched platform blocks placement and is rechecked before dispatch.
Tool capabilities are operator attestations: verify installed tools, daemon
access and runtime acceptance before advertising them. Missing capability tags
cannot satisfy a job's requirements. Older untagged registries still admit
generic jobs, but cannot admit jobs requiring a capability.

```sh theme={null}
ttr resources run --hosts --requires ios -- flutter build ios --no-codesign
ttr resources run --hosts --requires web -- bun run test
ttr resources run --hosts --requires docker --requires rust -- sh verify.sh
```

`--requires` is repeatable and augments direct-tool inference. Xcode tools,
CocoaPods and codesign require `macos`; Flutter requires `flutter` and adds `ios`
for iOS/IPA targets or `macos` for macOS targets; Cargo/Rust tools require `rust`;
Docker requires `docker`. Shell/package scripts and arbitrary executables must
declare their requirements explicitly. Both Apple tags also require a declared
Darwin host. Configure placement as follows, preserving measured weighted slots,
worker caps and headroom:

Nested `--hosts` calls validate explicit and inferred requirements against the
actual local host before reusing either a heavy-lane ancestor or a light host
reservation. Incompatible nesting errors before spawning or adding another
ticket; compatible nesting keeps the existing reservation and limits. A nested
call cannot migrate its already-running wrapper to a different host.
Requirement parsing and applicable local compatibility checks also run before
the trusted trivial-command shortcut. Unknown requirements fail closed even
for `/usr/bin/true`; compatible trivial tools remain admission-free. Explicit
`TTR_RESOURCES_BYPASS=1` retains its deliberate raw local-execution behavior.

Set lower `preference` on Linux than Studio for portable work; capability checks
still send Apple jobs only to Studio. Do not register held hosts. Studio has
one pool A; the proposed pool B was not created. Do not add a second host entry to count the same machine twice. Mastermind must reconcile all
resource homes and external CI consumers before declaring available slots.

An incompatible starving waiter holds only hosts it could use, leaving Linux
available behind an iOS waiter. Existing repository-share ordering, bounded
bypass and local lane FIFO remain in force. Repeated enqueue preserves the
original ticket owner, requirements, age and bypass count; a reserved token
cannot be enqueued or admitted twice. Requeues retain age/bypass, and the ticket
UUID is the remote create's idempotency key. An unacknowledged write never
triggers another placement or a local retry; reconcile the original operation
through `ttr box list` before deciding what happened.

Regression coverage: `resources-hosts-nesting.test.ts`, `resources-hosts-requirements.test.ts`,
`resources-hosts-dispatch.test.ts` and `resources-hosts-ledger.test.ts` cover
capability/OS placement, hub refusal before writes, ordering, duplicate tickets,
stable operation identity and unknown-outcome refusal.

#### Studio operator lane update

Mastermind applied the 2026-10-25 lane change: Studio now has one pool A at
6 base/8 max lanes, and Linux has 3 lanes. Pool B was not created. The physical
Studio ceiling remains 16. No further lane raise is proposed by this change;
configuration and activation remain Mastermind's custody. The Studio source of
operational detail is `/Users/thanh/Documents/STUDIO_LANES.md`; re-read current
status before using declared worker totals as capacity evidence.

Future changes require a full idle drain (zero owners, waiters, reservations
and queued remote runs), saved config/registry/launcher bytes, the same roots
and shell settings, a compatible pinned CLI and a reviewed `setup --dry-run`.
Let existing work finish in order; never kill/reorder waiters or create another
queue. Apply only as the operator, monitor CPU/memory/disk/I/O and effective
worker caps, and roll back saved settings only after another idle drain.

Operator-owned remaining evidence: reviewed registry installation, actual
runner registration and runtime capability acceptance. Source tests and offline
simulation do not activate multi-host admission or prove remote execution.

### Docker metadata lifecycle diagnostic

The SDK metadata subprocess is silent by default. Disposable CI can opt in with
`CI=true` and `TTR_DOCKER_METADATA_DIAGNOSTIC=1`. Each invocation emits one JSON
record (`schema: ttr-docker-metadata-v1`) at its existing settlement boundary.
It records a process-local ordinal, Node/Bun runtime versions, monotonic elapsed
milliseconds, spawn/first stdout/error/exit/close times, first and total stdout
byte counts, deadline time and callback lateness, kill return value, fixed spawn
classification, numeric exit code and an allowlisted signal. Numeric counters
saturate at 2,147,483,647; versions are validated and bounded; records stay below
1024 bytes. No arguments, paths, environment values, Docker host/context, metadata,
output or exception text are included.

A null event time means it was not observed before settlement. In particular,
settlement still follows error or exit and never waits for close. The stdout
consumer continues draining with the existing 65,536-character retained cap;
diagnostics add no timers, subprocesses, probes or retries. The 4000ms deadline
and fail-closed capacity behavior remain unchanged. Focused pure mocks in
`devbox-docker-metadata-diagnostic.test.ts` cover opt-in gating, bounded fields,
event order, deadline/kill outcomes, errors, close timing, overflow and redaction.

### Private staff feedback

`ttr feedback list|show` uses the authenticated, host-scoped Web staff API; it
never resolves a selected workspace or grants access from a local email claim.
The service rechecks current exact-domain activated staff and the canonical
registry for every list/detail operation. The default-off staff feature flag
must be enabled by the release owner before live use.

List returns one bounded metadata page and an explicit filter-bound next cursor.
`show <uuid>` omits the private body unless `--include-content` is present.
Status, archive timestamp and revision are read only. With `--json`, success
goes to stdout; sanitized failures are one JSON object on stderr with
`error.code`, `error.status` and a fixed `error.message`, and the CLI exits 1.
Provider diagnostics, credentials and URLs are never forwarded.

The CLI-to-staff-service composition fixture covers pagination, detail/content
opt-in, status filters and denied current identities/registry reads through the
real PostgREST serializer. These synthetic boundaries do not qualify a hosted
Auth or database deployment.

Node config-file options (`--experimental-config-file` and `--experimental-default-config-file`, including attached values) can activate the native test runner. Resource admission treats them as ambiguous and injects `--test-concurrency` before program arguments. A positive explicit lower concurrency remains lower; zero (Node auto) is bounded by the configured worker cap. Regression: `resources-node-config.test.ts` includes real Node config-selected five-file runs.

### Budget scheduler rollout and rollback

The budget-capable setup preflight runs before `--force`: force applies only to managed launchers already carrying protocol 3. A foreign legacy launcher is refused even with `--force --dry-run`. For that incident, an operator must stop all work, take exclusive custody, verify zero owners and waiters, and preserve the config and launcher bytes. Move only the identified foreign managed launcher files to an operator-owned backup outside `bin`; preserve unmanaged files and any existing budget marker. Then use the verified owning global CLI to run setup with the saved roots and shell settings. Verify every launcher and global version before resuming. Do not use a stale workspace CLI for recovery.

Protocol 3 permanently fences legacy clients on the first normal admission, even when no project budget is configured. The frozen 0.28.0 error `Unknown resource slot; admission is closed.` means upgrade the global CLI and refresh its shims; it is not permission to delete a live marker. At 12 lanes, 0.28.0 already fails closed independently of this marker.

Before rollout, fix [PID start identity #6561](https://github.com/tutur3u/platform/issues/6561) before enabling budgets on long-uptime Studio hosts: PID reuse can retain a dead reservation and stall every project. Source review and a package build do not publish or activate the new scheduler.

1. Pause admissions across every project and runner sharing the home. Drain all owners and queued tickets. Save the config, roots, shell settings, worker/lane limits and the exact legacy supplier version for rollback. Take exclusive operator custody before changing installations.
2. Publish the qualified budget-capable release through the maintained SDK workflows. Upgrade **every** owning global install with `~/.bun/bin/bun add -g tuturuuu@<published-budget-version>`. Inventory interactive shells, runner services, PATH aliases, caches and other hosts; do not admit new work yet. Remove only confirmed stale workspace aliases using the incident procedure.
3. Use each upgraded owning global CLI to refresh launchers with the **existing roots and shell settings**: `~/.bun/bin/ttr resources setup --root <existing-root-1> --root <existing-root-2> --shell <existing-shell>`. Setup does not publish the fence. It requires an idle queue when refreshing legacy launchers and refuses a foreign installation; a verified same-global release upgrade is permitted. Do not install this release into a separate npm-prefix path for setup.
4. Verify every global version and launcher target. New launchers carry `# Resource scheduler protocol: 3`. The preflight checks known launcher files in this local resource home only. It does **not** inventory global installations, PATH aliases, cached binaries, running processes or other hosts; operator inventory is required even if the preflight passes.
5. Configure budgets atomically while idle, then resume admissions. The first new-version admission fsyncs its staging file, atomically links `slots/budget-v3`, and prints upgrade/rollback guidance once. Later admissions reuse the marker and sweep stale staging files. Removing the budget config does not remove this persistent fence.

For rollback, perform these steps under exclusive operator custody:

1. Stop every runner pickup, shell and explicit `run` that could start new work. With the **new** CLI, run `resources disable`, then verify zero owners, occupied slots and waiting tickets. Disabling alone is insufficient: it would let shims run unmanaged, so all work must remain stopped.
2. While the fence still exists, use the **new** CLI's `resources uninstall` to remove managed launchers and shell hooks, including `.zshenv` activation. Verify the shim files and managed shell blocks are gone, preserving unrelated shell content. Complete all new-version mutations now; even disable/uninstall can enter the admission lock and publish the fence.
3. Restore the saved config with admission disabled, no budget and at most two base/burst lanes, preserving roots. Downgrade **every** global install with `~/.bun/bin/bun add -g tuturuuu@<saved-legacy-version>` while work remains stopped. Verify the selected legacy binary version without invoking new-version resource commands.
4. Inspect high-numbered slot directories and remove only empty ones with `rmdir`. Never delete owners or tickets to manufacture idleness. Remove **only** `<resource-home>/slots/budget-v3` with `rm -- <resource-home>/slots/budget-v3`; do not delete the slots tree.
5. Use the selected legacy owning CLI's `resources setup` with the saved roots, shell and worker/lane settings. Verify a controlled legacy admission and a fresh noninteractive shell invocation succeed without recreating the marker, then resume work. No new-version admission or mutation may occur after marker removal: it would republish the fence.

Private rollback evidence exercises disable, uninstall, shell-hook removal, legacy-compatible config restore, empty-slot removal, marker removal and restored direct/shell admissions using the real published 0.28.0 supplier. It simulates supplier selection in a disposable home; it does not perform or authorise a shared global upgrade or downgrade.

Regression coverage: `resources-budget-publish.test.ts` proves fsync-before-link, one-time warning, fast reuse and stale-stage cleanup. `resources-budget-upgrade.test.ts` kills a publisher with an empty stage and verifies recovery. `resources-budget-rollout.test.ts` covers legacy preflight, installation-only setup, same-global versus consumer identity and idle upgrade. Native worker charging/caps retain positive lower `--test-concurrency`, while zero/auto uses the configured cap (`resources-node-budget.test.ts`).

Cross-process resource fixtures prepare shims once per home before concurrent run launches. Their barriers name the relevant child, operation or detached group, allow a one-second settle window for final writes, and report scoped stderr before the Vitest deadline. Fixed synthetic CPU/memory/load telemetry keeps policy fixtures independent of host contention. The existing 45-second cross-process test budget also covers standalone config cases; idle-warning status composition uses one injected CPU table and asserts warning data, rendered text and the absence of a warning for a busy table. Waiting for a preliminary zero sample cannot stabilise a later ps read, so status must not resample an injected table. A fixture home's CPU/memory budget is immutable after its first shim is written; changed budgets use a fresh home.

Repository operational scripts, including `bun ttr` and `check:changed`, invoke `~/.bun/bin/ttr` directly so package-manager PATH changes cannot select stale workspace SDK dist. `resources run` and `shim` never install launchers. Setup refuses launchers from another CLI installation. For managed protocol-3 launchers, preview an intentional switch with `setup --force --dry-run`, drain all jobs, and explicitly apply `setup --force`; foreign legacy launchers require the operator-controlled recovery above. Same-install Bun global version upgrades remain supported. Source CLI experiments require a disposable resources home. Regression coverage: `scripts/trusted-ttr.test.js` and `resources-provisioning.test.ts`.

### Launcher mismatch incident recovery

Symptom: the global CLI rejects missing, stale or malformed launchers. A stale workspace SDK dist can write its own entry into shared launchers before admission, and its nested run can block the queue. Never run operational commands through workspace or ancestor `node_modules/.bin/ttr` or stale `packages/sdk/dist`.

Repository admission uses the verified global `~/.bun/bin/ttr` (stable >= 0.28.0). `check:changed` and `node scripts/ttr-run.js -- COMMAND` run directly when the inherited `TTR_RESOURCES_ADMITTED` or `TTR_RESOURCE_OWNER` marker is present. When the global install is absent, `check:changed` warns and runs sequentially with its existing worker limits. The operational wrappers still require a global CLI, and an invalid/old installed global fails with `bun add -g tuturuuu` recovery guidance. None falls back to a workspace binary. Refresh declared workspace bin links after adopting the source wrapper. `bun install` alone can leave orphan aliases unchanged; use the explicit orphan inspection/removal procedure below. This does not rebuild dist. The shipped bin works in installed packages; workspace aliases refuse to execute dist, including from `bunx`.

An operator with installation authority must identify and drain the offending jobs, preserve the existing resource configuration, then restore canonical launchers through the trusted global CLI with the **same existing roots and shell settings**:

```sh theme={null}
~/.bun/bin/ttr resources setup --root <existing-root-1> --root <existing-root-2> --shell <existing-shell>
~/.bun/bin/ttr resources status --json
```

Fence-enabled CLI versions refuse a different installation by default. For managed protocol-3 launchers, inspect `setup --force --dry-run` before an intentional cross-install restore, then use `setup --force` with the same roots after the queue drains. Foreign legacy launchers require the operator-controlled recovery in the budget rollout section; force does not bypass that preflight. The plan reports each old/new launcher. Force never overwrites unmanaged files. Version changes within one Bun global installation are allowed; versioned cache paths normalise to its stable global link. Run/shim never write launchers. Review status for enabled installation and an empty queue before resuming work. Source changes do not repair already-installed links or prove historical writer attribution.

Regression coverage: `scripts/trusted-ttr.test.js`, `scripts/workspace-ttr-bin.test.js`, and `resources-provisioning.test.ts` exercise ancestor lookup, inherited admission, minimum version, stale bins, same-install upgrades, refusal and forced replacement with disposable homes.

#### Orphan workspace aliases

A refusal can also mean stale workspace bin links in an ancestor checkout that still has a legitimate SDK dependency. Inspect that ancestor's package.json and links first. For a declared dependency, run `~/.bun/bin/ttr resources run -- bun install --force` there to regenerate aliases pointing to `bin/ttr.cjs`; retain its legitimate package link. `--no-ttr` does not bypass unsafe ancestor links. The removal procedure below applies only to confirmed undeclared orphan symlinks.

If the root manifest has no `tuturuuu` dependency, old symlinks can remain: `node_modules/tuturuuu -> ../packages/sdk` and `node_modules/.bin/{ttr,tuturuuu,tutur3u} -> ../tuturuuu/dist/cli/index.js`. Bun may report no changes and keep them. The trusted repo wrapper and `check:changed` refuse such ancestor aliases, even inside an admitted lane; they never execute or remove them silently. A healthy global CLI does not make those bare aliases safe.

From the affected ancestor checkout, inspect the manifest and every link first. Only after confirming these are the orphan symlinks above, remove those links explicitly and reinstall under admission:

```sh theme={null}
ls -l node_modules/tuturuuu node_modules/.bin/ttr node_modules/.bin/tuturuuu node_modules/.bin/tutur3u
# Confirm the root has no tuturuuu dependency and each path is a symlink.
for alias in ttr tuturuuu tutur3u; do
  file="node_modules/.bin/$alias"
  if [ -L "$file" ] && [ "$(readlink "$file")" = '../tuturuuu/dist/cli/index.js' ]; then
    rm -- "$file"
  fi
done
if [ -L node_modules/tuturuuu ] && [ "$(readlink node_modules/tuturuuu)" = '../packages/sdk' ]; then
  rm -- node_modules/tuturuuu
fi
~/.bun/bin/ttr resources run -- bun install
```

Do not remove `packages/sdk` or its dist. A declared dependency can recreate aliases pointing to the new `bin/ttr.cjs` wrapper; an undeclared orphan can remain absent. Inspect the resulting links before resuming. Native temp-directory and symlinked-home tests use physical paths, so macOS `/var/folders` aliases do not change installation identity. Resolve HOME and the Bun install base independently: a symlinked `.bun` or `.bun/install` is supported, while entries outside that resolved install base are still refused.

# @tuturuuu/supabase
Source: https://docs.tuturuuu.com/reference/packages/supabase

Supabase client creation patterns and utilities

# @tuturuuu/supabase

The `@tuturuuu/supabase` package provides type-safe Supabase client utilities for the Tuturuuu platform with different privilege levels and execution contexts.

## Installation

```bash theme={null}
# Already included in monorepo workspace
import { createClient, createAdminClient } from '@tuturuuu/supabase/next/server';
```

## Client Types

### `createClient()` - User-Scoped Client

**Use Case:** Standard operations respecting Row-Level Security (RLS) policies.

**Context:** Server Components, Server Actions, API Routes

**Privilege Level:** Current authenticated user

```typescript theme={null}
import { createClient } from '@tuturuuu/supabase/next/server';

export default async function TaskPage() {
  const supabase = await createClient();

// Queries respect RLS policies
  const { data: tasks } = await supabase
    .from('workspace_tasks')
    .select('*')
    .eq('ws_id', 'workspace-id');

// User can only see tasks they have permission to view
  return <div>{tasks?.length} tasks</div>;
}
```

**Important:**

* ✅ Respects RLS policies
* ✅ Safe for user-initiated operations
* ❌ Cannot bypass workspace isolation
* ❌ Cannot perform privileged operations

### `createAdminClient()` - Service Role Client

**Use Case:** Privileged operations bypassing RLS (admin tasks, system operations).

**Context:** Server-side only (never expose to client)

**Privilege Level:** Service role (bypasses RLS)

```typescript theme={null}
import { createAdminClient } from '@tuturuuu/supabase/next/server';

export async function createWorkspace(name: string, ownerId: string) {
  const sbAdmin = await createAdminClient();

// Bypasses RLS - can insert into any workspace
  const { data: workspace } = await sbAdmin
    .from('workspaces')
    .insert({ name })
    .select()
    .single();

// Add owner as member
  await sbAdmin
    .from('workspace_members')
    .insert({
      ws_id: workspace.id,
      user_id: ownerId,
      role: 'owner',
    });

return workspace;
}
```

**⚠️ Critical Security Warning:**

* ✅ Only use server-side
* ✅ Only for privileged operations
* ❌ NEVER expose to client
* ❌ NEVER use for user-initiated queries (always prefer `createClient()`)

> **Return type note:** `createAdminClient()` has the signature
> `({ noCookie }?: { noCookie?: boolean }) => SupabaseClient | Promise<SupabaseClient>`.
> The default call (`createAdminClient()` with `noCookie: false`) resolves cookies
> via `next/headers`, so it returns a `Promise` — `await` it as shown above. The
> `createAdminClient({ noCookie: true })` variant returns a client synchronously.
> Awaiting either form is safe (`await` on a non-Promise is a no-op), so prefer
> `await createAdminClient()` everywhere for consistency.

### `createDynamicClient()` - Middleware Client

**Use Case:** Middleware and edge runtime contexts.

**Context:** Next.js middleware, edge functions

```typescript theme={null}
import { createDynamicClient } from '@tuturuuu/supabase/next/server';
import { NextRequest } from 'next/server';

export async function proxy(request: NextRequest) {
  const supabase = await createDynamicClient();

const { data: { user } } = await supabase.auth.getUser();

if (!user) {
    return Response.redirect('/login');
  }
}
```

## Common Patterns

### Authentication

#### Revalidated Session User

Use `resolveAuthenticatedSessionUser()` from
`@tuturuuu/supabase/next/auth-session-user` when shared server code needs the
current Supabase session user. The helper may probe `auth.getClaims()` for
compatibility or timing context, but it must revalidate the session with
`auth.getUser()` before returning a user.

Treat JWT claims as verified token contents, not current account state. Do not
authorize privileged routes, staff-only checks, or `createAdminClient()` flows
from claim-derived `email`, `role`, or metadata alone. For those paths, make the
authorization decision from the Auth-server user returned by `getUser()` so
revoked, deleted, or offboarded sessions are rejected before any service-role
operation runs.

#### Get Current User

```typescript theme={null}
import { createClient } from '@tuturuuu/supabase/next/server';

export async function getCurrentUser() {
  const supabase = await createClient();
  const { data: { user }, error } = await supabase.auth.getUser();

if (error || !user) {
    return null;
  }

return user;
}
```

#### Server Action with Auth Check

```typescript theme={null}
'use server';

import { createClient } from '@tuturuuu/supabase/next/server';

export async function createTask(formData: FormData) {
  const supabase = await createClient();

// Check authentication
  const { data: { user } } = await supabase.auth.getUser();
  if (!user) {
    throw new Error('Unauthorized');
  }

// Perform operation (RLS policies apply)
  const { data, error } = await supabase
    .from('workspace_tasks')
    .insert({
      name: formData.get('name') as string,
      ws_id: formData.get('wsId') as string,
      created_by: user.id,
    })
    .select()
    .single();

if (error) throw error;
  return data;
}
```

### Workspace Operations

#### Get User's Workspaces

```typescript theme={null}
import { createClient } from '@tuturuuu/supabase/next/server';

export async function getUserWorkspaces(userId: string) {
  const supabase = await createClient();

const { data: memberships } = await supabase
    .from('workspace_members')
    .select(`
      ws_id,
      role,
      pending,
      workspaces (
        id,
        name,
        logo_url
      )
    `)
    .eq('user_id', userId)
    .eq('pending', false);

return memberships?.map((m) => m.workspaces) || [];
}
```

#### Check Workspace Permission

```typescript theme={null}
import { createClient } from '@tuturuuu/supabase/next/server';
import type { Database } from '@tuturuuu/types';

type Permission = Database['public']['Enums']['workspace_role_permission'];

export async function hasPermission(
  userId: string,
  wsId: string,
  permission: Permission
): Promise<boolean> {
  const supabase = await createClient();

const { data } = await supabase
    .from('workspace_members')
    .select(`
      role,
      workspace_role_permissions!inner (
        permission
      )
    `)
    .eq('user_id', userId)
    .eq('ws_id', wsId)
    .eq('workspace_role_permissions.permission', permission)
    .limit(1);

return (data?.length || 0) > 0;
}
```

### Data Fetching

#### Paginated Query

```typescript theme={null}
import { createClient } from '@tuturuuu/supabase/next/server';

export async function getTasks(wsId: string, page = 0, pageSize = 20) {
  const supabase = await createClient();

const from = page * pageSize;
  const to = from + pageSize - 1;

const { data: tasks, error, count } = await supabase
    .from('workspace_tasks')
    .select('*', { count: 'exact' })
    .eq('ws_id', wsId)
    .order('created_at', { ascending: false })
    .range(from, to);

if (error) throw error;

return {
    tasks,
    totalCount: count,
    currentPage: page,
    totalPages: Math.ceil((count || 0) / pageSize),
  };
}
```

#### Filtered Query with Relations

```typescript theme={null}
import { createClient } from '@tuturuuu/supabase/next/server';

export async function getTasksWithAssignees(wsId: string, completed?: boolean) {
  const supabase = await createClient();

let query = supabase
    .from('workspace_tasks')
    .select(`
      *,
      task_assignees (
        workspace_users (
          id,
          display_name,
          avatar_url
        )
      ),
      task_lists (
        id,
        name
      )
    `)
    .eq('ws_id', wsId);

if (completed !== undefined) {
    query = query.eq('completed', completed);
  }

const { data, error } = await query;
  if (error) throw error;

return data;
}
```

### Realtime Subscriptions

The browser `createClient()` from `@tuturuuu/supabase/next/client` is
**synchronous** (returns a `SupabaseClient`, not a `Promise`), so it is used
without `await`. Note this client is deprecated for general CRUD/storage — route
those through `@tuturuuu/internal-api` — but it remains valid for realtime
channel subscriptions, which are not covered by the internal API client.

```typescript theme={null}
'use client';

import { createClient } from '@tuturuuu/supabase/next/client';
import { useEffect, useState } from 'react';
import type { Database } from '@tuturuuu/types';

type Task = Database['public']['Tables']['workspace_tasks']['Row'];

export function useTaskSubscription(wsId: string) {
  const [tasks, setTasks] = useState<Task[]>([]);
  const supabase = createClient();

useEffect(() => {
    // Initial fetch
    supabase
      .from('workspace_tasks')
      .select('*')
      .eq('ws_id', wsId)
      .then(({ data }) => setTasks(data || []));

// Subscribe to changes
    const channel = supabase
      .channel(`workspace-tasks-${wsId}`)
      .on(
        'postgres_changes',
        {
          event: '*',
          schema: 'public',
          table: 'workspace_tasks',
          filter: `ws_id=eq.${wsId}`,
        },
        (payload) => {
          if (payload.eventType === 'INSERT') {
            setTasks((prev) => [...prev, payload.new as Task]);
          } else if (payload.eventType === 'UPDATE') {
            setTasks((prev) =>
              prev.map((task) =>
                task.id === payload.new.id ? (payload.new as Task) : task
              )
            );
          } else if (payload.eventType === 'DELETE') {
            setTasks((prev) => prev.filter((task) => task.id !== payload.old.id));
          }
        }
      )
      .subscribe();

return () => {
      channel.unsubscribe();
    };
  }, [wsId]);

return tasks;
}
```

## Type Safety

### Using Generated Types

```typescript theme={null}
import type { Database } from '@tuturuuu/types';
import { createClient } from '@tuturuuu/supabase/next/server';

type Task = Database['public']['Tables']['workspace_tasks']['Row'];
type TaskInsert = Database['public']['Tables']['workspace_tasks']['Insert'];
type TaskUpdate = Database['public']['Tables']['workspace_tasks']['Update'];

export async function createTypedTask(task: TaskInsert): Promise<Task> {
  const supabase = await createClient();

const { data, error } = await supabase
    .from('workspace_tasks')
    .insert(task)
    .select()
    .single();

if (error) throw error;
  return data;
}
```

### Custom Type Helpers

```typescript theme={null}
import type { Database } from '@tuturuuu/types';

// Extract table types
export type Tables<T extends keyof Database['public']['Tables']> =
  Database['public']['Tables'][T]['Row'];

export type Enums<T extends keyof Database['public']['Enums']> =
  Database['public']['Enums'][T];

// Usage
type Task = Tables<'workspace_tasks'>;
type Permission = Enums<'workspace_role_permission'>;
```

## Error Handling

### Standard Pattern

```typescript theme={null}
import { createClient } from '@tuturuuu/supabase/next/server';

export async function getTask(taskId: string) {
  const supabase = await createClient();

const { data, error } = await supabase
    .from('workspace_tasks')
    .select('*')
    .eq('id', taskId)
    .single();

if (error) {
    console.error('Failed to fetch task:', error);
    throw new Error(`Task not found: ${taskId}`);
  }

return data;
}
```

### With Try-Catch

```typescript theme={null}
import { createClient } from '@tuturuuu/supabase/next/server';

export async function safeGetTask(taskId: string) {
  try {
    const supabase = await createClient();

const { data, error } = await supabase
      .from('workspace_tasks')
      .select('*')
      .eq('id', taskId)
      .single();

if (error) throw error;
    return { data, error: null };
  } catch (error) {
    console.error('Error fetching task:', error);
    return { data: null, error };
  }
}
```

## Storage Operations

### Upload File

```typescript theme={null}
import { createClient } from '@tuturuuu/supabase/next/server';

export async function uploadAvatar(userId: string, file: File) {
  const supabase = await createClient();

const fileName = `${userId}-${Date.now()}.${file.name.split('.').pop()}`;
  const filePath = `avatars/${fileName}`;

const { data, error } = await supabase.storage
    .from('public')
    .upload(filePath, file, {
      cacheControl: '3600',
      upsert: false,
    });

if (error) throw error;

const { data: { publicUrl } } = supabase.storage
    .from('public')
    .getPublicUrl(filePath);

return publicUrl;
}
```

### Download File

```typescript theme={null}
import { createClient } from '@tuturuuu/supabase/next/server';

export async function downloadFile(path: string) {
  const supabase = await createClient();

const { data, error } = await supabase.storage
    .from('public')
    .download(path);

if (error) throw error;
  return data; // Blob
}
```

## Best Practices

### ✅ DO

1. **Use `createClient()` by default**
   ```typescript theme={null}
   const supabase = await createClient(); // Respects RLS
   ```

2. **Check authentication early**
   ```typescript theme={null}
   const { data: { user } } = await supabase.auth.getUser();
   if (!user) throw new Error('Unauthorized');
   ```

3. **Handle errors explicitly**
   ```typescript theme={null}
   const { data, error } = await supabase.from('table').select();
   if (error) throw error;
   ```

4. **Use TypeScript types**
   ```typescript theme={null}
   import type { Database } from '@tuturuuu/types';
   ```

5. **Limit data fetching**
   ```typescript theme={null}
   .select('id, name, created_at') // Only needed fields
   .limit(20) // Pagination
   ```

### ❌ DON'T

1. **Never use `createAdminClient()` for user operations**
   ```typescript theme={null}
   // ❌ Bad: Bypasses RLS
   const sbAdmin = await createAdminClient();
   const tasks = await sbAdmin.from('workspace_tasks').select();
   ```

2. **If you must use `createAdminClient()`, enforce membership and RBAC before the admin-backed operation**
   ```typescript theme={null}
   const member = await verifyWorkspaceMembershipType({
     wsId,
     userId: user.id,
     supabase: requestScopedSupabase,
   });
   if (!member.ok) {
     return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
   }

const permissions = await getPermissions({ wsId, user });
   if (!permissions?.containsPermission('manage_projects')) {
     return NextResponse.json(
       { error: "You don't have permission" },
       { status: 403 }
     );
   }
   ```

3. **Keep workspace-scoped admin mutations filtered by workspace ID**
   ```typescript theme={null}
   await sbAdmin
     .from('workspace_boards')
     .update({ deleted_at: new Date().toISOString() })
     .eq('id', boardId)
     .eq('ws_id', wsId);
   ```

4. **Don't expose service role key**
   ```typescript theme={null}
   // ❌ Bad: Never do this
   const client = createClient(process.env.SUPABASE_SECRET_KEY);
   ```

5. **Don't ignore errors**
   ```typescript theme={null}
   // ❌ Bad: Silent failure
   const { data } = await supabase.from('table').select();
   return data; // Could be null!
   ```

6. **Don't fetch unnecessary data**
   ```typescript theme={null}
   // ❌ Bad: Over-fetching
   .select('*')
   .order('created_at')
   // No limit!
   ```

## Testing

### Mock Supabase Client

```typescript theme={null}
// __mocks__/@tuturuuu/supabase/next/server.ts
export const createClient = vi.fn(() => ({
  from: vi.fn(() => ({
    select: vi.fn(() => ({
      eq: vi.fn(() => ({
        single: vi.fn(() => Promise.resolve({ data: mockData, error: null })),
      })),
    })),
  })),
  auth: {
    getUser: vi.fn(() =>
      Promise.resolve({ data: { user: mockUser }, error: null })
    ),
  },
}));
```

### Test Example

```typescript theme={null}
import { describe, it, expect, vi } from 'vitest';
import { getTask } from './tasks';

vi.mock('@tuturuuu/supabase/next/server');

describe('getTask', () => {
  it('should fetch task by ID', async () => {
    const task = await getTask('task-123');
    expect(task).toBeDefined();
    expect(task.id).toBe('task-123');
  });
});
```

## Related Documentation

* [Database Schema](/reference/database/schema-overview)
* [RLS Policies](/reference/database/rls-policies)
* [Authentication](/platform/architecture/authentication)
* [Authorization](/platform/architecture/authorization)

## External Resources

* [Supabase JavaScript Client Docs](https://supabase.com/docs/reference/javascript/introduction)
* [Supabase Auth Helpers](https://supabase.com/docs/guides/auth/auth-helpers/nextjs)

# @tuturuuu/trigger
Source: https://docs.tuturuuu.com/reference/packages/trigger

Calendar provider-sync and scheduling helpers

# @tuturuuu/trigger

`@tuturuuu/trigger` is the historical package name for Tuturuuu's reusable
Calendar provider-sync and scheduling helpers. It does not depend on or deploy
to Trigger.dev.

Production recurring work is scheduled by Vercel Cron. The cron route owns
authentication, cadence, observability, and orchestration; this package owns
the testable provider and scheduling operations invoked by that route.

## Calendar provider sync

Use the direct helpers from a server-only route or service:

```ts theme={null}
import { performFullSyncForWorkspace } from "@tuturuuu/trigger/google-calendar-full-sync";
import { performIncrementalSyncForWorkspace } from "@tuturuuu/trigger/google-calendar-incremental-sync";

await performIncrementalSyncForWorkspace(
  calendarId,
  workspaceId,
  accessToken,
  refreshToken,
);
```

The lower-level `google-calendar-sync` export contains token persistence,
Google event normalization, and batched database synchronization.

## Scheduling helpers

The package also exposes `schedulableTasksHelper` and
`unifiedScheduleHelper`. Call these from authenticated server routes rather
than adding another scheduler:

```ts theme={null}
import {
  schedulableTasksHelper,
  unifiedScheduleHelper,
} from "@tuturuuu/trigger";

await schedulableTasksHelper(workspaceId);
await unifiedScheduleHelper(workspaceId, {
  windowDays: 30,
  forceReschedule: false,
});
```

## Cron ownership

Calendar provider sync is configured in `apps/web/cron.config.json` and served
through `/api/cron/calendar/provider-sync`. Keep `apps/web/vercel.json`
generated from that configuration with:

```bash theme={null}
node scripts/sync-web-crons.js
```

Do not add task-runner wrappers, provider-specific recurring jobs, or a second
source of cadence inside this package.

## Validation

```bash theme={null}
bun run --filter @tuturuuu/trigger test
bun run --filter @tuturuuu/trigger type-check
```

# @tuturuuu/utils/effect
Source: https://docs.tuturuuu.com/reference/packages/utils-effect

Curated Effect entrypoint and Tuturuuu error helpers

# @tuturuuu/utils/effect

`@tuturuuu/utils/effect` is the platform entrypoint for [Effect](https://effect.website/docs/quickstart).
It keeps Effect adoption consistent across Tuturuuu apps and services while
preserving existing React, TanStack Query, Zod, and Supabase conventions.

```ts theme={null}
import {
  Effect,
  fromDataError,
  runEffectAsResult,
  TuturuuuEffectError,
} from '@tuturuuu/utils/effect';
```

## Exports

The entrypoint re-exports the Effect modules that Tuturuuu code should use by
default:

* `Effect`
* `Data`
* `Context`
* `Layer`
* `Schedule`
* `Duration`
* `Option`
* `Either`
* `Cause`

It also exports Tuturuuu helpers:

* `TuturuuuEffectError`
* `toTuturuuuEffectError`
* `serializeTuturuuuEffectError`
* `fromDataError`
* `fromPromise`
* `withTuturuuuRetry`
* `withTuturuuuTimeout`
* `forEachConcurrently`
* `runEffectAsResult`

## Expected Errors

Use `TuturuuuEffectError` for expected, typed failures that can cross a
server/action/API boundary in a sanitized shape.

```ts theme={null}
import { Effect, TuturuuuEffectError } from '@tuturuuu/utils/effect';

const requireWorkspace = (wsId?: string) =>
  wsId
    ? Effect.succeed(wsId)
    : Effect.fail(
        new TuturuuuEffectError({
          code: 'WORKSPACE_REQUIRED',
          message: 'Workspace ID is required.',
          status: 400,
        })
      );
```

## Supabase-Style Results

Use `fromDataError` for APIs that return `{ data, error }`, including Supabase
queries and RPC calls.

```ts theme={null}
const program = fromDataError(
  () =>
    supabase
      .from('workspaces')
      .select('id')
      .eq('id', wsId)
      .maybeSingle(),
  {
    code: 'WORKSPACE_READ_FAILED',
    message: 'Workspace read failed.',
    context: { wsId },
  }
);
```

`fromDataError` preserves service-specific `code`, `message`, `details`, and
`hint` fields when present, then falls back to the provided Tuturuuu metadata.

## Promise Results

Use `fromPromise` for async work that can throw or reject.

```ts theme={null}
const response = fromPromise(
  () => fetch(url, { cache: 'no-store' }),
  {
    code: 'UPSTREAM_REQUEST_FAILED',
    message: 'Upstream request failed.',
    context: { url },
  }
);
```

`fromPromise` receives the Effect-managed `AbortSignal`. Pass it into
`fetch`, SDK calls, or other abortable APIs so timeouts and fiber interruption
can cancel the underlying work.

## Retry And Timeout

Use `withTuturuuuRetry` and `withTuturuuuTimeout` when a server/service workflow
needs explicit resilience policy with Tuturuuu error metadata.

```ts theme={null}
const resilient = withTuturuuuRetry(
  withTuturuuuTimeout(response, {
    code: 'UPSTREAM_TIMEOUT',
    duration: '10 seconds',
    message: 'Upstream timed out.',
  }),
  {
    times: 2,
    delay: '250 millis',
    while: (error) => error.code === 'UPSTREAM_REQUEST_FAILED',
  }
);
```

Keep retry predicates narrow. Retry transient network, timeout, and temporary
upstream failures. Do not retry validation, permission, or tenant-boundary
errors unless the domain package documents idempotency.

## Controlled Concurrency

Use `forEachConcurrently` for bounded parallel work. It defaults to Tuturuuu's
shared concurrency value and can be tightened per service.

```ts theme={null}
const enrichedRows = forEachConcurrently(
  rows,
  (row) => enrichRowEffect(row),
  { concurrency: 4 }
);
```

## Boundary Conversion

Use `runEffectAsResult` at route, action, or helper boundaries that already
return result objects.

```ts theme={null}
const result = await runEffectAsResult(program);

if (!result.ok) {
  return Response.json({ error: result.error.message }, { status: 500 });
}

return Response.json(result.data);
```

Do not expose raw upstream diagnostics, secrets, URLs with credentials, stack
traces, or filesystem paths in public responses. Add safe metadata to
`context`, and keep detailed diagnostics in the existing server logging path.

# All apps, services, and packages
Source: https://docs.tuturuuu.com/reference/repository/catalog

Complete source-derived index of the Tuturuuu monorepo and its route references.

Use the [product directory](/platform/applications/overview) to learn workflows, and this catalog to locate every implementation workspace. The table includes infrastructure, experiments, and migration targets; inclusion is not a claim of a publicly launched product. External integrations such as [Shiraoki](/platform/applications/shiraoki) can live outside this repository.

## Apps and services

## Shared packages

| Package | Source | Public exports |
| - | - | - |
| `@tuturuuu/agent-quota` | [packages/agent-quota](https://github.com/tutur3u/platform/blob/main/packages/agent-quota/package.json) | `.` |
| `@tuturuuu/ai` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) | `./*` |
| `@tuturuuu/apis` | [packages/apis](https://github.com/tutur3u/platform/blob/main/packages/apis/package.json) | `./*`, `./meet/actions` |
| `@tuturuuu/auth` | [packages/auth](https://github.com/tutur3u/platform/blob/main/packages/auth/package.json) | `.`, `./app-coordination`, `./app-session-policy`, `./app-session`, `./cli-session`, `./supabase-session-user`, `./proxy`, `./cross-app`, `./cross-app/server`, `./cross-app/token-verifier`, `./mfa-mobile-approval`, `./identity-linking`, `./api-keys`, `./app-session-core` |
| `@tuturuuu/devbox` | [packages/devbox](https://github.com/tutur3u/platform/blob/main/packages/devbox/package.json) | `.` |
| `@tuturuuu/editor` | [packages/editor](https://github.com/tutur3u/platform/blob/main/packages/editor/package.json) | `.`, `./react`, `./styles.css` |
| `@tuturuuu/education-core` | [packages/education-core](https://github.com/tutur3u/platform/blob/main/packages/education-core/package.json) | `./todo/service`, `.`, `./tulearn`, `./tulearn/*`, `./education`, `./education/*`, `./teach`, `./teach/*` |
| `@tuturuuu/email-service` | [packages/email-service](https://github.com/tutur3u/platform/blob/main/packages/email-service/package.json) | `.`, `./types`, `./constants`, `./providers/ses`, `./validation` |
| `@tuturuuu/finance-core` | [packages/finance-core](https://github.com/tutur3u/platform/blob/main/packages/finance-core/package.json) | `.`, `./route-auth`, `./storage-access`, `./storage-limits` |
| `@tuturuuu/games` | [packages/games](https://github.com/tutur3u/platform/blob/main/packages/games/package.json) | See package manifest |
| `@tuturuuu/google` | [packages/google](https://github.com/tutur3u/platform/blob/main/packages/google/package.json) | `.` |
| `@tuturuuu/hive-ui` | [packages/hive-ui](https://github.com/tutur3u/platform/blob/main/packages/hive-ui/package.json) | `.`, `./access`, `./config`, `./studio` |
| `@tuturuuu/hooks` | [packages/hooks](https://github.com/tutur3u/platform/blob/main/packages/hooks/package.json) | `.`, `./hooks/*`, `./types/*`, `./utils/*` |
| `@tuturuuu/icons` | [packages/icons](https://github.com/tutur3u/platform/blob/main/packages/icons/package.json) | `.`, `./lab`, `./lucide`, `./lucide-static` |
| `@tuturuuu/internal-api` | [packages/internal-api](https://github.com/tutur3u/platform/blob/main/packages/internal-api/package.json) | `.`, `./lettin-server`, `./lettin`, `./ai`, `./ai-studio`, `./mira-soul`, `./ai-memory`, `./auth`, `./backend`, `./calendar`, `./calendar-provider-series`, `./calendar-series`, `./chat`, `./client`, `./documents`, `./education`, `./programming`, `./external-project-team`, `./external-app-drive`, `./external-projects`, `./finance`, `./finance-exchange-rates`, `./finance-subscription-analytics`, `./finance-reconciliation`, `./habit-trackers`, `./hive`, `./infrastructure`, `./infrastructure/abuse`, `./infrastructure/ai`, `./infrastructure/apps`, `./infrastructure/github-bot`, `./infrastructure/mobile`, `./infrastructure/monitoring`, `./infrastructure/types`, `./infrastructure/workspace`, `./inventory`, `./mail`, `./meet`, `./mind`, `./notes`, `./personal-journal`, `./nova`, `./onboarding`, `./promotions`, `./posts`, `./reports`, `./roles`, `./settings`, `./storage`, `./tasks`, `./task-media-cleanup`, `./task-history`, `./tutoring`, `./tutoring-suggestion`, `./tutoring-policy`, `./tutoring-queue-rules`, `./task-templates`, `./tasks-scheduling`, `./teach`, `./user-group-attendance`, `./user-groups`, `./templates`, `./time-tracking`, `./users`, `./users-server`, `./users-feedbacks`, `./workspace-configs`, `./workspace-config-ids`, `./workspaces`, `./colab`, `./chatgpt`, `./profile-media`, `./realtime`, `./meet-call`, `./playgrounds`, `./notes-voice`, `./product-feedback`, `./sso`, `./native-integrity`, `./calendar-settings-server` |
| `@tuturuuu/inventory-core` | [packages/inventory-core](https://github.com/tutur3u/platform/blob/main/packages/inventory-core/package.json) | `./infrastructure/employee-sql/process`, `./infrastructure/employee-sql/catalog`, `./infrastructure/employee-sql/database-readiness`, `./commerce/square`, `./infrastructure/log-drain`, `./*` |
| `@tuturuuu/legal` | [packages/legal](https://github.com/tutur3u/platform/blob/main/packages/legal/package.json) | `.` |
| `@tuturuuu/masonry` | [packages/masonry](https://github.com/tutur3u/platform/blob/main/packages/masonry/package.json) | `.`, `./masonry` |
| `@tuturuuu/meet-core` | [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json) | `./styles.css`, `./runtime`, `./runtime.ts`, `./parley-access`, `./parley-access.ts`, `./constants/common`, `./constants/common.ts`, `./constants/prefs`, `./constants/prefs.ts`, `./constants/configs`, `./constants/configs.ts`, `./constants/configs/reports`, `./constants/configs/reports.ts`, `./cloudflare/live/session-cleanup`, `./cloudflare/live/session-cleanup.ts`, `./cloudflare/live/room`, `./cloudflare/live/room.ts`, `./cloudflare/live/memory-store`, `./cloudflare/live/memory-store.ts`, `./cloudflare/live/finalize-billing`, `./cloudflare/live/finalize-billing.ts`, `./cloudflare/live/publish-transcript`, `./cloudflare/live/publish-transcript.ts`, `./cloudflare/live/usage`, `./cloudflare/live/usage.ts`, `./cloudflare/live/erase-context`, `./cloudflare/live/erase-context.ts`, `./cloudflare/live/session-state`, `./cloudflare/live/session-state.ts`, `./cloudflare/live/public-speech`, `./cloudflare/live/public-speech.ts`, `./cloudflare/live/session-usage`, `./cloudflare/live/session-usage.ts`, `./cloudflare/live/storage`, `./cloudflare/live/storage.ts`, `./cloudflare/live/usage-report`, `./cloudflare/live/usage-report.ts`, `./cloudflare/live/decision`, `./cloudflare/live/decision.ts`, `./cloudflare/live/session`, `./cloudflare/live/session.ts`, `./cloudflare/live/actions`, `./cloudflare/live/actions.ts`, `./cloudflare/live/audio-batcher`, `./cloudflare/live/audio-batcher.ts`, `./cloudflare/live/registry-heartbeat`, `./cloudflare/live/registry-heartbeat.ts`, `./cloudflare/live/tool-responses`, `./cloudflare/live/tool-responses.ts`, `./cloudflare/live/tools`, `./cloudflare/live/tools.ts`, `./cloudflare/live/room-audio-batcher`, `./cloudflare/live/room-audio-batcher.ts`, `./cloudflare/live/registry`, `./cloudflare/live/registry.ts`, `./cloudflare/live/workspace-review`, `./cloudflare/live/workspace-review.ts`, `./cloudflare/live/provider`, `./cloudflare/live/provider.ts`, `./cloudflare/live/audio-input`, `./cloudflare/live/audio-input.ts`, `./cloudflare/live/billing`, `./cloudflare/live/billing.ts`, `./cloudflare/live/session-tools`, `./cloudflare/live/session-tools.ts`, `./cloudflare/live/reviews`, `./cloudflare/live/reviews.ts`, `./features/live-assistant/memory-command`, `./features/live-assistant/memory-command.ts`, `./features/live-assistant/live-review-card`, `./features/live-assistant/live-review-card.tsx`, `./features/live-assistant/audio`, `./features/live-assistant/audio.ts`, `./features/live-assistant/contracts`, `./features/live-assistant/contracts.ts`, `./features/live-assistant/privacy-reset`, `./features/live-assistant/privacy-reset.ts`, `./features/live-assistant/context`, `./features/live-assistant/context.ts`, `./features/live-assistant/room-audio`, `./features/live-assistant/room-audio.tsx`, `./features/live-assistant/live-panel`, `./features/live-assistant/live-panel.tsx`, `./features/live-assistant/input-sources`, `./features/live-assistant/input-sources.ts`, `./features/live-assistant/playback-meter`, `./features/live-assistant/playback-meter.ts`, `./features/live-assistant/mention-relay`, `./features/live-assistant/mention-relay.ts`, `./features/live-assistant/request-body`, `./features/live-assistant/request-body.ts`, `./features/live-assistant/memory-settings`, `./features/live-assistant/memory-settings.tsx`, `./features/live-assistant/room-players`, `./features/live-assistant/room-players.ts`, `./features/live-assistant/token`, `./features/live-assistant/token.ts`, `./features/live-assistant/workspace-tools`, `./features/live-assistant/workspace-tools.ts`, `./features/live-assistant/use-live-assistant`, `./features/live-assistant/use-live-assistant.ts`, `./features/loading/meet-loading`, `./features/loading/meet-loading.tsx`, `./features/meeting-ai/followup-conflicts`, `./features/meeting-ai/followup-conflicts.tsx`, `./features/meeting-ai/use-meeting-ai`, `./features/meeting-ai/use-meeting-ai.ts`, `./features/meeting-ai/meeting-ai-panel`, `./features/meeting-ai/meeting-ai-panel.tsx`, `./features/meeting-ai/audio`, `./features/meeting-ai/audio.ts`, `./features/meeting-ai/followup-review`, `./features/meeting-ai/followup-review.tsx`, `./features/meeting-ai/followup-review-form`, `./features/meeting-ai/followup-review-form.tsx`, `./features/meeting-ai/chunk-recovery`, `./features/meeting-ai/chunk-recovery.ts`, `./features/meeting-ai/followup-destination`, `./features/meeting-ai/followup-destination.tsx`, `./features/meeting-ai/followup-save`, `./features/meeting-ai/followup-save.ts`, `./features/meeting-ai/meeting-transcript`, `./features/meeting-ai/meeting-transcript.tsx`, `./features/meeting-ai/followup-time`, `./features/meeting-ai/followup-time.ts`, `./features/meeting-ai/notes-sharing-control`, `./features/meeting-ai/notes-sharing-control.tsx`, `./features/meeting-ai/use-followup-context`, `./features/meeting-ai/use-followup-context.ts`, `./features/meeting-ai/followup-types`, `./features/meeting-ai/followup-types.ts`, `./features/meeting-ai/audio-batches`, `./features/meeting-ai/audio-batches.ts`, `./features/meeting-ai/meeting-ai-overview`, `./features/meeting-ai/meeting-ai-overview.tsx`, `./features/meeting-ai/followup-assignees`, `./features/meeting-ai/followup-assignees.tsx`, `./features/meeting-ai/meeting-followups`, `./features/meeting-ai/meeting-followups.tsx`, `./features/meeting-ai/followup-picker`, `./features/meeting-ai/followup-picker.tsx`, `./features/meeting-ai/audio-sources`, `./features/meeting-ai/audio-sources.ts`, `./features/meeting-ai/server/chunks`, `./features/meeting-ai/server/chunks.ts`, `./features/meeting-ai/server/followup-context`, `./features/meeting-ai/server/followup-context.ts`, `./features/meeting-ai/server/followup-create`, `./features/meeting-ai/server/followup-create.ts`, `./features/meeting-ai/server/room-access`, `./features/meeting-ai/server/room-access.ts`, `./features/meeting-ai/server/followup-task`, `./features/meeting-ai/server/followup-task.ts`, `./features/meeting-ai/server/followup-members`, `./features/meeting-ai/server/followup-members.ts`, `./features/meeting-ai/server/access`, `./features/meeting-ai/server/access.ts`, `./features/meeting-ai/server/transcript-speaker`, `./features/meeting-ai/server/transcript-speaker.ts`, `./features/meeting-ai/server/body`, `./features/meeting-ai/server/body.ts`, `./features/meeting-ai/server/audio-input`, `./features/meeting-ai/server/audio-input.ts`, `./features/meeting-ai/server/followup-event`, `./features/meeting-ai/server/followup-event.ts`, `./features/meeting-ai/server/sessions`, `./features/meeting-ai/server/sessions.ts`, `./features/call/server/read-upload`, `./features/call/server/read-upload.ts`, `./features/call/server/personal-chat-request`, `./features/call/server/personal-chat-request.ts`, `./features/call/server/personal-chat-body`, `./features/call/server/personal-chat-body.ts`, `./features/call/server/room-service`, `./features/call/server/room-service.ts`, `./features/call/server/assistant-generation`, `./features/call/server/assistant-generation.ts`, `./features/call/server/chat-model`, `./features/call/server/chat-model.ts`, `./features/call/server/personal-assistant`, `./features/call/server/personal-assistant.ts`, `./features/call/components/mira-participant`, `./features/call/components/mira-participant.tsx`, `./features/call/components/call-shell`, `./features/call/components/call-shell.tsx`, `./features/call/components/admission-notice`, `./features/call/components/admission-notice.tsx`, `./features/call/components/meeting-entry`, `./features/call/components/meeting-entry.tsx`, `./features/call/components/meeting-public-invite`, `./features/call/components/meeting-public-invite.tsx`, `./features/call/components/room-host-controls`, `./features/call/components/room-host-controls.tsx`, `./features/call/components/participant-name-form`, `./features/call/components/participant-name-form.tsx`, `./features/call/components/join-outcome`, `./features/call/components/join-outcome.tsx`, `./features/call/components/lobby`, `./features/call/components/lobby.tsx`, `./features/call/components/leave-dialog`, `./features/call/components/leave-dialog.tsx`, `./features/call/components/call-ended`, `./features/call/components/call-ended.tsx`, `./features/call/components/side-panel`, `./features/call/components/side-panel.tsx`, `./features/call/components/screen-audio-status`, `./features/call/components/screen-audio-status.tsx`, `./features/call/components/shared-audio-control`, `./features/call/components/shared-audio-control.tsx`, `./features/call/components/cloudflare-costs`, `./features/call/components/cloudflare-costs.tsx`, `./features/call/components/personal-chat`, `./features/call/components/personal-chat.tsx`, `./features/call/components/connection-panel`, `./features/call/components/connection-panel.tsx`, `./features/call/components/mira-profile`, `./features/call/components/mira-profile.tsx`, `./features/call/components/participants-panel`, `./features/call/components/participants-panel.tsx`, `./features/call/components/call-preparation`, `./features/call/components/call-preparation.tsx`, `./features/call/components/device-session-gate`, `./features/call/components/device-session-gate.tsx`, `./features/call/components/conversation-panel`, `./features/call/components/conversation-panel.tsx`, `./features/call/components/resizable-call-panel`, `./features/call/components/resizable-call-panel.tsx`, `./features/call/components/reaction-overlay`, `./features/call/components/reaction-overlay.tsx`, `./features/call/components/chat-panel`, `./features/call/components/chat-panel.tsx`, `./features/call/components/playback-volume`, `./features/call/components/playback-volume.tsx`, `./features/call/components/call-resource-notice`, `./features/call/components/call-resource-notice.tsx`, `./features/call/components/room-countdown`, `./features/call/components/room-countdown.tsx`, `./features/call/components/call-settings`, `./features/call/components/call-settings.tsx`, `./features/call/components/mira-audio-status`, `./features/call/components/mira-audio-status.tsx`, `./features/call/components/control-bar`, `./features/call/components/control-bar.tsx`, `./features/call/components/connection-overview`, `./features/call/components/connection-overview.tsx`, `./features/call/components/copy-invite`, `./features/call/components/copy-invite.tsx`, `./features/call/components/meeting-duration-info`, `./features/call/components/meeting-duration-info.tsx`, `./features/call/components/meeting-title`, `./features/call/components/meeting-title.tsx`, `./features/call/components/ended-meeting-settings`, `./features/call/components/ended-meeting-settings.tsx`, `./features/call/components/call-extras`, `./features/call/components/call-extras.tsx`, `./features/call/components/media-receiving-status`, `./features/call/components/media-receiving-status.tsx`, `./features/call/components/microphone-recovery`, `./features/call/components/microphone-recovery.tsx`, `./features/call/components/meeting-room-action`, `./features/call/components/meeting-room-action.tsx`, `./features/call/components/recording-history`, `./features/call/components/recording-history.tsx`, `./features/call/components/participant-tile`, `./features/call/components/participant-tile.tsx`, `./features/call/components/assistant-workspace-picker`, `./features/call/components/assistant-workspace-picker.tsx`, `./features/call/components/assistant-private-review`, `./features/call/components/assistant-private-review.tsx`, `./features/call/components/device-settings`, `./features/call/components/device-settings.tsx`, `./features/call/components/ai-costs`, `./features/call/components/ai-costs.tsx`, `./features/call/components/chat-message-body`, `./features/call/components/chat-message-body.tsx`, `./features/call/components/meeting-local-time`, `./features/call/components/meeting-local-time.tsx`, `./features/call/components/meeting-public-settings`, `./features/call/components/meeting-public-settings.tsx`, `./features/call/components/assistant-tool-preview`, `./features/call/components/assistant-tool-preview.tsx`, `./features/call/components/call-stage`, `./features/call/components/call-stage.tsx`, `./features/call/components/live-avatar`, `./features/call/components/live-avatar.tsx`, `./features/call/components/audio-processing-settings`, `./features/call/components/audio-processing-settings.tsx`, `./features/call/components/recording-settings`, `./features/call/components/recording-settings.tsx`, `./features/call/components/chat-settings`, `./features/call/components/chat-settings.tsx`, `./features/call/hooks/use-sender-bandwidth`, `./features/call/hooks/use-sender-bandwidth.ts`, `./features/call/hooks/use-room-recording`, `./features/call/hooks/use-room-recording.ts`, `./features/call/hooks/use-room-usage`, `./features/call/hooks/use-room-usage.ts`, `./features/call/hooks/use-publish-session`, `./features/call/hooks/use-publish-session.ts`, `./features/call/hooks/use-call-notifications`, `./features/call/hooks/use-call-notifications.ts`, `./features/call/hooks/use-solo-transport`, `./features/call/hooks/use-solo-transport.ts`, `./features/call/hooks/use-call-recording`, `./features/call/hooks/use-call-recording.ts`, `./features/call/hooks/use-meet-room`, `./features/call/hooks/use-meet-room.ts`, `./features/call/hooks/use-shared-room-audio`, `./features/call/hooks/use-shared-room-audio.ts`, `./features/call/hooks/use-ended-room`, `./features/call/hooks/use-ended-room.ts`, `./features/call/hooks/use-camera-controls`, `./features/call/hooks/use-camera-controls.ts`, `./features/call/lib/ended-room-cache`, `./features/call/lib/ended-room-cache.ts`, `./features/call/lib/meeting-metadata`, `./features/call/lib/meeting-metadata.ts`, `./features/call/lib/negotiation`, `./features/call/lib/negotiation.ts`, `./features/call/lib/subscribe-response`, `./features/call/lib/subscribe-response.ts`, `./features/call/lib/call-state`, `./features/call/lib/call-state.ts`, `./features/call/lib/room-code`, `./features/call/lib/room-code.ts`, `./features/call/lib/local-media-controls`, `./features/call/lib/local-media-controls.ts`, `./features/call/lib/startup-error`, `./features/call/lib/startup-error.ts`, `./features/call/lib/room-actions`, `./features/call/lib/room-actions.ts`, `./features/call/lib/media-playback`, `./features/call/lib/media-playback.ts`, `./features/call/lib/publish-response`, `./features/call/lib/publish-response.ts`, `./features/call/lib/screen-capture`, `./features/call/lib/screen-capture.ts`, `./features/call/lib/meeting-code-input`, `./features/call/lib/meeting-code-input.ts`, `./features/call/lib/recover-media-state`, `./features/call/lib/recover-media-state.ts`, `./features/call/lib/room-controller`, `./features/call/lib/room-controller.ts`, `./features/call/lib/forced-media`, `./features/call/lib/forced-media.ts`, `./features/call/lib/adopt-camera-preview`, `./features/call/lib/adopt-camera-preview.ts`, `./features/call/lib/published-senders`, `./features/call/lib/published-senders.ts`, `./features/call/lib/receiver-packet-state`, `./features/call/lib/receiver-packet-state.ts`, `./features/call/lib/receiver-health`, `./features/call/lib/receiver-health.ts`, `./features/call/lib/call-session`, `./features/call/lib/call-session.ts`, `./features/call/lib/sfu-response`, `./features/call/lib/sfu-response.ts`, `./features/call/lib/chat-sources`, `./features/call/lib/chat-sources.ts`, `./features/call/lib/call-notifications`, `./features/call/lib/call-notifications.ts`, `./features/call/lib/meeting-duration`, `./features/call/lib/meeting-duration.ts`, `./features/call/lib/bandwidth`, `./features/call/lib/bandwidth.ts`, `./features/call/lib/invite-continuation`, `./features/call/lib/invite-continuation.ts`, `./features/call/lib/call-access`, `./features/call/lib/call-access.ts`, `./features/call/lib/meeting-public-info`, `./features/call/lib/meeting-public-info.ts`, `./features/call/lib/media-error`, `./features/call/lib/media-error.ts`, `./features/call/lib/remote-playback`, `./features/call/lib/remote-playback.ts`, `./features/call/lib/calendar-link`, `./features/call/lib/calendar-link.ts`, `./features/call/lib/audio-processing`, `./features/call/lib/audio-processing.ts`, `./features/call/lib/video-presentation`, `./features/call/lib/video-presentation.ts`, `./features/call/lib/camera-effects`, `./features/call/lib/camera-effects.ts`, `./features/call/lib/assistant-identity`, `./features/call/lib/assistant-identity.ts`, `./features/call/lib/recording`, `./features/call/lib/recording.ts`, `./features/call/lib/chat-delivery`, `./features/call/lib/chat-delivery.ts`, `./features/call/lib/peer-recovery`, `./features/call/lib/peer-recovery.ts`, `./features/call/lib/room-recorder`, `./features/call/lib/room-recorder.ts`, `./features/call/lib/participant-name`, `./features/call/lib/participant-name.ts`, `./features/call/lib/shared-audio-policy`, `./features/call/lib/shared-audio-policy.ts`, `./features/call/lib/signaling`, `./features/call/lib/signaling.ts`, `./features/call/lib/audio-overlap`, `./features/call/lib/audio-overlap.ts`, `./features/call/lib/meeting-time`, `./features/call/lib/meeting-time.ts`, `./features/call/lib/reconnect`, `./features/call/lib/reconnect.ts`, `./features/call/lib/remote-streams`, `./features/call/lib/remote-streams.ts`, `./features/call/lib/audio-overlap-monitor`, `./features/call/lib/audio-overlap-monitor.ts`, `./features/call/lib/media-diagnostics`, `./features/call/lib/media-diagnostics.ts`, `./features/call/lib/open-peer-session`, `./features/call/lib/open-peer-session.ts`, `./features/call/lib/peer-connection`, `./features/call/lib/peer-connection.ts`, `./utils/date-helper`, `./utils/date-helper.ts`, `./utils/configs`, `./utils/configs.ts`, `./parley/admin-actions`, `./parley/admin-actions.ts`, `./parley/scenario-mutations`, `./parley/scenario-mutations.ts`, `./parley/repository`, `./parley/repository.ts`, `./parley/contracts`, `./parley/contracts.ts`, `./parley/authorization`, `./parley/authorization.ts`, `./parley/database`, `./parley/database.ts`, `./hooks/useTranscription`, `./hooks/useTranscription.ts`, `./hooks/useRecordingLoader`, `./hooks/useRecordingLoader.ts`, `./lib/workspace-navigation`, `./lib/workspace-navigation.ts`, `./i18n/routing`, `./i18n/routing.ts`, `./routes/[locale]/r/[code]/loading`, `./routes/[locale]/r/[code]/loading.tsx`, `./routes/[locale]/r/[code]/page`, `./routes/[locale]/r/[code]/page.tsx`, `./routes/[locale]/r/[code]/preview/route`, `./routes/[locale]/r/[code]/preview/route.tsx`, `./routes/[locale]/(auth)/login/page`, `./routes/[locale]/(auth)/login/page.tsx`, `./routes/api/meet-live/memory/route`, `./routes/api/meet-live/memory/route.ts`, `./routes/api/meet-live/[meetingId]/route`, `./routes/api/meet-live/[meetingId]/route.ts`, `./routes/api/meet-live/[meetingId]/review/route`, `./routes/api/meet-live/[meetingId]/review/route.ts`, `./routes/api/meet-call/[meetingId]/token/route`, `./routes/api/meet-call/[meetingId]/token/route.ts`, `./routes/api/meet-call/[meetingId]/assistant/route`, `./routes/api/meet-call/[meetingId]/assistant/route.ts`, `./routes/api/meet-call/[meetingId]/assistant/personal/route`, `./routes/api/meet-call/[meetingId]/assistant/personal/route.ts`, `./routes/api/meet-call/[meetingId]/assistant/review/route`, `./routes/api/meet-call/[meetingId]/assistant/review/route.ts`, `./routes/api/meet-call/[meetingId]/costs/route`, `./routes/api/meet-call/[meetingId]/costs/route.ts`, `./routes/api/meet-call/[meetingId]/title/route`, `./routes/api/meet-call/[meetingId]/title/route.ts`, `./routes/api/meet-call/[meetingId]/recording/route`, `./routes/api/meet-call/[meetingId]/recording/route.ts`, `./routes/api/meet-call/[meetingId]/state/route`, `./routes/api/meet-call/[meetingId]/state/route.ts`, `./routes/api/meet-call/[meetingId]/public-info/route`, `./routes/api/meet-call/[meetingId]/public-info/route.ts`, `./routes/api/meet-call/[meetingId]/files/route`, `./routes/api/meet-call/[meetingId]/files/route.ts`, `./routes/api/auth/verify-app-token/route`, `./routes/api/auth/verify-app-token/route.ts`, `./routes/api/auth/logout/route`, `./routes/api/auth/logout/route.ts`, `./routes/api/auth/refresh-app-session/route`, `./routes/api/auth/refresh-app-session/route.ts`, `./routes/api/meet-ai/[wsId]/[meetingId]/route`, `./routes/api/meet-ai/[wsId]/[meetingId]/route.ts`, `./routes/api/meet-ai/[wsId]/[meetingId]/followups/route`, `./routes/api/meet-ai/[wsId]/[meetingId]/followups/route.ts`, `./routes/api/meet-ai/[wsId]/[meetingId]/chunks/route`, `./routes/api/meet-ai/[wsId]/[meetingId]/chunks/route.ts`, `./parley/role-editor`, `./features/meeting-ai/server/artifact-billing`, `./cloudflare/provider-proxy`, `./features/call/server/documents.ts`, `./features/call/server/documents`, `./features/call/server/chat-billing.ts`, `./features/call/server/chat-billing`, `./features/call/server/programming.ts`, `./features/call/server/programming`, `./features/call/components/programming-panel.tsx`, `./features/call/components/programming-panel`, `./features/call/components/document-panel.tsx`, `./features/call/components/document-panel`, `./routes/api/meet-call/[meetingId]/programming/route.ts`, `./routes/api/meet-call/[meetingId]/programming/route`, `./routes/api/meet-call/[meetingId]/programming/preview/[port]/[[...path]]/route.ts`, `./routes/api/meet-call/[meetingId]/programming/preview/[port]/[[...path]]/route`, `./routes/api/meet-call/[meetingId]/document/route.ts`, `./routes/api/meet-call/[meetingId]/document/route` |
| `@tuturuuu/microsoft` | [packages/microsoft](https://github.com/tutur3u/platform/blob/main/packages/microsoft/package.json) | `.`, `./calendar` |
| `@tuturuuu/mind-core` | [packages/mind-core](https://github.com/tutur3u/platform/blob/main/packages/mind-core/package.json) | `.`, `./access` |
| `@tuturuuu/mind-ui` | [packages/mind-ui](https://github.com/tutur3u/platform/blob/main/packages/mind-ui/package.json) | `.`, `./dashboard`, `./model`, `./routes` |
| `@tuturuuu/multiplayer` | [packages/multiplayer](https://github.com/tutur3u/platform/blob/main/packages/multiplayer/package.json) | `.` |
| `@tuturuuu/offline` | [packages/offline](https://github.com/tutur3u/platform/blob/main/packages/offline/package.json) | `./worker`, `./config`, `./manifest`, `./precache`, `./components`, `./route`, `./provider` |
| `@tuturuuu/payment` | [packages/payment](https://github.com/tutur3u/platform/blob/main/packages/payment/package.json) | `./polar`, `./polar/checkout/embed`, `./polar/next`, `./polar/*` |
| `@tuturuuu/payment-core` | [packages/payment-core](https://github.com/tutur3u/platform/blob/main/packages/payment-core/package.json) | `.`, `./ai-credits-helper`, `./billing-helper`, `./customer-helper`, `./migrations-helper`, `./polar-order-helper`, `./polar-product-helper`, `./polar-product-metadata`, `./polar-seat-helper`, `./polar-subscription-helper`, `./price-helper`, `./proration`, `./seat-limits`, `./subscription-constants`, `./subscription-helper`, `./polar-price`, `./self-serve-products`, `./public-prices` |
| `@tuturuuu/programming-ui` | [packages/programming-ui](https://github.com/tutur3u/platform/blob/main/packages/programming-ui/package.json) | `.`, `./*` |
| `@tuturuuu/realtime` | [packages/realtime](https://github.com/tutur3u/platform/blob/main/packages/realtime/package.json) | `./chat`, `./chat/token`, `.`, `./hive`, `./hive/yjs`, `./meet`, `./meet/token`, `./core/token`, `./collaboration`, `./channels`, `./channels/server`, `./documents`, `./documents/server`, `./core/retry-budget`, `./collaboration/server` |
| `@tuturuuu/satellite` | [packages/satellite](https://github.com/tutur3u/platform/blob/main/packages/satellite/package.json) | `.`, `./apps-launcher-core`, `./providers`, `./client-providers`, `./auth`, `./workspace-access`, `./user-nav`, `./user-nav-wrapper`, `./user-nav-client`, `./user-nav-metadata`, `./settings-dialog-intent`, `./account-switcher-menu`, `./app-guide-overlay`, `./create-user-nav`, `./create-user-nav-client`, `./command-launcher`, `./create-navbar-actions`, `./navbar-actions`, `./sidebar-structure`, `./sidebar-workspace-select-section`, `./fixed-app-brand`, `./workspace-shell`, `./notification-popover`, `./language-wrapper`, `./system-language-wrapper`, `./system-language-dropdown-item`, `./theme-dropdown-items`, `./auth-layout`, `./verify-token-page`, `./version-badge`, `./workspace-invitation`, `./account-settings`, `./workspace-settings`, `./i18n`, `./constants`, `./sidebar-context`, `./workspace-layout-helpers`, `./workspace-actions`, `./workspace-settings-route-handlers` |
| `tuturuuu` | [packages/sdk](https://github.com/tutur3u/platform/blob/main/packages/sdk/package.json) | `.`, `./storage`, `./types`, `./errors`, `./external-projects`, `./external-projects/public-assets`, `./epm`, `./platform` |
| `@tuturuuu/sso` | [packages/sso](https://github.com/tutur3u/platform/blob/main/packages/sso/package.json) | `.`, `./node-signer` |
| `@tuturuuu/storage-core` | [packages/storage-core](https://github.com/tutur3u/platform/blob/main/packages/storage-core/package.json) | `./*` |
| `@tuturuuu/supabase` | [packages/supabase](https://github.com/tutur3u/platform/blob/main/packages/supabase/package.json) | `.`, `./auth-errors`, `./next/client`, `./next/auth-browser`, `./next/auth-session-user`, `./next/common`, `./next/proxy`, `./next/realtime-log-provider`, `./request/server`, `./next/server`, `./next/user`, `./types`, `./next/realtime-log-actions` |
| `@tuturuuu/tasks-api` | [packages/tasks-api](https://github.com/tutur3u/platform/blob/main/packages/tasks-api/package.json) | `.`, `./progress`, `./progress/preferences`, `./progress/types`, `./server/*` |
| `@tuturuuu/tasks-ui` | [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json) | `.`, `./globals.css`, `./progress/task-progress-page`, `./calendar/task-calendar-page-shell`, `./calendar/components/*`, `./hooks/*`, `./settings/task-card-hotkey-settings`, `./settings/task-settings`, `./text-editor/task-mention-node-view`, `./text-editor/task-rich-text-editor`, `./tu-do/hooks/useTaskDialog`, `./tu-do/providers/task-dialog-provider`, `./tu-do/shared/task-dialog-manager`, `./tu-do/shared/recent-sidebar-events`, `./tu-do/shared/task-time-tracking-cache`, `./tu-do/hooks/*`, `./tu-do/providers/*`, `./tu-do/shared/*`, `./tu-do/shared/task-edit-dialog/*`, `./tu-do/shared/estimation-mapping`, `./tu-do/utils/label-colors`, `./tu-do/boards/*`, `./tu-do/drafts/*`, `./tu-do/my-tasks/use-my-tasks-state`, `./tu-do/my-tasks/*`, `./tu-do/habits/*`, `./tu-do/notes/*`, `./tu-do/labels/types`, `./tu-do/labels/*`, `./tu-do/labels/components/*`, `./tu-do/labels/hooks/*`, `./tu-do/estimates/*`, `./tu-do/initiatives/*`, `./tu-do/cycles/*`, `./tu-do/logs/*`, `./tu-do/templates/types`, `./tu-do/templates/*`, `./tu-do/templates/marketplace/*`, `./tu-do/templates/templateId/*`, `./tu-do/projects/types`, `./tu-do/projects/*`, `./tu-do/projects/components/*`, `./tu-do/projects/dialogs/*`, `./tu-do/projects/hooks/*`, `./tu-do/projects/projectId/*`, `./tu-do/projects/projectId/components/*`, `./tu-do/projects/projectId/components/overview/*`, `./tu-do/projects/projectId/dialogs/*`, `./tu-do/projects/projectId/hooks/*`, `./tu-do/shared/task-detail-page`, `./tu-do/shared/text-diff-viewer`, `./tu-do/*` |
| `@tuturuuu/transactional` | [packages/transactional](https://github.com/tutur3u/platform/blob/main/packages/transactional/package.json) | `./react/email`, `./emails/notification-digest`, `./emails/workspace-invite`, `./emails/deadline-reminder`, `./emails/guest-template`, `./emails/post-template`, `./emails/vercel-invite-user` |
| `@tuturuuu/trigger` | [packages/trigger](https://github.com/tutur3u/platform/blob/main/packages/trigger/package.json) | `.`, `./effect`, `./calendar-sync-coordination`, `./google-calendar-sync`, `./google-calendar-full-sync`, `./google-calendar-incremental-sync` |
| `@tuturuuu/turnstile` | [packages/turnstile](https://github.com/tutur3u/platform/blob/main/packages/turnstile/package.json) | `.`, `./client`, `./server` |
| `@tuturuuu/types` | [packages/types](https://github.com/tutur3u/platform/blob/main/packages/types/package.json) | `.`, `./sdk`, `./primitives`, `./primitives/*`, `./db`, `./supabase`, `./tiptap` |
| `@tuturuuu/typescript-config` | [packages/typescript-config](https://github.com/tutur3u/platform/blob/main/packages/typescript-config/package.json) | See package manifest |
| `@tuturuuu/ui` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) | `./custom/education-todo`, `./globals.css`, `./marketing`, `./postcss.config`, `./badge`, `./button`, `./chart`, `./command`, `./dialog`, `./tooltip`, `./form`, `./sheet`, `./sonner`, `./storefront`, `./hooks/use-board-actions`, `./hooks/*`, `./hooks/time-blocking-provider`, `./hooks/use-at-bottom`, `./hooks/use-calendar-day-zone`, `./lib/calendar-day`, `./hooks/use-calendar-preferences`, `./hooks/use-calendar-sync`, `./hooks/use-calendar`, `./hooks/use-enter-submit`, `./hooks/use-popover-manager`, `./hooks/useSearchParams`, `./resolvers`, `./gsap`, `./xlsx`, `./tiptap`, `./utils/label-colors`, `./finance/wallets/wallet-form-schema`, `./finance/wallets/interest`, `./finance/transactions/categories/hooks`, `./finance/categories-tags-tabs`, `./lib/template-background`, `./legacy/calendar/settings/types`, `./legacy/calendar/settings/*`, `./custom/sidebar-context`, `./custom/animated-slot-text`, `./custom/nav`, `./custom/nav-link`, `./custom/theme-dropdown-items`, `./custom/language-dropdown-item`, `./custom/language-dropdown-wrapper`, `./custom/ops`, `./custom/locale-preference`, `./custom/system-language-dropdown-item`, `./custom/system-language-wrapper`, `./custom/tuturuuu-wordmark`, `./custom/tuturuuu-logo`, `./custom/tuturuuu-logo-urls`, `./custom/workspace-select`, `./custom/workspace-select-reveal`, `./custom/notification-popover-client`, `./custom/sidebar-footer-actions`, `./custom/structure`, `./custom/app-error-boundary`, `./custom/settings-dialog-shell`, `./custom/workspace-access`, `./custom/version-badge`, `./custom/settings/*`, `./custom/missed-entry/*`, `./custom/workspace-wrapper`, `./lib/workspace-actions`, `./lib/calendar-settings-resolver`, `./chat/chat-workspace`, `./chat/hooks`, `./chat/utils`, `./chat/*`, `./calendar-app/hooks`, `./calendar-app/calendar-client-page`, `./calendar-app/calendar-page-shell`, `./calendar-app/hooks/*`, `./calendar-app/components/*`, `./custom/icon-picker`, `./finance/debts`, `./*`, `./lib/task-personal-external`, `./lib/tasks-app-url`, `./lib/task-open-events`, `./lib/calendar/planning-query-client`, `./lib/calendar/preview-engine`, `./time-tracker/types`, `./text-editor/editor`, `./text-editor/mention-extension`, `./text-editor/text-replacements`, `./custom/satellite-brand`, `./custom/satellite-navigation`, `./custom/satellite-content`, `./custom/satellite-workspace-section`, `./custom/satellite-shell-utils`, `./custom/satellite-shell`, `./custom/use-satellite-shell`, `./custom/satellite-user-menu`, `./custom/satellite-footer-actions`, `./custom/satellite-user-menu-items`, `./custom/satellite-account-switcher-menu`, `./custom/satellite-theme-dropdown-items`, `./custom/satellite-language-item`, `./report-problem-dialog-content`, `./custom/satellite-settings-dialog-shell`, `./custom/satellite-onboarding-settings-panel`, `./custom/satellite-notification-popover`, `./custom/notification-runtime`, `./finance/invoices/query-invalidation`, `./finance/shared/charts/use-finance-confidential-visibility`, `./text-editor/collaboration-carets` |
| `@tuturuuu/users-core` | [packages/users-core](https://github.com/tutur3u/platform/blob/main/packages/users-core/package.json) | `.`, `./lib/*`, `./features/*`, `./database/*`, `./reports/*`, `./routes/*` |
| `@tuturuuu/users-ui` | [packages/users-ui](https://github.com/tutur3u/platform/blob/main/packages/users-ui/package.json) | `.`, `./hooks/*`, `./components/*`, `./database/*` |
| `@tuturuuu/utils` | [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json) | `./timezones`, `./effect`, `./email/validation`, `./hooks/*`, `./task-helper/personal-external-staging`, `./*`, `./common/scan`, `./common/metadata`, `./common/nextjs`, `./permissions`, `./editor`, `./abuse-protection`, `./abuse-protection/backend-rate-limit`, `./abuse-protection/client-ip`, `./abuse-protection/edge`, `./abuse-protection/edge-trust`, `./abuse-protection/user-suspension`, `./currencies`, `./exchange-rates`, `./encryption`, `./finance` |
| `@tuturuuu/vercel` | [packages/vercel](https://github.com/tutur3u/platform/blob/main/packages/vercel/package.json) | `.` |
| `@tuturuuu/workflows` | [packages/workflows](https://github.com/tutur3u/platform/blob/main/packages/workflows/package.json) | See package manifest |

Wildcard exports describe supported import families, not every runtime symbol. Read the package's source and tests before extending an integration.

# Dart locked dependencies 1
Source: https://docs.tuturuuu.com/reference/repository/dart-dependencies-1

Resolved Dart package versions in the maintained mobile workspace.

Source: [apps/mobile/pubspec.lock](https://github.com/tutur3u/platform/blob/main/apps/mobile/pubspec.lock). This reference includes direct and transitive lockfile entries; resolution markers, platform constraints, and dependency relationships remain in the owning lockfile. It is not a deployment or upstream-latest claim.

| Package | Locked version |
| - | - |
| `_fe_analyzer_shared` | `103.0.0` |
| `_flutterfire_internals` | `1.3.77` |
| `analyzer` | `13.3.0` |
| `android_file_picker` | `1.1.1` |
| `animation_kit` | `0.0.2` |
| `ansicolor` | `2.0.3` |
| `app_attest` | `0.2.1` |
| `app_links` | `7.2.1` |
| `app_links_linux` | `1.0.3` |
| `app_links_platform_interface` | `2.0.4` |
| `app_links_web` | `1.0.4` |
| `archive` | `4.3.0` |
| `args` | `2.7.0` |
| `async` | `2.13.1` |
| `background_downloader` | `9.6.3` |
| `bloc` | `9.2.1` |
| `bloc_test` | `10.0.0` |
| `boolean_selector` | `2.1.2` |
| `build` | `4.0.11` |
| `build_config` | `1.3.3` |
| `build_daemon` | `4.1.6` |
| `build_runner` | `2.16.1` |
| `built_collection` | `5.1.1` |
| `built_value` | `8.13.0` |
| `cached_network_image` | `4.0.0` |
| `cached_network_image_platform_interface` | `5.0.0` |
| `cached_network_image_web` | `2.0.0` |
| `camera` | `0.12.1` |
| `camera_android_camerax` | `0.7.4+8` |
| `camera_avfoundation` | `0.10.3` |
| `camera_platform_interface` | `2.13.1` |
| `camera_web` | `0.3.5+6` |
| `characters` | `1.4.1` |
| `charcode` | `1.4.0` |
| `checked_yaml` | `2.0.4` |
| `cli_config` | `0.2.0` |
| `cli_util` | `0.4.2` |
| `clock` | `1.1.3` |
| `cloudflare_turnstile` | `3.8.1` |
| `code_assets` | `1.2.1` |
| `collection` | `1.19.1` |
| `connectivity_plus` | `7.3.1` |
| `connectivity_plus_platform_interface` | `2.1.0` |
| `convert` | `3.1.2` |
| `country_flags` | `4.1.2` |
| `coverage` | `1.15.1` |
| `cross_file` | `0.3.5+5` |
| `crypto` | `3.0.7` |
| `cryptography` | `2.9.0` |
| `csslib` | `1.0.2` |
| `cupertino_icons` | `1.0.9` |
| `cupertino_ui` | `1.0.2` |
| `dart_jsonwebtoken` | `3.4.1` |
| `dart_quill_delta` | `10.8.3` |
| `dart_style` | `3.1.13` |
| `dart_webrtc` | `1.8.2` |
| `data_widget` | `0.0.3` |
| `dbus` | `0.7.15` |
| `decimal` | `3.2.6` |
| `desktop_webview_window` | `0.4.0` |
| `device_info_plus` | `13.2.0` |
| `device_info_plus_platform_interface` | `8.1.0` |
| `diff_match_patch` | `0.4.1` |
| `email_validator` | `3.0.0` |
| `equatable` | `2.1.0` |
| `expressions` | `0.2.5+3` |
| `fake_async` | `1.3.3` |
| `ffi` | `2.2.0` |
| `ffi_leak_tracker` | `0.1.2` |
| `file` | `7.0.1` |
| `file_picker` | `12.3.0` |
| `file_picker_darwin` | `1.2.0` |
| `file_picker_linux` | `1.1.0` |
| `file_picker_platform_interface` | `3.4.0` |
| `file_picker_web` | `3.1.0` |
| `file_selector_linux` | `0.9.4+1` |
| `file_selector_macos` | `0.9.5+1` |
| `file_selector_platform_interface` | `2.7.0` |
| `file_selector_windows` | `0.9.3+6` |
| `firebase_analytics` | `12.5.0` |
| `firebase_analytics_platform_interface` | `6.0.7` |
| `firebase_analytics_web` | `0.6.1+13` |
| `firebase_core` | `4.14.0` |
| `firebase_core_platform_interface` | `8.1.1` |
| `firebase_core_web` | `3.11.0` |
| `firebase_crashlytics` | `5.3.0` |
| `firebase_crashlytics_platform_interface` | `3.9.0` |
| `firebase_messaging` | `16.6.0` |
| `firebase_messaging_platform_interface` | `4.10.0` |
| `firebase_messaging_web` | `4.2.5` |
| `fixnum` | `1.1.1` |
| `flutter` | `0.0.0` |
| `flutter_bloc` | `9.1.1` |
| `flutter_cache_manager` | `3.4.2` |
| `flutter_colorpicker` | `1.1.0` |
| `flutter_driver` | `0.0.0` |
| `flutter_edge_ai` | `2.0.0` |
| `flutter_edge_ai_litertlm` | `1.8.7` |
| `flutter_inappwebview` | `6.1.5` |
| `flutter_inappwebview_android` | `1.1.3` |

[Version guide](/reference/repository/versions).

# Dart locked dependencies 2
Source: https://docs.tuturuuu.com/reference/repository/dart-dependencies-2

Resolved Dart package versions in the maintained mobile workspace.

| Package | Locked version |
| - | - |
| `flutter_inappwebview_internal_annotations` | `1.3.0` |
| `flutter_inappwebview_ios` | `1.1.2` |
| `flutter_inappwebview_macos` | `1.1.2` |
| `flutter_inappwebview_platform_interface` | `1.3.0+1` |
| `flutter_inappwebview_web` | `1.1.2` |
| `flutter_inappwebview_windows` | `0.6.0` |
| `flutter_keyboard_visibility_linux` | `1.0.0` |
| `flutter_keyboard_visibility_macos` | `1.0.0` |
| `flutter_keyboard_visibility_platform_interface` | `2.0.0` |
| `flutter_keyboard_visibility_temp_fork` | `0.1.5` |
| `flutter_keyboard_visibility_windows` | `1.0.0` |
| `flutter_launcher_icons` | `0.14.4` |
| `flutter_local_notifications` | `22.3.1` |
| `flutter_local_notifications_linux` | `8.0.1` |
| `flutter_local_notifications_platform_interface` | `12.2.0` |
| `flutter_local_notifications_web` | `1.0.0` |
| `flutter_local_notifications_windows` | `3.1.1` |
| `flutter_localizations` | `0.0.0` |
| `flutter_markdown_plus` | `1.0.12` |
| `flutter_native_splash` | `2.4.8` |
| `flutter_pcm_sound` | `3.3.3` |
| `flutter_plugin_android_lifecycle` | `2.0.35` |
| `flutter_quill` | `11.5.1` |
| `flutter_quill_delta_from_html` | `1.5.3` |
| `flutter_secure_storage` | `11.1.1` |
| `flutter_secure_storage_darwin` | `0.4.2` |
| `flutter_secure_storage_linux` | `3.0.3` |
| `flutter_secure_storage_platform_interface` | `2.1.0` |
| `flutter_secure_storage_web` | `2.1.1` |
| `flutter_secure_storage_windows` | `4.2.2` |
| `flutter_svg` | `2.3.0` |
| `flutter_test` | `0.0.0` |
| `flutter_timezone` | `5.1.0` |
| `flutter_web_plugins` | `0.0.0` |
| `flutter_webrtc` | `1.6.2+hotfix.3` |
| `frontend_server_client` | `4.0.0` |
| `fuchsia_remote_debug_protocol` | `0.0.0` |
| `functions_client` | `2.7.1` |
| `gap` | `3.0.1` |
| `genai_primitives` | `0.2.4` |
| `glob` | `2.2.0` |
| `go_router` | `18.0.1` |
| `google_identity_services_web` | `0.3.3+1` |
| `google_sign_in` | `7.2.0` |
| `google_sign_in_android` | `7.2.17` |
| `google_sign_in_ios` | `6.3.3` |
| `google_sign_in_platform_interface` | `3.1.0` |
| `google_sign_in_web` | `1.1.3` |
| `gotrue` | `2.27.2` |
| `graphs` | `2.3.2` |
| `gtk` | `2.2.0` |
| `hive` | `2.2.3` |
| `hooks` | `2.2.0` |
| `html` | `0.15.7` |
| `html_unescape` | `2.0.0` |
| `http` | `1.6.0` |
| `http_multi_server` | `3.2.2` |
| `http_parser` | `4.1.2` |
| `image` | `4.10.1` |
| `image_cropper` | `12.2.1` |
| `image_cropper_for_web` | `7.0.0` |
| `image_cropper_platform_interface` | `8.0.0` |
| `image_picker` | `1.2.3` |
| `image_picker_android` | `0.8.13+23` |
| `image_picker_for_web` | `3.1.1` |
| `image_picker_ios` | `0.8.13+7` |
| `image_picker_linux` | `0.2.2` |
| `image_picker_macos` | `0.2.2+1` |
| `image_picker_platform_interface` | `2.11.1` |
| `image_picker_windows` | `0.2.2` |
| `integration_test` | `0.0.0` |
| `intl` | `0.20.3` |
| `io` | `1.1.0` |
| `is_ios_simulator` | `1.0.1` |
| `jni` | `1.0.3` |
| `jni_flutter` | `1.0.3` |
| `jni_util` | `1.0.0` |
| `jovial_misc` | `0.10.0` |
| `jovial_svg` | `1.1.30` |
| `json_annotation` | `4.12.0` |
| `json_schema_builder` | `0.1.7` |
| `json_serializable` | `6.14.1` |
| `large_file_handler` | `0.5.2` |
| `leak_tracker` | `11.0.2` |
| `leak_tracker_flutter_testing` | `3.0.10` |
| `leak_tracker_testing` | `3.0.2` |
| `local_auth` | `3.0.2` |
| `local_auth_android` | `2.0.10` |
| `local_auth_darwin` | `2.0.4` |
| `local_auth_platform_interface` | `1.1.0` |
| `local_auth_windows` | `2.0.2` |
| `logger` | `2.8.0` |
| `logging` | `1.3.0` |
| `markdown` | `7.3.1` |
| `matcher` | `0.12.20` |
| `material_color_utilities` | `0.13.0` |
| `material_ui` | `1.2.0` |
| `meta` | `1.19.0` |
| `mime` | `2.1.0` |
| `mobile_scanner` | `7.4.1` |

[Version guide](/reference/repository/versions).

# Dart locked dependencies 3
Source: https://docs.tuturuuu.com/reference/repository/dart-dependencies-3

Resolved Dart package versions in the maintained mobile workspace.

| Package | Locked version |
| - | - |
| `mocktail` | `1.0.5` |
| `mutex` | `3.1.0` |
| `nested` | `1.0.0` |
| `nm` | `0.5.0` |
| `node_preamble` | `2.0.2` |
| `objective_c` | `9.5.0` |
| `octo_image` | `2.1.0` |
| `package_config` | `2.2.0` |
| `package_info_plus` | `10.2.1` |
| `package_info_plus_platform_interface` | `4.1.0` |
| `passkeys` | `2.23.1` |
| `passkeys_android` | `2.14.1` |
| `passkeys_darwin` | `0.4.5` |
| `passkeys_doctor` | `1.6.2` |
| `passkeys_platform_interface` | `2.10.0` |
| `passkeys_web` | `2.10.1` |
| `passkeys_windows` | `0.1.5` |
| `path` | `1.9.1` |
| `path_parsing` | `1.1.0` |
| `path_provider` | `2.1.6` |
| `path_provider_android` | `2.3.1` |
| `path_provider_foundation` | `2.6.0` |
| `path_provider_linux` | `2.2.2` |
| `path_provider_platform_interface` | `2.1.3` |
| `path_provider_windows` | `2.3.0` |
| `permission_handler` | `13.0.2` |
| `permission_handler_android` | `14.1.0` |
| `permission_handler_apple` | `9.6.1` |
| `permission_handler_html` | `0.1.4+1` |
| `permission_handler_platform_interface` | `4.4.1` |
| `permission_handler_windows` | `0.2.2` |
| `petitparser` | `7.0.2` |
| `phonecodes` | `0.0.4` |
| `platform` | `3.2.0` |
| `plugin_platform_interface` | `2.1.8` |
| `pointycastle` | `4.0.0` |
| `pool` | `1.5.3` |
| `posix` | `6.5.2` |
| `postgrest` | `2.9.1` |
| `process` | `5.0.6` |
| `provider` | `6.1.5+1` |
| `pub_semver` | `2.2.1` |
| `pubspec_parse` | `1.6.0` |
| `qr` | `3.0.2` |
| `qr_flutter` | `4.1.0` |
| `quill_native_bridge` | `11.2.0` |
| `quill_native_bridge_android` | `0.0.2` |
| `quill_native_bridge_ios` | `0.0.3` |
| `quill_native_bridge_linux` | `0.0.3` |
| `quill_native_bridge_macos` | `0.0.1` |
| `quill_native_bridge_platform_interface` | `0.0.2+1` |
| `quill_native_bridge_web` | `0.0.2` |
| `quill_native_bridge_windows` | `0.1.0` |
| `quiver` | `3.2.2` |
| `rational` | `2.2.3` |
| `realtime_client` | `2.13.0` |
| `record` | `7.1.1` |
| `record_android` | `2.2.0` |
| `record_ios` | `2.1.1` |
| `record_linux` | `2.1.1` |
| `record_macos` | `2.1.1` |
| `record_platform_interface` | `2.1.0` |
| `record_use` | `1.1.1` |
| `record_web` | `2.1.3` |
| `record_windows` | `2.3.0` |
| `rxdart` | `0.28.0` |
| `shadcn_flutter` | `0.0.54` |
| `share_plus` | `13.3.0` |
| `share_plus_platform_interface` | `7.2.0` |
| `shared_preferences` | `2.5.5` |
| `shared_preferences_android` | `2.4.28` |
| `shared_preferences_foundation` | `2.5.7` |
| `shared_preferences_linux` | `2.4.1` |
| `shared_preferences_platform_interface` | `2.4.2` |
| `shared_preferences_web` | `2.4.3` |
| `shared_preferences_windows` | `2.4.1` |
| `shelf` | `1.4.2` |
| `shelf_packages_handler` | `3.0.2` |
| `shelf_static` | `1.1.3` |
| `shelf_web_socket` | `3.0.0` |
| `sign_in_with_apple` | `8.2.0` |
| `sign_in_with_apple_platform_interface` | `2.0.0` |
| `sign_in_with_apple_web` | `3.0.0` |
| `skeletonizer` | `2.1.3` |
| `sky_engine` | `0.0.0` |
| `source_gen` | `4.2.4` |
| `source_helper` | `1.3.13` |
| `source_map_stack_trace` | `2.1.2` |
| `source_maps` | `0.10.14` |
| `source_span` | `1.10.2` |
| `sqflite` | `2.4.4` |
| `sqflite_android` | `2.4.4` |
| `sqflite_common` | `2.5.12` |
| `sqflite_darwin` | `2.4.4` |
| `sqflite_platform_interface` | `2.4.2` |
| `stack_trace` | `1.12.2` |
| `storage_client` | `2.8.0` |
| `stream_channel` | `2.1.4` |
| `stream_transform` | `2.1.2` |
| `string_scanner` | `1.4.1` |

[Version guide](/reference/repository/versions).

# Dart locked dependencies 4
Source: https://docs.tuturuuu.com/reference/repository/dart-dependencies-4

Resolved Dart package versions in the maintained mobile workspace.

| Package | Locked version |
| - | - |
| `supabase` | `2.16.1` |
| `supabase_common` | `0.1.2` |
| `supabase_flutter` | `2.17.2` |
| `sync_http` | `0.3.1` |
| `synchronized` | `3.4.2` |
| `term_glyph` | `1.2.2` |
| `test` | `1.31.1` |
| `test_api` | `0.7.12` |
| `test_core` | `0.6.18` |
| `timezone` | `0.11.1` |
| `typed_data` | `1.4.0` |
| `universal_io` | `2.3.1` |
| `url_launcher` | `6.3.2` |
| `url_launcher_android` | `6.3.33` |
| `url_launcher_ios` | `6.4.2` |
| `url_launcher_linux` | `3.2.3` |
| `url_launcher_macos` | `3.2.6` |
| `url_launcher_platform_interface` | `2.3.2` |
| `url_launcher_web` | `2.4.3` |
| `url_launcher_windows` | `3.1.6` |
| `uuid` | `4.6.0` |
| `vector_graphics` | `1.2.3` |
| `vector_graphics_codec` | `1.1.13` |
| `vector_graphics_compiler` | `1.3.0` |
| `vector_math` | `2.4.2` |
| `very_good_analysis` | `11.0.0` |
| `video_player` | `2.14.0` |
| `video_player_android` | `2.12.2` |
| `video_player_avfoundation` | `2.12.0` |
| `video_player_platform_interface` | `6.9.0` |
| `video_player_web` | `2.4.0` |
| `vm_service` | `15.3.0` |
| `vsc_quill_delta_to_html` | `1.0.5` |
| `watcher` | `1.2.1` |
| `web` | `1.1.2` |
| `web_socket` | `1.0.1` |
| `web_socket_channel` | `3.0.3` |
| `webdriver` | `3.2.0` |
| `webkit_inspection_protocol` | `1.2.1` |
| `webrtc_interface` | `1.5.1` |
| `win32` | `6.4.0` |
| `win32_registry` | `3.0.3` |
| `windows_file_picker` | `1.3.0` |
| `xdg_directories` | `1.1.0` |
| `xml` | `7.0.1` |
| `yaml` | `3.1.4` |
| `yet_another_json_isolate` | `2.1.1` |

[Version guide](/reference/repository/versions).

# Dependency versions 1
Source: https://docs.tuturuuu.com/reference/repository/dependencies-1

Declared dependency ranges, locked resolutions, and owning workspaces.

[Version guide](/reference/repository/versions). Locked versions include every resolution of each direct dependency, not just one workspace's resolution. Peer declarations do not necessarily install a package.

| Dependency | Declared ranges | Lockfile resolutions | Declaring workspaces |
| - | - | - | - |
| `@ai-sdk/amazon-bedrock` | `^5.0.121` | `5.0.121` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@ai-sdk/anthropic` | `^4.0.85` | `4.0.85` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@ai-sdk/azure` | `^4.0.107` | `4.0.107` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@ai-sdk/cerebras` | `^3.0.75` | `3.0.75` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@ai-sdk/cohere` | `^4.0.66` | `4.0.66` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@ai-sdk/deepgram` | `^3.1.36` | `3.1.36` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@ai-sdk/deepinfra` | `^3.0.75` | `3.0.75` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@ai-sdk/deepseek` | `^3.0.70` | `3.0.70` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@ai-sdk/elevenlabs` | `^3.0.66` | `3.0.66` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@ai-sdk/fal` | `^3.0.66` | `3.0.66` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@ai-sdk/fireworks` | `^3.0.78` | `3.0.78` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@ai-sdk/gateway` | `^4.0.121` | `4.0.121` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@ai-sdk/gladia` | `^3.0.65` | `3.0.65` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@ai-sdk/google` | `^4.0.102` | `4.0.102` | [apps/ai](https://github.com/tutur3u/platform/blob/main/apps/ai/package.json), [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/inventory](https://github.com/tutur3u/platform/blob/main/apps/inventory/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/playground](https://github.com/tutur3u/platform/blob/main/apps/playground/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@ai-sdk/google-vertex` | `^5.0.119` | `5.0.119` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@ai-sdk/groq` | `^4.0.67` | `4.0.67` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@ai-sdk/hume` | `^3.0.65` | `3.0.65` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@ai-sdk/lmnt` | `^3.0.36` | `3.0.36` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@ai-sdk/luma` | `^3.0.66` | `3.0.66` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@ai-sdk/mistral` | `^4.0.69` | `4.0.69` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@ai-sdk/openai` | `^4.0.99` | `4.0.99` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@ai-sdk/openai-compatible` | `^3.0.75` | `3.0.75` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@ai-sdk/perplexity` | `^4.0.52` | `4.0.52` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@ai-sdk/react` | `^4.0.152` | `4.0.152` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@ai-sdk/replicate` | `^3.0.66` | `3.0.66` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@ai-sdk/revai` | `^3.0.65` | `3.0.65` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@ai-sdk/togetherai` | `^3.0.76` | `3.0.76` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@ai-sdk/xai` | `^4.0.59` | `4.0.59` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@aws-sdk/client-s3` | `3.1154.0` | `3.1154.0`, `3.984.0` | [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/storage-core](https://github.com/tutur3u/platform/blob/main/packages/storage-core/package.json) |
| `@aws-sdk/client-ses` | `^3.1154.0` | `3.1154.0` | [packages/email-service](https://github.com/tutur3u/platform/blob/main/packages/email-service/package.json) |
| `@aws-sdk/s3-request-presigner` | `3.1154.0`, `^3.1154.0` | `3.1154.0` | [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/storage-core](https://github.com/tutur3u/platform/blob/main/packages/storage-core/package.json) |
| `@azure/msal-node` | `^7.1.0` | `7.1.1` | [packages/microsoft](https://github.com/tutur3u/platform/blob/main/packages/microsoft/package.json) |
| `@babel/parser` | `7.29.9`, `^7.29.9` | `7.29.2`, `7.29.9` | [.](https://github.com/tutur3u/platform/blob/main/package.json), [packages/sdk](https://github.com/tutur3u/platform/blob/main/packages/sdk/package.json) |
| `@beeper/chat-adapter-matrix` | `^0.2.0` | `0.2.0` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@biomejs/biome` | `2.5.13`, `^2.5.13` | `2.5.13` | [.](https://github.com/tutur3u/platform/blob/main/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json) |
| `@bitbasti/chat-adapter-webex` | `^0.1.0` | `0.1.0` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@blamejs/pki` | `0.9.7` | `0.9.7` | [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json) |
| `@chat-adapter/discord` | `^4.43.0` | `4.43.0` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@chat-adapter/gchat` | `^4.43.0` | `4.43.0` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@chat-adapter/github` | `^4.43.0` | `4.43.0` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@chat-adapter/linear` | `^4.43.0` | `4.43.0` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@chat-adapter/messenger` | `^4.43.0` | `4.43.0` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@chat-adapter/slack` | `^4.43.0` | `4.43.0` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@chat-adapter/state-ioredis` | `^4.43.0` | `4.43.0` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@chat-adapter/state-memory` | `^4.43.0` | `4.43.0` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@chat-adapter/state-pg` | `^4.43.0` | `4.43.0` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@chat-adapter/state-redis` | `^4.43.0` | `4.43.0` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@chat-adapter/teams` | `^4.43.0` | `4.43.0` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@chat-adapter/telegram` | `^4.43.0` | `4.43.0` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@chat-adapter/web` | `^4.43.0` | `4.43.0` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@chat-adapter/whatsapp` | `^4.43.0` | `4.43.0` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@cloudflare/pages-plugin-vercel-og` | `0.1.2` | `0.1.2` | [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json) |
| `@cloudflare/vite-plugin` | `1.64.0` | `1.64.0` | [apps/colab](https://github.com/tutur3u/platform/blob/main/apps/colab/package.json), [apps/coordination](https://github.com/tutur3u/platform/blob/main/apps/coordination/package.json), [apps/cron-control](https://github.com/tutur3u/platform/blob/main/apps/cron-control/package.json), [apps/devbox-control](https://github.com/tutur3u/platform/blob/main/apps/devbox-control/package.json), [apps/meet-realtime](https://github.com/tutur3u/platform/blob/main/apps/meet-realtime/package.json) |
| `@cloudflare/workers-types` | `5.20261022.1`, `^5.20261022.1` | `5.20261022.1` | [apps/apps](https://github.com/tutur3u/platform/blob/main/apps/apps/package.json), [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/colab](https://github.com/tutur3u/platform/blob/main/apps/colab/package.json), [apps/lettin](https://github.com/tutur3u/platform/blob/main/apps/lettin/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/shortener](https://github.com/tutur3u/platform/blob/main/apps/shortener/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json) |
| `@deepgram/sdk` | `^5.15.0` | `5.15.0` | [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `@dnd-kit/core` | `^6.3.1` | `6.3.1` | [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json), [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json) |
| `@dnd-kit/sortable` | `^10.0.0` | `10.0.0` | [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@dnd-kit/utilities` | `^3.2.2` | `3.2.2` | [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@dqcai/vn-lunar` | `^1.0.1` | `1.0.1` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@electric-sql/pglite` | `0.5.11` | `0.5.11` | [apps/database](https://github.com/tutur3u/platform/blob/main/apps/database/package.json) |
| `@electric-sql/pglite-pgtap` | `0.0.12` | `0.0.12` | [apps/database](https://github.com/tutur3u/platform/blob/main/apps/database/package.json) |
| `@emotion/react` | `^11.14.0` | `11.14.0` | [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `@emotion/server` | `^11.11.0` | `11.11.0` | [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `@excalidraw/excalidraw` | `^0.18.1` | `0.18.1` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `@fontsource-variable/noto-sans` | `5.3.0` | `5.3.0` | [apps/apps](https://github.com/tutur3u/platform/blob/main/apps/apps/package.json), [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json) |
| `@formatjs/intl-localematcher` | `^0.9.0` | `0.6.2`, `0.8.14`, `0.9.0` | [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/chat](https://github.com/tutur3u/platform/blob/main/apps/chat/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn/package.json), [apps/lettin](https://github.com/tutur3u/platform/blob/main/apps/lettin/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/pay](https://github.com/tutur3u/platform/blob/main/apps/pay/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json) |
| `@google/genai` | `^2.30.0` | `2.30.0` | [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json) |
| `@google/generative-ai` | `^0.24.1` | `0.24.1` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `@gsap/react` | `^2.1.2` | `2.1.2` | [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json) |
| `@hookform/resolvers` | `^5.9.2` | `5.9.2` | [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@js-temporal/polyfill` | `^0.5.1` | `0.5.1` | [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json) |
| `@json-render/core` | `^0.20.0` | `0.20.0` | [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json), [packages/mind-ui](https://github.com/tutur3u/platform/blob/main/packages/mind-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@json-render/react` | `^0.20.0` | `0.20.0` | [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json), [packages/mind-ui](https://github.com/tutur3u/platform/blob/main/packages/mind-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@lingual/i18n-check` | `0.9.5` | `0.9.5` | [.](https://github.com/tutur3u/platform/blob/main/package.json) |
| `@liveblocks/chat-sdk-adapter` | `^3.24.4` | `3.24.4` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@lucide/lab` | `^0.7.0` | `0.7.0` | [packages/icons](https://github.com/tutur3u/platform/blob/main/packages/icons/package.json) |
| `@mantine/charts` | `^9.7.3` | `9.7.3` | [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `@mantine/core` | `^9.7.3` | `9.7.3` | [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `@mantine/hooks` | `^9.7.3` | `9.7.3` | [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `@marsidev/react-turnstile` | `^1.6.2` | `1.6.2` | [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `@microsoft/microsoft-graph-client` | `^3.0.7` | `3.0.7` | [packages/microsoft](https://github.com/tutur3u/platform/blob/main/packages/microsoft/package.json) |
| `@modelcontextprotocol/sdk` | `1.32.1` | `1.32.1` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `@monaco-editor/react` | `4.7.0`, `^4.7.0` | `4.7.0` | [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn/package.json), [packages/programming-ui](https://github.com/tutur3u/platform/blob/main/packages/programming-ui/package.json) |
| `@next/bundle-analyzer` | `^16.4.2` | `16.4.2` | [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `@next/playwright` | `^16.4.2` | `16.4.2` | [apps/inventory](https://github.com/tutur3u/platform/blob/main/apps/inventory/package.json) |
| `@noble/ciphers` | `^2.4.0` | `1.3.0`, `2.4.0` | [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json) |
| `@noble/hashes` | `^2.4.0` | `1.8.0`, `2.4.0` | [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json) |
| `@node-saml/node-saml` | `5.1.0` | `5.1.0` | [packages/sso](https://github.com/tutur3u/platform/blob/main/packages/sso/package.json) |
| `@octokit/auth-app` | `^8.3.1` | `8.3.1` | [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `@octokit/rest` | `^22.0.1` | `22.0.1` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@opennextjs/cloudflare` | `^1.20.6`, `https://registry.npmjs.org/@opennextjs/cloudflare/-/cloudflare-1.20.6.tgz` | `1.20.6` | [apps/lettin](https://github.com/tutur3u/platform/blob/main/apps/lettin/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json) |
| `@playwright/test` | `^1.64.1` | `1.64.1` | [apps/colab](https://github.com/tutur3u/platform/blob/main/apps/colab/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [apps/inventory](https://github.com/tutur3u/platform/blob/main/apps/inventory/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `@polar-sh/checkout` | `^0.4.1` | `0.4.1` | [packages/payment](https://github.com/tutur3u/platform/blob/main/packages/payment/package.json) |
| `@polar-sh/nextjs` | `^0.9.6` | `0.9.6` | [packages/payment](https://github.com/tutur3u/platform/blob/main/packages/payment/package.json) |
| `@polar-sh/sdk` | `0.49.0` | `0.49.0` | [packages/payment](https://github.com/tutur3u/platform/blob/main/packages/payment/package.json) |
| `@radix-ui/react-accordion` | `^1.3.1` | `1.3.1` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@radix-ui/react-alert-dialog` | `^1.2.1` | `1.2.1` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@radix-ui/react-aspect-ratio` | `^1.2.0` | `1.2.0` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@radix-ui/react-avatar` | `^1.3.1` | `1.3.1` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@radix-ui/react-checkbox` | `^1.4.1` | `1.4.1` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |

# Dependency versions 2
Source: https://docs.tuturuuu.com/reference/repository/dependencies-2

Declared dependency ranges, locked resolutions, and owning workspaces.

| Dependency | Declared ranges | Lockfile resolutions | Declaring workspaces |
| - | - | - | - |
| `@radix-ui/react-collapsible` | `^1.2.1` | `1.2.1` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@radix-ui/react-context-menu` | `^2.4.1` | `2.4.1` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@radix-ui/react-dialog` | `^1.3.1` | `1.3.1` | [packages/satellite](https://github.com/tutur3u/platform/blob/main/packages/satellite/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@radix-ui/react-dropdown-menu` | `^2.2.1` | `2.2.1` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@radix-ui/react-hover-card` | `^1.2.1` | `1.2.1` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@radix-ui/react-label` | `^2.1.17` | `2.1.17` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@radix-ui/react-menubar` | `^1.2.1` | `1.2.1` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@radix-ui/react-navigation-menu` | `^1.4.1` | `1.4.1` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@radix-ui/react-popover` | `^1.3.1` | `1.1.6`, `1.3.1` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@radix-ui/react-progress` | `^1.2.1` | `1.2.1` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@radix-ui/react-radio-group` | `^1.5.1` | `1.5.1` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@radix-ui/react-scroll-area` | `^1.4.0` | `1.4.0` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@radix-ui/react-select` | `^2.4.1` | `2.4.1` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@radix-ui/react-separator` | `^1.2.0` | `1.2.0` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@radix-ui/react-slider` | `^1.6.1` | `1.6.1` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@radix-ui/react-slot` | `^1.5.0` | `1.0.1`, `1.1.2`, `1.5.0` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@radix-ui/react-switch` | `^1.4.1` | `1.4.1` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@radix-ui/react-tabs` | `^1.2.1` | `1.0.2`, `1.2.1` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@radix-ui/react-toast` | `^1.3.1` | `1.3.1` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@radix-ui/react-toggle` | `^1.2.1` | `1.2.1` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@radix-ui/react-toggle-group` | `^1.2.1` | `1.2.1` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@radix-ui/react-tooltip` | `^1.4.1` | `1.4.1` | [packages/satellite](https://github.com/tutur3u/platform/blob/main/packages/satellite/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@react-email/components` | `^1.0.12` | `1.0.12` | [packages/transactional](https://github.com/tutur3u/platform/blob/main/packages/transactional/package.json) |
| `@react-email/preview-server` | `^5.2.10` | `5.2.10` | [packages/transactional](https://github.com/tutur3u/platform/blob/main/packages/transactional/package.json) |
| `@react-email/render` | `^2.1.1` | `2.0.6`, `2.1.1` | [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/transactional](https://github.com/tutur3u/platform/blob/main/packages/transactional/package.json) |
| `@react-three/drei` | `^10.7.9` | `10.7.9` | [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [packages/hive-ui](https://github.com/tutur3u/platform/blob/main/packages/hive-ui/package.json) |
| `@react-three/fiber` | `^9.8.2` | `9.8.2` | [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [packages/hive-ui](https://github.com/tutur3u/platform/blob/main/packages/hive-ui/package.json) |
| `@resend/chat-sdk-adapter` | `^0.3.0` | `0.3.0` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@streamdown/cjk` | `^1.0.4` | `1.0.4` | [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json), [packages/mind-ui](https://github.com/tutur3u/platform/blob/main/packages/mind-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@streamdown/code` | `^1.1.1` | `1.1.1` | [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json), [packages/mind-ui](https://github.com/tutur3u/platform/blob/main/packages/mind-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@streamdown/math` | `^1.0.3` | `1.0.3` | [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json), [packages/mind-ui](https://github.com/tutur3u/platform/blob/main/packages/mind-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@streamdown/mermaid` | `^1.0.3` | `1.0.3` | [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json), [packages/mind-ui](https://github.com/tutur3u/platform/blob/main/packages/mind-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@supabase/ssr` | `^0.12.7` | `0.12.7` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/supabase](https://github.com/tutur3u/platform/blob/main/packages/supabase/package.json) |
| `@supabase/supabase-js` | `2.117.1`, `^2.117.1` | `2.117.1` | [apps/database](https://github.com/tutur3u/platform/blob/main/apps/database/package.json), [apps/inventory](https://github.com/tutur3u/platform/blob/main/apps/inventory/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/supabase](https://github.com/tutur3u/platform/blob/main/packages/supabase/package.json), [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json) |
| `@tailwindcss/postcss` | `^4.3.3` | `4.3.3` | [apps/ai](https://github.com/tutur3u/platform/blob/main/apps/ai/package.json), [apps/apps](https://github.com/tutur3u/platform/blob/main/apps/apps/package.json), [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/chat](https://github.com/tutur3u/platform/blob/main/apps/chat/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/external](https://github.com/tutur3u/platform/blob/main/apps/external/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/inventory](https://github.com/tutur3u/platform/blob/main/apps/inventory/package.json), [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn/package.json), [apps/lettin](https://github.com/tutur3u/platform/blob/main/apps/lettin/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/pay](https://github.com/tutur3u/platform/blob/main/apps/pay/package.json), [apps/playground](https://github.com/tutur3u/platform/blob/main/apps/playground/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/shortener](https://github.com/tutur3u/platform/blob/main/apps/shortener/package.json), [apps/storefront](https://github.com/tutur3u/platform/blob/main/apps/storefront/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/tools](https://github.com/tutur3u/platform/blob/main/apps/tools/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@tailwindcss/typography` | `^0.5.20` | `0.5.20` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@tailwindcss/vite` | `4.3.3`, `^4.3.3` | `4.3.3` | [apps/apps](https://github.com/tutur3u/platform/blob/main/apps/apps/package.json), [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/colab](https://github.com/tutur3u/platform/blob/main/apps/colab/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/shortener](https://github.com/tutur3u/platform/blob/main/apps/shortener/package.json) |
| `@tanstack/react-hotkeys` | `^0.10.0` | `0.10.0` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@tanstack/react-pacer` | `^0.23.0` | `0.23.0` | [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@tanstack/react-query` | `5.104.5`, `^5.101.2`, `^5.104.5` | `5.104.5` | [apps/ai](https://github.com/tutur3u/platform/blob/main/apps/ai/package.json), [apps/apps](https://github.com/tutur3u/platform/blob/main/apps/apps/package.json), [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/chat](https://github.com/tutur3u/platform/blob/main/apps/chat/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/colab](https://github.com/tutur3u/platform/blob/main/apps/colab/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/external](https://github.com/tutur3u/platform/blob/main/apps/external/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/inventory](https://github.com/tutur3u/platform/blob/main/apps/inventory/package.json), [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn/package.json), [apps/lettin](https://github.com/tutur3u/platform/blob/main/apps/lettin/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/pay](https://github.com/tutur3u/platform/blob/main/apps/pay/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/storefront](https://github.com/tutur3u/platform/blob/main/apps/storefront/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/tools](https://github.com/tutur3u/platform/blob/main/apps/tools/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/hive-ui](https://github.com/tutur3u/platform/blob/main/packages/hive-ui/package.json), [packages/hooks](https://github.com/tutur3u/platform/blob/main/packages/hooks/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json), [packages/mind-ui](https://github.com/tutur3u/platform/blob/main/packages/mind-ui/package.json), [packages/programming-ui](https://github.com/tutur3u/platform/blob/main/packages/programming-ui/package.json), [packages/satellite](https://github.com/tutur3u/platform/blob/main/packages/satellite/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json), [packages/users-ui](https://github.com/tutur3u/platform/blob/main/packages/users-ui/package.json), [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json) |
| `@tanstack/react-query-devtools` | `5.104.5`, `^5.104.5` | `5.104.5` | [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/chat](https://github.com/tutur3u/platform/blob/main/apps/chat/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/satellite](https://github.com/tutur3u/platform/blob/main/packages/satellite/package.json) |
| `@tanstack/react-router` | `1.170.45` | `1.170.41`, `1.170.45` | [apps/apps](https://github.com/tutur3u/platform/blob/main/apps/apps/package.json), [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/shortener](https://github.com/tutur3u/platform/blob/main/apps/shortener/package.json) |
| `@tanstack/react-start` | `1.169.3` | `1.168.60`, `1.169.3` | [apps/apps](https://github.com/tutur3u/platform/blob/main/apps/apps/package.json), [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/shortener](https://github.com/tutur3u/platform/blob/main/apps/shortener/package.json) |
| `@tanstack/react-table` | `^9.0.0`, `^9.2.3`, `^9.3.1` | `9.3.1` | [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/inventory](https://github.com/tutur3u/platform/blob/main/apps/inventory/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@tanstack/react-virtual` | `^3.14.21` | `3.14.21` | [apps/chat](https://github.com/tutur3u/platform/blob/main/apps/chat/package.json), [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@testing-library/jest-dom` | `^7.0.1` | `7.0.1` | [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/tools](https://github.com/tutur3u/platform/blob/main/apps/tools/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/masonry](https://github.com/tutur3u/platform/blob/main/packages/masonry/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@testing-library/react` | `16.3.3`, `^16.3.3` | `16.3.3` | [apps/apps](https://github.com/tutur3u/platform/blob/main/apps/apps/package.json), [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/chat](https://github.com/tutur3u/platform/blob/main/apps/chat/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/inventory](https://github.com/tutur3u/platform/blob/main/apps/inventory/package.json), [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/pay](https://github.com/tutur3u/platform/blob/main/apps/pay/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/shortener](https://github.com/tutur3u/platform/blob/main/apps/shortener/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/tools](https://github.com/tutur3u/platform/blob/main/apps/tools/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/editor](https://github.com/tutur3u/platform/blob/main/packages/editor/package.json), [packages/hive-ui](https://github.com/tutur3u/platform/blob/main/packages/hive-ui/package.json), [packages/masonry](https://github.com/tutur3u/platform/blob/main/packages/masonry/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json), [packages/mind-ui](https://github.com/tutur3u/platform/blob/main/packages/mind-ui/package.json), [packages/satellite](https://github.com/tutur3u/platform/blob/main/packages/satellite/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json), [packages/users-ui](https://github.com/tutur3u/platform/blob/main/packages/users-ui/package.json) |
| `@tiptap/core` | `3.32.0` | `3.31.3`, `3.32.0` | [packages/editor](https://github.com/tutur3u/platform/blob/main/packages/editor/package.json), [packages/sdk](https://github.com/tutur3u/platform/blob/main/packages/sdk/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json), [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json) |
| `@tiptap/extension-collaboration` | `3.32.0` | `3.32.0` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@tiptap/extension-collaboration-caret` | `3.32.0` | `3.32.0` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@tiptap/extension-color` | `3.32.0` | `3.32.0` | [packages/editor](https://github.com/tutur3u/platform/blob/main/packages/editor/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@tiptap/extension-details` | `3.32.0` | `3.32.0` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@tiptap/extension-drag-handle` | `3.32.0` | `3.32.0` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@tiptap/extension-drag-handle-react` | `3.32.0` | `3.32.0` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@tiptap/extension-highlight` | `3.32.0` | `3.32.0` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/editor](https://github.com/tutur3u/platform/blob/main/packages/editor/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@tiptap/extension-horizontal-rule` | `3.32.0` | `3.32.0` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@tiptap/extension-image` | `3.32.0` | `3.32.0` | [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [packages/editor](https://github.com/tutur3u/platform/blob/main/packages/editor/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@tiptap/extension-link` | `3.32.0` | `3.32.0` | [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/editor](https://github.com/tutur3u/platform/blob/main/packages/editor/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@tiptap/extension-list` | `3.32.0` | `3.32.0` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@tiptap/extension-node-range` | `3.32.0` | `3.32.0` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@tiptap/extension-placeholder` | `3.32.0` | `3.32.0` | [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [packages/editor](https://github.com/tutur3u/platform/blob/main/packages/editor/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@tiptap/extension-strike` | `3.32.0` | `3.32.0` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@tiptap/extension-subscript` | `3.32.0` | `3.32.0` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@tiptap/extension-superscript` | `3.32.0` | `3.32.0` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@tiptap/extension-table` | `3.32.0` | `3.32.0` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@tiptap/extension-table-cell` | `3.32.0` | `3.32.0` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@tiptap/extension-table-header` | `3.32.0` | `3.32.0` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@tiptap/extension-table-row` | `3.32.0` | `3.32.0` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@tiptap/extension-text-align` | `3.32.0` | `3.32.0` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/editor](https://github.com/tutur3u/platform/blob/main/packages/editor/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@tiptap/extension-text-style` | `3.32.0` | `3.32.0` | [packages/editor](https://github.com/tutur3u/platform/blob/main/packages/editor/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@tiptap/extension-underline` | `3.32.0` | `3.32.0` | [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `@tiptap/extension-youtube` | `3.32.0` | `3.32.0` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@tiptap/html` | `3.32.0` | `3.32.0` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `@tiptap/pm` | `3.32.0` | `3.31.3`, `3.32.0` | [packages/editor](https://github.com/tutur3u/platform/blob/main/packages/editor/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@tiptap/react` | `3.32.0`, `^3.32.0` | `3.31.3`, `3.32.0` | [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/lettin](https://github.com/tutur3u/platform/blob/main/apps/lettin/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/editor](https://github.com/tutur3u/platform/blob/main/packages/editor/package.json), [packages/sdk](https://github.com/tutur3u/platform/blob/main/packages/sdk/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/types](https://github.com/tutur3u/platform/blob/main/packages/types/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json), [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json) |
| `@tiptap/starter-kit` | `3.32.0` | `3.32.0` | [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/lettin](https://github.com/tutur3u/platform/blob/main/apps/lettin/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/editor](https://github.com/tutur3u/platform/blob/main/packages/editor/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@trpc/client` | `^11.19.0` | `11.19.0` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `@trpc/react-query` | `^11.19.0` | `11.19.0` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `@trpc/server` | `^11.19.0` | `11.19.0` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `@types/bcrypt` | `^6.0.0` | `6.0.0` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `@types/canvas-confetti` | `^1.9.0` | `1.9.0` | [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `@types/debug` | `^4.1.13` | `4.1.13` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@types/diff` | `^8.0.0` | `8.0.0` | [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json) |
| `@types/dompurify` | `^3.2.0` | `3.2.0` | [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `@types/html2canvas` | `^1.0.0` | `1.0.0` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@types/js-cookie` | `^3.0.6` | `3.0.6` | [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `@types/lodash` | `^4.17.27` | `4.17.27` | [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@types/negotiator` | `^0.6.5` | `0.6.5` | [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/chat](https://github.com/tutur3u/platform/blob/main/apps/chat/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn/package.json), [apps/lettin](https://github.com/tutur3u/platform/blob/main/apps/lettin/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/pay](https://github.com/tutur3u/platform/blob/main/apps/pay/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json) |
| `@types/node` | `26.6.5`, `^26.6.5` | `18.19.130`, `24.19.2`, `26.6.5` | [.](https://github.com/tutur3u/platform/blob/main/package.json), [apps/ai](https://github.com/tutur3u/platform/blob/main/apps/ai/package.json), [apps/apps](https://github.com/tutur3u/platform/blob/main/apps/apps/package.json), [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/chat](https://github.com/tutur3u/platform/blob/main/apps/chat/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/external](https://github.com/tutur3u/platform/blob/main/apps/external/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/inventory](https://github.com/tutur3u/platform/blob/main/apps/inventory/package.json), [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn/package.json), [apps/lettin](https://github.com/tutur3u/platform/blob/main/apps/lettin/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/pay](https://github.com/tutur3u/platform/blob/main/apps/pay/package.json), [apps/playground](https://github.com/tutur3u/platform/blob/main/apps/playground/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/shortener](https://github.com/tutur3u/platform/blob/main/apps/shortener/package.json), [apps/storefront](https://github.com/tutur3u/platform/blob/main/apps/storefront/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/tools](https://github.com/tutur3u/platform/blob/main/apps/tools/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json), [packages/apis](https://github.com/tutur3u/platform/blob/main/packages/apis/package.json), [packages/auth](https://github.com/tutur3u/platform/blob/main/packages/auth/package.json), [packages/devbox](https://github.com/tutur3u/platform/blob/main/packages/devbox/package.json), [packages/education-core](https://github.com/tutur3u/platform/blob/main/packages/education-core/package.json), [packages/email-service](https://github.com/tutur3u/platform/blob/main/packages/email-service/package.json), [packages/finance-core](https://github.com/tutur3u/platform/blob/main/packages/finance-core/package.json), [packages/games](https://github.com/tutur3u/platform/blob/main/packages/games/package.json), [packages/google](https://github.com/tutur3u/platform/blob/main/packages/google/package.json), [packages/hive-ui](https://github.com/tutur3u/platform/blob/main/packages/hive-ui/package.json), [packages/hooks](https://github.com/tutur3u/platform/blob/main/packages/hooks/package.json), [packages/internal-api](https://github.com/tutur3u/platform/blob/main/packages/internal-api/package.json), [packages/inventory-core](https://github.com/tutur3u/platform/blob/main/packages/inventory-core/package.json), [packages/masonry](https://github.com/tutur3u/platform/blob/main/packages/masonry/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json), [packages/microsoft](https://github.com/tutur3u/platform/blob/main/packages/microsoft/package.json), [packages/mind-core](https://github.com/tutur3u/platform/blob/main/packages/mind-core/package.json), [packages/mind-ui](https://github.com/tutur3u/platform/blob/main/packages/mind-ui/package.json), [packages/offline](https://github.com/tutur3u/platform/blob/main/packages/offline/package.json), [packages/payment-core](https://github.com/tutur3u/platform/blob/main/packages/payment-core/package.json), [packages/realtime](https://github.com/tutur3u/platform/blob/main/packages/realtime/package.json), [packages/satellite](https://github.com/tutur3u/platform/blob/main/packages/satellite/package.json), [packages/sdk](https://github.com/tutur3u/platform/blob/main/packages/sdk/package.json), [packages/sso](https://github.com/tutur3u/platform/blob/main/packages/sso/package.json), [packages/storage-core](https://github.com/tutur3u/platform/blob/main/packages/storage-core/package.json), [packages/supabase](https://github.com/tutur3u/platform/blob/main/packages/supabase/package.json), [packages/tasks-api](https://github.com/tutur3u/platform/blob/main/packages/tasks-api/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/transactional](https://github.com/tutur3u/platform/blob/main/packages/transactional/package.json), [packages/turnstile](https://github.com/tutur3u/platform/blob/main/packages/turnstile/package.json), [packages/types](https://github.com/tutur3u/platform/blob/main/packages/types/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json), [packages/users-core](https://github.com/tutur3u/platform/blob/main/packages/users-core/package.json), [packages/users-ui](https://github.com/tutur3u/platform/blob/main/packages/users-ui/package.json), [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json), [packages/vercel](https://github.com/tutur3u/platform/blob/main/packages/vercel/package.json), [packages/workflows](https://github.com/tutur3u/platform/blob/main/packages/workflows/package.json) |
| `@types/papaparse` | `^5.5.2` | `5.5.2` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `@types/qrcode` | `^1.5.6` | `1.5.6` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@types/react` | `^19.2.18`, `~19.2.18` | `19.2.18` | [apps/ai](https://github.com/tutur3u/platform/blob/main/apps/ai/package.json), [apps/apps](https://github.com/tutur3u/platform/blob/main/apps/apps/package.json), [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/chat](https://github.com/tutur3u/platform/blob/main/apps/chat/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/colab](https://github.com/tutur3u/platform/blob/main/apps/colab/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/external](https://github.com/tutur3u/platform/blob/main/apps/external/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/inventory](https://github.com/tutur3u/platform/blob/main/apps/inventory/package.json), [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn/package.json), [apps/lettin](https://github.com/tutur3u/platform/blob/main/apps/lettin/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/pay](https://github.com/tutur3u/platform/blob/main/apps/pay/package.json), [apps/playground](https://github.com/tutur3u/platform/blob/main/apps/playground/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/shortener](https://github.com/tutur3u/platform/blob/main/apps/shortener/package.json), [apps/storefront](https://github.com/tutur3u/platform/blob/main/apps/storefront/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/tools](https://github.com/tutur3u/platform/blob/main/apps/tools/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json), [packages/apis](https://github.com/tutur3u/platform/blob/main/packages/apis/package.json), [packages/auth](https://github.com/tutur3u/platform/blob/main/packages/auth/package.json), [packages/editor](https://github.com/tutur3u/platform/blob/main/packages/editor/package.json), [packages/games](https://github.com/tutur3u/platform/blob/main/packages/games/package.json), [packages/google](https://github.com/tutur3u/platform/blob/main/packages/google/package.json), [packages/hive-ui](https://github.com/tutur3u/platform/blob/main/packages/hive-ui/package.json), [packages/hooks](https://github.com/tutur3u/platform/blob/main/packages/hooks/package.json), [packages/masonry](https://github.com/tutur3u/platform/blob/main/packages/masonry/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json), [packages/mind-ui](https://github.com/tutur3u/platform/blob/main/packages/mind-ui/package.json), [packages/offline](https://github.com/tutur3u/platform/blob/main/packages/offline/package.json), [packages/programming-ui](https://github.com/tutur3u/platform/blob/main/packages/programming-ui/package.json), [packages/satellite](https://github.com/tutur3u/platform/blob/main/packages/satellite/package.json), [packages/supabase](https://github.com/tutur3u/platform/blob/main/packages/supabase/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/transactional](https://github.com/tutur3u/platform/blob/main/packages/transactional/package.json), [packages/types](https://github.com/tutur3u/platform/blob/main/packages/types/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json), [packages/users-core](https://github.com/tutur3u/platform/blob/main/packages/users-core/package.json), [packages/users-ui](https://github.com/tutur3u/platform/blob/main/packages/users-ui/package.json), [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json), [packages/vercel](https://github.com/tutur3u/platform/blob/main/packages/vercel/package.json) |
| `@types/react-dom` | `~19.2.7` | `19.2.7` | [apps/ai](https://github.com/tutur3u/platform/blob/main/apps/ai/package.json), [apps/apps](https://github.com/tutur3u/platform/blob/main/apps/apps/package.json), [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/chat](https://github.com/tutur3u/platform/blob/main/apps/chat/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/colab](https://github.com/tutur3u/platform/blob/main/apps/colab/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/external](https://github.com/tutur3u/platform/blob/main/apps/external/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/inventory](https://github.com/tutur3u/platform/blob/main/apps/inventory/package.json), [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn/package.json), [apps/lettin](https://github.com/tutur3u/platform/blob/main/apps/lettin/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/pay](https://github.com/tutur3u/platform/blob/main/apps/pay/package.json), [apps/playground](https://github.com/tutur3u/platform/blob/main/apps/playground/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/shortener](https://github.com/tutur3u/platform/blob/main/apps/shortener/package.json), [apps/storefront](https://github.com/tutur3u/platform/blob/main/apps/storefront/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/tools](https://github.com/tutur3u/platform/blob/main/apps/tools/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/auth](https://github.com/tutur3u/platform/blob/main/packages/auth/package.json), [packages/hive-ui](https://github.com/tutur3u/platform/blob/main/packages/hive-ui/package.json), [packages/masonry](https://github.com/tutur3u/platform/blob/main/packages/masonry/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json), [packages/mind-ui](https://github.com/tutur3u/platform/blob/main/packages/mind-ui/package.json), [packages/satellite](https://github.com/tutur3u/platform/blob/main/packages/satellite/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json), [packages/users-ui](https://github.com/tutur3u/platform/blob/main/packages/users-ui/package.json) |
| `@types/react-resizable` | `^4.0.0` | `4.0.0` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@types/react-syntax-highlighter` | `^15.5.13` | `15.5.13` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@types/sanitize-html` | `^2.16.2` | `2.16.2` | [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/email-service](https://github.com/tutur3u/platform/blob/main/packages/email-service/package.json) |
| `@types/three` | `^0.186.0` | `0.186.0` | [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [packages/hive-ui](https://github.com/tutur3u/platform/blob/main/packages/hive-ui/package.json) |
| `@types/uuid` | `^11.0.0` | `11.0.0` | [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `@typescript/native-preview` | `7.0.0-dev.20260707.2` | `7.0.0-dev.20260707.2` | [apps/ai](https://github.com/tutur3u/platform/blob/main/apps/ai/package.json), [apps/chat](https://github.com/tutur3u/platform/blob/main/apps/chat/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/external](https://github.com/tutur3u/platform/blob/main/apps/external/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/inventory](https://github.com/tutur3u/platform/blob/main/apps/inventory/package.json), [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn/package.json), [apps/lettin](https://github.com/tutur3u/platform/blob/main/apps/lettin/package.json), [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/pay](https://github.com/tutur3u/platform/blob/main/apps/pay/package.json), [apps/playground](https://github.com/tutur3u/platform/blob/main/apps/playground/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/storefront](https://github.com/tutur3u/platform/blob/main/apps/storefront/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/tools](https://github.com/tutur3u/platform/blob/main/apps/tools/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `@typescript/typescript-aix-ppc64` | `7.0.2` | `7.0.2` | [.](https://github.com/tutur3u/platform/blob/main/package.json) |

# Dependency versions 3
Source: https://docs.tuturuuu.com/reference/repository/dependencies-3

Declared dependency ranges, locked resolutions, and owning workspaces.

| Dependency | Declared ranges | Lockfile resolutions | Declaring workspaces |
| - | - | - | - |
| `@typescript/typescript-darwin-arm64` | `7.0.2` | `7.0.2` | [.](https://github.com/tutur3u/platform/blob/main/package.json) |
| `@typescript/typescript-darwin-x64` | `7.0.2` | `7.0.2` | [.](https://github.com/tutur3u/platform/blob/main/package.json) |
| `@typescript/typescript-freebsd-arm64` | `7.0.2` | `7.0.2` | [.](https://github.com/tutur3u/platform/blob/main/package.json) |
| `@typescript/typescript-freebsd-x64` | `7.0.2` | `7.0.2` | [.](https://github.com/tutur3u/platform/blob/main/package.json) |
| `@typescript/typescript-linux-arm` | `7.0.2` | `7.0.2` | [.](https://github.com/tutur3u/platform/blob/main/package.json) |
| `@typescript/typescript-linux-arm64` | `7.0.2` | `7.0.2` | [.](https://github.com/tutur3u/platform/blob/main/package.json) |
| `@typescript/typescript-linux-loong64` | `7.0.2` | `7.0.2` | [.](https://github.com/tutur3u/platform/blob/main/package.json) |
| `@typescript/typescript-linux-mips64el` | `7.0.2` | `7.0.2` | [.](https://github.com/tutur3u/platform/blob/main/package.json) |
| `@typescript/typescript-linux-ppc64` | `7.0.2` | `7.0.2` | [.](https://github.com/tutur3u/platform/blob/main/package.json) |
| `@typescript/typescript-linux-riscv64` | `7.0.2` | `7.0.2` | [.](https://github.com/tutur3u/platform/blob/main/package.json) |
| `@typescript/typescript-linux-s390x` | `7.0.2` | `7.0.2` | [.](https://github.com/tutur3u/platform/blob/main/package.json) |
| `@typescript/typescript-linux-x64` | `7.0.2` | `7.0.2` | [.](https://github.com/tutur3u/platform/blob/main/package.json) |
| `@typescript/typescript-netbsd-arm64` | `7.0.2` | `7.0.2` | [.](https://github.com/tutur3u/platform/blob/main/package.json) |
| `@typescript/typescript-netbsd-x64` | `7.0.2` | `7.0.2` | [.](https://github.com/tutur3u/platform/blob/main/package.json) |
| `@typescript/typescript-openbsd-arm64` | `7.0.2` | `7.0.2` | [.](https://github.com/tutur3u/platform/blob/main/package.json) |
| `@typescript/typescript-openbsd-x64` | `7.0.2` | `7.0.2` | [.](https://github.com/tutur3u/platform/blob/main/package.json) |
| `@typescript/typescript-sunos-x64` | `7.0.2` | `7.0.2` | [.](https://github.com/tutur3u/platform/blob/main/package.json) |
| `@typescript/typescript-win32-arm64` | `7.0.2` | `7.0.2` | [.](https://github.com/tutur3u/platform/blob/main/package.json) |
| `@typescript/typescript-win32-x64` | `7.0.2` | `7.0.2` | [.](https://github.com/tutur3u/platform/blob/main/package.json) |
| `@upstash/cli` | `^1.5.0` | `1.5.0` | [apps/redis](https://github.com/tutur3u/platform/blob/main/apps/redis/package.json) |
| `@upstash/qstash` | `^2.12.1` | `2.12.1` | [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `@upstash/ratelimit` | `^2.2.0` | `2.2.0` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json) |
| `@upstash/redis` | `^1.39.0` | `1.39.0` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/email-service](https://github.com/tutur3u/platform/blob/main/packages/email-service/package.json), [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json) |
| `@vercel/analytics` | `^2.0.1` | `2.0.1` | [packages/vercel](https://github.com/tutur3u/platform/blob/main/packages/vercel/package.json) |
| `@vercel/functions` | `^3.10.2` | `3.10.2` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `@vercel/sandbox` | `^3.8.0` | `3.8.0` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `@vercel/speed-insights` | `^2.0.0` | `2.0.0` | [packages/vercel](https://github.com/tutur3u/platform/blob/main/packages/vercel/package.json) |
| `@vitejs/plugin-react` | `6.1.2`, `^6.1.2` | `6.1.2` | [apps/apps](https://github.com/tutur3u/platform/blob/main/apps/apps/package.json), [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/chat](https://github.com/tutur3u/platform/blob/main/apps/chat/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/colab](https://github.com/tutur3u/platform/blob/main/apps/colab/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/pay](https://github.com/tutur3u/platform/blob/main/apps/pay/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/shortener](https://github.com/tutur3u/platform/blob/main/apps/shortener/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/tools](https://github.com/tutur3u/platform/blob/main/apps/tools/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/games](https://github.com/tutur3u/platform/blob/main/packages/games/package.json), [packages/google](https://github.com/tutur3u/platform/blob/main/packages/google/package.json), [packages/hive-ui](https://github.com/tutur3u/platform/blob/main/packages/hive-ui/package.json), [packages/hooks](https://github.com/tutur3u/platform/blob/main/packages/hooks/package.json), [packages/inventory-core](https://github.com/tutur3u/platform/blob/main/packages/inventory-core/package.json), [packages/masonry](https://github.com/tutur3u/platform/blob/main/packages/masonry/package.json), [packages/mind-ui](https://github.com/tutur3u/platform/blob/main/packages/mind-ui/package.json), [packages/satellite](https://github.com/tutur3u/platform/blob/main/packages/satellite/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json), [packages/users-ui](https://github.com/tutur3u/platform/blob/main/packages/users-ui/package.json), [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json), [packages/vercel](https://github.com/tutur3u/platform/blob/main/packages/vercel/package.json) |
| `@vitest/coverage-v8` | `5.0.5` | `5.0.5` | [.](https://github.com/tutur3u/platform/blob/main/package.json) |
| `@xmldom/xmldom` | `0.9.12` | `0.8.15`, `0.9.12` | [packages/sso](https://github.com/tutur3u/platform/blob/main/packages/sso/package.json) |
| `@xyflow/react` | `^12.12.0` | `12.12.0` | [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/hive-ui](https://github.com/tutur3u/platform/blob/main/packages/hive-ui/package.json), [packages/mind-ui](https://github.com/tutur3u/platform/blob/main/packages/mind-ui/package.json) |
| `@zernio/chat-sdk-adapter` | `^0.5.1` | `0.5.1` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `acorn` | `8.19.0` | `8.19.0` | [.](https://github.com/tutur3u/platform/blob/main/package.json) |
| `ai` | `^7.0.148` | `7.0.148` | [apps/ai](https://github.com/tutur3u/platform/blob/main/apps/ai/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/inventory](https://github.com/tutur3u/platform/blob/main/apps/inventory/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json), [packages/mind-ui](https://github.com/tutur3u/platform/blob/main/packages/mind-ui/package.json) |
| `autoprefixer` | `^10.6.1` | `10.6.1` | [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `babel-plugin-react-compiler` | `^1.0.0` | `1.0.0` | [apps/apps](https://github.com/tutur3u/platform/blob/main/apps/apps/package.json), [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/chat](https://github.com/tutur3u/platform/blob/main/apps/chat/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/external](https://github.com/tutur3u/platform/blob/main/apps/external/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/inventory](https://github.com/tutur3u/platform/blob/main/apps/inventory/package.json), [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/playground](https://github.com/tutur3u/platform/blob/main/apps/playground/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/shortener](https://github.com/tutur3u/platform/blob/main/apps/shortener/package.json), [apps/storefront](https://github.com/tutur3u/platform/blob/main/apps/storefront/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/tools](https://github.com/tutur3u/platform/blob/main/apps/tools/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json) |
| `bcrypt` | `^6.0.0` | `6.0.0` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `bcryptjs` | `3.0.3` | `3.0.3` | [apps/shortener](https://github.com/tutur3u/platform/blob/main/apps/shortener/package.json) |
| `browser-image-compression` | `^2.0.2` | `2.0.2` | [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/hooks](https://github.com/tutur3u/platform/blob/main/packages/hooks/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `bun-types` | `1.4.4` | `1.4.4` | [apps/hive-realtime](https://github.com/tutur3u/platform/blob/main/apps/hive-realtime/package.json) |
| `canvas-confetti` | `^1.9.4` | `1.9.4` | [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `cbor-x` | `1.6.0` | `1.6.0` | [packages/internal-api](https://github.com/tutur3u/platform/blob/main/packages/internal-api/package.json) |
| `cf` | `1.0.0-beta.20` | `1.0.0-beta.20` | [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/coordination](https://github.com/tutur3u/platform/blob/main/apps/coordination/package.json), [apps/cron-control](https://github.com/tutur3u/platform/blob/main/apps/cron-control/package.json), [apps/devbox-control](https://github.com/tutur3u/platform/blob/main/apps/devbox-control/package.json) |
| `chat` | `^4.43.0` | `4.43.0` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `chat-adapter-baileys` | `^2.1.0` | `2.1.0` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `chat-adapter-blooio` | `^0.1.0` | `0.1.0` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `chat-adapter-imessage` | `^1.1.0` | `1.1.0` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `chat-adapter-mattermost` | `^2.0.0` | `2.0.0` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `chat-adapter-sendblue` | `^0.2.0` | `0.2.0` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `chat-adapter-zalo` | `^0.1.0` | `0.1.0` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `chat-state-cloudflare-do` | `^0.2.0` | `0.2.0` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `chat-state-mysql` | `^0.1.0` | `0.1.0` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `cheerio` | `^1.2.0` | `1.2.0` | [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json) |
| `class-variance-authority` | `^0.7.1` | `0.7.1` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `cldr-core` | `^48.2.0` | `48.2.0` | [packages/microsoft](https://github.com/tutur3u/platform/blob/main/packages/microsoft/package.json) |
| `client-only` | `^0.0.1` | `0.0.1` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `cmdk` | `^1.1.1` | `1.1.1` | [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `cn` | `^0.3.3` | `0.3.3` | [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json) |
| `cookies-next` | `^6.1.1` | `6.1.1` | [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/satellite](https://github.com/tutur3u/platform/blob/main/packages/satellite/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `cron-parser` | `^5.10.2` | `5.10.2` | [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `cronstrue` | `^3.37.0` | `3.37.0` | [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `date-fns` | `^4.4.0` | `4.4.0` | [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/pay](https://github.com/tutur3u/platform/blob/main/apps/pay/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json), [packages/payment-core](https://github.com/tutur3u/platform/blob/main/packages/payment-core/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json), [packages/users-core](https://github.com/tutur3u/platform/blob/main/packages/users-core/package.json), [packages/users-ui](https://github.com/tutur3u/platform/blob/main/packages/users-ui/package.json), [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json) |
| `date-fns-tz` | `^3.2.0` | `3.2.0` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `dayjs` | `1.11.23`, `^1.11.23` | `1.11.23` | [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/playground](https://github.com/tutur3u/platform/blob/main/apps/playground/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/shortener](https://github.com/tutur3u/platform/blob/main/apps/shortener/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json), [packages/apis](https://github.com/tutur3u/platform/blob/main/packages/apis/package.json), [packages/hooks](https://github.com/tutur3u/platform/blob/main/packages/hooks/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/trigger](https://github.com/tutur3u/platform/blob/main/packages/trigger/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json), [packages/users-core](https://github.com/tutur3u/platform/blob/main/packages/users-core/package.json), [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json) |
| `debug` | `^4.4.3` | `4.4.3` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `diff` | `^9.0.0` | `8.0.4`, `9.0.0` | [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json) |
| `docx-preview` | `0.4.1` | `0.4.1` | [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json) |
| `dompurify` | `^3.4.16` | `3.4.17` | [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `effect` | `^3.22.3` | `3.22.3` | [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json) |
| `embla-carousel-react` | `^8.6.0` | `8.6.0` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `entities` | `^8.1.0` | `4.5.0`, `6.0.1`, `7.0.1`, `8.1.0` | [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json) |
| `esbuild-wasm` | `0.28.2` | `0.28.2` | [packages/offline](https://github.com/tutur3u/platform/blob/main/packages/offline/package.json) |
| `eventemitter3` | `^5.0.4` | `4.0.7`, `5.0.4` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `firebase-admin` | `^14.5.0` | `14.5.0` | [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `framer-motion` | `^13.5.1` | `13.5.1` | [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `glob` | `^13.0.6` | `10.5.0`, `12.0.0`, `13.0.6`, `9.3.5` | [packages/offline](https://github.com/tutur3u/platform/blob/main/packages/offline/package.json) |
| `google-auth-library` | `^11.0.2` | `11.0.2` | [packages/google](https://github.com/tutur3u/platform/blob/main/packages/google/package.json) |
| `googleapis` | `^180.0.0` | `180.0.0` | [packages/google](https://github.com/tutur3u/platform/blob/main/packages/google/package.json) |
| `gsap` | `^3.15.0` | `3.15.0` | [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `html-entities` | `^2.6.0` | `2.6.0` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `html2canvas-pro` | `^2.5.2` | `2.5.2` | [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `input-otp` | `^1.5.0` | `1.5.0` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `isomorphic-dompurify` | `^4.6.0` | `4.6.0` | [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `jose` | `^6.2.13` | `5.10.0`, `6.2.13`, `6.2.3` | [apps/hive-realtime](https://github.com/tutur3u/platform/blob/main/apps/hive-realtime/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `jotai` | `^3.0.1` | `2.11.0`, `3.0.1` | [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `jsdom` | `30.1.3`, `^30.1.3` | `30.1.3` | [apps/apps](https://github.com/tutur3u/platform/blob/main/apps/apps/package.json), [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/chat](https://github.com/tutur3u/platform/blob/main/apps/chat/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/pay](https://github.com/tutur3u/platform/blob/main/apps/pay/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/shortener](https://github.com/tutur3u/platform/blob/main/apps/shortener/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/tools](https://github.com/tutur3u/platform/blob/main/apps/tools/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/editor](https://github.com/tutur3u/platform/blob/main/packages/editor/package.json), [packages/hive-ui](https://github.com/tutur3u/platform/blob/main/packages/hive-ui/package.json), [packages/masonry](https://github.com/tutur3u/platform/blob/main/packages/masonry/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json), [packages/mind-ui](https://github.com/tutur3u/platform/blob/main/packages/mind-ui/package.json), [packages/satellite](https://github.com/tutur3u/platform/blob/main/packages/satellite/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json), [packages/users-ui](https://github.com/tutur3u/platform/blob/main/packages/users-ui/package.json) |
| `jspdf` | `^4.2.1` | `4.2.1` | [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `juice` | `^12.2.0` | `12.2.0` | [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/email-service](https://github.com/tutur3u/platform/blob/main/packages/email-service/package.json) |
| `katex` | `^0.18.11` | `0.18.11`, `0.18.2` | [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/mind-ui](https://github.com/tutur3u/platform/blob/main/packages/mind-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `lib0` | `^0.2.119` | `0.2.119` | [packages/realtime](https://github.com/tutur3u/platform/blob/main/packages/realtime/package.json) |
| `lodash` | `4.18.1`, `^4.18.1` | `4.18.1` | [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `lucide-react` | `^1.61.0` | `1.61.0` | [packages/editor](https://github.com/tutur3u/platform/blob/main/packages/editor/package.json), [packages/icons](https://github.com/tutur3u/platform/blob/main/packages/icons/package.json) |
| `lucide-static` | `^1.61.0` | `1.61.0` | [.](https://github.com/tutur3u/platform/blob/main/package.json) |
| `mailauth` | `^5.0.3` | `5.0.3` | [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json) |
| `mdast-util-from-markdown` | `^2.1.0` | `2.1.0` | [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json), [packages/realtime](https://github.com/tutur3u/platform/blob/main/packages/realtime/package.json) |
| `mdast-util-gfm` | `^3.1.0` | `3.1.0` | [packages/realtime](https://github.com/tutur3u/platform/blob/main/packages/realtime/package.json) |
| `mermaid` | `^12.2.0` | `11.17.2`, `12.2.0` | [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `mic` | `^2.1.2` | `2.1.2` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `micromark-extension-gfm` | `^3.0.0` | `3.0.0` | [packages/realtime](https://github.com/tutur3u/platform/blob/main/packages/realtime/package.json) |
| `miniflare` | `5.20260908.0-alpha`, `^4.20260730.0` | `4.20260730.0`, `5.20260908.0-alpha`, `5.20261012.0-beta`, `5.20261019.0-beta`, `5.20261019.1-beta`, `5.20261019.2-beta` | [apps/colab](https://github.com/tutur3u/platform/blob/main/apps/colab/package.json), [apps/lettin](https://github.com/tutur3u/platform/blob/main/apps/lettin/package.json) |

# Dependency versions 4
Source: https://docs.tuturuuu.com/reference/repository/dependencies-4

Declared dependency ranges, locked resolutions, and owning workspaces.

| Dependency | Declared ranges | Lockfile resolutions | Declaring workspaces |
| - | - | - | - |
| `moment` | `^2.31.0` | `2.31.0` | [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json), [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json) |
| `monaco-editor` | `0.57.0`, `^0.57.0` | `0.57.0` | [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn/package.json), [packages/programming-ui](https://github.com/tutur3u/platform/blob/main/packages/programming-ui/package.json) |
| `motion` | `^13.5.1` | `13.5.1` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `nanoid` | `^6.0.2` | `3.3.18`, `3.3.20`, `5.1.16`, `6.0.2` | [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/shortener](https://github.com/tutur3u/platform/blob/main/apps/shortener/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json) |
| `negotiator` | `^1.1.0` | `0.6.3`, `1.1.0` | [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/chat](https://github.com/tutur3u/platform/blob/main/apps/chat/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn/package.json), [apps/lettin](https://github.com/tutur3u/platform/blob/main/apps/lettin/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/pay](https://github.com/tutur3u/platform/blob/main/apps/pay/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json) |
| `next` | `16.3.5`, `>=16.3.0`, `^16.4.0` | `16.4.2` | [apps/ai](https://github.com/tutur3u/platform/blob/main/apps/ai/package.json), [apps/apps](https://github.com/tutur3u/platform/blob/main/apps/apps/package.json), [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/chat](https://github.com/tutur3u/platform/blob/main/apps/chat/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/external](https://github.com/tutur3u/platform/blob/main/apps/external/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/inventory](https://github.com/tutur3u/platform/blob/main/apps/inventory/package.json), [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn/package.json), [apps/lettin](https://github.com/tutur3u/platform/blob/main/apps/lettin/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/pay](https://github.com/tutur3u/platform/blob/main/apps/pay/package.json), [apps/playground](https://github.com/tutur3u/platform/blob/main/apps/playground/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/shortener](https://github.com/tutur3u/platform/blob/main/apps/shortener/package.json), [apps/storefront](https://github.com/tutur3u/platform/blob/main/apps/storefront/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/tools](https://github.com/tutur3u/platform/blob/main/apps/tools/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json), [packages/apis](https://github.com/tutur3u/platform/blob/main/packages/apis/package.json), [packages/auth](https://github.com/tutur3u/platform/blob/main/packages/auth/package.json), [packages/education-core](https://github.com/tutur3u/platform/blob/main/packages/education-core/package.json), [packages/finance-core](https://github.com/tutur3u/platform/blob/main/packages/finance-core/package.json), [packages/games](https://github.com/tutur3u/platform/blob/main/packages/games/package.json), [packages/hive-ui](https://github.com/tutur3u/platform/blob/main/packages/hive-ui/package.json), [packages/inventory-core](https://github.com/tutur3u/platform/blob/main/packages/inventory-core/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json), [packages/mind-core](https://github.com/tutur3u/platform/blob/main/packages/mind-core/package.json), [packages/mind-ui](https://github.com/tutur3u/platform/blob/main/packages/mind-ui/package.json), [packages/offline](https://github.com/tutur3u/platform/blob/main/packages/offline/package.json), [packages/payment](https://github.com/tutur3u/platform/blob/main/packages/payment/package.json), [packages/programming-ui](https://github.com/tutur3u/platform/blob/main/packages/programming-ui/package.json), [packages/satellite](https://github.com/tutur3u/platform/blob/main/packages/satellite/package.json), [packages/supabase](https://github.com/tutur3u/platform/blob/main/packages/supabase/package.json), [packages/tasks-api](https://github.com/tutur3u/platform/blob/main/packages/tasks-api/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json), [packages/users-core](https://github.com/tutur3u/platform/blob/main/packages/users-core/package.json), [packages/users-ui](https://github.com/tutur3u/platform/blob/main/packages/users-ui/package.json), [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json) |
| `next-intl` | `4.14.9`, `^4.14.9` | `4.14.9` | [apps/ai](https://github.com/tutur3u/platform/blob/main/apps/ai/package.json), [apps/apps](https://github.com/tutur3u/platform/blob/main/apps/apps/package.json), [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/chat](https://github.com/tutur3u/platform/blob/main/apps/chat/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/inventory](https://github.com/tutur3u/platform/blob/main/apps/inventory/package.json), [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn/package.json), [apps/lettin](https://github.com/tutur3u/platform/blob/main/apps/lettin/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/pay](https://github.com/tutur3u/platform/blob/main/apps/pay/package.json), [apps/playground](https://github.com/tutur3u/platform/blob/main/apps/playground/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/shortener](https://github.com/tutur3u/platform/blob/main/apps/shortener/package.json), [apps/storefront](https://github.com/tutur3u/platform/blob/main/apps/storefront/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/tools](https://github.com/tutur3u/platform/blob/main/apps/tools/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/hive-ui](https://github.com/tutur3u/platform/blob/main/packages/hive-ui/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json), [packages/mind-ui](https://github.com/tutur3u/platform/blob/main/packages/mind-ui/package.json), [packages/programming-ui](https://github.com/tutur3u/platform/blob/main/packages/programming-ui/package.json), [packages/satellite](https://github.com/tutur3u/platform/blob/main/packages/satellite/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json), [packages/users-ui](https://github.com/tutur3u/platform/blob/main/packages/users-ui/package.json) |
| `next-themes` | `0.4.6`, `^0.4.6` | `0.4.6` | [apps/ai](https://github.com/tutur3u/platform/blob/main/apps/ai/package.json), [apps/apps](https://github.com/tutur3u/platform/blob/main/apps/apps/package.json), [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/chat](https://github.com/tutur3u/platform/blob/main/apps/chat/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/colab](https://github.com/tutur3u/platform/blob/main/apps/colab/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/inventory](https://github.com/tutur3u/platform/blob/main/apps/inventory/package.json), [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/pay](https://github.com/tutur3u/platform/blob/main/apps/pay/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json), [packages/mind-ui](https://github.com/tutur3u/platform/blob/main/packages/mind-ui/package.json), [packages/satellite](https://github.com/tutur3u/platform/blob/main/packages/satellite/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json), [packages/users-ui](https://github.com/tutur3u/platform/blob/main/packages/users-ui/package.json) |
| `nuqs` | `^2.10.2` | `2.10.2` | [apps/ai](https://github.com/tutur3u/platform/blob/main/apps/ai/package.json), [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/inventory](https://github.com/tutur3u/platform/blob/main/apps/inventory/package.json), [apps/lettin](https://github.com/tutur3u/platform/blob/main/apps/lettin/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/storefront](https://github.com/tutur3u/platform/blob/main/apps/storefront/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json), [packages/satellite](https://github.com/tutur3u/platform/blob/main/packages/satellite/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json), [packages/users-ui](https://github.com/tutur3u/platform/blob/main/packages/users-ui/package.json) |
| `octokit` | `^5.0.5` | `5.0.5` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `oxfmt` | `0.74.0` | `0.73.0`, `0.74.0` | [.](https://github.com/tutur3u/platform/blob/main/package.json) |
| `oxlint` | `1.89.0` | `1.88.0`, `1.89.0` | [.](https://github.com/tutur3u/platform/blob/main/package.json) |
| `papaparse` | `^5.7.0` | `5.7.0` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `playwright` | `^1.64.1` | `1.64.1` | [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `portless` | `^0.15.8` | `0.15.8` | [.](https://github.com/tutur3u/platform/blob/main/package.json) |
| `postal-mime` | `4.0.8` | `2.7.6`, `4.0.11`, `4.0.8` | [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json) |
| `postcss` | `^8.5.31` | `8.5.23`, `8.5.31` | [apps/ai](https://github.com/tutur3u/platform/blob/main/apps/ai/package.json), [apps/apps](https://github.com/tutur3u/platform/blob/main/apps/apps/package.json), [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/chat](https://github.com/tutur3u/platform/blob/main/apps/chat/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/external](https://github.com/tutur3u/platform/blob/main/apps/external/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/inventory](https://github.com/tutur3u/platform/blob/main/apps/inventory/package.json), [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/playground](https://github.com/tutur3u/platform/blob/main/apps/playground/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/shortener](https://github.com/tutur3u/platform/blob/main/apps/shortener/package.json), [apps/storefront](https://github.com/tutur3u/platform/blob/main/apps/storefront/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/tools](https://github.com/tutur3u/platform/blob/main/apps/tools/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `postcss-load-config` | `^6.0.1` | `6.0.1` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `postcss-preset-mantine` | `^1.18.0` | `1.18.0` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `postcss-simple-vars` | `^7.0.1` | `7.0.1` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `postgres` | `^3.4.9` | `3.4.9` | [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [apps/hive-realtime](https://github.com/tutur3u/platform/blob/main/apps/hive-realtime/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/inventory](https://github.com/tutur3u/platform/blob/main/apps/inventory/package.json), [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn/package.json), [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/supermemory](https://github.com/tutur3u/platform/blob/main/apps/supermemory/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/inventory-core](https://github.com/tutur3u/platform/blob/main/packages/inventory-core/package.json), [packages/mind-core](https://github.com/tutur3u/platform/blob/main/packages/mind-core/package.json) |
| `prosemirror-model` | `^1.25.12` | `1.25.12` | [packages/sdk](https://github.com/tutur3u/platform/blob/main/packages/sdk/package.json), [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json) |
| `prosemirror-state` | `^1.4.4` | `1.4.4` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `prosemirror-view` | `1.42.3` | `1.42.3` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `qrcode` | `^1.5.4` | `1.5.4` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `qrcode.react` | `^4.2.0` | `4.2.0` | [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `react` | `19.2.8`, `>=19.2.7`, `^19.2.8`, `~19.2.8` | `19.2.8` | [apps/ai](https://github.com/tutur3u/platform/blob/main/apps/ai/package.json), [apps/apps](https://github.com/tutur3u/platform/blob/main/apps/apps/package.json), [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/chat](https://github.com/tutur3u/platform/blob/main/apps/chat/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/colab](https://github.com/tutur3u/platform/blob/main/apps/colab/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/external](https://github.com/tutur3u/platform/blob/main/apps/external/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/inventory](https://github.com/tutur3u/platform/blob/main/apps/inventory/package.json), [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn/package.json), [apps/lettin](https://github.com/tutur3u/platform/blob/main/apps/lettin/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/pay](https://github.com/tutur3u/platform/blob/main/apps/pay/package.json), [apps/playground](https://github.com/tutur3u/platform/blob/main/apps/playground/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/shortener](https://github.com/tutur3u/platform/blob/main/apps/shortener/package.json), [apps/storefront](https://github.com/tutur3u/platform/blob/main/apps/storefront/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/tools](https://github.com/tutur3u/platform/blob/main/apps/tools/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json), [packages/apis](https://github.com/tutur3u/platform/blob/main/packages/apis/package.json), [packages/auth](https://github.com/tutur3u/platform/blob/main/packages/auth/package.json), [packages/editor](https://github.com/tutur3u/platform/blob/main/packages/editor/package.json), [packages/games](https://github.com/tutur3u/platform/blob/main/packages/games/package.json), [packages/hive-ui](https://github.com/tutur3u/platform/blob/main/packages/hive-ui/package.json), [packages/hooks](https://github.com/tutur3u/platform/blob/main/packages/hooks/package.json), [packages/masonry](https://github.com/tutur3u/platform/blob/main/packages/masonry/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json), [packages/mind-ui](https://github.com/tutur3u/platform/blob/main/packages/mind-ui/package.json), [packages/offline](https://github.com/tutur3u/platform/blob/main/packages/offline/package.json), [packages/programming-ui](https://github.com/tutur3u/platform/blob/main/packages/programming-ui/package.json), [packages/satellite](https://github.com/tutur3u/platform/blob/main/packages/satellite/package.json), [packages/supabase](https://github.com/tutur3u/platform/blob/main/packages/supabase/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/transactional](https://github.com/tutur3u/platform/blob/main/packages/transactional/package.json), [packages/types](https://github.com/tutur3u/platform/blob/main/packages/types/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json), [packages/users-core](https://github.com/tutur3u/platform/blob/main/packages/users-core/package.json), [packages/users-ui](https://github.com/tutur3u/platform/blob/main/packages/users-ui/package.json), [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json) |
| `react-colorful` | `^5.8.1` | `5.8.1` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `react-confetti` | `^6.4.0` | `6.4.0` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `react-day-picker` | `^10.0.2` | `10.0.2` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `react-dom` | `>=19.2.7`, `^19.2.8`, `~19.2.8` | `19.2.8` | [apps/ai](https://github.com/tutur3u/platform/blob/main/apps/ai/package.json), [apps/apps](https://github.com/tutur3u/platform/blob/main/apps/apps/package.json), [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/chat](https://github.com/tutur3u/platform/blob/main/apps/chat/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/colab](https://github.com/tutur3u/platform/blob/main/apps/colab/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/external](https://github.com/tutur3u/platform/blob/main/apps/external/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/inventory](https://github.com/tutur3u/platform/blob/main/apps/inventory/package.json), [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn/package.json), [apps/lettin](https://github.com/tutur3u/platform/blob/main/apps/lettin/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/pay](https://github.com/tutur3u/platform/blob/main/apps/pay/package.json), [apps/playground](https://github.com/tutur3u/platform/blob/main/apps/playground/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/shortener](https://github.com/tutur3u/platform/blob/main/apps/shortener/package.json), [apps/storefront](https://github.com/tutur3u/platform/blob/main/apps/storefront/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/tools](https://github.com/tutur3u/platform/blob/main/apps/tools/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json), [packages/apis](https://github.com/tutur3u/platform/blob/main/packages/apis/package.json), [packages/editor](https://github.com/tutur3u/platform/blob/main/packages/editor/package.json), [packages/games](https://github.com/tutur3u/platform/blob/main/packages/games/package.json), [packages/hive-ui](https://github.com/tutur3u/platform/blob/main/packages/hive-ui/package.json), [packages/hooks](https://github.com/tutur3u/platform/blob/main/packages/hooks/package.json), [packages/masonry](https://github.com/tutur3u/platform/blob/main/packages/masonry/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json), [packages/mind-ui](https://github.com/tutur3u/platform/blob/main/packages/mind-ui/package.json), [packages/satellite](https://github.com/tutur3u/platform/blob/main/packages/satellite/package.json), [packages/supabase](https://github.com/tutur3u/platform/blob/main/packages/supabase/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/types](https://github.com/tutur3u/platform/blob/main/packages/types/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json), [packages/users-ui](https://github.com/tutur3u/platform/blob/main/packages/users-ui/package.json), [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json) |
| `react-dropzone` | `^20.1.4` | `20.1.4` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `react-easy-crop` | `^6.2.4` | `6.2.4` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/users-ui](https://github.com/tutur3u/platform/blob/main/packages/users-ui/package.json) |
| `react-email` | `^6.11.3` | `6.11.3` | [packages/transactional](https://github.com/tutur3u/platform/blob/main/packages/transactional/package.json) |
| `react-hook-form` | `^7.90.0` | `7.90.0` | [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/pay](https://github.com/tutur3u/platform/blob/main/apps/pay/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `react-intersection-observer` | `^11.0.1` | `11.0.1` | [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `react-markdown` | `^10.1.0` | `10.1.0` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `react-papaparse` | `^4.4.0` | `4.4.0` | [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `react-pdf` | `^11.0.0` | `11.0.0` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `react-quizlet-flashcard` | `^4.0.22` | `4.0.22` | [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `react-resizable` | `^4.0.2` | `4.0.2` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `react-resizable-panels` | `^4.14.8` | `4.14.8` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `react-syntax-highlighter` | `^16.1.2` | `16.1.2` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `react-textarea-autosize` | `^8.5.9` | `8.5.9` | [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `react-use` | `^17.6.1` | `17.6.1` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `recharts` | `3.10.1`, `^3.10.1` | `3.10.1` | [apps/ai](https://github.com/tutur3u/platform/blob/main/apps/ai/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/inventory](https://github.com/tutur3u/platform/blob/main/apps/inventory/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `rehype-katex` | `^7.0.1` | `7.0.1` | [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `remark-gfm` | `^4.0.1` | `4.0.1` | [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/colab](https://github.com/tutur3u/platform/blob/main/apps/colab/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `remark-math` | `^6.0.0` | `6.0.0` | [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `remark-parse` | `^11.0.0` | `11.0.0` | [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json) |
| `sanitize-filename` | `^1.6.4` | `1.6.4` | [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json) |
| `sanitize-html` | `^2.18.1` | `2.18.1` | [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/email-service](https://github.com/tutur3u/platform/blob/main/packages/email-service/package.json) |
| `server-only` | `^0.0.1` | `0.0.1` | [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/pay](https://github.com/tutur3u/platform/blob/main/apps/pay/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/education-core](https://github.com/tutur3u/platform/blob/main/packages/education-core/package.json), [packages/finance-core](https://github.com/tutur3u/platform/blob/main/packages/finance-core/package.json), [packages/inventory-core](https://github.com/tutur3u/platform/blob/main/packages/inventory-core/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json), [packages/mind-core](https://github.com/tutur3u/platform/blob/main/packages/mind-core/package.json), [packages/storage-core](https://github.com/tutur3u/platform/blob/main/packages/storage-core/package.json), [packages/users-core](https://github.com/tutur3u/platform/blob/main/packages/users-core/package.json), [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json) |
| `sharp` | `^0.35.5` | `0.35.5` | [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `shiki` | `^4.4.3` | `4.4.3` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `slot-text` | `^0.3.4` | `0.3.4` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `sonner` | `^2.0.8` | `2.0.8` | [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `streamdown` | `^2.7.1` | `2.7.1` | [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json), [packages/mind-ui](https://github.com/tutur3u/platform/blob/main/packages/mind-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `supabase` | `2.117.0` | `2.117.0` | [apps/database](https://github.com/tutur3u/platform/blob/main/apps/database/package.json) |
| `superjson` | `^2.2.6` | `2.2.6` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `tailwind-scrollbar` | `^4.0.2` | `4.0.2` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `tailwind-scrollbar-hide` | `^4.0.0` | `4.0.0` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `tailwindcss` | `^4.3.3` | `4.3.3` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `tailwindcss-animate` | `^1.0.7` | `1.0.7` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `three` | `0.186.1` | `0.170.0`, `0.186.1` | [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [packages/hive-ui](https://github.com/tutur3u/platform/blob/main/packages/hive-ui/package.json) |
| `tiptap-extension-resize-image` | `^1.4.7` | `1.4.7` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `turbo` | `^2.11.10` | `2.11.10` | [.](https://github.com/tutur3u/platform/blob/main/package.json) |
| `typescript` | `7.0.2` | `7.0.2` | [.](https://github.com/tutur3u/platform/blob/main/package.json), [apps/ai](https://github.com/tutur3u/platform/blob/main/apps/ai/package.json), [apps/apps](https://github.com/tutur3u/platform/blob/main/apps/apps/package.json), [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/chat](https://github.com/tutur3u/platform/blob/main/apps/chat/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/colab](https://github.com/tutur3u/platform/blob/main/apps/colab/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/coordination](https://github.com/tutur3u/platform/blob/main/apps/coordination/package.json), [apps/cron-control](https://github.com/tutur3u/platform/blob/main/apps/cron-control/package.json), [apps/database](https://github.com/tutur3u/platform/blob/main/apps/database/package.json), [apps/devbox-control](https://github.com/tutur3u/platform/blob/main/apps/devbox-control/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/external](https://github.com/tutur3u/platform/blob/main/apps/external/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [apps/hive-realtime](https://github.com/tutur3u/platform/blob/main/apps/hive-realtime/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/inventory](https://github.com/tutur3u/platform/blob/main/apps/inventory/package.json), [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn/package.json), [apps/lettin](https://github.com/tutur3u/platform/blob/main/apps/lettin/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/meet-realtime](https://github.com/tutur3u/platform/blob/main/apps/meet-realtime/package.json), [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/pay](https://github.com/tutur3u/platform/blob/main/apps/pay/package.json), [apps/playground](https://github.com/tutur3u/platform/blob/main/apps/playground/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/shortener](https://github.com/tutur3u/platform/blob/main/apps/shortener/package.json), [apps/storefront](https://github.com/tutur3u/platform/blob/main/apps/storefront/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/tools](https://github.com/tutur3u/platform/blob/main/apps/tools/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/agent-quota](https://github.com/tutur3u/platform/blob/main/packages/agent-quota/package.json), [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json), [packages/apis](https://github.com/tutur3u/platform/blob/main/packages/apis/package.json), [packages/auth](https://github.com/tutur3u/platform/blob/main/packages/auth/package.json), [packages/devbox](https://github.com/tutur3u/platform/blob/main/packages/devbox/package.json), [packages/editor](https://github.com/tutur3u/platform/blob/main/packages/editor/package.json), [packages/education-core](https://github.com/tutur3u/platform/blob/main/packages/education-core/package.json), [packages/email-service](https://github.com/tutur3u/platform/blob/main/packages/email-service/package.json), [packages/finance-core](https://github.com/tutur3u/platform/blob/main/packages/finance-core/package.json), [packages/games](https://github.com/tutur3u/platform/blob/main/packages/games/package.json), [packages/google](https://github.com/tutur3u/platform/blob/main/packages/google/package.json), [packages/hive-ui](https://github.com/tutur3u/platform/blob/main/packages/hive-ui/package.json), [packages/hooks](https://github.com/tutur3u/platform/blob/main/packages/hooks/package.json), [packages/icons](https://github.com/tutur3u/platform/blob/main/packages/icons/package.json), [packages/internal-api](https://github.com/tutur3u/platform/blob/main/packages/internal-api/package.json), [packages/inventory-core](https://github.com/tutur3u/platform/blob/main/packages/inventory-core/package.json), [packages/legal](https://github.com/tutur3u/platform/blob/main/packages/legal/package.json), [packages/masonry](https://github.com/tutur3u/platform/blob/main/packages/masonry/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json), [packages/microsoft](https://github.com/tutur3u/platform/blob/main/packages/microsoft/package.json), [packages/mind-core](https://github.com/tutur3u/platform/blob/main/packages/mind-core/package.json), [packages/mind-ui](https://github.com/tutur3u/platform/blob/main/packages/mind-ui/package.json), [packages/multiplayer](https://github.com/tutur3u/platform/blob/main/packages/multiplayer/package.json), [packages/offline](https://github.com/tutur3u/platform/blob/main/packages/offline/package.json), [packages/payment](https://github.com/tutur3u/platform/blob/main/packages/payment/package.json), [packages/payment-core](https://github.com/tutur3u/platform/blob/main/packages/payment-core/package.json), [packages/programming-ui](https://github.com/tutur3u/platform/blob/main/packages/programming-ui/package.json), [packages/realtime](https://github.com/tutur3u/platform/blob/main/packages/realtime/package.json), [packages/satellite](https://github.com/tutur3u/platform/blob/main/packages/satellite/package.json), [packages/sdk](https://github.com/tutur3u/platform/blob/main/packages/sdk/package.json), [packages/sso](https://github.com/tutur3u/platform/blob/main/packages/sso/package.json), [packages/storage-core](https://github.com/tutur3u/platform/blob/main/packages/storage-core/package.json), [packages/supabase](https://github.com/tutur3u/platform/blob/main/packages/supabase/package.json), [packages/tasks-api](https://github.com/tutur3u/platform/blob/main/packages/tasks-api/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/transactional](https://github.com/tutur3u/platform/blob/main/packages/transactional/package.json), [packages/trigger](https://github.com/tutur3u/platform/blob/main/packages/trigger/package.json), [packages/turnstile](https://github.com/tutur3u/platform/blob/main/packages/turnstile/package.json), [packages/types](https://github.com/tutur3u/platform/blob/main/packages/types/package.json), [packages/typescript-config](https://github.com/tutur3u/platform/blob/main/packages/typescript-config/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json), [packages/users-core](https://github.com/tutur3u/platform/blob/main/packages/users-core/package.json), [packages/users-ui](https://github.com/tutur3u/platform/blob/main/packages/users-ui/package.json), [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json), [packages/vercel](https://github.com/tutur3u/platform/blob/main/packages/vercel/package.json), [packages/workflows](https://github.com/tutur3u/platform/blob/main/packages/workflows/package.json) |
| `undici` | `^8.12.3` | `6.29.1`, `7.29.1`, `8.10.2`, `8.12.3` | [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `unified` | `^11.0.5` | `11.0.5` | [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json) |
| `unzipper` | `^0.12.5` | `0.12.5` | [apps/storage-unzip-proxy](https://github.com/tutur3u/platform/blob/main/apps/storage-unzip-proxy/package.json) |
| `use-debounce` | `^10.1.1` | `10.1.1` | [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/inventory](https://github.com/tutur3u/platform/blob/main/apps/inventory/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `use-intl` | `4.14.9` | `4.14.9` | [apps/apps](https://github.com/tutur3u/platform/blob/main/apps/apps/package.json), [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json) |
| `uuid` | `^14.0.3` | `11.1.1`, `14.0.3` | [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/inventory](https://github.com/tutur3u/platform/blob/main/apps/inventory/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json), [packages/games](https://github.com/tutur3u/platform/blob/main/packages/games/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json), [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json) |
| `vaul` | `^1.1.2` | `1.1.2` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `vega-embed` | `^7.3.0` | `7.3.0` | [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |
| `vite` | `^8.3.5`, `npm:@voidzero-dev/vite-plus-core@1.3.0` | `8.3.5` | [.](https://github.com/tutur3u/platform/blob/main/package.json), [apps/apps](https://github.com/tutur3u/platform/blob/main/apps/apps/package.json), [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/colab](https://github.com/tutur3u/platform/blob/main/apps/colab/package.json), [apps/coordination](https://github.com/tutur3u/platform/blob/main/apps/coordination/package.json), [apps/cron-control](https://github.com/tutur3u/platform/blob/main/apps/cron-control/package.json), [apps/devbox-control](https://github.com/tutur3u/platform/blob/main/apps/devbox-control/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/meet-realtime](https://github.com/tutur3u/platform/blob/main/apps/meet-realtime/package.json), [apps/shortener](https://github.com/tutur3u/platform/blob/main/apps/shortener/package.json), [packages/games](https://github.com/tutur3u/platform/blob/main/packages/games/package.json), [packages/google](https://github.com/tutur3u/platform/blob/main/packages/google/package.json), [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json), [packages/vercel](https://github.com/tutur3u/platform/blob/main/packages/vercel/package.json) |
| `vite-plus` | `1.3.0` | `1.3.0` | [apps/apps](https://github.com/tutur3u/platform/blob/main/apps/apps/package.json), [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/colab](https://github.com/tutur3u/platform/blob/main/apps/colab/package.json), [apps/coordination](https://github.com/tutur3u/platform/blob/main/apps/coordination/package.json), [apps/cron-control](https://github.com/tutur3u/platform/blob/main/apps/cron-control/package.json), [apps/devbox-control](https://github.com/tutur3u/platform/blob/main/apps/devbox-control/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/meet-realtime](https://github.com/tutur3u/platform/blob/main/apps/meet-realtime/package.json), [apps/shortener](https://github.com/tutur3u/platform/blob/main/apps/shortener/package.json) |
| `vitest` | `5.0.0`, `5.0.5`, `^5.0.5` | `5.0.5` | [.](https://github.com/tutur3u/platform/blob/main/package.json), [apps/ai](https://github.com/tutur3u/platform/blob/main/apps/ai/package.json), [apps/chat](https://github.com/tutur3u/platform/blob/main/apps/chat/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [apps/hive-realtime](https://github.com/tutur3u/platform/blob/main/apps/hive-realtime/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn/package.json), [apps/lettin](https://github.com/tutur3u/platform/blob/main/apps/lettin/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/pay](https://github.com/tutur3u/platform/blob/main/apps/pay/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/tools](https://github.com/tutur3u/platform/blob/main/apps/tools/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/auth](https://github.com/tutur3u/platform/blob/main/packages/auth/package.json), [packages/devbox](https://github.com/tutur3u/platform/blob/main/packages/devbox/package.json), [packages/editor](https://github.com/tutur3u/platform/blob/main/packages/editor/package.json), [packages/education-core](https://github.com/tutur3u/platform/blob/main/packages/education-core/package.json), [packages/email-service](https://github.com/tutur3u/platform/blob/main/packages/email-service/package.json), [packages/finance-core](https://github.com/tutur3u/platform/blob/main/packages/finance-core/package.json), [packages/hive-ui](https://github.com/tutur3u/platform/blob/main/packages/hive-ui/package.json), [packages/internal-api](https://github.com/tutur3u/platform/blob/main/packages/internal-api/package.json), [packages/inventory-core](https://github.com/tutur3u/platform/blob/main/packages/inventory-core/package.json), [packages/legal](https://github.com/tutur3u/platform/blob/main/packages/legal/package.json), [packages/masonry](https://github.com/tutur3u/platform/blob/main/packages/masonry/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json), [packages/microsoft](https://github.com/tutur3u/platform/blob/main/packages/microsoft/package.json), [packages/mind-core](https://github.com/tutur3u/platform/blob/main/packages/mind-core/package.json), [packages/mind-ui](https://github.com/tutur3u/platform/blob/main/packages/mind-ui/package.json), [packages/offline](https://github.com/tutur3u/platform/blob/main/packages/offline/package.json), [packages/payment-core](https://github.com/tutur3u/platform/blob/main/packages/payment-core/package.json), [packages/programming-ui](https://github.com/tutur3u/platform/blob/main/packages/programming-ui/package.json), [packages/realtime](https://github.com/tutur3u/platform/blob/main/packages/realtime/package.json), [packages/sdk](https://github.com/tutur3u/platform/blob/main/packages/sdk/package.json), [packages/sso](https://github.com/tutur3u/platform/blob/main/packages/sso/package.json), [packages/storage-core](https://github.com/tutur3u/platform/blob/main/packages/storage-core/package.json), [packages/supabase](https://github.com/tutur3u/platform/blob/main/packages/supabase/package.json), [packages/tasks-api](https://github.com/tutur3u/platform/blob/main/packages/tasks-api/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/transactional](https://github.com/tutur3u/platform/blob/main/packages/transactional/package.json), [packages/trigger](https://github.com/tutur3u/platform/blob/main/packages/trigger/package.json), [packages/turnstile](https://github.com/tutur3u/platform/blob/main/packages/turnstile/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json), [packages/users-core](https://github.com/tutur3u/platform/blob/main/packages/users-core/package.json), [packages/users-ui](https://github.com/tutur3u/platform/blob/main/packages/users-ui/package.json), [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json) |
| `void` | `1.1.12` | `1.1.12` | [apps/apps](https://github.com/tutur3u/platform/blob/main/apps/apps/package.json), [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/shortener](https://github.com/tutur3u/platform/blob/main/apps/shortener/package.json) |
| `wrangler` | `4.151.2`, `4.152.0`, `^4.152.0` | `4.151.0`, `4.151.2`, `4.152.0` | [.](https://github.com/tutur3u/platform/blob/main/package.json), [apps/apps](https://github.com/tutur3u/platform/blob/main/apps/apps/package.json), [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/colab](https://github.com/tutur3u/platform/blob/main/apps/colab/package.json), [apps/lettin](https://github.com/tutur3u/platform/blob/main/apps/lettin/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/meet-realtime](https://github.com/tutur3u/platform/blob/main/apps/meet-realtime/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/shortener](https://github.com/tutur3u/platform/blob/main/apps/shortener/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json) |
| `xlsx` | `file:vendor/xlsx-0.20.3.tgz` | `vendor/xlsx-0.20.3.tgz` | [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `xml-crypto` | `6.4.0` | `6.4.0` | [packages/sso](https://github.com/tutur3u/platform/blob/main/packages/sso/package.json) |
| `y-prosemirror` | `^1.3.7` | `1.3.7` | [packages/realtime](https://github.com/tutur3u/platform/blob/main/packages/realtime/package.json), [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json) |
| `y-protocols` | `^1.0.7` | `1.0.7` | [packages/realtime](https://github.com/tutur3u/platform/blob/main/packages/realtime/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json) |
| `yaml` | `^2.9.1` | `1.10.3`, `2.9.1` | [packages/sdk](https://github.com/tutur3u/platform/blob/main/packages/sdk/package.json) |
| `yjs` | `13.6.33`, `^13.6.33` | `13.6.33` | [packages/programming-ui](https://github.com/tutur3u/platform/blob/main/packages/programming-ui/package.json), [packages/realtime](https://github.com/tutur3u/platform/blob/main/packages/realtime/package.json), [packages/sdk](https://github.com/tutur3u/platform/blob/main/packages/sdk/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json), [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json) |
| `zca-js` | `^2.2.0` | `2.2.0` | [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json) |
| `zod` | `4.6.7`, `^4.6.7` | `4.1.11`, `4.6.5`, `4.6.7` | [apps/ai](https://github.com/tutur3u/platform/blob/main/apps/ai/package.json), [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar/package.json), [apps/chat](https://github.com/tutur3u/platform/blob/main/apps/chat/package.json), [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms/package.json), [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts/package.json), [apps/coordination](https://github.com/tutur3u/platform/blob/main/apps/coordination/package.json), [apps/database](https://github.com/tutur3u/platform/blob/main/apps/database/package.json), [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive/package.json), [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance/package.json), [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms/package.json), [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git/package.json), [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive/package.json), [apps/hive-realtime](https://github.com/tutur3u/platform/blob/main/apps/hive-realtime/package.json), [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/package.json), [apps/inventory](https://github.com/tutur3u/platform/blob/main/apps/inventory/package.json), [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn/package.json), [apps/lettin](https://github.com/tutur3u/platform/blob/main/apps/lettin/package.json), [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail/package.json), [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet/package.json), [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind/package.json), [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova/package.json), [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley/package.json), [apps/pay](https://github.com/tutur3u/platform/blob/main/apps/pay/package.json), [apps/playground](https://github.com/tutur3u/platform/blob/main/apps/playground/package.json), [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise/package.json), [apps/shortener](https://github.com/tutur3u/platform/blob/main/apps/shortener/package.json), [apps/storefront](https://github.com/tutur3u/platform/blob/main/apps/storefront/package.json), [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks/package.json), [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach/package.json), [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json), [packages/ai](https://github.com/tutur3u/platform/blob/main/packages/ai/package.json), [packages/apis](https://github.com/tutur3u/platform/blob/main/packages/apis/package.json), [packages/auth](https://github.com/tutur3u/platform/blob/main/packages/auth/package.json), [packages/education-core](https://github.com/tutur3u/platform/blob/main/packages/education-core/package.json), [packages/email-service](https://github.com/tutur3u/platform/blob/main/packages/email-service/package.json), [packages/finance-core](https://github.com/tutur3u/platform/blob/main/packages/finance-core/package.json), [packages/games](https://github.com/tutur3u/platform/blob/main/packages/games/package.json), [packages/hive-ui](https://github.com/tutur3u/platform/blob/main/packages/hive-ui/package.json), [packages/internal-api](https://github.com/tutur3u/platform/blob/main/packages/internal-api/package.json), [packages/inventory-core](https://github.com/tutur3u/platform/blob/main/packages/inventory-core/package.json), [packages/meet-core](https://github.com/tutur3u/platform/blob/main/packages/meet-core/package.json), [packages/mind-core](https://github.com/tutur3u/platform/blob/main/packages/mind-core/package.json), [packages/mind-ui](https://github.com/tutur3u/platform/blob/main/packages/mind-ui/package.json), [packages/realtime](https://github.com/tutur3u/platform/blob/main/packages/realtime/package.json), [packages/sdk](https://github.com/tutur3u/platform/blob/main/packages/sdk/package.json), [packages/sso](https://github.com/tutur3u/platform/blob/main/packages/sso/package.json), [packages/supabase](https://github.com/tutur3u/platform/blob/main/packages/supabase/package.json), [packages/tasks-api](https://github.com/tutur3u/platform/blob/main/packages/tasks-api/package.json), [packages/tasks-ui](https://github.com/tutur3u/platform/blob/main/packages/tasks-ui/package.json), [packages/types](https://github.com/tutur3u/platform/blob/main/packages/types/package.json), [packages/ui](https://github.com/tutur3u/platform/blob/main/packages/ui/package.json), [packages/users-core](https://github.com/tutur3u/platform/blob/main/packages/users-core/package.json), [packages/utils](https://github.com/tutur3u/platform/blob/main/packages/utils/package.json) |
| `zustand` | `^5.0.15` | `4.5.7`, `5.0.15` | [apps/external](https://github.com/tutur3u/platform/blob/main/apps/external/package.json), [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web/package.json) |

# Python locked dependencies 1
Source: https://docs.tuturuuu.com/reference/repository/python-dependencies-1

Resolved Python package versions in the maintained discord workspace.

Source: [apps/discord/uv.lock](https://github.com/tutur3u/platform/blob/main/apps/discord/uv.lock). This reference includes direct and transitive lockfile entries; resolution markers, platform constraints, and dependency relationships remain in the owning lockfile. It is not a deployment or upstream-latest claim.

| Package | Locked version |
| - | - |
| `aiohappyeyeballs` | `2.7.1` |
| `aiohttp` | `3.14.5` |
| `aiosignal` | `1.4.0` |
| `annotated-doc` | `0.0.5` |
| `annotated-types` | `0.8.0` |
| `anyio` | `4.15.1` |
| `ast-serialize` | `0.11.2` |
| `attrs` | `26.1.0` |
| `audioop-lts` | `0.2.2` |
| `azure-ai-contentunderstanding` | `1.2.0b3` |
| `azure-ai-documentintelligence` | `1.0.2` |
| `azure-core` | `1.41.0` |
| `azure-identity` | `1.25.3` |
| `beautifulsoup4` | `4.15.0` |
| `cbor2` | `6.1.4` |
| `certifi` | `2026.10.19` |
| `cffi` | `2.1.1` |
| `charset-normalizer` | `3.5.1` |
| `click` | `8.5.0` |
| `cobble` | `0.1.4` |
| `colorama` | `0.4.6` |
| `coloredlogs` | `15.0.1` |
| `coverage` | `7.16.1` |
| `cryptography` | `50.0.1` |
| `defusedxml` | `0.7.1` |
| `deprecation` | `2.1.0` |
| `et-xmlfile` | `2.0.0` |
| `fastapi` | `0.141.1` |
| `flatbuffers` | `25.12.19` |
| `frozenlist` | `1.8.0` |
| `grpclib` | `0.4.9` |
| `h11` | `0.16.0` |
| `h2` | `4.4.1` |
| `hpack` | `4.2.0` |
| `httpcore` | `1.0.9` |
| `httptools` | `0.8.0` |
| `httpx` | `0.28.1` |
| `humanfriendly` | `10.0` |
| `hyperframe` | `6.1.0` |
| `idna` | `3.19` |
| `iniconfig` | `2.3.0` |
| `isodate` | `0.7.2` |
| `librt` | `0.15.0` |
| `lxml` | `6.1.3` |
| `magika` | `0.6.3` |
| `mammoth` | `1.11.0` |
| `markdown-it-py` | `4.2.0` |
| `markdownify` | `1.2.3` |
| `markitdown` | `0.1.7` |
| `mdurl` | `0.1.2` |
| `modal` | `1.5.5` |
| `mpmath` | `1.3.0` |
| `msal` | `1.38.0` |
| `msal-extensions` | `1.3.1` |
| `multidict` | `6.9.1` |
| `mypy` | `2.3.1` |
| `mypy-extensions` | `1.1.0` |
| `nanoid` | `2.0.0` |
| `numpy` | `2.5.3` |
| `olefile` | `0.47` |
| `onnxruntime` | `1.20.1` |
| `openpyxl` | `3.1.5` |
| `packaging` | `26.3` |
| `pandas` | `3.0.5` |
| `pathspec` | `1.1.1` |
| `pdfminer-six` | `20260107` |
| `pdfplumber` | `0.11.10` |
| `pillow` | `13.0.0` |
| `pluggy` | `1.6.0` |
| `postgrest` | `2.31.0` |
| `propcache` | `0.5.2` |
| `protobuf` | `6.33.6` |
| `pycparser` | `3.0` |
| `pydantic` | `2.13.5` |
| `pydantic-core` | `2.46.5` |
| `pydub` | `0.25.1` |
| `pygments` | `2.21.0` |
| `pyjwt` | `2.15.1` |
| `pynacl` | `1.6.2` |
| `pypdfium2` | `5.13.0` |
| `pyreadline3` | `3.5.6` |
| `pytest` | `9.1.1` |
| `pytest-asyncio` | `1.4.0` |
| `pytest-cov` | `7.1.0` |
| `python-dateutil` | `2.9.0.post0` |
| `python-dotenv` | `1.2.3` |
| `python-pptx` | `1.0.2` |
| `pytz` | `2026.3.post1` |
| `pyyaml` | `6.0.3` |
| `realtime` | `2.31.0` |
| `requests` | `2.34.2` |
| `rich` | `15.0.0` |
| `ruff` | `0.16.7` |
| `six` | `1.17.0` |
| `soupsieve` | `2.9.2` |
| `speechrecognition` | `3.17.0` |
| `standard-aifc` | `3.13.0` |
| `standard-chunk` | `3.13.0` |
| `starlette` | `1.6.0` |
| `storage3` | `2.31.0` |

[Version guide](/reference/repository/versions).

# Python locked dependencies 2
Source: https://docs.tuturuuu.com/reference/repository/python-dependencies-2

Resolved Python package versions in the maintained discord workspace.

| Package | Locked version |
| - | - |
| `strenum` | `0.4.15` |
| `supabase` | `2.31.0` |
| `supabase-auth` | `2.31.0` |
| `supabase-functions` | `2.31.0` |
| `sympy` | `1.14.0` |
| `synchronicity` | `0.12.5` |
| `toml` | `0.10.2` |
| `tuturuuu-discord-bot` | `0.1.0` |
| `types-certifi` | `2021.10.8.3` |
| `types-pytz` | `2026.3.1.20260727` |
| `types-requests` | `2.33.0.20260906` |
| `types-toml` | `0.10.8.20260518` |
| `typing-extensions` | `4.16.0` |
| `typing-inspection` | `0.4.4` |
| `tzdata` | `2026.4` |
| `urllib3` | `2.8.0` |
| `uvicorn` | `0.52.4` |
| `uvloop` | `0.22.1` |
| `watchfiles` | `1.2.0` |
| `websockets` | `15.0.1` |
| `xlrd` | `2.0.2` |
| `xlsxwriter` | `3.2.9` |
| `yarl` | `1.25.1` |
| `youtube-transcript-api` | `1.0.3` |

[Version guide](/reference/repository/versions).

# ai: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/ai

Source entry points and route ownership for the ai workspace.

Runtime: **Next.js App Router**. Source: [apps/ai](https://github.com/tutur3u/platform/blob/main/apps/ai). Package: `@tuturuuu/ai-studio`.

This inventory lists concrete Next page and handler files, including generated wrappers. Methods are lexical source evidence; consult the implementation for re-exports, authorization, status codes, payloads, and fallbacks. Filesystem presence does not establish public access, deployment, entitlement, or a supported external API contract. Route groups are omitted from URLs; dynamic parameters are shown in brackets.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/[locale]/auth-error` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/%5Blocale%5D/$auth$/auth-error/page.tsx) |
| `/[locale]/login` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/%5Blocale%5D/$auth$/login/page.tsx) |
| `/[locale]/verify-token` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/%5Blocale%5D/$auth$/verify-token/page.tsx) |
| `/[locale]/[wsId]/agents` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/%5Blocale%5D/%5BwsId%5D/agents/page.tsx) |
| `/[locale]/[wsId]/api-keys` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/%5Blocale%5D/%5BwsId%5D/api-keys/page.tsx) |
| `/[locale]/[wsId]/credits` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/%5Blocale%5D/%5BwsId%5D/credits/page.tsx) |
| `/[locale]/[wsId]/datasets` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/%5Blocale%5D/%5BwsId%5D/datasets/page.tsx) |
| `/[locale]/[wsId]/developer-docs` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/%5Blocale%5D/%5BwsId%5D/developer-docs/page.tsx) |
| `/[locale]/[wsId]/integrations` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/%5Blocale%5D/%5BwsId%5D/integrations/page.tsx) |
| `/[locale]/[wsId]/logs` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/%5Blocale%5D/%5BwsId%5D/logs/page.tsx) |
| `/[locale]/[wsId]/model-policy` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/%5Blocale%5D/%5BwsId%5D/model-policy/page.tsx) |
| `/[locale]/[wsId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/%5Blocale%5D/%5BwsId%5D/page.tsx) |
| `/[locale]/[wsId]/playground` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/%5Blocale%5D/%5BwsId%5D/playground/page.tsx) |
| `/[locale]/[wsId]/prompts` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/%5Blocale%5D/%5BwsId%5D/prompts/page.tsx) |
| `/[locale]/[wsId]/runs` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/%5Blocale%5D/%5BwsId%5D/runs/page.tsx) |
| `/[locale]/[wsId]/usage` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/%5Blocale%5D/%5BwsId%5D/usage/page.tsx) |
| `/[locale]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/%5Blocale%5D/page.tsx) |
| `/api/auth/logout` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/api/auth/logout/route.ts) |
| `/api/auth/refresh-app-session` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/api/auth/refresh-app-session/route.ts) |
| `/api/auth/verify-app-token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/api/auth/verify-app-token/route.ts) |
| `/api/build-info` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/api/build-info/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/catalog/[resource]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/api/v1/workspaces/%5BwsId%5D/ai/catalog/%5Bresource%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/credits` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/api/v1/workspaces/%5BwsId%5D/ai/credits/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/keys/[keyId]` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/api/v1/workspaces/%5BwsId%5D/ai/keys/%5BkeyId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/keys` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/api/v1/workspaces/%5BwsId%5D/ai/keys/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/overview` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/api/v1/workspaces/%5BwsId%5D/ai/overview/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/playground` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/api/v1/workspaces/%5BwsId%5D/ai/playground/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/policy` | GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/api/v1/workspaces/%5BwsId%5D/ai/policy/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/provider-costs` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/api/v1/workspaces/%5BwsId%5D/ai/provider-costs/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/provider-invoices` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/api/v1/workspaces/%5BwsId%5D/ai/provider-invoices/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/runs/[runId]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/api/v1/workspaces/%5BwsId%5D/ai/runs/%5BrunId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/runs` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/api/v1/workspaces/%5BwsId%5D/ai/runs/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/usage` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/api/v1/workspaces/%5BwsId%5D/ai/usage/route.ts) |
| `/api/v1/workspaces/[wsId]/avatar` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/api/v1/workspaces/%5BwsId%5D/avatar/route.ts) |
| `/api/v1/workspaces/[wsId]/avatar/upload-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/api/v1/workspaces/%5BwsId%5D/avatar/upload-url/route.ts) |
| `/api/workspaces/[wsId]` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/api/workspaces/%5BwsId%5D/route.ts) |
| `/v1/agents/[agentId]/responses` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/v1/agents/%5BagentId%5D/responses/route.ts) |
| `/v1/audio/speech` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/v1/audio/speech/route.ts) |
| `/v1/chat/completions` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/v1/chat/completions/route.ts) |
| `/v1/colab/responses` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/v1/colab/responses/route.ts) |
| `/v1/embeddings` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/v1/embeddings/route.ts) |
| `/v1/images/generations` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/v1/images/generations/route.ts) |
| `/v1/models` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/v1/models/route.ts) |
| `/v1/provider-costs` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/v1/provider-costs/route.ts) |
| `/v1/provider-invoices` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/v1/provider-invoices/route.ts) |
| `/v1/responses` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/v1/responses/route.ts) |
| `/v1/usage` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/ai/src/app/v1/usage/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# apps: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/apps

Source entry points and route ownership for the apps workspace.

Runtime: **Next.js App Router**. Source: [apps/apps](https://github.com/tutur3u/platform/blob/main/apps/apps). Package: `@tuturuuu/apps`.

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# calendar: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/calendar

Source entry points and route ownership for the calendar workspace.

Runtime: **Next.js App Router**. Source: [apps/calendar](https://github.com/tutur3u/platform/blob/main/apps/calendar). Package: `@tuturuuu/calendar`.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/[locale]/login` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/%5Blocale%5D/$auth$/login/page.tsx) |
| `/[locale]/verify-token` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/%5Blocale%5D/$auth$/verify-token/page.tsx) |
| `/[locale]/[wsId]/lab` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/lab/page.tsx) |
| `/[locale]/[wsId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/page.tsx) |
| `/[locale]/[wsId]/tasks/[taskId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/tasks/%5BtaskId%5D/page.tsx) |
| `/[locale]/[wsId]/tasks/boards/[boardId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/tasks/boards/%5BboardId%5D/page.tsx) |
| `/[locale]/[wsId]/tasks/boards` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/tasks/boards/page.tsx) |
| `/[locale]/[wsId]/tasks` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/tasks/page.tsx) |
| `/api/[wsId]/calendar/auto-schedule` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/%5BwsId%5D/calendar/auto-schedule/route.ts) |
| `/api/auth/logout` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/auth/logout/route.ts) |
| `/api/auth/refresh-app-session` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/auth/refresh-app-session/route.ts) |
| `/api/auth/verify-app-token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/auth/verify-app-token/route.ts) |
| `/api/build-info` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/build-info/route.ts) |
| `/api/cron/calendar/provider-sync` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/cron/calendar/provider-sync/route.ts) |
| `/api/cron/calendar/smart-schedule` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/cron/calendar/smart-schedule/route.ts) |
| `/api/test-events` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/test-events/route.ts) |
| `/api/v1/calendar/audio` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/calendar/audio/route.ts) |
| `/api/v1/calendar/auth/accounts` | DELETE, GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/calendar/auth/accounts/route.ts) |
| `/api/v1/calendar/auth/callback` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/calendar/auth/callback/route.ts) |
| `/api/v1/calendar/auth/fetch` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/calendar/auth/fetch/route.ts) |
| `/api/v1/calendar/auth/full-sync` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/calendar/auth/full-sync/route.ts) |
| `/api/v1/calendar/auth/import-calendars` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/calendar/auth/import-calendars/route.ts) |
| `/api/v1/calendar/auth/list-calendars` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/calendar/auth/list-calendars/route.ts) |
| `/api/v1/calendar/auth/microsoft/callback` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/calendar/auth/microsoft/callback/route.ts) |
| `/api/v1/calendar/auth/microsoft` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/calendar/auth/microsoft/route.ts) |
| `/api/v1/calendar/auth/provider-calendars` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/calendar/auth/provider-calendars/route.ts) |
| `/api/v1/calendar/auth` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/calendar/auth/route.ts) |
| `/api/v1/calendar/auth/sync` | DELETE, POST, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/calendar/auth/sync/route.ts) |
| `/api/v1/calendar/auth/sync-to-google` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/calendar/auth/sync-to-google/route.ts) |
| `/api/v1/calendar/auth/tokens` | DELETE, GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/calendar/auth/tokens/route.ts) |
| `/api/v1/calendar/connections` | DELETE, GET, PATCH, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/calendar/connections/route.ts) |
| `/api/v1/calendar/events/generate` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/calendar/events/generate/route.ts) |
| `/api/v1/calendar/image` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/calendar/image/route.ts) |
| `/api/v1/calendar/mock` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/calendar/mock/route.ts) |
| `/api/v1/mira/calendar` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/mira/calendar/route.ts) |
| `/api/v1/users/calendar-settings` | GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/users/calendar-settings/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/credits` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/workspaces/%5BwsId%5D/ai/credits/route.ts) |
| `/api/v1/workspaces/[wsId]/avatar` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/workspaces/%5BwsId%5D/avatar/route.ts) |
| `/api/v1/workspaces/[wsId]/avatar/upload-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/workspaces/%5BwsId%5D/avatar/upload-url/route.ts) |
| `/api/v1/workspaces/[wsId]/calendar/categories/[categoryId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/workspaces/%5BwsId%5D/calendar/categories/%5BcategoryId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/calendar/categories/reorder` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/workspaces/%5BwsId%5D/calendar/categories/reorder/route.ts) |
| `/api/v1/workspaces/[wsId]/calendar/categories` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/workspaces/%5BwsId%5D/calendar/categories/route.ts) |
| `/api/v1/workspaces/[wsId]/calendar/colors` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/workspaces/%5BwsId%5D/calendar/colors/route.ts) |
| `/api/v1/workspaces/[wsId]/calendar/default-source` | GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/workspaces/%5BwsId%5D/calendar/default-source/route.ts) |
| `/api/v1/workspaces/[wsId]/calendar/events/[eventId]/color-operation` | DELETE, GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/workspaces/%5BwsId%5D/calendar/events/%5BeventId%5D/color-operation/route.ts) |
| `/api/v1/workspaces/[wsId]/calendar/events/[eventId]/link-preview` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/workspaces/%5BwsId%5D/calendar/events/%5BeventId%5D/link-preview/route.ts) |
| `/api/v1/workspaces/[wsId]/calendar/events/[eventId]/response` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/workspaces/%5BwsId%5D/calendar/events/%5BeventId%5D/response/route.ts) |
| `/api/v1/workspaces/[wsId]/calendar/events/[eventId]` | DELETE, GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/workspaces/%5BwsId%5D/calendar/events/%5BeventId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/calendar/events` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/workspaces/%5BwsId%5D/calendar/events/route.ts) |
| `/api/v1/workspaces/[wsId]/calendar/habit-events` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/workspaces/%5BwsId%5D/calendar/habit-events/route.ts) |
| `/api/v1/workspaces/[wsId]/calendar/schedulable-tasks` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/workspaces/%5BwsId%5D/calendar/schedulable-tasks/route.ts) |
| `/api/v1/workspaces/[wsId]/calendar/schedule/preview` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/workspaces/%5BwsId%5D/calendar/schedule/preview/route.ts) |
| `/api/v1/workspaces/[wsId]/calendar/schedule` | DELETE, GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/workspaces/%5BwsId%5D/calendar/schedule/route.ts) |
| `/api/v1/workspaces/[wsId]/calendar/series/[seriesId]` | DELETE, GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/workspaces/%5BwsId%5D/calendar/series/%5BseriesId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/calendar/series/provider-operations/[operationId]` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/workspaces/%5BwsId%5D/calendar/series/provider-operations/%5BoperationId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/calendar/series/provider-operations` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/workspaces/%5BwsId%5D/calendar/series/provider-operations/route.ts) |
| `/api/v1/workspaces/[wsId]/calendar/series` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/workspaces/%5BwsId%5D/calendar/series/route.ts) |
| `/api/v1/workspaces/[wsId]/calendar/sync` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/workspaces/%5BwsId%5D/calendar/sync/route.ts) |
| `/api/v1/workspaces/[wsId]/calendar/sync-preferences` | GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/workspaces/%5BwsId%5D/calendar/sync-preferences/route.ts) |
| `/api/v1/workspaces/[wsId]/calendar/sync-status` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/workspaces/%5BwsId%5D/calendar/sync-status/route.ts) |
| `/api/v1/workspaces/[wsId]/calendar-hours` | GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/workspaces/%5BwsId%5D/calendar-hours/route.ts) |
| `/api/v1/workspaces/[wsId]/calendar-settings` | GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/workspaces/%5BwsId%5D/calendar-settings/route.ts) |
| `/api/v1/workspaces/[wsId]/calendars/reset` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/workspaces/%5BwsId%5D/calendars/reset/route.ts) |
| `/api/v1/workspaces/[wsId]/calendars` | DELETE, GET, PATCH, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/v1/workspaces/%5BwsId%5D/calendars/route.ts) |
| `/api/workspaces/[wsId]` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/api/workspaces/%5BwsId%5D/route.ts) |
| `/serwist/[path]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/calendar/src/app/serwist/%5Bpath%5D/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# chat: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/chat

Source entry points and route ownership for the chat workspace.

Runtime: **Next.js App Router**. Source: [apps/chat](https://github.com/tutur3u/platform/blob/main/apps/chat). Package: `@tuturuuu/chat`.

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# chat-realtime: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/chat-realtime

Source entry points and route ownership for the chat-realtime workspace.

Runtime: **Service or supporting workspace**. Source: [apps/chat-realtime](https://github.com/tutur3u/platform/blob/main/apps/chat-realtime).

This workspace has no Next.js page/handler inventory. Read [the owning workspace](https://github.com/tutur3u/platform/blob/main/apps/chat-realtime) for native, Worker, or infrastructure entry points and the [active runtime map](/build/devops/active-runtime) for operational ownership.

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# cms: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/cms

Source entry points and route ownership for the cms workspace.

Runtime: **Next.js App Router**. Source: [apps/cms](https://github.com/tutur3u/platform/blob/main/apps/cms). Package: `@tuturuuu/cms`.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/[locale]/verify-token` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/%5Blocale%5D/$auth$/verify-token/page.tsx) |
| `/[locale]/[wsId]/chat/inbox` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/chat/inbox/page.tsx) |
| `/[locale]/[wsId]/chat` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/chat/page.tsx) |
| `/[locale]/[wsId]/content/collections/[collectionId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/content/collections/%5BcollectionId%5D/page.tsx) |
| `/[locale]/[wsId]/content/entries/[entryId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/content/entries/%5BentryId%5D/page.tsx) |
| `/[locale]/[wsId]/content/entries/[entryId]/webgl/[assetId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/content/entries/%5BentryId%5D/webgl/%5BassetId%5D/page.tsx) |
| `/[locale]/[wsId]/content` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/content/page.tsx) |
| `/[locale]/[wsId]/games` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/games/page.tsx) |
| `/[locale]/[wsId]/media` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/media/page.tsx) |
| `/[locale]/[wsId]/members` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/members/page.tsx) |
| `/[locale]/[wsId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/page.tsx) |
| `/[locale]/[wsId]/pages` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/pages/page.tsx) |
| `/[locale]/[wsId]/preview` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/preview/page.tsx) |
| `/[locale]/[wsId]/products` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/products/page.tsx) |
| `/[locale]/[wsId]/projects` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/projects/page.tsx) |
| `/[locale]/[wsId]/settings` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/settings/page.tsx) |
| `/[locale]/[wsId]/storefront` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/storefront/page.tsx) |
| `/[locale]/[wsId]/taxonomy` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/taxonomy/page.tsx) |
| `/[locale]/no-access` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/%5Blocale%5D/no-access/page.tsx) |
| `/[locale]/play/[wsId]/webgl/[assetId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/%5Blocale%5D/play/%5BwsId%5D/webgl/%5BassetId%5D/page.tsx) |
| `/api/auth/logout` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/api/auth/logout/route.ts) |
| `/api/auth/refresh-app-session` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/api/auth/refresh-app-session/route.ts) |
| `/api/auth/verify-app-token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/api/auth/verify-app-token/route.ts) |
| `/api/build-info` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/api/build-info/route.ts) |
| `/api/v1/admin/external-project-audits` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/api/v1/admin/external-project-audits/route.ts) |
| `/api/v1/admin/external-project-bindings/[workspaceId]` | GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/api/v1/admin/external-project-bindings/%5BworkspaceId%5D/route.ts) |
| `/api/v1/admin/external-project-bindings` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/api/v1/admin/external-project-bindings/route.ts) |
| `/api/v1/admin/external-projects/[canonicalId]` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/api/v1/admin/external-projects/%5BcanonicalId%5D/route.ts) |
| `/api/v1/admin/external-projects` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/api/v1/admin/external-projects/route.ts) |
| `/api/v1/commerce/insights` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/api/v1/commerce/insights/route.ts) |
| `/api/v1/commerce/overview` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/api/v1/commerce/overview/route.ts) |
| `/api/v1/commerce/products` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/api/v1/commerce/products/route.ts) |
| `/api/v1/commerce/storefront` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/api/v1/commerce/storefront/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/credits` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/api/v1/workspaces/%5BwsId%5D/ai/credits/route.ts) |
| `/api/v1/workspaces/[wsId]/avatar` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/api/v1/workspaces/%5BwsId%5D/avatar/route.ts) |
| `/api/v1/workspaces/[wsId]/avatar/upload-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/api/v1/workspaces/%5BwsId%5D/avatar/upload-url/route.ts) |
| `/api/workspaces/[wsId]` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/cms/src/app/api/workspaces/%5BwsId%5D/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# colab: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/colab

Source entry points and route ownership for the colab workspace.

Runtime: **Service or supporting workspace**. Source: [apps/colab](https://github.com/tutur3u/platform/blob/main/apps/colab). Package: `@tuturuuu/colab`.

This workspace has no Next.js page/handler inventory. Read [the owning workspace](https://github.com/tutur3u/platform/blob/main/apps/colab) for native, Worker, or infrastructure entry points and the [active runtime map](/build/devops/active-runtime) for operational ownership.

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# contacts: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/contacts

Source entry points and route ownership for the contacts workspace.

Runtime: **Next.js App Router**. Source: [apps/contacts](https://github.com/tutur3u/platform/blob/main/apps/contacts). Package: `@tuturuuu/contacts`.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/[locale]/[wsId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/page.tsx) |
| `/[locale]/[wsId]/posts` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/posts/page.tsx) |
| `/[locale]/[wsId]/reports` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/reports/page.tsx) |
| `/[locale]/[wsId]/users/[userId]/follow-up` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/%5BuserId%5D/follow-up/page.tsx) |
| `/[locale]/[wsId]/users/approvals` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/approvals/page.tsx) |
| `/[locale]/[wsId]/users/attendance` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/attendance/page.tsx) |
| `/[locale]/[wsId]/users/database/[userId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/database/%5BuserId%5D/page.tsx) |
| `/[locale]/[wsId]/users/database` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/database/page.tsx) |
| `/[locale]/[wsId]/users/feedbacks` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/feedbacks/page.tsx) |
| `/[locale]/[wsId]/users/group-tags/[tagId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/group-tags/%5BtagId%5D/page.tsx) |
| `/[locale]/[wsId]/users/group-tags` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/group-tags/page.tsx) |
| `/[locale]/[wsId]/users/groups/[groupId]/attendance` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/groups/%5BgroupId%5D/attendance/page.tsx) |
| `/[locale]/[wsId]/users/groups/[groupId]/content` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/groups/%5BgroupId%5D/content/page.tsx) |
| `/[locale]/[wsId]/users/groups/[groupId]/indicators` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/groups/%5BgroupId%5D/indicators/page.tsx) |
| `/[locale]/[wsId]/users/groups/[groupId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/groups/%5BgroupId%5D/page.tsx) |
| `/[locale]/[wsId]/users/groups/[groupId]/posts/[postId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/groups/%5BgroupId%5D/posts/%5BpostId%5D/page.tsx) |
| `/[locale]/[wsId]/users/groups/[groupId]/reports` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/groups/%5BgroupId%5D/reports/page.tsx) |
| `/[locale]/[wsId]/users/groups/[groupId]/requests` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/groups/%5BgroupId%5D/requests/page.tsx) |
| `/[locale]/[wsId]/users/groups/[groupId]/schedule` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/groups/%5BgroupId%5D/schedule/page.tsx) |
| `/[locale]/[wsId]/users/groups/calendar` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/groups/calendar/page.tsx) |
| `/[locale]/[wsId]/users/groups/indicators` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/groups/indicators/page.tsx) |
| `/[locale]/[wsId]/users/groups` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/groups/page.tsx) |
| `/[locale]/[wsId]/users/guest-leads` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/guest-leads/page.tsx) |
| `/[locale]/[wsId]/users` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/page.tsx) |
| `/[locale]/[wsId]/users/reports/[reportId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/reports/%5BreportId%5D/page.tsx) |
| `/[locale]/[wsId]/users/reports` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/reports/page.tsx) |
| `/[locale]/[wsId]/users/structure` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/structure/page.tsx) |
| `/[locale]/[wsId]/users/topic-announcements/announcements` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/topic-announcements/announcements/page.tsx) |
| `/[locale]/[wsId]/users/topic-announcements/contacts` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/topic-announcements/contacts/page.tsx) |
| `/[locale]/[wsId]/users/topic-announcements/delivery` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/topic-announcements/delivery/page.tsx) |
| `/[locale]/[wsId]/users/topic-announcements/import` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/topic-announcements/import/page.tsx) |
| `/[locale]/[wsId]/users/topic-announcements` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/topic-announcements/page.tsx) |
| `/[locale]/[wsId]/users/topic-announcements/templates` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/topic-announcements/templates/page.tsx) |
| `/[locale]/[wsId]/users/tutoring` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/users/tutoring/page.tsx) |
| `/[locale]/[wsId]/workforce` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/%5BwsId%5D/workforce/page.tsx) |
| `/[locale]/dashboard` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/dashboard/page.tsx) |
| `/[locale]/login` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/login/page.tsx) |
| `/[locale]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/page.tsx) |
| `/[locale]/verify-token` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/%5Blocale%5D/verify-token/page.tsx) |
| `/api/auth/logout` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/auth/logout/route.ts) |
| `/api/auth/refresh-app-session` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/auth/refresh-app-session/route.ts) |
| `/api/auth/verify-app-token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/auth/verify-app-token/route.ts) |
| `/api/build-info` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/build-info/route.ts) |
| `/api/v1/notifications/[id]/metadata` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/notifications/%5Bid%5D/metadata/route.ts) |
| `/api/v1/notifications/[id]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/notifications/%5Bid%5D/route.ts) |
| `/api/v1/notifications` | GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/notifications/route.ts) |
| `/api/v1/notifications/unread-count` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/notifications/unread-count/route.ts) |
| `/api/v1/users/me/profile` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/users/me/profile/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/credits` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/ai/credits/route.ts) |
| `/api/v1/workspaces/[wsId]/avatar` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/avatar/route.ts) |
| `/api/v1/workspaces/[wsId]/avatar/upload-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/avatar/upload-url/route.ts) |
| `/api/v1/workspaces/[wsId]/group-tags/[tagId]` | DELETE, GET, HEAD, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/group-tags/%5BtagId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/group-tags/[tagId]/user-groups/[groupId]` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/group-tags/%5BtagId%5D/user-groups/%5BgroupId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/group-tags/[tagId]/user-groups` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/group-tags/%5BtagId%5D/user-groups/route.ts) |
| `/api/v1/workspaces/[wsId]/group-tags` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/group-tags/route.ts) |
| `/api/v1/workspaces/[wsId]/posts/bootstrap` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/posts/bootstrap/route.ts) |
| `/api/v1/workspaces/[wsId]/posts/filter-options` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/posts/filter-options/route.ts) |
| `/api/v1/workspaces/[wsId]/posts/permissions` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/posts/permissions/route.ts) |
| `/api/v1/workspaces/[wsId]/posts` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/posts/route.ts) |
| `/api/v1/workspaces/[wsId]/products/options` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/products/options/route.ts) |
| `/api/v1/workspaces/[wsId]/promotions` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/promotions/route.ts) |
| `/api/v1/workspaces/[wsId]/settings/[configId]` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/settings/%5BconfigId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/settings/approvals/pending-summary` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/settings/approvals/pending-summary/route.ts) |
| `/api/v1/workspaces/[wsId]/settings/configs` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/settings/configs/route.ts) |
| `/api/v1/workspaces/[wsId]/settings/feature-secrets/[secretName]` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/settings/feature-secrets/%5BsecretName%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/topic-announcements/preview` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/topic-announcements/preview/route.ts) |
| `/api/v1/workspaces/[wsId]/topic-announcements` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/topic-announcements/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/attendance` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/attendance/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/group-checks/[postId]/email` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/group-checks/%5BpostId%5D/email/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/group-checks/[postId]/logs` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/group-checks/%5BpostId%5D/logs/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/group-checks/[postId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/group-checks/%5BpostId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/group-checks` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/group-checks/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/indicators/[indicatorId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/indicators/%5BindicatorId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/indicators/categories/[categoryId]` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/indicators/categories/%5BcategoryId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/indicators/categories` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/indicators/categories/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/indicators` | GET, HEAD, PATCH, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/indicators/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/linked-products/[productId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/linked-products/%5BproductId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/linked-products` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/linked-products/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/members/[userId]/feedbacks` | DELETE, GET, HEAD, POST, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/members/%5BuserId%5D/feedbacks/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/members/[userId]` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/members/%5BuserId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/members` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/members/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/posts/[postId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/posts/%5BpostId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/posts/[postId]/status` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/posts/%5BpostId%5D/status/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/posts` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/posts/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]` | DELETE, GET, HEAD, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/activity-logs` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/activity-logs/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/sessions/[sessionId]/reconcile` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/sessions/%5BsessionId%5D/reconcile/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/sessions/[sessionId]/restore` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/sessions/%5BsessionId%5D/restore/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/sessions/[sessionId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/sessions/%5BsessionId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/sessions/group-summaries` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/sessions/group-summaries/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/sessions/occurrences` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/sessions/occurrences/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/sessions` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/sessions/route.ts) |
| `/api/v1/workspaces/[wsId]/users/[userId]/attendance` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/%5BuserId%5D/attendance/route.ts) |
| `/api/v1/workspaces/[wsId]/users/[userId]/emails` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/%5BuserId%5D/emails/route.ts) |
| `/api/v1/workspaces/[wsId]/users/[userId]/linked-promotions` | DELETE, GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/%5BuserId%5D/linked-promotions/route.ts) |
| `/api/v1/workspaces/[wsId]/users/[userId]/referral-discounts` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/%5BuserId%5D/referral-discounts/route.ts) |
| `/api/v1/workspaces/[wsId]/users/[userId]` | DELETE, GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/%5BuserId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/users/approvals/logs` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/approvals/logs/route.ts) |
| `/api/v1/workspaces/[wsId]/users/approvals` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/approvals/route.ts) |
| `/api/v1/workspaces/[wsId]/users/audit-logs/backfill` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/audit-logs/backfill/route.ts) |
| `/api/v1/workspaces/[wsId]/users/audit-logs` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/audit-logs/route.ts) |
| `/api/v1/workspaces/[wsId]/users/avatar` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/avatar/route.ts) |
| `/api/v1/workspaces/[wsId]/users/bulk-import` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/bulk-import/route.ts) |
| `/api/v1/workspaces/[wsId]/users/database` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/database/route.ts) |
| `/api/v1/workspaces/[wsId]/users/duplicates/detect` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/duplicates/detect/route.ts) |
| `/api/v1/workspaces/[wsId]/users/feedbacks` | DELETE, GET, HEAD, POST, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/feedbacks/route.ts) |
| `/api/v1/workspaces/[wsId]/users/fields` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/fields/route.ts) |
| `/api/v1/workspaces/[wsId]/users/groups/featured-counts` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/groups/featured-counts/route.ts) |
| `/api/v1/workspaces/[wsId]/users/groups/possible-excluded` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/groups/possible-excluded/route.ts) |
| `/api/v1/workspaces/[wsId]/users/groups` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/groups/route.ts) |
| `/api/v1/workspaces/[wsId]/users/links/manual` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/links/manual/route.ts) |
| `/api/v1/workspaces/[wsId]/users/merge/bulk` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/merge/bulk/route.ts) |
| `/api/v1/workspaces/[wsId]/users/merge` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/merge/route.ts) |
| `/api/v1/workspaces/[wsId]/users/reports/[reportId]/delivery` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/reports/%5BreportId%5D/delivery/route.ts) |
| `/api/v1/workspaces/[wsId]/users/reports/[reportId]/logs` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/reports/%5BreportId%5D/logs/route.ts) |
| `/api/v1/workspaces/[wsId]/users/reports/[reportId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/reports/%5BreportId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/users/reports/groups/[groupId]/bulk-export` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/reports/groups/%5BgroupId%5D/bulk-export/route.ts) |
| `/api/v1/workspaces/[wsId]/users/reports/groups/[groupId]/dashboard` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/reports/groups/%5BgroupId%5D/dashboard/route.ts) |
| `/api/v1/workspaces/[wsId]/users/reports/groups` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/reports/groups/route.ts) |
| `/api/v1/workspaces/[wsId]/users/reports` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/reports/route.ts) |
| `/api/v1/workspaces/[wsId]/users/reports/schedules` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/reports/schedules/route.ts) |
| `/api/v1/workspaces/[wsId]/users` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/v1/workspaces/%5BwsId%5D/users/route.ts) |
| `/api/workspaces/[wsId]` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/contacts/src/app/api/workspaces/%5BwsId%5D/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# coordination: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/coordination

Source entry points and route ownership for the coordination workspace.

Runtime: **Service or supporting workspace**. Source: [apps/coordination](https://github.com/tutur3u/platform/blob/main/apps/coordination). Package: `@tuturuuu/coordination`.

This workspace has no Next.js page/handler inventory. Read [the owning workspace](https://github.com/tutur3u/platform/blob/main/apps/coordination) for native, Worker, or infrastructure entry points and the [active runtime map](/build/devops/active-runtime) for operational ownership.

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# cron-control: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/cron-control

Source entry points and route ownership for the cron-control workspace.

Runtime: **Service or supporting workspace**. Source: [apps/cron-control](https://github.com/tutur3u/platform/blob/main/apps/cron-control). Package: `@tuturuuu/cron-control`.

This workspace has no Next.js page/handler inventory. Read [the owning workspace](https://github.com/tutur3u/platform/blob/main/apps/cron-control) for native, Worker, or infrastructure entry points and the [active runtime map](/build/devops/active-runtime) for operational ownership.

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# database: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/database

Source entry points and route ownership for the database workspace.

Runtime: **Service or supporting workspace**. Source: [apps/database](https://github.com/tutur3u/platform/blob/main/apps/database). Package: `@tuturuuu/database`.

This workspace has no Next.js page/handler inventory. Read [the owning workspace](https://github.com/tutur3u/platform/blob/main/apps/database) for native, Worker, or infrastructure entry points and the [active runtime map](/build/devops/active-runtime) for operational ownership.

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# devbox-control: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/devbox-control

Source entry points and route ownership for the devbox-control workspace.

Runtime: **Service or supporting workspace**. Source: [apps/devbox-control](https://github.com/tutur3u/platform/blob/main/apps/devbox-control). Package: `@tuturuuu/devbox-control`.

This workspace has no Next.js page/handler inventory. Read [the owning workspace](https://github.com/tutur3u/platform/blob/main/apps/devbox-control) for native, Worker, or infrastructure entry points and the [active runtime map](/build/devops/active-runtime) for operational ownership.

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# discord: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/discord

Source entry points and route ownership for the discord workspace.

Runtime: **Service or supporting workspace**. Source: [apps/discord](https://github.com/tutur3u/platform/blob/main/apps/discord).

This workspace has no Next.js page/handler inventory. Read [the owning workspace](https://github.com/tutur3u/platform/blob/main/apps/discord) for native, Worker, or infrastructure entry points and the [active runtime map](/build/devops/active-runtime) for operational ownership.

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# docs: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/docs

Source entry points and route ownership for the docs workspace.

Runtime: **Service or supporting workspace**. Source: [apps/docs](https://github.com/tutur3u/platform/blob/main/apps/docs).

This workspace has no Next.js page/handler inventory. Read [the owning workspace](https://github.com/tutur3u/platform/blob/main/apps/docs) for native, Worker, or infrastructure entry points and the [active runtime map](/build/devops/active-runtime) for operational ownership.

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# drive: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/drive

Source entry points and route ownership for the drive workspace.

Runtime: **Next.js App Router**. Source: [apps/drive](https://github.com/tutur3u/platform/blob/main/apps/drive). Package: `@tuturuuu/drive`.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/[locale]/verify-token` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/drive/src/app/%5Blocale%5D/$auth$/verify-token/page.tsx) |
| `/[locale]/[wsId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/drive/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/page.tsx) |
| `/api/auth/logout` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/drive/src/app/api/auth/logout/route.ts) |
| `/api/auth/refresh-app-session` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/drive/src/app/api/auth/refresh-app-session/route.ts) |
| `/api/auth/verify-app-token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/drive/src/app/api/auth/verify-app-token/route.ts) |
| `/api/build-info` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/drive/src/app/api/build-info/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/credits` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/drive/src/app/api/v1/workspaces/%5BwsId%5D/ai/credits/route.ts) |
| `/api/v1/workspaces/[wsId]/avatar` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/drive/src/app/api/v1/workspaces/%5BwsId%5D/avatar/route.ts) |
| `/api/v1/workspaces/[wsId]/avatar/upload-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/drive/src/app/api/v1/workspaces/%5BwsId%5D/avatar/upload-url/route.ts) |
| `/api/workspaces/[wsId]` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/drive/src/app/api/workspaces/%5BwsId%5D/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# external: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/external

Source entry points and route ownership for the external workspace.

Runtime: **Next.js App Router**. Source: [apps/external](https://github.com/tutur3u/platform/blob/main/apps/external). Package: `@tuturuuu/external`.

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# finance: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/finance

Source entry points and route ownership for the finance workspace.

Runtime: **Next.js App Router**. Source: [apps/finance](https://github.com/tutur3u/platform/blob/main/apps/finance). Package: `@tuturuuu/finance`.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/[locale]/verify-token` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/%5Blocale%5D/$auth$/verify-token/page.tsx) |
| `/[locale]/[wsId]/analytics` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/analytics/page.tsx) |
| `/[locale]/[wsId]/budgets` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/budgets/page.tsx) |
| `/[locale]/[wsId]/categories` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/categories/page.tsx) |
| `/[locale]/[wsId]/debts/[debtId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/debts/%5BdebtId%5D/page.tsx) |
| `/[locale]/[wsId]/debts` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/debts/page.tsx) |
| `/[locale]/[wsId]/invoices/[invoiceId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/invoices/%5BinvoiceId%5D/page.tsx) |
| `/[locale]/[wsId]/invoices/new` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/invoices/new/page.tsx) |
| `/[locale]/[wsId]/invoices` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/invoices/page.tsx) |
| `/[locale]/[wsId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/page.tsx) |
| `/[locale]/[wsId]/promotions` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/promotions/page.tsx) |
| `/[locale]/[wsId]/recurring` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/recurring/page.tsx) |
| `/[locale]/[wsId]/tags` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/tags/page.tsx) |
| `/[locale]/[wsId]/transactions/[transactionId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/transactions/%5BtransactionId%5D/page.tsx) |
| `/[locale]/[wsId]/transactions/categories` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/transactions/categories/page.tsx) |
| `/[locale]/[wsId]/transactions` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/transactions/page.tsx) |
| `/[locale]/[wsId]/wallets/[walletId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/wallets/%5BwalletId%5D/page.tsx) |
| `/[locale]/[wsId]/wallets` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/wallets/page.tsx) |
| `/api/auth/logout` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/auth/logout/route.ts) |
| `/api/auth/refresh-app-session` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/auth/refresh-app-session/route.ts) |
| `/api/auth/verify-app-token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/auth/verify-app-token/route.ts) |
| `/api/build-info` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/build-info/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/credits` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/ai/credits/route.ts) |
| `/api/v1/workspaces/[wsId]/avatar` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/avatar/route.ts) |
| `/api/v1/workspaces/[wsId]/avatar/upload-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/avatar/upload-url/route.ts) |
| `/api/v1/workspaces/[wsId]/finance/budgets/[budgetId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/finance/budgets/%5BbudgetId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/finance/budgets` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/finance/budgets/route.ts) |
| `/api/v1/workspaces/[wsId]/finance/budgets/status` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/finance/budgets/status/route.ts) |
| `/api/v1/workspaces/[wsId]/finance/debts/[debtId]` | DELETE, GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/finance/debts/%5BdebtId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/finance/debts` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/finance/debts/route.ts) |
| `/api/v1/workspaces/[wsId]/finance/debts/summary` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/finance/debts/summary/route.ts) |
| `/api/v1/workspaces/[wsId]/finance/filter-users` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/finance/filter-users/route.ts) |
| `/api/v1/workspaces/[wsId]/finance/invoices/[invoiceId]/restore` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/finance/invoices/%5BinvoiceId%5D/restore/route.ts) |
| `/api/v1/workspaces/[wsId]/finance/invoices/[invoiceId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/finance/invoices/%5BinvoiceId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/finance/invoices/analytics` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/finance/invoices/analytics/route.ts) |
| `/api/v1/workspaces/[wsId]/finance/invoices/count` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/finance/invoices/count/route.ts) |
| `/api/v1/workspaces/[wsId]/finance/invoices/history` | DELETE, GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/finance/invoices/history/route.ts) |
| `/api/v1/workspaces/[wsId]/finance/invoices/pending` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/finance/invoices/pending/route.ts) |
| `/api/v1/workspaces/[wsId]/finance/invoices` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/finance/invoices/route.ts) |
| `/api/v1/workspaces/[wsId]/finance/invoices/subscription/context` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/finance/invoices/subscription/context/route.ts) |
| `/api/v1/workspaces/[wsId]/finance/invoices/subscription` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/finance/invoices/subscription/route.ts) |
| `/api/v1/workspaces/[wsId]/finance/invoices/subscription-analytics` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/finance/invoices/subscription-analytics/route.ts) |
| `/api/v1/workspaces/[wsId]/finance/recurring-transactions/[recurringTransactionId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/finance/recurring-transactions/%5BrecurringTransactionId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/finance/recurring-transactions` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/finance/recurring-transactions/route.ts) |
| `/api/v1/workspaces/[wsId]/finance/recurring-transactions/upcoming` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/finance/recurring-transactions/upcoming/route.ts) |
| `/api/v1/workspaces/[wsId]/finance/wallets/expense/count` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/finance/wallets/expense/count/route.ts) |
| `/api/v1/workspaces/[wsId]/finance/wallets/expense/sum` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/finance/wallets/expense/sum/route.ts) |
| `/api/v1/workspaces/[wsId]/finance/wallets/income/count` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/finance/wallets/income/count/route.ts) |
| `/api/v1/workspaces/[wsId]/finance/wallets/income/sum` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/finance/wallets/income/sum/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/offline-mutations` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/inventory/offline-mutations/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/products` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/inventory/products/route.ts) |
| `/api/v1/workspaces/[wsId]/promotions/[promotionId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/promotions/%5BpromotionId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/promotions` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/promotions/route.ts) |
| `/api/v1/workspaces/[wsId]/settings/configs` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/settings/configs/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/linked-products` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/linked-products/route.ts) |
| `/api/v1/workspaces/[wsId]/users/[userId]/linked-promotions` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/users/%5BuserId%5D/linked-promotions/route.ts) |
| `/api/v1/workspaces/[wsId]/wallets/infinite` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/v1/workspaces/%5BwsId%5D/wallets/infinite/route.ts) |
| `/api/workspaces/[wsId]/finance/charts/balance` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/finance/charts/balance/route.ts) |
| `/api/workspaces/[wsId]/finance/charts/balance-trend` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/finance/charts/balance-trend/route.ts) |
| `/api/workspaces/[wsId]/finance/charts/categories` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/finance/charts/categories/route.ts) |
| `/api/workspaces/[wsId]/finance/charts/daily` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/finance/charts/daily/route.ts) |
| `/api/workspaces/[wsId]/finance/charts/income-expense-summary` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/finance/charts/income-expense-summary/route.ts) |
| `/api/workspaces/[wsId]/finance/charts/monthly` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/finance/charts/monthly/route.ts) |
| `/api/workspaces/[wsId]/finance/inventory-reconciliation/bulk-link` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/finance/inventory-reconciliation/bulk-link/route.ts) |
| `/api/workspaces/[wsId]/finance/inventory-reconciliation/bulk-unlink` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/finance/inventory-reconciliation/bulk-unlink/route.ts) |
| `/api/workspaces/[wsId]/finance/inventory-reconciliation/manual-adjustments` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/finance/inventory-reconciliation/manual-adjustments/route.ts) |
| `/api/workspaces/[wsId]/finance/inventory-reconciliation/mappings` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/finance/inventory-reconciliation/mappings/route.ts) |
| `/api/workspaces/[wsId]/finance/inventory-reconciliation/provider-sync` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/finance/inventory-reconciliation/provider-sync/route.ts) |
| `/api/workspaces/[wsId]/finance/inventory-reconciliation` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/finance/inventory-reconciliation/route.ts) |
| `/api/workspaces/[wsId]/finance/overview` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/finance/overview/route.ts) |
| `/api/workspaces/[wsId]` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/route.ts) |
| `/api/workspaces/[wsId]/transactions/[transactionId]` | DELETE, GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/transactions/%5BtransactionId%5D/route.ts) |
| `/api/workspaces/[wsId]/transactions/[transactionId]/tags` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/transactions/%5BtransactionId%5D/tags/route.ts) |
| `/api/workspaces/[wsId]/transactions/categories/[categoryId]` | DELETE, GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/transactions/categories/%5BcategoryId%5D/route.ts) |
| `/api/workspaces/[wsId]/transactions/categories/migrate` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/transactions/categories/migrate/route.ts) |
| `/api/workspaces/[wsId]/transactions/categories` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/transactions/categories/route.ts) |
| `/api/workspaces/[wsId]/transactions/category-breakdown` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/transactions/category-breakdown/route.ts) |
| `/api/workspaces/[wsId]/transactions/export` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/transactions/export/route.ts) |
| `/api/workspaces/[wsId]/transactions/import/money-lover` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/transactions/import/money-lover/route.ts) |
| `/api/workspaces/[wsId]/transactions/infinite` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/transactions/infinite/route.ts) |
| `/api/workspaces/[wsId]/transactions/periods` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/transactions/periods/route.ts) |
| `/api/workspaces/[wsId]/transactions` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/transactions/route.ts) |
| `/api/workspaces/[wsId]/transactions/spending-trends` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/transactions/spending-trends/route.ts) |
| `/api/workspaces/[wsId]/transactions/stats` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/transactions/stats/route.ts) |
| `/api/workspaces/[wsId]/wallets/[walletId]/checkpoints/[checkpointId]/reconcile` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/wallets/%5BwalletId%5D/checkpoints/%5BcheckpointId%5D/reconcile/route.ts) |
| `/api/workspaces/[wsId]/wallets/[walletId]/checkpoints/[checkpointId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/wallets/%5BwalletId%5D/checkpoints/%5BcheckpointId%5D/route.ts) |
| `/api/workspaces/[wsId]/wallets/[walletId]/checkpoints` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/wallets/%5BwalletId%5D/checkpoints/route.ts) |
| `/api/workspaces/[wsId]/wallets/[walletId]/credit-summary` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/wallets/%5BwalletId%5D/credit-summary/route.ts) |
| `/api/workspaces/[wsId]/wallets/[walletId]/interest/calculate` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/wallets/%5BwalletId%5D/interest/calculate/route.ts) |
| `/api/workspaces/[wsId]/wallets/[walletId]/interest/config` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/wallets/%5BwalletId%5D/interest/config/route.ts) |
| `/api/workspaces/[wsId]/wallets/[walletId]/interest/project` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/wallets/%5BwalletId%5D/interest/project/route.ts) |
| `/api/workspaces/[wsId]/wallets/[walletId]/interest/rates` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/wallets/%5BwalletId%5D/interest/rates/route.ts) |
| `/api/workspaces/[wsId]/wallets/[walletId]/interest` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/wallets/%5BwalletId%5D/interest/route.ts) |
| `/api/workspaces/[wsId]/wallets/[walletId]` | DELETE, GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/wallets/%5BwalletId%5D/route.ts) |
| `/api/workspaces/[wsId]/wallets/checkpoints/history` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/wallets/checkpoints/history/route.ts) |
| `/api/workspaces/[wsId]/wallets/checkpoints` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/wallets/checkpoints/route.ts) |
| `/api/workspaces/[wsId]/wallets/infinite` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/wallets/infinite/route.ts) |
| `/api/workspaces/[wsId]/wallets/migrate` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/wallets/migrate/route.ts) |
| `/api/workspaces/[wsId]/wallets` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/wallets/route.ts) |
| `/api/workspaces/[wsId]/wallets/transactions/migrate` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/finance/src/app/api/workspaces/%5BwsId%5D/wallets/transactions/migrate/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# forms: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/forms

Source entry points and route ownership for the forms workspace.

Runtime: **Next.js App Router**. Source: [apps/forms](https://github.com/tutur3u/platform/blob/main/apps/forms). Package: `@tuturuuu/forms`.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/[locale]/[wsId]/forms/[formId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/%5Blocale%5D/%5BwsId%5D/forms/%5BformId%5D/page.tsx) |
| `/[locale]/[wsId]/forms/new` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/%5Blocale%5D/%5BwsId%5D/forms/new/page.tsx) |
| `/[locale]/[wsId]/forms` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/%5Blocale%5D/%5BwsId%5D/forms/page.tsx) |
| `/[locale]/[wsId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/%5Blocale%5D/%5BwsId%5D/page.tsx) |
| `/[locale]/dashboard` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/%5Blocale%5D/dashboard/page.tsx) |
| `/[locale]/embed/[shareCode]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/%5Blocale%5D/embed/%5BshareCode%5D/page.tsx) |
| `/[locale]/f/[shareCode]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/%5Blocale%5D/f/%5BshareCode%5D/page.tsx) |
| `/[locale]/login` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/%5Blocale%5D/login/page.tsx) |
| `/[locale]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/%5Blocale%5D/page.tsx) |
| `/[locale]/verify-token` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/%5Blocale%5D/verify-token/page.tsx) |
| `/api/auth/logout` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/api/auth/logout/route.ts) |
| `/api/auth/refresh-app-session` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/api/auth/refresh-app-session/route.ts) |
| `/api/auth/verify-app-token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/api/auth/verify-app-token/route.ts) |
| `/api/build-info` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/api/build-info/route.ts) |
| `/api/v1/shared/forms/[shareCode]/response-copy` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/api/v1/shared/forms/%5BshareCode%5D/response-copy/route.ts) |
| `/api/v1/shared/forms/[shareCode]` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/api/v1/shared/forms/%5BshareCode%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/credits` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/api/v1/workspaces/%5BwsId%5D/ai/credits/route.ts) |
| `/api/v1/workspaces/[wsId]/avatar` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/api/v1/workspaces/%5BwsId%5D/avatar/route.ts) |
| `/api/v1/workspaces/[wsId]/avatar/upload-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/api/v1/workspaces/%5BwsId%5D/avatar/upload-url/route.ts) |
| `/api/v1/workspaces/[wsId]/forms/[formId]/analytics` | DELETE, GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/api/v1/workspaces/%5BwsId%5D/forms/%5BformId%5D/analytics/route.ts) |
| `/api/v1/workspaces/[wsId]/forms/[formId]/archive` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/api/v1/workspaces/%5BwsId%5D/forms/%5BformId%5D/archive/route.ts) |
| `/api/v1/workspaces/[wsId]/forms/[formId]/copy` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/api/v1/workspaces/%5BwsId%5D/forms/%5BformId%5D/copy/route.ts) |
| `/api/v1/workspaces/[wsId]/forms/[formId]/export` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/api/v1/workspaces/%5BwsId%5D/forms/%5BformId%5D/export/route.ts) |
| `/api/v1/workspaces/[wsId]/forms/[formId]/responses/export` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/api/v1/workspaces/%5BwsId%5D/forms/%5BformId%5D/responses/export/route.ts) |
| `/api/v1/workspaces/[wsId]/forms/[formId]/responses` | DELETE, GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/api/v1/workspaces/%5BwsId%5D/forms/%5BformId%5D/responses/route.ts) |
| `/api/v1/workspaces/[wsId]/forms/[formId]` | DELETE, GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/api/v1/workspaces/%5BwsId%5D/forms/%5BformId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/forms/[formId]/share-link` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/api/v1/workspaces/%5BwsId%5D/forms/%5BformId%5D/share-link/route.ts) |
| `/api/v1/workspaces/[wsId]/forms/media` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/api/v1/workspaces/%5BwsId%5D/forms/media/route.ts) |
| `/api/v1/workspaces/[wsId]/forms` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/api/v1/workspaces/%5BwsId%5D/forms/route.ts) |
| `/api/workspaces/[wsId]` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/forms/src/app/api/workspaces/%5BwsId%5D/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# git: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/git

Source entry points and route ownership for the git workspace.

Runtime: **Next.js App Router**. Source: [apps/git](https://github.com/tutur3u/platform/blob/main/apps/git). Package: `@tuturuuu/git`.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/[locale]/-/[wsId]/github-app` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/git/src/app/%5Blocale%5D/-/%5BwsId%5D/github-app/page.tsx) |
| `/[locale]/-/[wsId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/git/src/app/%5Blocale%5D/-/%5BwsId%5D/page.tsx) |
| `/[locale]/-/[wsId]/repositories` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/git/src/app/%5Blocale%5D/-/%5BwsId%5D/repositories/page.tsx) |
| `/[locale]/[owner]/[repo]/[[...view]]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/git/src/app/%5Blocale%5D/%5Bowner%5D/%5Brepo%5D/%5B%5B...view%5D%5D/page.tsx) |
| `/[locale]/login` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/git/src/app/%5Blocale%5D/login/page.tsx) |
| `/[locale]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/git/src/app/%5Blocale%5D/page.tsx) |
| `/[locale]/verify-token` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/git/src/app/%5Blocale%5D/verify-token/page.tsx) |
| `/api/auth/logout` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/git/src/app/api/auth/logout/route.ts) |
| `/api/auth/refresh-app-session` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/git/src/app/api/auth/refresh-app-session/route.ts) |
| `/api/auth/verify-app-token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/git/src/app/api/auth/verify-app-token/route.ts) |
| `/api/build-info` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/git/src/app/api/build-info/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# hive: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/hive

Source entry points and route ownership for the hive workspace.

Runtime: **Next.js App Router**. Source: [apps/hive](https://github.com/tutur3u/platform/blob/main/apps/hive). Package: `@tuturuuu/hive`.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/[locale]/login` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/%5Blocale%5D/$auth$/login/page.tsx) |
| `/[locale]/not-whitelisted` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/%5Blocale%5D/$auth$/not-whitelisted/page.tsx) |
| `/[locale]/verify-token` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/%5Blocale%5D/$auth$/verify-token/page.tsx) |
| `/[locale]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/%5Blocale%5D/$dashboard$/page.tsx) |
| `/~recover-browser-state` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/~recover-browser-state/route.ts) |
| `/api/auth/logout` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/auth/logout/route.ts) |
| `/api/auth/refresh-app-session` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/auth/refresh-app-session/route.ts) |
| `/api/auth/verify-app-token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/auth/verify-app-token/route.ts) |
| `/api/build-info` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/build-info/route.ts) |
| `/api/cron/hive/simulate` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/cron/hive/simulate/route.ts) |
| `/api/v1/hive/access-requests/[requestId]/approve` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/access-requests/%5BrequestId%5D/approve/route.ts) |
| `/api/v1/hive/access-requests/me` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/access-requests/me/route.ts) |
| `/api/v1/hive/access-requests` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/access-requests/route.ts) |
| `/api/v1/hive/ai/credits` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/ai/credits/route.ts) |
| `/api/v1/hive/ai/models` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/ai/models/route.ts) |
| `/api/v1/hive/backfill` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/backfill/route.ts) |
| `/api/v1/hive/members` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/members/route.ts) |
| `/api/v1/hive/servers/[serverId]/crdt` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/servers/%5BserverId%5D/crdt/route.ts) |
| `/api/v1/hive/servers/[serverId]/economy` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/servers/%5BserverId%5D/economy/route.ts) |
| `/api/v1/hive/servers/[serverId]/events` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/servers/%5BserverId%5D/events/route.ts) |
| `/api/v1/hive/servers/[serverId]/farming` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/servers/%5BserverId%5D/farming/route.ts) |
| `/api/v1/hive/servers/[serverId]/interactions` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/servers/%5BserverId%5D/interactions/route.ts) |
| `/api/v1/hive/servers/[serverId]/mind-simulations` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/servers/%5BserverId%5D/mind-simulations/route.ts) |
| `/api/v1/hive/servers/[serverId]/npcs/[npcId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/servers/%5BserverId%5D/npcs/%5BnpcId%5D/route.ts) |
| `/api/v1/hive/servers/[serverId]/npcs/[npcId]/run` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/servers/%5BserverId%5D/npcs/%5BnpcId%5D/run/route.ts) |
| `/api/v1/hive/servers/[serverId]/npcs` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/servers/%5BserverId%5D/npcs/route.ts) |
| `/api/v1/hive/servers/[serverId]/ollama` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/servers/%5BserverId%5D/ollama/route.ts) |
| `/api/v1/hive/servers/[serverId]/realtime-token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/servers/%5BserverId%5D/realtime-token/route.ts) |
| `/api/v1/hive/servers/[serverId]/research-sessions/[sessionId]/export` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/servers/%5BserverId%5D/research-sessions/%5BsessionId%5D/export/route.ts) |
| `/api/v1/hive/servers/[serverId]/research-sessions/[sessionId]` | GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/servers/%5BserverId%5D/research-sessions/%5BsessionId%5D/route.ts) |
| `/api/v1/hive/servers/[serverId]/research-sessions/[sessionId]/run-pair-queue` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/servers/%5BserverId%5D/research-sessions/%5BsessionId%5D/run-pair-queue/route.ts) |
| `/api/v1/hive/servers/[serverId]/research-sessions` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/servers/%5BserverId%5D/research-sessions/route.ts) |
| `/api/v1/hive/servers/[serverId]` | DELETE, GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/servers/%5BserverId%5D/route.ts) |
| `/api/v1/hive/servers/[serverId]/settings` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/servers/%5BserverId%5D/settings/route.ts) |
| `/api/v1/hive/servers/[serverId]/simulate` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/servers/%5BserverId%5D/simulate/route.ts) |
| `/api/v1/hive/servers/[serverId]/timeline` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/servers/%5BserverId%5D/timeline/route.ts) |
| `/api/v1/hive/servers/[serverId]/trades` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/servers/%5BserverId%5D/trades/route.ts) |
| `/api/v1/hive/servers/[serverId]/warehouses` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/servers/%5BserverId%5D/warehouses/route.ts) |
| `/api/v1/hive/servers/[serverId]/workflows/[workflowId]` | DELETE, GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/servers/%5BserverId%5D/workflows/%5BworkflowId%5D/route.ts) |
| `/api/v1/hive/servers/[serverId]/workflows/[workflowId]/run` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/servers/%5BserverId%5D/workflows/%5BworkflowId%5D/run/route.ts) |
| `/api/v1/hive/servers/[serverId]/workflows/[workflowId]/runs/[runId]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/servers/%5BserverId%5D/workflows/%5BworkflowId%5D/runs/%5BrunId%5D/route.ts) |
| `/api/v1/hive/servers/[serverId]/workflows/[workflowId]/runs` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/servers/%5BserverId%5D/workflows/%5BworkflowId%5D/runs/route.ts) |
| `/api/v1/hive/servers/[serverId]/workflows` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/servers/%5BserverId%5D/workflows/route.ts) |
| `/api/v1/hive/servers` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/servers/route.ts) |
| `/api/v1/hive/workspaces` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/hive/src/app/api/v1/hive/workspaces/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# hive-realtime: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/hive-realtime

Source entry points and route ownership for the hive-realtime workspace.

Runtime: **Service or supporting workspace**. Source: [apps/hive-realtime](https://github.com/tutur3u/platform/blob/main/apps/hive-realtime). Package: `@tuturuuu/hive-realtime`.

This workspace has no Next.js page/handler inventory. Read [the owning workspace](https://github.com/tutur3u/platform/blob/main/apps/hive-realtime) for native, Worker, or infrastructure entry points and the [active runtime map](/build/devops/active-runtime) for operational ownership.

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# infrastructure: routes (1/2)
Source: https://docs.tuturuuu.com/reference/repository/routes/infrastructure-1

Source entry points and route ownership for the infrastructure workspace.

Runtime: **Next.js App Router**. Source: [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure). Package: `@tuturuuu/infrastructure`.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/[locale]/login` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$auth$/login/page.tsx) |
| `/[locale]/verify-token` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$auth$/verify-token/page.tsx) |
| `/[locale]/[wsId]/abuse-events` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/abuse-events/page.tsx) |
| `/[locale]/[wsId]/abuse-intelligence` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/abuse-intelligence/page.tsx) |
| `/[locale]/[wsId]/account-benefits` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/account-benefits/page.tsx) |
| `/[locale]/[wsId]/ai/studio` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/ai/studio/page.tsx) |
| `/[locale]/[wsId]/ai/whitelist/domains` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/ai/whitelist/domains/page.tsx) |
| `/[locale]/[wsId]/ai/whitelist/emails` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/ai/whitelist/emails/page.tsx) |
| `/[locale]/[wsId]/ai-agents` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/ai-agents/page.tsx) |
| `/[locale]/[wsId]/ai-credits` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/ai-credits/page.tsx) |
| `/[locale]/[wsId]/app-coordination` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/app-coordination/page.tsx) |
| `/[locale]/[wsId]/auth-recovery` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/auth-recovery/page.tsx) |
| `/[locale]/[wsId]/blocked-ips` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/blocked-ips/page.tsx) |
| `/[locale]/[wsId]/calendar-sync` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/calendar-sync/page.tsx) |
| `/[locale]/[wsId]/changelog/[id]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/changelog/%5Bid%5D/page.tsx) |
| `/[locale]/[wsId]/changelog/new` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/changelog/new/page.tsx) |
| `/[locale]/[wsId]/changelog` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/changelog/page.tsx) |
| `/[locale]/[wsId]/cron/whitelist/domains` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/cron/whitelist/domains/page.tsx) |
| `/[locale]/[wsId]/desktop-deployment` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/desktop-deployment/page.tsx) |
| `/[locale]/[wsId]/devboxes` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/devboxes/page.tsx) |
| `/[locale]/[wsId]/email-audit` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/email-audit/page.tsx) |
| `/[locale]/[wsId]/email-blacklist` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/email-blacklist/page.tsx) |
| `/[locale]/[wsId]/email-templates` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/email-templates/page.tsx) |
| `/[locale]/[wsId]/entity-creation-limits` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/entity-creation-limits/page.tsx) |
| `/[locale]/[wsId]/external-apps/approve` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/external-apps/approve/page.tsx) |
| `/[locale]/[wsId]/external-apps` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/external-apps/page.tsx) |
| `/[locale]/[wsId]/external-chat-lab` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/external-chat-lab/page.tsx) |
| `/[locale]/[wsId]/fleet/machines/[runnerId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/fleet/machines/%5BrunnerId%5D/page.tsx) |
| `/[locale]/[wsId]/fleet` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/fleet/page.tsx) |
| `/[locale]/[wsId]/github-bot` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/github-bot/page.tsx) |
| `/[locale]/[wsId]/holidays` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/holidays/page.tsx) |
| `/[locale]/[wsId]/internal-accounts` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/internal-accounts/page.tsx) |
| `/[locale]/[wsId]/migrations` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/migrations/page.tsx) |
| `/[locale]/[wsId]/mobile-deployment` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/mobile-deployment/page.tsx) |
| `/[locale]/[wsId]/mobile-versions` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/mobile-versions/page.tsx) |
| `/[locale]/[wsId]/monitoring/analytics` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/monitoring/analytics/page.tsx) |
| `/[locale]/[wsId]/monitoring/cron` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/monitoring/cron/page.tsx) |
| `/[locale]/[wsId]/monitoring/deployments` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/monitoring/deployments/page.tsx) |
| `/[locale]/[wsId]/monitoring/logs` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/monitoring/logs/page.tsx) |
| `/[locale]/[wsId]/monitoring/observability` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/monitoring/observability/page.tsx) |
| `/[locale]/[wsId]/monitoring` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/monitoring/page.tsx) |
| `/[locale]/[wsId]/monitoring/projects` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/monitoring/projects/page.tsx) |
| `/[locale]/[wsId]/monitoring/requests` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/monitoring/requests/page.tsx) |
| `/[locale]/[wsId]/monitoring/resources` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/monitoring/resources/page.tsx) |
| `/[locale]/[wsId]/monitoring/rollouts` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/monitoring/rollouts/page.tsx) |
| `/[locale]/[wsId]/monitoring/stress-tests` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/monitoring/stress-tests/page.tsx) |
| `/[locale]/[wsId]/monitoring/watcher-logs` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/monitoring/watcher-logs/page.tsx) |
| `/[locale]/[wsId]/otp-limits` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/otp-limits/page.tsx) |
| `/[locale]/[wsId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/page.tsx) |
| `/[locale]/[wsId]/parley` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/parley/page.tsx) |
| `/[locale]/[wsId]/post-email-queue` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/post-email-queue/page.tsx) |
| `/[locale]/[wsId]/push-notifications` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/push-notifications/page.tsx) |
| `/[locale]/[wsId]/rate-limit-appeals` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/rate-limit-appeals/page.tsx) |
| `/[locale]/[wsId]/rate-limits` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/rate-limits/page.tsx) |
| `/[locale]/[wsId]/realtime` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/realtime/page.tsx) |
| `/[locale]/[wsId]/timezones` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/timezones/page.tsx) |
| `/[locale]/[wsId]/translations` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/translations/page.tsx) |
| `/[locale]/[wsId]/users` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/users/page.tsx) |
| `/[locale]/[wsId]/workspaces` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/workspaces/page.tsx) |
| `/[locale]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/%5Blocale%5D/page.tsx) |
| `/api/ai/translate` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/ai/translate/route.ts) |
| `/api/auth/logout` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/auth/logout/route.ts) |
| `/api/auth/refresh-app-session` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/auth/refresh-app-session/route.ts) |
| `/api/auth/verify-app-token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/auth/verify-app-token/route.ts) |
| `/api/build-info` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/build-info/route.ts) |
| `/api/cron/calendar/[job]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/cron/calendar/%5Bjob%5D/route.ts) |
| `/api/cron/infrastructure/docker-recovery-alerts` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/cron/infrastructure/docker-recovery-alerts/route.ts) |
| `/api/cron/infrastructure/sample-resources` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/cron/infrastructure/sample-resources/route.ts) |
| `/api/cron/infrastructure/sync-trust-cache` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/cron/infrastructure/sync-trust-cache/route.ts) |
| `/api/parley/references/[id]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/parley/references/%5Bid%5D/route.ts) |
| `/api/v1/admin/account-benefits` | DELETE, GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/admin/account-benefits/route.ts) |
| `/api/v1/admin/ai-credits/allocations` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/admin/ai-credits/allocations/route.ts) |
| `/api/v1/admin/ai-credits/balances` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/admin/ai-credits/balances/route.ts) |
| `/api/v1/admin/ai-credits/entity-detail` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/admin/ai-credits/entity-detail/route.ts) |
| `/api/v1/admin/ai-credits/features` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/admin/ai-credits/features/route.ts) |
| `/api/v1/admin/ai-credits/models/facets` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/admin/ai-credits/models/facets/route.ts) |
| `/api/v1/admin/ai-credits/models` | GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/admin/ai-credits/models/route.ts) |
| `/api/v1/admin/ai-credits/overview` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/admin/ai-credits/overview/route.ts) |
| `/api/v1/admin/ai-credits/sync-models` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/admin/ai-credits/sync-models/route.ts) |
| `/api/v1/admin/ai-credits/transactions` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/admin/ai-credits/transactions/route.ts) |
| `/api/v1/desktop-deployment/bundle` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/desktop-deployment/bundle/route.ts) |
| `/api/v1/desktop-deployment/resources` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/desktop-deployment/resources/route.ts) |
| `/api/v1/desktop-deployment` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/desktop-deployment/route.ts) |
| `/api/v1/infrastructure/abuse-events` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/abuse-events/route.ts) |
| `/api/v1/infrastructure/abuse-intelligence/overrides/[overrideId]` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/abuse-intelligence/overrides/%5BoverrideId%5D/route.ts) |
| `/api/v1/infrastructure/abuse-intelligence` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/abuse-intelligence/route.ts) |
| `/api/v1/infrastructure/ai/models` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/ai/models/route.ts) |
| `/api/v1/infrastructure/ai/stt/modal` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/ai/stt/modal/route.ts) |
| `/api/v1/infrastructure/ai/studio/workspaces` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/ai/studio/workspaces/route.ts) |
| `/api/v1/infrastructure/ai/whitelist/[email]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/ai/whitelist/%5Bemail%5D/route.ts) |
| `/api/v1/infrastructure/ai/whitelist/domain/[domain]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/ai/whitelist/domain/%5Bdomain%5D/route.ts) |
| `/api/v1/infrastructure/ai/whitelist/domains` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/ai/whitelist/domains/route.ts) |
| `/api/v1/infrastructure/ai/whitelist/emails` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/ai/whitelist/emails/route.ts) |
| `/api/v1/infrastructure/ai-agents/[agentId]/channels/[channelId]/secrets` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/ai-agents/%5BagentId%5D/channels/%5BchannelId%5D/secrets/route.ts) |
| `/api/v1/infrastructure/ai-agents/[agentId]/channels/[channelId]/zalo-personal/qr-login` | DELETE, GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/ai-agents/%5BagentId%5D/channels/%5BchannelId%5D/zalo-personal/qr-login/route.ts) |
| `/api/v1/infrastructure/ai-agents/[agentId]/channels/[channelId]/zalo-personal` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/ai-agents/%5BagentId%5D/channels/%5BchannelId%5D/zalo-personal/route.ts) |
| `/api/v1/infrastructure/ai-agents/[agentId]/deploy` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/ai-agents/%5BagentId%5D/deploy/route.ts) |
| `/api/v1/infrastructure/ai-agents/[agentId]/pause` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/ai-agents/%5BagentId%5D/pause/route.ts) |
| `/api/v1/infrastructure/ai-agents/[agentId]/test` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/ai-agents/%5BagentId%5D/test/route.ts) |
| `/api/v1/infrastructure/ai-agents/chat-integrations` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/ai-agents/chat-integrations/route.ts) |
| `/api/v1/infrastructure/ai-agents/discord-gateway/watcher-config` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/ai-agents/discord-gateway/watcher-config/route.ts) |
| `/api/v1/infrastructure/ai-agents/external-threads/[threadId]/draft` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/ai-agents/external-threads/%5BthreadId%5D/draft/route.ts) |
| `/api/v1/infrastructure/ai-agents/external-threads/[threadId]/messages` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/ai-agents/external-threads/%5BthreadId%5D/messages/route.ts) |
| `/api/v1/infrastructure/ai-agents/external-threads/[threadId]/send` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/ai-agents/external-threads/%5BthreadId%5D/send/route.ts) |
| `/api/v1/infrastructure/ai-agents/external-threads/[threadId]/sync` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/ai-agents/external-threads/%5BthreadId%5D/sync/route.ts) |
| `/api/v1/infrastructure/ai-agents/external-threads` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/ai-agents/external-threads/route.ts) |
| `/api/v1/infrastructure/ai-agents/identities` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/ai-agents/identities/route.ts) |
| `/api/v1/infrastructure/ai-agents` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/ai-agents/route.ts) |
| `/api/v1/infrastructure/app-coordination` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/app-coordination/route.ts) |
| `/api/v1/infrastructure/auth-recovery/[overrideId]` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/auth-recovery/%5BoverrideId%5D/route.ts) |
| `/api/v1/infrastructure/auth-recovery/[overrideId]/send-email` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/auth-recovery/%5BoverrideId%5D/send-email/route.ts) |
| `/api/v1/infrastructure/auth-recovery` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/auth-recovery/route.ts) |
| `/api/v1/infrastructure/bill-coupons` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/bill-coupons/route.ts) |
| `/api/v1/infrastructure/bill-packages` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/bill-packages/route.ts) |
| `/api/v1/infrastructure/bills` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/bills/route.ts) |
| `/api/v1/infrastructure/blocked-ips` | DELETE, GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/blocked-ips/route.ts) |
| `/api/v1/infrastructure/changelog/[id]/publish` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/changelog/%5Bid%5D/publish/route.ts) |
| `/api/v1/infrastructure/changelog/[id]` | DELETE, GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/changelog/%5Bid%5D/route.ts) |
| `/api/v1/infrastructure/changelog` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/changelog/route.ts) |
| `/api/v1/infrastructure/changelog/slug/[slug]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/changelog/slug/%5Bslug%5D/route.ts) |
| `/api/v1/infrastructure/changelog/upload` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/changelog/upload/route.ts) |
| `/api/v1/infrastructure/class-attendance` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/class-attendance/route.ts) |
| `/api/v1/infrastructure/class-members` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/class-members/route.ts) |
| `/api/v1/infrastructure/class-packages` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/class-packages/route.ts) |
| `/api/v1/infrastructure/class-scores` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/class-scores/route.ts) |
| `/api/v1/infrastructure/classes` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/classes/route.ts) |
| `/api/v1/infrastructure/coupons` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/coupons/route.ts) |
| `/api/v1/infrastructure/cron/whitelist/domain/[domain]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/cron/whitelist/domain/%5Bdomain%5D/route.ts) |
| `/api/v1/infrastructure/cron/whitelist/domains` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/cron/whitelist/domains/route.ts) |
| `/api/v1/infrastructure/devboxes` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/devboxes/route.ts) |
| `/api/v1/infrastructure/devboxes/runners/[runnerId]/drain` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/devboxes/runners/%5BrunnerId%5D/drain/route.ts) |
| `/api/v1/infrastructure/devboxes/runners/[runnerId]/features` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/devboxes/runners/%5BrunnerId%5D/features/route.ts) |
| `/api/v1/infrastructure/email-blacklist/[entryId]` | DELETE, GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/email-blacklist/%5BentryId%5D/route.ts) |
| `/api/v1/infrastructure/email-blacklist` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/email-blacklist/route.ts) |
| `/api/v1/infrastructure/entity-creation-limits` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/entity-creation-limits/route.ts) |
| `/api/v1/infrastructure/external-apps/[appId]/secrets` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/external-apps/%5BappId%5D/secrets/route.ts) |
| `/api/v1/infrastructure/external-apps/managed-cron-approval` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/external-apps/managed-cron-approval/route.ts) |
| `/api/v1/infrastructure/external-apps` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/external-apps/route.ts) |
| `/api/v1/infrastructure/github-bot/auto-pickup` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/github-bot/auto-pickup/route.ts) |
| `/api/v1/infrastructure/github-bot/clients/[clientId]` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/github-bot/clients/%5BclientId%5D/route.ts) |
| `/api/v1/infrastructure/github-bot/clients` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/github-bot/clients/route.ts) |
| `/api/v1/infrastructure/github-bot/installation-token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/github-bot/installation-token/route.ts) |
| `/api/v1/infrastructure/github-bot` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/github-bot/route.ts) |
| `/api/v1/infrastructure/github-bot/test` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/github-bot/test/route.ts) |
| `/api/v1/infrastructure/internal-accounts/[userId]` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/internal-accounts/%5BuserId%5D/route.ts) |
| `/api/v1/infrastructure/internal-accounts` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/internal-accounts/route.ts) |
| `/api/v1/infrastructure/languages` | DELETE, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/languages/route.ts) |
| `/api/v1/infrastructure/lessons` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/lessons/route.ts) |
| `/api/v1/infrastructure/migrate/bill-coupons` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/bill-coupons/route.ts) |
| `/api/v1/infrastructure/migrate/bill-packages` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/bill-packages/route.ts) |
| `/api/v1/infrastructure/migrate/bills` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/bills/route.ts) |
| `/api/v1/infrastructure/migrate/class-attendance` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/class-attendance/route.ts) |
| `/api/v1/infrastructure/migrate/class-members` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/class-members/route.ts) |
| `/api/v1/infrastructure/migrate/class-packages` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/class-packages/route.ts) |
| `/api/v1/infrastructure/migrate/class-scores` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/class-scores/route.ts) |
| `/api/v1/infrastructure/migrate/class-sessions` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/class-sessions/route.ts) |
| `/api/v1/infrastructure/migrate/classes` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/classes/route.ts) |
| `/api/v1/infrastructure/migrate/coupons` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/coupons/route.ts) |
| `/api/v1/infrastructure/migrate/credit-wallets` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/credit-wallets/route.ts) |
| `/api/v1/infrastructure/migrate/email-blacklist` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/email-blacklist/route.ts) |
| `/api/v1/infrastructure/migrate/ensure-platform-users` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/ensure-platform-users/route.ts) |
| `/api/v1/infrastructure/migrate/finance-budgets` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/finance-budgets/route.ts) |
| `/api/v1/infrastructure/migrate/finance-invoice-products` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/finance-invoice-products/route.ts) |
| `/api/v1/infrastructure/migrate/finance-invoice-promotions` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/finance-invoice-promotions/route.ts) |
| `/api/v1/infrastructure/migrate/finance-invoice-transaction-links` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/finance-invoice-transaction-links/route.ts) |
| `/api/v1/infrastructure/migrate/finance-invoice-user-groups` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/finance-invoice-user-groups/route.ts) |
| `/api/v1/infrastructure/migrate/finance-invoices` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/finance-invoices/route.ts) |
| `/api/v1/infrastructure/migrate/grouped-score-names` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/grouped-score-names/route.ts) |
| `/api/v1/infrastructure/migrate/inventory-batch-products` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/inventory-batch-products/route.ts) |
| `/api/v1/infrastructure/migrate/inventory-batches` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/inventory-batches/route.ts) |
| `/api/v1/infrastructure/migrate/inventory-manufacturers` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/inventory-manufacturers/route.ts) |
| `/api/v1/infrastructure/migrate/inventory-products` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/inventory-products/route.ts) |
| `/api/v1/infrastructure/migrate/inventory-suppliers` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/inventory-suppliers/route.ts) |
| `/api/v1/infrastructure/migrate/lessons` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/lessons/route.ts) |
| `/api/v1/infrastructure/migrate/package-stock-changes` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/package-stock-changes/route.ts) |
| `/api/v1/infrastructure/migrate/packages` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/packages/route.ts) |
| `/api/v1/infrastructure/migrate/payment-methods` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/payment-methods/route.ts) |
| `/api/v1/infrastructure/migrate/post-email-queue` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/post-email-queue/route.ts) |
| `/api/v1/infrastructure/migrate/product-categories` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/product-categories/route.ts) |
| `/api/v1/infrastructure/migrate/product-prices` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/product-prices/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# infrastructure: routes (2/2)
Source: https://docs.tuturuuu.com/reference/repository/routes/infrastructure-2

Source entry points and route ownership for the infrastructure workspace.

Runtime: **Next.js App Router**. Source: [apps/infrastructure](https://github.com/tutur3u/platform/blob/main/apps/infrastructure). Package: `@tuturuuu/infrastructure`.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/api/v1/infrastructure/migrate/product-units` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/product-units/route.ts) |
| `/api/v1/infrastructure/migrate/roles` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/roles/route.ts) |
| `/api/v1/infrastructure/migrate/score-names` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/score-names/route.ts) |
| `/api/v1/infrastructure/migrate/sent-emails` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/sent-emails/route.ts) |
| `/api/v1/infrastructure/migrate/student-feedbacks` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/student-feedbacks/route.ts) |
| `/api/v1/infrastructure/migrate/transaction-categories` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/transaction-categories/route.ts) |
| `/api/v1/infrastructure/migrate/user-coupons` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/user-coupons/route.ts) |
| `/api/v1/infrastructure/migrate/user-group-post-checks` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/user-group-post-checks/route.ts) |
| `/api/v1/infrastructure/migrate/user-monthly-report-logs` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/user-monthly-report-logs/route.ts) |
| `/api/v1/infrastructure/migrate/user-monthly-reports` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/user-monthly-reports/route.ts) |
| `/api/v1/infrastructure/migrate/user-roles` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/user-roles/route.ts) |
| `/api/v1/infrastructure/migrate/user-status-changes` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/user-status-changes/route.ts) |
| `/api/v1/infrastructure/migrate/users` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/users/route.ts) |
| `/api/v1/infrastructure/migrate/wallet-transaction-tags` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/wallet-transaction-tags/route.ts) |
| `/api/v1/infrastructure/migrate/wallet-transactions` | GET, PATCH, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/wallet-transactions/route.ts) |
| `/api/v1/infrastructure/migrate/wallet-types` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/wallet-types/route.ts) |
| `/api/v1/infrastructure/migrate/wallets` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/wallets/route.ts) |
| `/api/v1/infrastructure/migrate/warehouses` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/warehouses/route.ts) |
| `/api/v1/infrastructure/migrate/workspace-configs` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/workspace-configs/route.ts) |
| `/api/v1/infrastructure/migrate/workspace-settings` | GET, PATCH, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/workspace-settings/route.ts) |
| `/api/v1/infrastructure/migrate/workspace-user-fields` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/workspace-user-fields/route.ts) |
| `/api/v1/infrastructure/migrate/workspace-user-group-session-files` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/workspace-user-group-session-files/route.ts) |
| `/api/v1/infrastructure/migrate/workspace-user-group-session-series` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/workspace-user-group-session-series/route.ts) |
| `/api/v1/infrastructure/migrate/workspace-user-group-session-tag-links` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/workspace-user-group-session-tag-links/route.ts) |
| `/api/v1/infrastructure/migrate/workspace-user-group-session-tags` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/workspace-user-group-session-tags/route.ts) |
| `/api/v1/infrastructure/migrate/workspace-user-group-sessions` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/workspace-user-group-sessions/route.ts) |
| `/api/v1/infrastructure/migrate/workspace-user-group-tag-groups` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/workspace-user-group-tag-groups/route.ts) |
| `/api/v1/infrastructure/migrate/workspace-user-group-tags` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/workspace-user-group-tags/route.ts) |
| `/api/v1/infrastructure/migrate/workspace-user-groups` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/workspace-user-groups/route.ts) |
| `/api/v1/infrastructure/migrate/workspace-user-groups-users` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/workspace-user-groups-users/route.ts) |
| `/api/v1/infrastructure/migrate/workspace-user-linked-users` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/workspace-user-linked-users/route.ts) |
| `/api/v1/infrastructure/migrate/workspace-user-status-changes` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/workspace-user-status-changes/route.ts) |
| `/api/v1/infrastructure/migrate/workspace-users` | GET, PATCH, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/workspace-users/route.ts) |
| `/api/v1/infrastructure/migrate/workspace-wallet-transfers` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/workspace-wallet-transfers/route.ts) |
| `/api/v1/infrastructure/migrate/workspace-wallets` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/migrate/workspace-wallets/route.ts) |
| `/api/v1/infrastructure/mobile-versions` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/mobile-versions/route.ts) |
| `/api/v1/infrastructure/monitoring/blue-green/deployment-pin` | DELETE, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/monitoring/blue-green/deployment-pin/route.ts) |
| `/api/v1/infrastructure/monitoring/blue-green/deployment-revert` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/monitoring/blue-green/deployment-revert/route.ts) |
| `/api/v1/infrastructure/monitoring/blue-green/instant-rollout` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/monitoring/blue-green/instant-rollout/route.ts) |
| `/api/v1/infrastructure/monitoring/blue-green/recovery-settings` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/monitoring/blue-green/recovery-settings/route.ts) |
| `/api/v1/infrastructure/monitoring/blue-green/requests` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/monitoring/blue-green/requests/route.ts) |
| `/api/v1/infrastructure/monitoring/blue-green` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/monitoring/blue-green/route.ts) |
| `/api/v1/infrastructure/monitoring/blue-green/watcher-logs` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/monitoring/blue-green/watcher-logs/route.ts) |
| `/api/v1/infrastructure/monitoring/blue-green/watcher-recovery` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/monitoring/blue-green/watcher-recovery/route.ts) |
| `/api/v1/infrastructure/monitoring/cron/control` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/monitoring/cron/control/route.ts) |
| `/api/v1/infrastructure/monitoring/cron/executions` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/monitoring/cron/executions/route.ts) |
| `/api/v1/infrastructure/monitoring/cron/managed/job` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/monitoring/cron/managed/job/route.ts) |
| `/api/v1/infrastructure/monitoring/cron/managed/run` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/monitoring/cron/managed/run/route.ts) |
| `/api/v1/infrastructure/monitoring/cron` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/monitoring/cron/route.ts) |
| `/api/v1/infrastructure/monitoring/cron/run` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/monitoring/cron/run/route.ts) |
| `/api/v1/infrastructure/monitoring/cron/runner-recovery` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/monitoring/cron/runner-recovery/route.ts) |
| `/api/v1/infrastructure/monitoring/stress-tests/[runId]/abort` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/monitoring/stress-tests/%5BrunId%5D/abort/route.ts) |
| `/api/v1/infrastructure/monitoring/stress-tests/[runId]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/monitoring/stress-tests/%5BrunId%5D/route.ts) |
| `/api/v1/infrastructure/monitoring/stress-tests` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/monitoring/stress-tests/route.ts) |
| `/api/v1/infrastructure/observability/analytics` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/observability/analytics/route.ts) |
| `/api/v1/infrastructure/observability/cron-runs` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/observability/cron-runs/route.ts) |
| `/api/v1/infrastructure/observability/deployments` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/observability/deployments/route.ts) |
| `/api/v1/infrastructure/observability/logs` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/observability/logs/route.ts) |
| `/api/v1/infrastructure/observability/overview` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/observability/overview/route.ts) |
| `/api/v1/infrastructure/observability/requests` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/observability/requests/route.ts) |
| `/api/v1/infrastructure/observability/resources` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/observability/resources/route.ts) |
| `/api/v1/infrastructure/otp-limits/reset` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/otp-limits/reset/route.ts) |
| `/api/v1/infrastructure/package-stock-changes` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/package-stock-changes/route.ts) |
| `/api/v1/infrastructure/packages` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/packages/route.ts) |
| `/api/v1/infrastructure/payment-methods` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/payment-methods/route.ts) |
| `/api/v1/infrastructure/post-email-queue` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/post-email-queue/route.ts) |
| `/api/v1/infrastructure/post-email-queue/run-now` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/post-email-queue/run-now/route.ts) |
| `/api/v1/infrastructure/product-categories` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/product-categories/route.ts) |
| `/api/v1/infrastructure/product-prices` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/product-prices/route.ts) |
| `/api/v1/infrastructure/product-units` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/product-units/route.ts) |
| `/api/v1/infrastructure/projects/[projectId]/deploy` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/projects/%5BprojectId%5D/deploy/route.ts) |
| `/api/v1/infrastructure/projects/[projectId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/projects/%5BprojectId%5D/route.ts) |
| `/api/v1/infrastructure/projects/[projectId]/sync` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/projects/%5BprojectId%5D/sync/route.ts) |
| `/api/v1/infrastructure/projects` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/projects/route.ts) |
| `/api/v1/infrastructure/push-notifications` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/push-notifications/route.ts) |
| `/api/v1/infrastructure/push-notifications/test` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/push-notifications/test/route.ts) |
| `/api/v1/infrastructure/rate-limit-appeals/[appealId]` | GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/rate-limit-appeals/%5BappealId%5D/route.ts) |
| `/api/v1/infrastructure/rate-limit-appeals` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/rate-limit-appeals/route.ts) |
| `/api/v1/infrastructure/rate-limit-subjects` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/rate-limit-subjects/route.ts) |
| `/api/v1/infrastructure/rate-limits/live-usage` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/rate-limits/live-usage/route.ts) |
| `/api/v1/infrastructure/rate-limits` | GET, PATCH, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/rate-limits/route.ts) |
| `/api/v1/infrastructure/rate-limits/rules/[ruleId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/rate-limits/rules/%5BruleId%5D/route.ts) |
| `/api/v1/infrastructure/rate-limits/workspace-secrets` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/rate-limits/workspace-secrets/route.ts) |
| `/api/v1/infrastructure/resolve-workspace-id` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/resolve-workspace-id/route.ts) |
| `/api/v1/infrastructure/review-accounts/[userId]` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/review-accounts/%5BuserId%5D/route.ts) |
| `/api/v1/infrastructure/review-accounts/apple-review` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/review-accounts/apple-review/route.ts) |
| `/api/v1/infrastructure/review-accounts` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/review-accounts/route.ts) |
| `/api/v1/infrastructure/roles` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/roles/route.ts) |
| `/api/v1/infrastructure/score-names` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/score-names/route.ts) |
| `/api/v1/infrastructure/sidebar` | DELETE, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/sidebar/route.ts) |
| `/api/v1/infrastructure/sidebar/sizes` | DELETE, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/sidebar/sizes/route.ts) |
| `/api/v1/infrastructure/student-feedbacks` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/student-feedbacks/route.ts) |
| `/api/v1/infrastructure/suspensions/[id]` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/suspensions/%5Bid%5D/route.ts) |
| `/api/v1/infrastructure/suspensions` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/suspensions/route.ts) |
| `/api/v1/infrastructure/timezones/[timezoneId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/timezones/%5BtimezoneId%5D/route.ts) |
| `/api/v1/infrastructure/timezones` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/timezones/route.ts) |
| `/api/v1/infrastructure/transaction-categories` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/transaction-categories/route.ts) |
| `/api/v1/infrastructure/user-coupons` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/user-coupons/route.ts) |
| `/api/v1/infrastructure/user-monthly-report-logs` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/user-monthly-report-logs/route.ts) |
| `/api/v1/infrastructure/user-monthly-reports` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/user-monthly-reports/route.ts) |
| `/api/v1/infrastructure/user-status-changes` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/user-status-changes/route.ts) |
| `/api/v1/infrastructure/users/fields/types` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/users/fields/types/route.ts) |
| `/api/v1/infrastructure/users` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/users/route.ts) |
| `/api/v1/infrastructure/wallet-transactions` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/wallet-transactions/route.ts) |
| `/api/v1/infrastructure/wallets` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/wallets/route.ts) |
| `/api/v1/infrastructure/warehouses` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/infrastructure/warehouses/route.ts) |
| `/api/v1/internal/holidays/[holidayId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/internal/holidays/%5BholidayId%5D/route.ts) |
| `/api/v1/internal/holidays/bulk` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/internal/holidays/bulk/route.ts) |
| `/api/v1/internal/holidays` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/internal/holidays/route.ts) |
| `/api/v1/mobile-calendar/[...path]` | DELETE, GET, PATCH, POST, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/mobile-calendar/%5B...path%5D/route.ts) |
| `/api/v1/mobile-deployment/activate` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/mobile-deployment/activate/route.ts) |
| `/api/v1/mobile-deployment/bundle` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/mobile-deployment/bundle/route.ts) |
| `/api/v1/mobile-deployment/env-export` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/mobile-deployment/env-export/route.ts) |
| `/api/v1/mobile-deployment/files/[kind]` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/mobile-deployment/files/%5Bkind%5D/route.ts) |
| `/api/v1/mobile-deployment/rollback` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/mobile-deployment/rollback/route.ts) |
| `/api/v1/mobile-deployment` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/mobile-deployment/route.ts) |
| `/api/v1/mobile-deployment/tokens/[tokenId]` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/mobile-deployment/tokens/%5BtokenId%5D/route.ts) |
| `/api/v1/mobile-deployment/tokens` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/mobile-deployment/tokens/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/credits` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/workspaces/%5BwsId%5D/ai/credits/route.ts) |
| `/api/v1/workspaces/[wsId]/avatar` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/workspaces/%5BwsId%5D/avatar/route.ts) |
| `/api/v1/workspaces/[wsId]/avatar/upload-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/workspaces/%5BwsId%5D/avatar/upload-url/route.ts) |
| `/api/v1/workspaces/[wsId]/infrastructure/realtime/analytics` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/workspaces/%5BwsId%5D/infrastructure/realtime/analytics/route.ts) |
| `/api/v1/workspaces/[wsId]/infrastructure/realtime/analytics/summary` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/workspaces/%5BwsId%5D/infrastructure/realtime/analytics/summary/route.ts) |
| `/api/v1/workspaces/[wsId]/settings/calendar-sync` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/workspaces/%5BwsId%5D/settings/calendar-sync/route.ts) |
| `/api/v1/workspaces/[wsId]/settings/email-audit` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/v1/workspaces/%5BwsId%5D/settings/email-audit/route.ts) |
| `/api/workspaces/[wsId]` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/workspaces/%5BwsId%5D/route.ts) |
| `/api/workspaces/[wsId]/secrets/[secretId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/workspaces/%5BwsId%5D/secrets/%5BsecretId%5D/route.ts) |
| `/api/workspaces/[wsId]/secrets` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/workspaces/%5BwsId%5D/secrets/route.ts) |
| `/api/workspaces` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/infrastructure/src/app/api/workspaces/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# inventory: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/inventory

Source entry points and route ownership for the inventory workspace.

Runtime: **Next.js App Router**. Source: [apps/inventory](https://github.com/tutur3u/platform/blob/main/apps/inventory). Package: `@tuturuuu/inventory`.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/[locale]/login` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/%5Blocale%5D/$auth$/login/page.tsx) |
| `/[locale]/verify-token` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/%5Blocale%5D/$auth$/verify-token/page.tsx) |
| `/[locale]/[wsId]/analytics` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/analytics/page.tsx) |
| `/[locale]/[wsId]/audits` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/audits/page.tsx) |
| `/[locale]/[wsId]/bundles` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/bundles/page.tsx) |
| `/[locale]/[wsId]/catalog` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/catalog/page.tsx) |
| `/[locale]/[wsId]/checkout` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/checkout/page.tsx) |
| `/[locale]/[wsId]/checkouts` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/checkouts/page.tsx) |
| `/[locale]/[wsId]/commerce` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/commerce/page.tsx) |
| `/[locale]/[wsId]/costing` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/costing/page.tsx) |
| `/[locale]/[wsId]/items` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/items/page.tsx) |
| `/[locale]/[wsId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/page.tsx) |
| `/[locale]/[wsId]/payments` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/payments/page.tsx) |
| `/[locale]/[wsId]/polar` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/polar/page.tsx) |
| `/[locale]/[wsId]/pos-devices` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/pos-devices/page.tsx) |
| `/[locale]/[wsId]/promotions` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/promotions/page.tsx) |
| `/[locale]/[wsId]/sales` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/sales/page.tsx) |
| `/[locale]/[wsId]/setup` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/setup/page.tsx) |
| `/[locale]/[wsId]/stock` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/stock/page.tsx) |
| `/[locale]/[wsId]/storefront` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/storefront/page.tsx) |
| `/[locale]/[wsId]/storefront/preview/[storefrontId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/storefront/preview/%5BstorefrontId%5D/page.tsx) |
| `/[locale]/[wsId]/stripe` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/stripe/page.tsx) |
| `/[locale]/dashboard` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/%5Blocale%5D/$dashboard$/dashboard/page.tsx) |
| `/[locale]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/%5Blocale%5D/page.tsx) |
| `/[locale]/store/[storeSlug]/cart` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/%5Blocale%5D/store/%5BstoreSlug%5D/cart/page.tsx) |
| `/[locale]/store/[storeSlug]/checkout` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/%5Blocale%5D/store/%5BstoreSlug%5D/checkout/page.tsx) |
| `/[locale]/store/[storeSlug]/orders/[publicToken]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/%5Blocale%5D/store/%5BstoreSlug%5D/orders/%5BpublicToken%5D/page.tsx) |
| `/[locale]/store/[storeSlug]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/%5Blocale%5D/store/%5BstoreSlug%5D/page.tsx) |
| `/[locale]/store/[storeSlug]/products/[listingId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/%5Blocale%5D/store/%5BstoreSlug%5D/products/%5BlistingId%5D/page.tsx) |
| `/api/auth/logout` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/auth/logout/route.ts) |
| `/api/auth/refresh-app-session` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/auth/refresh-app-session/route.ts) |
| `/api/auth/verify-app-token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/auth/verify-app-token/route.ts) |
| `/api/build-info` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/build-info/route.ts) |
| `/api/cron/inventory/checkout-expiry` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/cron/inventory/checkout-expiry/route.ts) |
| `/api/cron/inventory/polar-product-sync` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/cron/inventory/polar-product-sync/route.ts) |
| `/api/v1/inventory/orders/[publicToken]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/inventory/orders/%5BpublicToken%5D/route.ts) |
| `/api/v1/inventory/orders` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/inventory/orders/route.ts) |
| `/api/v1/inventory/polar/webhook/[wsId]` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/inventory/polar/webhook/%5BwsId%5D/route.ts) |
| `/api/v1/inventory/square/oauth/callback` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/inventory/square/oauth/callback/route.ts) |
| `/api/v1/inventory/square/pos/callback` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/inventory/square/pos/callback/route.ts) |
| `/api/v1/inventory/square/webhook/[wsId]` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/inventory/square/webhook/%5BwsId%5D/route.ts) |
| `/api/v1/inventory/square/webhook` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/inventory/square/webhook/route.ts) |
| `/api/v1/inventory/storefronts/[slug]/analytics/events` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/inventory/storefronts/%5Bslug%5D/analytics/events/route.ts) |
| `/api/v1/inventory/storefronts/[slug]/checkout-options` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/inventory/storefronts/%5Bslug%5D/checkout-options/route.ts) |
| `/api/v1/inventory/storefronts/[slug]/checkouts` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/inventory/storefronts/%5Bslug%5D/checkouts/route.ts) |
| `/api/v1/inventory/storefronts/[slug]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/inventory/storefronts/%5Bslug%5D/route.ts) |
| `/api/v1/inventory/storefronts/[slug]/staff-checkout-options` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/inventory/storefronts/%5Bslug%5D/staff-checkout-options/route.ts) |
| `/api/v1/webhooks/sepay/[token]` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/webhooks/sepay/%5Btoken%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/credits` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/ai/credits/route.ts) |
| `/api/v1/workspaces/[wsId]/avatar` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/avatar/route.ts) |
| `/api/v1/workspaces/[wsId]/avatar/upload-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/avatar/upload-url/route.ts) |
| `/api/v1/workspaces/[wsId]/integrations/sepay/disconnect` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/integrations/sepay/disconnect/route.ts) |
| `/api/v1/workspaces/[wsId]/integrations/sepay/endpoints/[id]/rotate` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/integrations/sepay/endpoints/%5Bid%5D/rotate/route.ts) |
| `/api/v1/workspaces/[wsId]/integrations/sepay/endpoints/[id]` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/integrations/sepay/endpoints/%5Bid%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/integrations/sepay/endpoints` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/integrations/sepay/endpoints/route.ts) |
| `/api/v1/workspaces/[wsId]/integrations/sepay/oauth/callback` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/integrations/sepay/oauth/callback/route.ts) |
| `/api/v1/workspaces/[wsId]/integrations/sepay/oauth/start` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/integrations/sepay/oauth/start/route.ts) |
| `/api/v1/workspaces/[wsId]/integrations/sepay/provision-webhooks` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/integrations/sepay/provision-webhooks/route.ts) |
| `/api/v1/workspaces/[wsId]/integrations/sepay/sync-bank-accounts` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/integrations/sepay/sync-bank-accounts/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/access` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/access/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/analytics` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/analytics/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/analytics/summary` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/analytics/summary/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/audit-logs` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/audit-logs/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/batches/[batchId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/batches/%5BbatchId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/batches` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/batches/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/bundles/[bundleId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/bundles/%5BbundleId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/bundles` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/bundles/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/categories/[categoryId]` | DELETE, PATCH, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/categories/%5BcategoryId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/categories` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/categories/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/checkouts/[checkoutId]/release` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/checkouts/%5BcheckoutId%5D/release/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/checkouts` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/checkouts/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/costing/[profileId]` | DELETE, GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/costing/%5BprofileId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/costing/analytics` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/costing/analytics/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/costing/import` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/costing/import/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/costing` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/costing/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/manufacturers/[manufacturerId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/manufacturers/%5BmanufacturerId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/manufacturers` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/manufacturers/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/media/read-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/media/read-url/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/media/upload-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/media/upload-url/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/offline-mutations` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/offline-mutations/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/option-templates/[templateId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/option-templates/%5BtemplateId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/option-templates` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/option-templates/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/overview` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/overview/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/owners/[ownerId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/owners/%5BownerId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/owners` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/owners/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/polar-product-sync` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/polar-product-sync/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/polar-settings` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/polar-settings/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/product-form-options` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/product-form-options/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/products` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/products/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/realtime` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/realtime/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/revenue-share` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/revenue-share/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/sale-requests/[requestId]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/sale-requests/%5BrequestId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/sales/[saleId]/period` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/sales/%5BsaleId%5D/period/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/sales/[saleId]` | DELETE, GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/sales/%5BsaleId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/sales/bulk-period` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/sales/bulk-period/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/sales/by-product` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/sales/by-product/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/sales/export` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/sales/export/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/sales` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/sales/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/sales/summary` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/sales/summary/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/sales-defaults` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/sales-defaults/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/sales-periods/[periodId]/prices` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/sales-periods/%5BperiodId%5D/prices/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/sales-periods/[periodId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/sales-periods/%5BperiodId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/sales-periods` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/sales-periods/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/square/catalog-sync` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/square/catalog-sync/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/square/device-codes` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/square/device-codes/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/square/devices` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/square/devices/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/square/locations` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/square/locations/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/square/oauth/start` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/square/oauth/start/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/square/terminal-checkouts/[checkoutId]/cancel` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/square/terminal-checkouts/%5BcheckoutId%5D/cancel/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/square/terminal-checkouts` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/square/terminal-checkouts/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/square-settings` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/square-settings/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/statistics` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/statistics/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/stock-beneficiaries` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/stock-beneficiaries/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/storefronts/[storefrontId]/listings/[listingId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/storefronts/%5BstorefrontId%5D/listings/%5BlistingId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/storefronts/[storefrontId]/listings/bulk-import` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/storefronts/%5BstorefrontId%5D/listings/bulk-import/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/storefronts/[storefrontId]/listings` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/storefronts/%5BstorefrontId%5D/listings/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/storefronts/[storefrontId]` | DELETE, GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/storefronts/%5BstorefrontId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/storefronts` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/storefronts/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/suppliers/[supplierId]` | DELETE, PATCH, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/suppliers/%5BsupplierId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/suppliers` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/suppliers/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/warehouses/[warehouseId]` | DELETE, PATCH, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/warehouses/%5BwarehouseId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/warehouses` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/inventory/warehouses/route.ts) |
| `/api/v1/workspaces/[wsId]/product-categories/[categoryId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/product-categories/%5BcategoryId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/product-categories` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/product-categories/route.ts) |
| `/api/v1/workspaces/[wsId]/product-suppliers/[supplierId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/product-suppliers/%5BsupplierId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/product-suppliers` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/product-suppliers/route.ts) |
| `/api/v1/workspaces/[wsId]/product-units/[unitId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/product-units/%5BunitId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/product-units` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/product-units/route.ts) |
| `/api/v1/workspaces/[wsId]/product-warehouses/[warehouseId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/product-warehouses/%5BwarehouseId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/product-warehouses` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/product-warehouses/route.ts) |
| `/api/v1/workspaces/[wsId]/products/[productId]/inventory/history` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/products/%5BproductId%5D/inventory/history/route.ts) |
| `/api/v1/workspaces/[wsId]/products/[productId]/inventory` | DELETE, GET, PATCH, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/products/%5BproductId%5D/inventory/route.ts) |
| `/api/v1/workspaces/[wsId]/products/[productId]` | DELETE, GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/products/%5BproductId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/products/count` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/products/count/route.ts) |
| `/api/v1/workspaces/[wsId]/products/options` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/products/options/route.ts) |
| `/api/v1/workspaces/[wsId]/products` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/products/route.ts) |
| `/api/v1/workspaces/[wsId]/promotions/[promotionId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/promotions/%5BpromotionId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/promotions/count` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/promotions/count/route.ts) |
| `/api/v1/workspaces/[wsId]/promotions/referral-settings` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/promotions/referral-settings/route.ts) |
| `/api/v1/workspaces/[wsId]/promotions` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/promotions/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/linked-products/[productId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/linked-products/%5BproductId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/linked-products` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/linked-products/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/linked-products` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/linked-products/route.ts) |
| `/api/v1/workspaces/[wsId]/users/[userId]/linked-promotions` | DELETE, GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/v1/workspaces/%5BwsId%5D/users/%5BuserId%5D/linked-promotions/route.ts) |
| `/api/workspaces/[wsId]` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/inventory/src/app/api/workspaces/%5BwsId%5D/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# learn: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/learn

Source entry points and route ownership for the learn workspace.

Runtime: **Next.js App Router**. Source: [apps/learn](https://github.com/tutur3u/platform/blob/main/apps/learn). Package: `@tuturuuu/learn`.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/[locale]/login` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/%5Blocale%5D/$auth$/login/page.tsx) |
| `/[locale]/verify-token` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/%5Blocale%5D/$auth$/verify-token/page.tsx) |
| `/[locale]/[wsId]/ai-chat` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/ai-chat/page.tsx) |
| `/[locale]/[wsId]/assignments` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/assignments/page.tsx) |
| `/[locale]/[wsId]/coding` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/coding/page.tsx) |
| `/[locale]/[wsId]/courses/[courseId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/courses/%5BcourseId%5D/page.tsx) |
| `/[locale]/[wsId]/courses/[courseId]/tests/[testId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/courses/%5BcourseId%5D/tests/%5BtestId%5D/page.tsx) |
| `/[locale]/[wsId]/courses` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/courses/page.tsx) |
| `/[locale]/[wsId]/marks` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/marks/page.tsx) |
| `/[locale]/[wsId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/page.tsx) |
| `/[locale]/[wsId]/practice` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/practice/page.tsx) |
| `/[locale]/[wsId]/programming` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/programming/page.tsx) |
| `/[locale]/[wsId]/programming/playgrounds/[projectId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/programming/playgrounds/%5BprojectId%5D/page.tsx) |
| `/[locale]/[wsId]/programming/playgrounds` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/programming/playgrounds/page.tsx) |
| `/[locale]/[wsId]/programming/problems/[problemId]/edit` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/programming/problems/%5BproblemId%5D/edit/page.tsx) |
| `/[locale]/[wsId]/programming/problems/[problemId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/programming/problems/%5BproblemId%5D/page.tsx) |
| `/[locale]/[wsId]/programming/problems/new` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/programming/problems/new/page.tsx) |
| `/[locale]/[wsId]/reports` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/reports/page.tsx) |
| `/[locale]/[wsId]/settings` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/settings/page.tsx) |
| `/[locale]/[wsId]/todo` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/todo/page.tsx) |
| `/[locale]/dashboard` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/%5Blocale%5D/dashboard/page.tsx) |
| `/[locale]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/%5Blocale%5D/page.tsx) |
| `/api/auth/logout` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/api/auth/logout/route.ts) |
| `/api/auth/refresh-app-session` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/api/auth/refresh-app-session/route.ts) |
| `/api/auth/verify-app-token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/api/auth/verify-app-token/route.ts) |
| `/api/build-info` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/api/build-info/route.ts) |
| `/api/v1/course` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/api/v1/course/route.ts) |
| `/api/v1/tulearn/bootstrap` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/api/v1/tulearn/bootstrap/route.ts) |
| `/api/v1/vocabulary/pronunciation` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/api/v1/vocabulary/pronunciation/route.ts) |
| `/api/v1/vocabulary/speech` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/api/v1/vocabulary/speech/route.ts) |
| `/api/v1/workspaces/[wsId]/course-modules/[moduleId]/vocabulary` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/api/v1/workspaces/%5BwsId%5D/course-modules/%5BmoduleId%5D/vocabulary/route.ts) |
| `/api/v1/workspaces/[wsId]/tulearn/assignments` | GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/api/v1/workspaces/%5BwsId%5D/tulearn/assignments/route.ts) |
| `/api/v1/workspaces/[wsId]/tulearn/courses/[courseId]/modules/[moduleId]` | DELETE, GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/api/v1/workspaces/%5BwsId%5D/tulearn/courses/%5BcourseId%5D/modules/%5BmoduleId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/tulearn/courses/[courseId]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/api/v1/workspaces/%5BwsId%5D/tulearn/courses/%5BcourseId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/tulearn/courses/[courseId]/tests/[testId]/attempt` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/api/v1/workspaces/%5BwsId%5D/tulearn/courses/%5BcourseId%5D/tests/%5BtestId%5D/attempt/route.ts) |
| `/api/v1/workspaces/[wsId]/tulearn/courses/[courseId]/tests/[testId]/save-answer` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/api/v1/workspaces/%5BwsId%5D/tulearn/courses/%5BcourseId%5D/tests/%5BtestId%5D/save-answer/route.ts) |
| `/api/v1/workspaces/[wsId]/tulearn/courses/[courseId]/tests/[testId]/start` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/api/v1/workspaces/%5BwsId%5D/tulearn/courses/%5BcourseId%5D/tests/%5BtestId%5D/start/route.ts) |
| `/api/v1/workspaces/[wsId]/tulearn/courses/[courseId]/tests/[testId]/submit` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/api/v1/workspaces/%5BwsId%5D/tulearn/courses/%5BcourseId%5D/tests/%5BtestId%5D/submit/route.ts) |
| `/api/v1/workspaces/[wsId]/tulearn/courses` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/api/v1/workspaces/%5BwsId%5D/tulearn/courses/route.ts) |
| `/api/v1/workspaces/[wsId]/tulearn/home` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/api/v1/workspaces/%5BwsId%5D/tulearn/home/route.ts) |
| `/api/v1/workspaces/[wsId]/tulearn/marks` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/api/v1/workspaces/%5BwsId%5D/tulearn/marks/route.ts) |
| `/api/v1/workspaces/[wsId]/tulearn/parent-links/[linkId]` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/api/v1/workspaces/%5BwsId%5D/tulearn/parent-links/%5BlinkId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/tulearn/parent-links` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/api/v1/workspaces/%5BwsId%5D/tulearn/parent-links/route.ts) |
| `/api/v1/workspaces/[wsId]/tulearn/practice` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/api/v1/workspaces/%5BwsId%5D/tulearn/practice/route.ts) |
| `/api/v1/workspaces/[wsId]/tulearn/reports` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/api/v1/workspaces/%5BwsId%5D/tulearn/reports/route.ts) |
| `/api/v1/workspaces/[wsId]/tulearn/todo` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/learn/src/app/api/v1/workspaces/%5BwsId%5D/tulearn/todo/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# lettin: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/lettin

Source entry points and route ownership for the lettin workspace.

Runtime: **Next.js App Router**. Source: [apps/lettin](https://github.com/tutur3u/platform/blob/main/apps/lettin). Package: `@tuturuuu/lettin`.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/[locale]/[wsId]/moderation` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/%5Blocale%5D/%5BwsId%5D/moderation/page.tsx) |
| `/[locale]/[wsId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/%5Blocale%5D/%5BwsId%5D/page.tsx) |
| `/[locale]/[wsId]/profile` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/%5Blocale%5D/%5BwsId%5D/profile/page.tsx) |
| `/[locale]/[wsId]/spaces/[space]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/%5Blocale%5D/%5BwsId%5D/spaces/%5Bspace%5D/page.tsx) |
| `/[locale]/[wsId]/toolkit` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/%5Blocale%5D/%5BwsId%5D/toolkit/page.tsx) |
| `/[locale]/[wsId]/wiki/[worldId]/[section]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/%5Blocale%5D/%5BwsId%5D/wiki/%5BworldId%5D/%5Bsection%5D/page.tsx) |
| `/[locale]/[wsId]/wiki` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/%5Blocale%5D/%5BwsId%5D/wiki/page.tsx) |
| `/[locale]/[wsId]/worlds/[worldId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/%5Blocale%5D/%5BwsId%5D/worlds/%5BworldId%5D/page.tsx) |
| `/[locale]/creators/[creatorId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/%5Blocale%5D/creators/%5BcreatorId%5D/page.tsx) |
| `/[locale]/dashboard` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/%5Blocale%5D/dashboard/page.tsx) |
| `/[locale]/login` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/%5Blocale%5D/login/page.tsx) |
| `/[locale]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/%5Blocale%5D/page.tsx) |
| `/[locale]/saved` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/%5Blocale%5D/saved/page.tsx) |
| `/[locale]/spaces` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/%5Blocale%5D/spaces/page.tsx) |
| `/[locale]/verify-token` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/%5Blocale%5D/verify-token/page.tsx) |
| `/[locale]/worlds/[worldId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/%5Blocale%5D/worlds/%5BworldId%5D/page.tsx) |
| `/[locale]/worlds` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/%5Blocale%5D/worlds/page.tsx) |
| `/api/auth/logout` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/api/auth/logout/route.ts) |
| `/api/auth/refresh-app-session` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/api/auth/refresh-app-session/route.ts) |
| `/api/auth/verify-app-token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/api/auth/verify-app-token/route.ts) |
| `/api/v1/lettin/bookmarks` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/api/v1/lettin/bookmarks/route.ts) |
| `/api/v1/lettin/creator-bookmarks` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/api/v1/lettin/creator-bookmarks/route.ts) |
| `/api/v1/lettin/health` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/api/v1/lettin/health/route.ts) |
| `/api/v1/lettin/media/[mediaId]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/api/v1/lettin/media/%5BmediaId%5D/route.ts) |
| `/api/v1/lettin/worlds` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/api/v1/lettin/worlds/route.ts) |
| `/api/v1/workspaces/[wsId]/lettin/exocorpse` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/api/v1/workspaces/%5BwsId%5D/lettin/exocorpse/route.ts) |
| `/api/v1/workspaces/[wsId]/lettin/export` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/api/v1/workspaces/%5BwsId%5D/lettin/export/route.ts) |
| `/api/v1/workspaces/[wsId]/lettin/import` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/api/v1/workspaces/%5BwsId%5D/lettin/import/route.ts) |
| `/api/v1/workspaces/[wsId]/lettin/media` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/api/v1/workspaces/%5BwsId%5D/lettin/media/route.ts) |
| `/api/v1/workspaces/[wsId]/lettin/moderation` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/api/v1/workspaces/%5BwsId%5D/lettin/moderation/route.ts) |
| `/api/v1/workspaces/[wsId]/lettin/profile` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/api/v1/workspaces/%5BwsId%5D/lettin/profile/route.ts) |
| `/api/v1/workspaces/[wsId]/lettin` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/lettin/src/app/api/v1/workspaces/%5BwsId%5D/lettin/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# mail: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/mail

Source entry points and route ownership for the mail workspace.

Runtime: **Next.js App Router**. Source: [apps/mail](https://github.com/tutur3u/platform/blob/main/apps/mail). Package: `@tuturuuu/mail`.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/[locale]/login` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/%5Blocale%5D/$auth$/login/page.tsx) |
| `/[locale]/verify-token` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/%5Blocale%5D/$auth$/verify-token/page.tsx) |
| `/[locale]/[wsId]/archive` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/archive/page.tsx) |
| `/[locale]/[wsId]/drafts` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/drafts/page.tsx) |
| `/[locale]/[wsId]/inbox` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/inbox/page.tsx) |
| `/[locale]/[wsId]/muted` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/muted/page.tsx) |
| `/[locale]/[wsId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/page.tsx) |
| `/[locale]/[wsId]/sent` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/sent/page.tsx) |
| `/[locale]/[wsId]/snoozed` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/snoozed/page.tsx) |
| `/[locale]/[wsId]/spam` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/spam/page.tsx) |
| `/[locale]/[wsId]/starred` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/starred/page.tsx) |
| `/[locale]/[wsId]/trash` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/trash/page.tsx) |
| `/[locale]/not-available` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/%5Blocale%5D/not-available/page.tsx) |
| `/[locale]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/%5Blocale%5D/page.tsx) |
| `/api/ai/email-draft` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/ai/email-draft/route.ts) |
| `/api/auth/logout` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/auth/logout/route.ts) |
| `/api/auth/refresh-app-session` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/auth/refresh-app-session/route.ts) |
| `/api/auth/verify-app-token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/auth/verify-app-token/route.ts) |
| `/api/build-info` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/build-info/route.ts) |
| `/api/v1/mail/connected/callback` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/mail/connected/callback/route.ts) |
| `/api/v1/mail/domains/[domainId]/catch-all` | GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/mail/domains/%5BdomainId%5D/catch-all/route.ts) |
| `/api/v1/mail/domains` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/mail/domains/route.ts) |
| `/api/v1/webhooks/mail/cloudflare` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/webhooks/mail/cloudflare/route.ts) |
| `/api/v1/webhooks/mail/ses` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/webhooks/mail/ses/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/bootstrap` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/bootstrap/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/connected/[[...segments]]` | DELETE, GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/connected/%5B%5B...segments%5D%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/mailboxes/[mailboxId]/ai/draft` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/mailboxes/%5BmailboxId%5D/ai/draft/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/mailboxes/[mailboxId]/ai/labels` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/mailboxes/%5BmailboxId%5D/ai/labels/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/mailboxes/[mailboxId]/drafts/[draftId]/attachments/[attachmentId]` | DELETE, GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/mailboxes/%5BmailboxId%5D/drafts/%5BdraftId%5D/attachments/%5BattachmentId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/mailboxes/[mailboxId]/drafts/[draftId]/attachments` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/mailboxes/%5BmailboxId%5D/drafts/%5BdraftId%5D/attachments/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/mailboxes/[mailboxId]/drafts/[draftId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/mailboxes/%5BmailboxId%5D/drafts/%5BdraftId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/mailboxes/[mailboxId]/drafts` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/mailboxes/%5BmailboxId%5D/drafts/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/mailboxes/[mailboxId]/folders/[folderId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/mailboxes/%5BmailboxId%5D/folders/%5BfolderId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/mailboxes/[mailboxId]/folders` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/mailboxes/%5BmailboxId%5D/folders/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/mailboxes/[mailboxId]/labels/[labelId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/mailboxes/%5BmailboxId%5D/labels/%5BlabelId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/mailboxes/[mailboxId]/labels` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/mailboxes/%5BmailboxId%5D/labels/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/mailboxes/[mailboxId]/members/[userId]` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/mailboxes/%5BmailboxId%5D/members/%5BuserId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/mailboxes/[mailboxId]/members` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/mailboxes/%5BmailboxId%5D/members/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/mailboxes/[mailboxId]/messages/[messageId]/attachments/[attachmentId]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/mailboxes/%5BmailboxId%5D/messages/%5BmessageId%5D/attachments/%5BattachmentId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/mailboxes/[mailboxId]/messages/[messageId]/blacklist` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/mailboxes/%5BmailboxId%5D/messages/%5BmessageId%5D/blacklist/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/mailboxes/[mailboxId]/messages/[messageId]/calendar-link/preview` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/mailboxes/%5BmailboxId%5D/messages/%5BmessageId%5D/calendar-link/preview/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/mailboxes/[mailboxId]/messages/[messageId]/calendar-link` | DELETE, GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/mailboxes/%5BmailboxId%5D/messages/%5BmessageId%5D/calendar-link/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/mailboxes/[mailboxId]/messages/[messageId]/invitation` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/mailboxes/%5BmailboxId%5D/messages/%5BmessageId%5D/invitation/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/mailboxes/[mailboxId]/messages/[messageId]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/mailboxes/%5BmailboxId%5D/messages/%5BmessageId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/mailboxes/[mailboxId]/messages/[messageId]/state` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/mailboxes/%5BmailboxId%5D/messages/%5BmessageId%5D/state/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/mailboxes/[mailboxId]/messages/bulk` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/mailboxes/%5BmailboxId%5D/messages/bulk/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/mailboxes/[mailboxId]/messages` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/mailboxes/%5BmailboxId%5D/messages/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/mailboxes/[mailboxId]/organization` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/mailboxes/%5BmailboxId%5D/organization/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/mailboxes/[mailboxId]/read-all` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/mailboxes/%5BmailboxId%5D/read-all/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/mailboxes/[mailboxId]/settings` | GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/mailboxes/%5BmailboxId%5D/settings/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/mailboxes/[mailboxId]/threads/[threadId]` | GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/mailboxes/%5BmailboxId%5D/threads/%5BthreadId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/mailboxes/[mailboxId]/threads/bulk` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/mailboxes/%5BmailboxId%5D/threads/bulk/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/mailboxes/[mailboxId]/threads` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/mailboxes/%5BmailboxId%5D/threads/route.ts) |
| `/api/v1/workspaces/[wsId]/mail` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/route.ts) |
| `/api/v1/workspaces/[wsId]/mail/send` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mail/src/app/api/v1/workspaces/%5BwsId%5D/mail/send/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# meet: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/meet

Source entry points and route ownership for the meet workspace.

Runtime: **Next.js App Router**. Source: [apps/meet](https://github.com/tutur3u/platform/blob/main/apps/meet). Package: `@tuturuuu/meet`.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/[locale]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/%5Blocale%5D/$app$/page.tsx) |
| `/[locale]/plans/[planId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/%5Blocale%5D/$app$/plans/%5BplanId%5D/page.tsx) |
| `/[locale]/login` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/%5Blocale%5D/$auth$/login/page.tsx) |
| `/[locale]/verify-token` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/%5Blocale%5D/$auth$/verify-token/page.tsx) |
| `/[locale]/[wsId]/meetings/[meetingId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/%5Blocale%5D/%5BwsId%5D/meetings/%5BmeetingId%5D/page.tsx) |
| `/[locale]/[wsId]/meetings` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/%5Blocale%5D/%5BwsId%5D/meetings/page.tsx) |
| `/[locale]/[wsId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/%5Blocale%5D/%5BwsId%5D/page.tsx) |
| `/[locale]/[wsId]/plans` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/%5Blocale%5D/%5BwsId%5D/plans/page.tsx) |
| `/[locale]/native-collaboration` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/%5Blocale%5D/native-collaboration/page.tsx) |
| `/[locale]/r/[code]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/%5Blocale%5D/r/%5Bcode%5D/page.tsx) |
| `/[locale]/r/[code]/preview` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/%5Blocale%5D/r/%5Bcode%5D/preview/route.tsx) |
| `/api/auth/logout` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/api/auth/logout/route.ts) |
| `/api/auth/refresh-app-session` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/api/auth/refresh-app-session/route.ts) |
| `/api/auth/verify-app-token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/api/auth/verify-app-token/route.ts) |
| `/api/build-info` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/api/build-info/route.ts) |
| `/api/meet-ai/[wsId]/[meetingId]/chunks` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/api/meet-ai/%5BwsId%5D/%5BmeetingId%5D/chunks/route.ts) |
| `/api/meet-ai/[wsId]/[meetingId]/followups` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/api/meet-ai/%5BwsId%5D/%5BmeetingId%5D/followups/route.ts) |
| `/api/meet-ai/[wsId]/[meetingId]` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/api/meet-ai/%5BwsId%5D/%5BmeetingId%5D/route.ts) |
| `/api/meet-call/[meetingId]/assistant/personal` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/api/meet-call/%5BmeetingId%5D/assistant/personal/route.ts) |
| `/api/meet-call/[meetingId]/assistant/review` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/api/meet-call/%5BmeetingId%5D/assistant/review/route.ts) |
| `/api/meet-call/[meetingId]/assistant` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/api/meet-call/%5BmeetingId%5D/assistant/route.ts) |
| `/api/meet-call/[meetingId]/costs` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/api/meet-call/%5BmeetingId%5D/costs/route.ts) |
| `/api/meet-call/[meetingId]/document` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/api/meet-call/%5BmeetingId%5D/document/route.ts) |
| `/api/meet-call/[meetingId]/files` | DELETE, GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/api/meet-call/%5BmeetingId%5D/files/route.ts) |
| `/api/meet-call/[meetingId]/programming/preview/[port]/[[...path]]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/api/meet-call/%5BmeetingId%5D/programming/preview/%5Bport%5D/%5B%5B...path%5D%5D/route.ts) |
| `/api/meet-call/[meetingId]/programming` | GET, POST, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/api/meet-call/%5BmeetingId%5D/programming/route.ts) |
| `/api/meet-call/[meetingId]/public-info` | GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/api/meet-call/%5BmeetingId%5D/public-info/route.ts) |
| `/api/meet-call/[meetingId]/recording` | GET, POST, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/api/meet-call/%5BmeetingId%5D/recording/route.ts) |
| `/api/meet-call/[meetingId]/state` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/api/meet-call/%5BmeetingId%5D/state/route.ts) |
| `/api/meet-call/[meetingId]/title` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/api/meet-call/%5BmeetingId%5D/title/route.ts) |
| `/api/meet-call/[meetingId]/token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/api/meet-call/%5BmeetingId%5D/token/route.ts) |
| `/api/meet-live/[meetingId]/review` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/api/meet-live/%5BmeetingId%5D/review/route.ts) |
| `/api/meet-live/[meetingId]` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/api/meet-live/%5BmeetingId%5D/route.ts) |
| `/api/meet-live/memory` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/meet/src/app/api/meet-live/memory/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# meet-realtime: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/meet-realtime

Source entry points and route ownership for the meet-realtime workspace.

Runtime: **Service or supporting workspace**. Source: [apps/meet-realtime](https://github.com/tutur3u/platform/blob/main/apps/meet-realtime). Package: `@tuturuuu/meet-realtime`.

This workspace has no Next.js page/handler inventory. Read [the owning workspace](https://github.com/tutur3u/platform/blob/main/apps/meet-realtime) for native, Worker, or infrastructure entry points and the [active runtime map](/build/devops/active-runtime) for operational ownership.

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# mind: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/mind

Source entry points and route ownership for the mind workspace.

Runtime: **Next.js App Router**. Source: [apps/mind](https://github.com/tutur3u/platform/blob/main/apps/mind). Package: `@tuturuuu/mind`.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/[locale]/login` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mind/src/app/%5Blocale%5D/$auth$/login/page.tsx) |
| `/[locale]/verify-token` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mind/src/app/%5Blocale%5D/$auth$/verify-token/page.tsx) |
| `/[locale]/[wsId]/boards/[boardId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mind/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/boards/%5BboardId%5D/page.tsx) |
| `/[locale]/[wsId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mind/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/page.tsx) |
| `/[locale]/dashboard` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mind/src/app/%5Blocale%5D/$dashboard$/dashboard/page.tsx) |
| `/[locale]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mind/src/app/%5Blocale%5D/page.tsx) |
| `/api/ai/mind` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mind/src/app/api/ai/mind/route.ts) |
| `/api/auth/logout` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mind/src/app/api/auth/logout/route.ts) |
| `/api/auth/refresh-app-session` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mind/src/app/api/auth/refresh-app-session/route.ts) |
| `/api/auth/verify-app-token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mind/src/app/api/auth/verify-app-token/route.ts) |
| `/api/build-info` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mind/src/app/api/build-info/route.ts) |
| `/api/v1/workspaces/[wsId]/mind/ai/patches/[patchId]/apply` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mind/src/app/api/v1/workspaces/%5BwsId%5D/mind/ai/patches/%5BpatchId%5D/apply/route.ts) |
| `/api/v1/workspaces/[wsId]/mind/boards/[boardId]/graph` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mind/src/app/api/v1/workspaces/%5BwsId%5D/mind/boards/%5BboardId%5D/graph/route.ts) |
| `/api/v1/workspaces/[wsId]/mind/boards/[boardId]/patches` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mind/src/app/api/v1/workspaces/%5BwsId%5D/mind/boards/%5BboardId%5D/patches/route.ts) |
| `/api/v1/workspaces/[wsId]/mind/boards/[boardId]` | DELETE, GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mind/src/app/api/v1/workspaces/%5BwsId%5D/mind/boards/%5BboardId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/mind/boards` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mind/src/app/api/v1/workspaces/%5BwsId%5D/mind/boards/route.ts) |
| `/api/v1/workspaces/[wsId]/mind/search` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/mind/src/app/api/v1/workspaces/%5BwsId%5D/mind/search/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# mobile: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/mobile

Source entry points and route ownership for the mobile workspace.

Runtime: **Flutter**. Source: [apps/mobile](https://github.com/tutur3u/platform/blob/main/apps/mobile). Package: `@tuturuuu/mobile`.

This workspace has no Next.js page/handler inventory. Read [the owning workspace](https://github.com/tutur3u/platform/blob/main/apps/mobile) for native, Worker, or infrastructure entry points and the [active runtime map](/build/devops/active-runtime) for operational ownership.

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# nova: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/nova

Source entry points and route ownership for the nova workspace.

Runtime: **Next.js App Router**. Source: [apps/nova](https://github.com/tutur3u/platform/blob/main/apps/nova). Package: `@tuturuuu/nova`.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/[locale]/not-whitelisted` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$auth$/not-whitelisted/page.tsx) |
| `/[locale]/verify-token` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$auth$/verify-token/page.tsx) |
| `/[locale]/problems/[problemId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$dashboard$/$admin$/$challenge-management$/problems/%5BproblemId%5D/page.tsx) |
| `/[locale]/problems` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$dashboard$/$admin$/$challenge-management$/problems/page.tsx) |
| `/[locale]/sessions/[sessionId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$dashboard$/$admin$/$challenge-management$/sessions/%5BsessionId%5D/page.tsx) |
| `/[locale]/sessions` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$dashboard$/$admin$/$challenge-management$/sessions/page.tsx) |
| `/[locale]/submissions/[submissionId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$dashboard$/$admin$/$challenge-management$/submissions/%5BsubmissionId%5D/page.tsx) |
| `/[locale]/submissions` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$dashboard$/$admin$/$challenge-management$/submissions/page.tsx) |
| `/[locale]/teams/[id]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$dashboard$/$admin$/$role-management$/teams/%5Bid%5D/page.tsx) |
| `/[locale]/teams` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$dashboard$/$admin$/$role-management$/teams/page.tsx) |
| `/[locale]/users` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$dashboard$/$admin$/$role-management$/users/page.tsx) |
| `/[locale]/users/whitelist` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$dashboard$/$admin$/$role-management$/users/whitelist/page.tsx) |
| `/[locale]/leaderboard` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$dashboard$/$leaderboard$/leaderboard/page.tsx) |
| `/[locale]/leaderboard/teams` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$dashboard$/$leaderboard$/leaderboard/teams/page.tsx) |
| `/[locale]/profile/[userId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$dashboard$/$leaderboard$/profile/%5BuserId%5D/page.tsx) |
| `/[locale]/profile/teams/[teamId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$dashboard$/$leaderboard$/profile/teams/%5BteamId%5D/page.tsx) |
| `/[locale]/challenges/[challengeId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$dashboard$/challenges/%5BchallengeId%5D/page.tsx) |
| `/[locale]/challenges/[challengeId]/problems/[problemId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$dashboard$/challenges/%5BchallengeId%5D/problems/%5BproblemId%5D/page.tsx) |
| `/[locale]/challenges/[challengeId]/results` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$dashboard$/challenges/%5BchallengeId%5D/results/page.tsx) |
| `/[locale]/challenges` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$dashboard$/challenges/page.tsx) |
| `/[locale]/home` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$dashboard$/home/page.tsx) |
| `/[locale]/judges` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$dashboard$/judges/page.tsx) |
| `/[locale]/score-calculator` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$dashboard$/score-calculator/page.tsx) |
| `/[locale]/competitions/neo-league/prompt-the-future/about` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$marketing$/competitions/neo-league/prompt-the-future/about/page.tsx) |
| `/[locale]/learn/advanced-strategies` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$marketing$/learn/advanced-strategies/page.tsx) |
| `/[locale]/learn/basic-techniques` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$marketing$/learn/basic-techniques/page.tsx) |
| `/[locale]/learn/best-practices` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$marketing$/learn/best-practices/page.tsx) |
| `/[locale]/learn/introduction` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$marketing$/learn/introduction/page.tsx) |
| `/[locale]/learn` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$marketing$/learn/page.tsx) |
| `/[locale]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/$marketing$/page.tsx) |
| `/[locale]/login` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/%5Blocale%5D/login/page.tsx) |
| `/api/auth/callback` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/auth/callback/route.ts) |
| `/api/auth/challenges/verify-password` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/auth/challenges/verify-password/route.ts) |
| `/api/auth/email` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/auth/email/route.ts) |
| `/api/auth/logout` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/auth/logout/route.ts) |
| `/api/auth/refresh-app-session` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/auth/refresh-app-session/route.ts) |
| `/api/auth/verify-app-token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/auth/verify-app-token/route.ts) |
| `/api/build-info` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/build-info/route.ts) |
| `/api/og/[userId]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/og/%5BuserId%5D/route.tsx) |
| `/api/og` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/og/route.tsx) |
| `/api/v1/challenges/[challengeId]/managers` | DELETE, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/v1/challenges/%5BchallengeId%5D/managers/route.ts) |
| `/api/v1/challenges/[challengeId]` | DELETE, GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/v1/challenges/%5BchallengeId%5D/route.ts) |
| `/api/v1/challenges/[challengeId]/whitelists` | DELETE, GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/v1/challenges/%5BchallengeId%5D/whitelists/route.ts) |
| `/api/v1/challenges` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/v1/challenges/route.ts) |
| `/api/v1/criteria/[criterionId]` | DELETE, GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/v1/criteria/%5BcriterionId%5D/route.ts) |
| `/api/v1/criteria` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/v1/criteria/route.ts) |
| `/api/v1/infrastructure/languages` | DELETE, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/v1/infrastructure/languages/route.ts) |
| `/api/v1/infrastructure/sidebar` | DELETE, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/v1/infrastructure/sidebar/route.ts) |
| `/api/v1/infrastructure/sidebar/sizes` | DELETE, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/v1/infrastructure/sidebar/sizes/route.ts) |
| `/api/v1/infrastructure/whitelist/[email]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/v1/infrastructure/whitelist/%5Bemail%5D/route.ts) |
| `/api/v1/nova/challenge-management/users/search` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/v1/nova/challenge-management/users/search/route.ts) |
| `/api/v1/nova/teams/[id]/invitations/[email]` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/v1/nova/teams/%5Bid%5D/invitations/%5Bemail%5D/route.ts) |
| `/api/v1/nova/teams/[id]/invitations` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/v1/nova/teams/%5Bid%5D/invitations/route.ts) |
| `/api/v1/nova/teams/[id]/members/[userId]` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/v1/nova/teams/%5Bid%5D/members/%5BuserId%5D/route.ts) |
| `/api/v1/nova/teams/[id]/members` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/v1/nova/teams/%5Bid%5D/members/route.ts) |
| `/api/v1/nova/teams/[id]` | DELETE, GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/v1/nova/teams/%5Bid%5D/route.ts) |
| `/api/v1/nova/teams` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/v1/nova/teams/route.ts) |
| `/api/v1/nova/users/[userId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/v1/nova/users/%5BuserId%5D/route.ts) |
| `/api/v1/problems/[problemId]` | DELETE, GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/v1/problems/%5BproblemId%5D/route.ts) |
| `/api/v1/problems` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/v1/problems/route.ts) |
| `/api/v1/sessions/[sessionId]` | DELETE, GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/v1/sessions/%5BsessionId%5D/route.ts) |
| `/api/v1/sessions/count` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/v1/sessions/count/route.ts) |
| `/api/v1/sessions` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/v1/sessions/route.ts) |
| `/api/v1/submissions/[submissionId]/criteria` | DELETE, GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/v1/submissions/%5BsubmissionId%5D/criteria/route.ts) |
| `/api/v1/submissions/[submissionId]` | DELETE, GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/v1/submissions/%5BsubmissionId%5D/route.ts) |
| `/api/v1/submissions/[submissionId]/test-cases` | DELETE, GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/v1/submissions/%5BsubmissionId%5D/test-cases/route.ts) |
| `/api/v1/submissions` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/v1/submissions/route.ts) |
| `/api/v1/test-cases/[testCaseId]` | DELETE, GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/v1/test-cases/%5BtestCaseId%5D/route.ts) |
| `/api/v1/test-cases` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/nova/src/app/api/v1/test-cases/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# parley: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/parley

Source entry points and route ownership for the parley workspace.

Runtime: **Next.js App Router**. Source: [apps/parley](https://github.com/tutur3u/platform/blob/main/apps/parley). Package: `@tuturuuu/parley`.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/[locale]/login` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/%5Blocale%5D/$auth$/login/page.tsx) |
| `/[locale]/manage/scenarios` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/%5Blocale%5D/$studio$/manage/scenarios/page.tsx) |
| `/[locale]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/%5Blocale%5D/$studio$/page.tsx) |
| `/[locale]/scenarios/[scenarioId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/%5Blocale%5D/$studio$/scenarios/%5BscenarioId%5D/page.tsx) |
| `/[locale]/sessions/[meetingId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/%5Blocale%5D/$studio$/sessions/%5BmeetingId%5D/page.tsx) |
| `/[locale]/sessions/new` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/%5Blocale%5D/$studio$/sessions/new/page.tsx) |
| `/[locale]/sessions` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/%5Blocale%5D/$studio$/sessions/page.tsx) |
| `/[locale]/access-denied` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/%5Blocale%5D/access-denied/page.tsx) |
| `/[locale]/r/[code]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/%5Blocale%5D/r/%5Bcode%5D/page.tsx) |
| `/[locale]/r/[code]/preview` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/%5Blocale%5D/r/%5Bcode%5D/preview/route.tsx) |
| `/[locale]/verify-token` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/%5Blocale%5D/verify-token/page.tsx) |
| `/api/auth/logout` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/api/auth/logout/route.ts) |
| `/api/auth/refresh-app-session` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/api/auth/refresh-app-session/route.ts) |
| `/api/auth/verify-app-token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/api/auth/verify-app-token/route.ts) |
| `/api/build-info` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/api/build-info/route.ts) |
| `/api/meet-ai/[wsId]/[meetingId]/chunks` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/api/meet-ai/%5BwsId%5D/%5BmeetingId%5D/chunks/route.ts) |
| `/api/meet-ai/[wsId]/[meetingId]/followups` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/api/meet-ai/%5BwsId%5D/%5BmeetingId%5D/followups/route.ts) |
| `/api/meet-ai/[wsId]/[meetingId]` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/api/meet-ai/%5BwsId%5D/%5BmeetingId%5D/route.ts) |
| `/api/meet-call/[meetingId]/assistant/personal` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/api/meet-call/%5BmeetingId%5D/assistant/personal/route.ts) |
| `/api/meet-call/[meetingId]/assistant/review` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/api/meet-call/%5BmeetingId%5D/assistant/review/route.ts) |
| `/api/meet-call/[meetingId]/assistant` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/api/meet-call/%5BmeetingId%5D/assistant/route.ts) |
| `/api/meet-call/[meetingId]/costs` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/api/meet-call/%5BmeetingId%5D/costs/route.ts) |
| `/api/meet-call/[meetingId]/files` | DELETE, GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/api/meet-call/%5BmeetingId%5D/files/route.ts) |
| `/api/meet-call/[meetingId]/public-info` | GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/api/meet-call/%5BmeetingId%5D/public-info/route.ts) |
| `/api/meet-call/[meetingId]/recording` | GET, POST, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/api/meet-call/%5BmeetingId%5D/recording/route.ts) |
| `/api/meet-call/[meetingId]/state` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/api/meet-call/%5BmeetingId%5D/state/route.ts) |
| `/api/meet-call/[meetingId]/title` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/api/meet-call/%5BmeetingId%5D/title/route.ts) |
| `/api/meet-call/[meetingId]/token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/api/meet-call/%5BmeetingId%5D/token/route.ts) |
| `/api/meet-live/[meetingId]/review` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/api/meet-live/%5BmeetingId%5D/review/route.ts) |
| `/api/meet-live/[meetingId]` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/api/meet-live/%5BmeetingId%5D/route.ts) |
| `/api/meet-live/memory` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/parley/src/app/api/meet-live/memory/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# pay: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/pay

Source entry points and route ownership for the pay workspace.

Runtime: **Next.js App Router**. Source: [apps/pay](https://github.com/tutur3u/platform/blob/main/apps/pay). Package: `@tuturuuu/pay`.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/[locale]/[wsId]/billing` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/%5Blocale%5D/%5BwsId%5D/billing/page.tsx) |
| `/[locale]/[wsId]/billing/success` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/%5Blocale%5D/%5BwsId%5D/billing/success/page.tsx) |
| `/[locale]/dashboard` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/%5Blocale%5D/dashboard/page.tsx) |
| `/[locale]/login` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/%5Blocale%5D/login/page.tsx) |
| `/[locale]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/%5Blocale%5D/page.tsx) |
| `/[locale]/verify-token` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/%5Blocale%5D/verify-token/page.tsx) |
| `/api/auth/logout` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/api/auth/logout/route.ts) |
| `/api/auth/refresh-app-session` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/api/auth/refresh-app-session/route.ts) |
| `/api/auth/verify-app-token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/api/auth/verify-app-token/route.ts) |
| `/api/billing/[wsId]/invoice` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/api/billing/%5BwsId%5D/invoice/route.ts) |
| `/api/build-info` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/api/build-info/route.ts) |
| `/api/cron/payment/orders` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/api/cron/payment/orders/route.ts) |
| `/api/cron/payment/products` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/api/cron/payment/products/route.ts) |
| `/api/cron/payment/subscriptions` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/api/cron/payment/subscriptions/route.ts) |
| `/api/payment/credit-packs/checkouts` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/api/payment/credit-packs/checkouts/route.ts) |
| `/api/payment/customer-portal/subscriptions/[subscriptionId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/api/payment/customer-portal/subscriptions/%5BsubscriptionId%5D/route.ts) |
| `/api/payment/migrations/subscriptions/cross-check/phase-1` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/api/payment/migrations/subscriptions/cross-check/phase-1/route.ts) |
| `/api/payment/migrations/subscriptions/cross-check/phase-2` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/api/payment/migrations/subscriptions/cross-check/phase-2/route.ts) |
| `/api/payment/migrations/subscriptions/cross-check/phase-3` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/api/payment/migrations/subscriptions/cross-check/phase-3/route.ts) |
| `/api/payment/migrations/subscriptions/cross-check` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/api/payment/migrations/subscriptions/cross-check/route.ts) |
| `/api/payment/migrations/subscriptions/duplicates` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/api/payment/migrations/subscriptions/duplicates/route.ts) |
| `/api/payment/migrations/subscriptions` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/api/payment/migrations/subscriptions/route.ts) |
| `/api/payment/migrations/subscriptions/unexisted-workspaces` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/api/payment/migrations/subscriptions/unexisted-workspaces/route.ts) |
| `/api/payment/orders/[orderId]/invoice` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/api/payment/orders/%5BorderId%5D/invoice/route.ts) |
| `/api/payment/seats` | GET, PATCH, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/api/payment/seats/route.ts) |
| `/api/payment/subscriptions/[subscriptionId]/change` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/api/payment/subscriptions/%5BsubscriptionId%5D/change/route.ts) |
| `/api/payment/subscriptions/[subscriptionId]/checkouts` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/api/payment/subscriptions/%5BsubscriptionId%5D/checkouts/route.ts) |
| `/api/payment/subscriptions/[subscriptionId]/preview` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/api/payment/subscriptions/%5BsubscriptionId%5D/preview/route.ts) |
| `/api/payment/webhooks` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/api/payment/webhooks/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/credits` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/api/v1/workspaces/%5BwsId%5D/ai/credits/route.ts) |
| `/api/v1/workspaces/[wsId]/billing` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/api/v1/workspaces/%5BwsId%5D/billing/route.ts) |
| `/api/v1/workspaces/[wsId]/billing/summary` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/pay/src/app/api/v1/workspaces/%5BwsId%5D/billing/summary/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# playground: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/playground

Source entry points and route ownership for the playground workspace.

Runtime: **Next.js App Router**. Source: [apps/playground](https://github.com/tutur3u/platform/blob/main/apps/playground). Package: `@tuturuuu/playground`.

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# redis: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/redis

Source entry points and route ownership for the redis workspace.

Runtime: **Service or supporting workspace**. Source: [apps/redis](https://github.com/tutur3u/platform/blob/main/apps/redis). Package: `@tuturuuu/redis`.

This workspace has no Next.js page/handler inventory. Read [the owning workspace](https://github.com/tutur3u/platform/blob/main/apps/redis) for native, Worker, or infrastructure entry points and the [active runtime map](/build/devops/active-runtime) for operational ownership.

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# rewise: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/rewise

Source entry points and route ownership for the rewise workspace.

Runtime: **Next.js App Router**. Source: [apps/rewise](https://github.com/tutur3u/platform/blob/main/apps/rewise). Package: `@tuturuuu/rewise`.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/[locale]/not-whitelisted` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/rewise/src/app/%5Blocale%5D/$auth$/not-whitelisted/page.tsx) |
| `/[locale]/verify-token` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/rewise/src/app/%5Blocale%5D/$auth$/verify-token/page.tsx) |
| `/[locale]/[wsId]/c/[chatId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/rewise/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/c/%5BchatId%5D/page.tsx) |
| `/[locale]/[wsId]/imagine` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/rewise/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/imagine/page.tsx) |
| `/[locale]/[wsId]/new` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/rewise/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/new/page.tsx) |
| `/[locale]/[wsId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/rewise/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/page.tsx) |
| `/[locale]/[wsId]/tools/[toolId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/rewise/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/tools/%5BtoolId%5D/page.tsx) |
| `/[locale]/[wsId]/tools` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/rewise/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/tools/page.tsx) |
| `/api/ai/chat/google/new` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/rewise/src/app/api/ai/chat/google/new/route.ts) |
| `/api/ai/chat/google` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/rewise/src/app/api/ai/chat/google/route.ts) |
| `/api/ai/chat/google/summary` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/rewise/src/app/api/ai/chat/google/summary/route.ts) |
| `/api/auth/callback` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/rewise/src/app/api/auth/callback/route.ts) |
| `/api/auth/email` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/rewise/src/app/api/auth/email/route.ts) |
| `/api/auth/logout` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/rewise/src/app/api/auth/logout/route.ts) |
| `/api/auth/refresh-app-session` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/rewise/src/app/api/auth/refresh-app-session/route.ts) |
| `/api/auth/verify-app-token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/rewise/src/app/api/auth/verify-app-token/route.ts) |
| `/api/build-info` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/rewise/src/app/api/build-info/route.ts) |
| `/api/v1/infrastructure/languages` | DELETE, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/rewise/src/app/api/v1/infrastructure/languages/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/credits` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/rewise/src/app/api/v1/workspaces/%5BwsId%5D/ai/credits/route.ts) |
| `/api/v1/workspaces/[wsId]/avatar` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/rewise/src/app/api/v1/workspaces/%5BwsId%5D/avatar/route.ts) |
| `/api/v1/workspaces/[wsId]/avatar/upload-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/rewise/src/app/api/v1/workspaces/%5BwsId%5D/avatar/upload-url/route.ts) |
| `/api/workspaces/[wsId]` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/rewise/src/app/api/workspaces/%5BwsId%5D/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# shortener: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/shortener

Source entry points and route ownership for the shortener workspace.

Runtime: **Next.js App Router**. Source: [apps/shortener](https://github.com/tutur3u/platform/blob/main/apps/shortener). Package: `@tuturuuu/shortener`.

This workspace has no Next.js page/handler inventory. Read [the owning workspace](https://github.com/tutur3u/platform/blob/main/apps/shortener) for native, Worker, or infrastructure entry points and the [active runtime map](/build/devops/active-runtime) for operational ownership.

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# storage-unzip-proxy: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/storage-unzip-proxy

Source entry points and route ownership for the storage-unzip-proxy workspace.

Runtime: **Service or supporting workspace**. Source: [apps/storage-unzip-proxy](https://github.com/tutur3u/platform/blob/main/apps/storage-unzip-proxy). Package: `@tuturuuu/storage-unzip-proxy`.

This workspace has no Next.js page/handler inventory. Read [the owning workspace](https://github.com/tutur3u/platform/blob/main/apps/storage-unzip-proxy) for native, Worker, or infrastructure entry points and the [active runtime map](/build/devops/active-runtime) for operational ownership.

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# storefront: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/storefront

Source entry points and route ownership for the storefront workspace.

Runtime: **Next.js App Router**. Source: [apps/storefront](https://github.com/tutur3u/platform/blob/main/apps/storefront). Package: `@tuturuuu/storefront`.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/[locale]/login` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/storefront/src/app/%5Blocale%5D/$auth$/login/page.tsx) |
| `/[locale]/verify-token` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/storefront/src/app/%5Blocale%5D/$auth$/verify-token/page.tsx) |
| `/[locale]/[storeSlug]/cart` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/storefront/src/app/%5Blocale%5D/%5BstoreSlug%5D/$shop$/cart/page.tsx) |
| `/[locale]/[storeSlug]/checkout/cancel` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/storefront/src/app/%5Blocale%5D/%5BstoreSlug%5D/$shop$/checkout/cancel/page.tsx) |
| `/[locale]/[storeSlug]/checkout` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/storefront/src/app/%5Blocale%5D/%5BstoreSlug%5D/$shop$/checkout/page.tsx) |
| `/[locale]/[storeSlug]/checkout/success` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/storefront/src/app/%5Blocale%5D/%5BstoreSlug%5D/$shop$/checkout/success/page.tsx) |
| `/[locale]/[storeSlug]/orders/[publicToken]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/storefront/src/app/%5Blocale%5D/%5BstoreSlug%5D/$shop$/orders/%5BpublicToken%5D/page.tsx) |
| `/[locale]/[storeSlug]/orders` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/storefront/src/app/%5Blocale%5D/%5BstoreSlug%5D/$shop$/orders/page.tsx) |
| `/[locale]/[storeSlug]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/storefront/src/app/%5Blocale%5D/%5BstoreSlug%5D/$shop$/page.tsx) |
| `/[locale]/[storeSlug]/products/[listingId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/storefront/src/app/%5Blocale%5D/%5BstoreSlug%5D/$shop$/products/%5BlistingId%5D/page.tsx) |
| `/[locale]/orders` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/storefront/src/app/%5Blocale%5D/orders/page.tsx) |
| `/[locale]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/storefront/src/app/%5Blocale%5D/page.tsx) |
| `/[locale]/store/[storeSlug]/cart` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/storefront/src/app/%5Blocale%5D/store/%5BstoreSlug%5D/cart/page.tsx) |
| `/[locale]/store/[storeSlug]/checkout/cancel` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/storefront/src/app/%5Blocale%5D/store/%5BstoreSlug%5D/checkout/cancel/page.tsx) |
| `/[locale]/store/[storeSlug]/checkout` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/storefront/src/app/%5Blocale%5D/store/%5BstoreSlug%5D/checkout/page.tsx) |
| `/[locale]/store/[storeSlug]/checkout/success` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/storefront/src/app/%5Blocale%5D/store/%5BstoreSlug%5D/checkout/success/page.tsx) |
| `/[locale]/store/[storeSlug]/orders/[publicToken]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/storefront/src/app/%5Blocale%5D/store/%5BstoreSlug%5D/orders/%5BpublicToken%5D/page.tsx) |
| `/[locale]/store/[storeSlug]/orders` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/storefront/src/app/%5Blocale%5D/store/%5BstoreSlug%5D/orders/page.tsx) |
| `/[locale]/store/[storeSlug]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/storefront/src/app/%5Blocale%5D/store/%5BstoreSlug%5D/page.tsx) |
| `/[locale]/store/[storeSlug]/products/[listingId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/storefront/src/app/%5Blocale%5D/store/%5BstoreSlug%5D/products/%5BlistingId%5D/page.tsx) |
| `/api/auth/logout` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/storefront/src/app/api/auth/logout/route.ts) |
| `/api/auth/refresh-app-session` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/storefront/src/app/api/auth/refresh-app-session/route.ts) |
| `/api/auth/verify-app-token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/storefront/src/app/api/auth/verify-app-token/route.ts) |
| `/api/build-info` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/storefront/src/app/api/build-info/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# supermemory: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/supermemory

Source entry points and route ownership for the supermemory workspace.

Runtime: **Service or supporting workspace**. Source: [apps/supermemory](https://github.com/tutur3u/platform/blob/main/apps/supermemory). Package: `@tuturuuu/supermemory`.

This workspace has no Next.js page/handler inventory. Read [the owning workspace](https://github.com/tutur3u/platform/blob/main/apps/supermemory) for native, Worker, or infrastructure entry points and the [active runtime map](/build/devops/active-runtime) for operational ownership.

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# tasks: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/tasks

Source entry points and route ownership for the tasks workspace.

Runtime: **Next.js App Router**. Source: [apps/tasks](https://github.com/tutur3u/platform/blob/main/apps/tasks). Package: `@tuturuuu/tasks`.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/[locale]/login` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/%5Blocale%5D/$auth$/login/page.tsx) |
| `/[locale]/verify-token` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/%5Blocale%5D/$auth$/verify-token/page.tsx) |
| `/[locale]/[wsId]/analytics` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/analytics/page.tsx) |
| `/[locale]/[wsId]/boards/[boardId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/boards/%5BboardId%5D/page.tsx) |
| `/[locale]/[wsId]/boards` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/boards/page.tsx) |
| `/[locale]/[wsId]/calendar` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/calendar/page.tsx) |
| `/[locale]/[wsId]/cycles` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/cycles/page.tsx) |
| `/[locale]/[wsId]/goals` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/goals/page.tsx) |
| `/[locale]/[wsId]/leaderboard` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/leaderboard/page.tsx) |
| `/[locale]/[wsId]/progress/[view]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/progress/%5Bview%5D/page.tsx) |
| `/[locale]/[wsId]/progress` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/progress/page.tsx) |
| `/[locale]/[wsId]/tasks/[taskId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/tasks/%5BtaskId%5D/page.tsx) |
| `/[locale]/[wsId]/tasks/boards/[boardId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/tasks/boards/%5BboardId%5D/page.tsx) |
| `/[locale]/[wsId]/tasks/new` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/tasks/new/page.tsx) |
| `/[locale]/[wsId]/tasks` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/tasks/page.tsx) |
| `/[locale]/shared/task/[shareCode]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/%5Blocale%5D/shared/task/%5BshareCode%5D/page.tsx) |
| `/[locale]/shared/task-boards/[code]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/%5Blocale%5D/shared/task-boards/%5Bcode%5D/page.tsx) |
| `/[locale]/task-link-preview` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/%5Blocale%5D/task-link-preview/page.tsx) |
| `/api/[...path]` | DELETE, GET, HEAD, PATCH, POST, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/%5B...path%5D/route.ts) |
| `/api/[wsId]/task/[taskId]/edit` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/%5BwsId%5D/task/%5BtaskId%5D/edit/route.ts) |
| `/api/[wsId]/task/create` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/%5BwsId%5D/task/create/route.ts) |
| `/api/admin/tasks/embeddings/generate` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/admin/tasks/embeddings/generate/route.ts) |
| `/api/admin/tasks/embeddings/stats` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/admin/tasks/embeddings/stats/route.ts) |
| `/api/auth/logout` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/auth/logout/route.ts) |
| `/api/auth/refresh-app-session` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/auth/refresh-app-session/route.ts) |
| `/api/auth/verify-app-token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/auth/verify-app-token/route.ts) |
| `/api/build-info` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/build-info/route.ts) |
| `/api/cron/tasks/cleanup-media` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/cron/tasks/cleanup-media/route.ts) |
| `/api/cron/tasks/generate-embeddings` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/cron/tasks/generate-embeddings/route.ts) |
| `/api/v1/mira/tasks/complete` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/mira/tasks/complete/route.ts) |
| `/api/v1/mira/tasks` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/mira/tasks/route.ts) |
| `/api/v1/shared/task-boards/[code]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/shared/task-boards/%5Bcode%5D/route.ts) |
| `/api/v1/shared/tasks/[shareCode]` | GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/shared/tasks/%5BshareCode%5D/route.ts) |
| `/api/v1/task-board-status-templates` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/task-board-status-templates/route.ts) |
| `/api/v1/task-projects/resolve-workspace` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/task-projects/resolve-workspace/route.ts) |
| `/api/v1/users/me/configs/[configId]` | DELETE, GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/users/me/configs/%5BconfigId%5D/route.ts) |
| `/api/v1/users/me/task-boards` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/users/me/task-boards/route.ts) |
| `/api/v1/users/me/tasks/[taskId]/overrides` | DELETE, GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/users/me/tasks/%5BtaskId%5D/overrides/route.ts) |
| `/api/v1/users/me/tasks/[taskId]/personal-placement` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/users/me/tasks/%5BtaskId%5D/personal-placement/route.ts) |
| `/api/v1/users/me/tasks/[taskId]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/users/me/tasks/%5BtaskId%5D/route.ts) |
| `/api/v1/users/me/tasks/[taskId]/schedule` | GET, PATCH, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/users/me/tasks/%5BtaskId%5D/schedule/route.ts) |
| `/api/v1/users/me/tasks` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/users/me/tasks/route.ts) |
| `/api/v1/users/me/workspaces/[wsId]/configs/[configId]` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/users/me/workspaces/%5BwsId%5D/configs/%5BconfigId%5D/route.ts) |
| `/api/v1/users/task-settings` | GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/users/task-settings/route.ts) |
| `/api/v1/webhooks/tasks/embedding` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/webhooks/tasks/embedding/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/credits` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/ai/credits/route.ts) |
| `/api/v1/workspaces/[wsId]/avatar` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/avatar/route.ts) |
| `/api/v1/workspaces/[wsId]/avatar/upload-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/avatar/upload-url/route.ts) |
| `/api/v1/workspaces/[wsId]/boards/[boardId]/archive` | DELETE, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/boards/%5BboardId%5D/archive/route.ts) |
| `/api/v1/workspaces/[wsId]/boards/[boardId]/estimation` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/boards/%5BboardId%5D/estimation/route.ts) |
| `/api/v1/workspaces/[wsId]/boards/[boardId]` | DELETE, PATCH, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/boards/%5BboardId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/boards/[boardId]/trash` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/boards/%5BboardId%5D/trash/route.ts) |
| `/api/v1/workspaces/[wsId]/boards/estimation` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/boards/estimation/route.ts) |
| `/api/v1/workspaces/[wsId]/boards` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/boards/route.ts) |
| `/api/v1/workspaces/[wsId]/boards-data` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/boards-data/route.ts) |
| `/api/v1/workspaces/[wsId]/boards-with-lists` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/boards-with-lists/route.ts) |
| `/api/v1/workspaces/[wsId]/habit-trackers/[trackerId]/entries/[entryId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/habit-trackers/%5BtrackerId%5D/entries/%5BentryId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/habit-trackers/[trackerId]/entries` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/habit-trackers/%5BtrackerId%5D/entries/route.ts) |
| `/api/v1/workspaces/[wsId]/habit-trackers/[trackerId]` | DELETE, GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/habit-trackers/%5BtrackerId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/habit-trackers/[trackerId]/streak-actions` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/habit-trackers/%5BtrackerId%5D/streak-actions/route.ts) |
| `/api/v1/workspaces/[wsId]/habit-trackers` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/habit-trackers/route.ts) |
| `/api/v1/workspaces/[wsId]/habits/[habitId]/complete` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/habits/%5BhabitId%5D/complete/route.ts) |
| `/api/v1/workspaces/[wsId]/habits/[habitId]` | DELETE, GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/habits/%5BhabitId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/habits/[habitId]/schedule/history` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/habits/%5BhabitId%5D/schedule/history/route.ts) |
| `/api/v1/workspaces/[wsId]/habits/[habitId]/schedule` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/habits/%5BhabitId%5D/schedule/route.ts) |
| `/api/v1/workspaces/[wsId]/habits/[habitId]/skips` | DELETE, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/habits/%5BhabitId%5D/skips/route.ts) |
| `/api/v1/workspaces/[wsId]/habits/[habitId]/stats` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/habits/%5BhabitId%5D/stats/route.ts) |
| `/api/v1/workspaces/[wsId]/habits/access` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/habits/access/route.ts) |
| `/api/v1/workspaces/[wsId]/habits` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/habits/route.ts) |
| `/api/v1/workspaces/[wsId]/labels/[labelId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/labels/%5BlabelId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/labels` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/labels/route.ts) |
| `/api/v1/workspaces/[wsId]/notes/[noteId]/convert-to-project` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/notes/%5BnoteId%5D/convert-to-project/route.ts) |
| `/api/v1/workspaces/[wsId]/notes/[noteId]/convert-to-task` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/notes/%5BnoteId%5D/convert-to-task/route.ts) |
| `/api/v1/workspaces/[wsId]/notes/[noteId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/notes/%5BnoteId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/notes` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/notes/route.ts) |
| `/api/v1/workspaces/[wsId]/task-boards/[boardId]/capacity-rules/[ruleId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-boards/%5BboardId%5D/capacity-rules/%5BruleId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/task-boards/[boardId]/capacity-rules` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-boards/%5BboardId%5D/capacity-rules/route.ts) |
| `/api/v1/workspaces/[wsId]/task-boards/[boardId]/copy` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-boards/%5BboardId%5D/copy/route.ts) |
| `/api/v1/workspaces/[wsId]/task-boards/[boardId]/lists/[listId]` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-boards/%5BboardId%5D/lists/%5BlistId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/task-boards/[boardId]/lists` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-boards/%5BboardId%5D/lists/route.ts) |
| `/api/v1/workspaces/[wsId]/task-boards/[boardId]/public-link` | DELETE, GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-boards/%5BboardId%5D/public-link/route.ts) |
| `/api/v1/workspaces/[wsId]/task-boards/[boardId]` | DELETE, GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-boards/%5BboardId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/task-boards/[boardId]/shares` | DELETE, GET, PATCH, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-boards/%5BboardId%5D/shares/route.ts) |
| `/api/v1/workspaces/[wsId]/task-boards/[boardId]/templates` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-boards/%5BboardId%5D/templates/route.ts) |
| `/api/v1/workspaces/[wsId]/task-boards/[boardId]/viewable-members` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-boards/%5BboardId%5D/viewable-members/route.ts) |
| `/api/v1/workspaces/[wsId]/task-boards` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-boards/route.ts) |
| `/api/v1/workspaces/[wsId]/task-cycles/[cycleId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-cycles/%5BcycleId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/task-cycles` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-cycles/route.ts) |
| `/api/v1/workspaces/[wsId]/task-drafts/[draftId]/convert` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-drafts/%5BdraftId%5D/convert/route.ts) |
| `/api/v1/workspaces/[wsId]/task-drafts/[draftId]` | DELETE, GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-drafts/%5BdraftId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/task-drafts` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-drafts/route.ts) |
| `/api/v1/workspaces/[wsId]/task-initiatives/[initiativeId]/projects/[projectId]` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-initiatives/%5BinitiativeId%5D/projects/%5BprojectId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/task-initiatives/[initiativeId]/projects` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-initiatives/%5BinitiativeId%5D/projects/route.ts) |
| `/api/v1/workspaces/[wsId]/task-initiatives/[initiativeId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-initiatives/%5BinitiativeId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/task-initiatives` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-initiatives/route.ts) |
| `/api/v1/workspaces/[wsId]/task-plans/[planId]/digest` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-plans/%5BplanId%5D/digest/route.ts) |
| `/api/v1/workspaces/[wsId]/task-plans/[planId]/items` | DELETE, GET, PATCH, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-plans/%5BplanId%5D/items/route.ts) |
| `/api/v1/workspaces/[wsId]/task-plans/[planId]` | DELETE, GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-plans/%5BplanId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/task-plans/[planId]/shares` | DELETE, GET, PATCH, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-plans/%5BplanId%5D/shares/route.ts) |
| `/api/v1/workspaces/[wsId]/task-plans/[planId]/workspaces` | DELETE, GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-plans/%5BplanId%5D/workspaces/route.ts) |
| `/api/v1/workspaces/[wsId]/task-plans` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-plans/route.ts) |
| `/api/v1/workspaces/[wsId]/task-progress/achievements` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-progress/achievements/route.ts) |
| `/api/v1/workspaces/[wsId]/task-progress/catchup` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-progress/catchup/route.ts) |
| `/api/v1/workspaces/[wsId]/task-progress/entries/[entryId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-progress/entries/%5BentryId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/task-progress/entries` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-progress/entries/route.ts) |
| `/api/v1/workspaces/[wsId]/task-progress/goals/[goalId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-progress/goals/%5BgoalId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/task-progress/goals` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-progress/goals/route.ts) |
| `/api/v1/workspaces/[wsId]/task-progress/import` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-progress/import/route.ts) |
| `/api/v1/workspaces/[wsId]/task-progress/leaderboards/[leaderboardId]/members` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-progress/leaderboards/%5BleaderboardId%5D/members/route.ts) |
| `/api/v1/workspaces/[wsId]/task-progress/leaderboards/[leaderboardId]` | DELETE, GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-progress/leaderboards/%5BleaderboardId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/task-progress/leaderboards/[leaderboardId]/teams` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-progress/leaderboards/%5BleaderboardId%5D/teams/route.ts) |
| `/api/v1/workspaces/[wsId]/task-progress/leaderboards/join` | DELETE, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-progress/leaderboards/join/route.ts) |
| `/api/v1/workspaces/[wsId]/task-progress/leaderboards` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-progress/leaderboards/route.ts) |
| `/api/v1/workspaces/[wsId]/task-progress/metrics/[metricId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-progress/metrics/%5BmetricId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/task-progress/metrics/pack` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-progress/metrics/pack/route.ts) |
| `/api/v1/workspaces/[wsId]/task-progress/metrics` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-progress/metrics/route.ts) |
| `/api/v1/workspaces/[wsId]/task-progress/recommendations` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-progress/recommendations/route.ts) |
| `/api/v1/workspaces/[wsId]/task-progress/stats` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-progress/stats/route.ts) |
| `/api/v1/workspaces/[wsId]/task-projects/[projectId]` | DELETE, GET, PATCH, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-projects/%5BprojectId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/task-projects/[projectId]/tasks/[taskId]` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-projects/%5BprojectId%5D/tasks/%5BtaskId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/task-projects/[projectId]/tasks` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-projects/%5BprojectId%5D/tasks/route.ts) |
| `/api/v1/workspaces/[wsId]/task-projects/[projectId]/updates/[updateId]/attachments` | DELETE, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-projects/%5BprojectId%5D/updates/%5BupdateId%5D/attachments/route.ts) |
| `/api/v1/workspaces/[wsId]/task-projects/[projectId]/updates/[updateId]/comments/[commentId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-projects/%5BprojectId%5D/updates/%5BupdateId%5D/comments/%5BcommentId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/task-projects/[projectId]/updates/[updateId]/comments` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-projects/%5BprojectId%5D/updates/%5BupdateId%5D/comments/route.ts) |
| `/api/v1/workspaces/[wsId]/task-projects/[projectId]/updates/[updateId]/reactions` | DELETE, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-projects/%5BprojectId%5D/updates/%5BupdateId%5D/reactions/route.ts) |
| `/api/v1/workspaces/[wsId]/task-projects/[projectId]/updates/[updateId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-projects/%5BprojectId%5D/updates/%5BupdateId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/task-projects/[projectId]/updates` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-projects/%5BprojectId%5D/updates/route.ts) |
| `/api/v1/workspaces/[wsId]/task-projects` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-projects/route.ts) |
| `/api/v1/workspaces/[wsId]/task-templates/[templateKey]/instantiate` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-templates/%5BtemplateKey%5D/instantiate/route.ts) |
| `/api/v1/workspaces/[wsId]/task-templates/[templateKey]` | DELETE, GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-templates/%5BtemplateKey%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/task-templates/from-task` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-templates/from-task/route.ts) |
| `/api/v1/workspaces/[wsId]/task-templates` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/task-templates/route.ts) |
| `/api/v1/workspaces/[wsId]/tasks/[taskId]/description` | GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/tasks/%5BtaskId%5D/description/route.ts) |
| `/api/v1/workspaces/[wsId]/tasks/[taskId]/embedding` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/tasks/%5BtaskId%5D/embedding/route.ts) |
| `/api/v1/workspaces/[wsId]/tasks/[taskId]/estimation` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/tasks/%5BtaskId%5D/estimation/route.ts) |
| `/api/v1/workspaces/[wsId]/tasks/[taskId]/history` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/tasks/%5BtaskId%5D/history/route.ts) |
| `/api/v1/workspaces/[wsId]/tasks/[taskId]/labels` | DELETE, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/tasks/%5BtaskId%5D/labels/route.ts) |
| `/api/v1/workspaces/[wsId]/tasks/[taskId]/mentions/cleanup` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/tasks/%5BtaskId%5D/mentions/cleanup/route.ts) |
| `/api/v1/workspaces/[wsId]/tasks/[taskId]/move` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/tasks/%5BtaskId%5D/move/route.ts) |
| `/api/v1/workspaces/[wsId]/tasks/[taskId]/relationships` | DELETE, GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/tasks/%5BtaskId%5D/relationships/route.ts) |
| `/api/v1/workspaces/[wsId]/tasks/[taskId]/revert` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/tasks/%5BtaskId%5D/revert/route.ts) |
| `/api/v1/workspaces/[wsId]/tasks/[taskId]` | DELETE, GET, PATCH, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/tasks/%5BtaskId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/tasks/[taskId]/schedule/history` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/tasks/%5BtaskId%5D/schedule/history/route.ts) |
| `/api/v1/workspaces/[wsId]/tasks/[taskId]/schedule` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/tasks/%5BtaskId%5D/schedule/route.ts) |
| `/api/v1/workspaces/[wsId]/tasks/[taskId]/share-links` | DELETE, GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/tasks/%5BtaskId%5D/share-links/route.ts) |
| `/api/v1/workspaces/[wsId]/tasks/[taskId]/shares` | DELETE, GET, PATCH, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/tasks/%5BtaskId%5D/shares/route.ts) |
| `/api/v1/workspaces/[wsId]/tasks/[taskId]/snapshot/[historyId]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/tasks/%5BtaskId%5D/snapshot/%5BhistoryId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/tasks/bulk` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/tasks/bulk/route.ts) |
| `/api/v1/workspaces/[wsId]/tasks/embeddings/generate` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/tasks/embeddings/generate/route.ts) |
| `/api/v1/workspaces/[wsId]/tasks/history` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/tasks/history/route.ts) |
| `/api/v1/workspaces/[wsId]/tasks/journal` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/tasks/journal/route.ts) |
| `/api/v1/workspaces/[wsId]/tasks/media` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/tasks/media/route.ts) |
| `/api/v1/workspaces/[wsId]/tasks` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/tasks/route.ts) |
| `/api/v1/workspaces/[wsId]/tasks/schedule-batch` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/tasks/schedule-batch/route.ts) |
| `/api/v1/workspaces/[wsId]/tasks/search` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/tasks/search/route.ts) |
| `/api/v1/workspaces/[wsId]/tasks/suggestions` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/tasks/suggestions/route.ts) |
| `/api/v1/workspaces/[wsId]/tasks/upload-url` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/tasks/upload-url/route.ts) |
| `/api/v1/workspaces/[wsId]/tasks/with-relationship` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/tasks/with-relationship/route.ts) |
| `/api/v1/workspaces/[wsId]/templates/[templateId]/background-url` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/templates/%5BtemplateId%5D/background-url/route.ts) |
| `/api/v1/workspaces/[wsId]/templates/[templateId]` | DELETE, GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/templates/%5BtemplateId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/templates/[templateId]/shares` | DELETE, GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/templates/%5BtemplateId%5D/shares/route.ts) |
| `/api/v1/workspaces/[wsId]/templates/[templateId]/use` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/templates/%5BtemplateId%5D/use/route.ts) |
| `/api/v1/workspaces/[wsId]/templates/background` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/templates/background/route.ts) |
| `/api/v1/workspaces/[wsId]/templates` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/templates/route.ts) |
| `/api/v1/workspaces/[wsId]/templates/upload-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/templates/upload-url/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/sessions/[sessionId]` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/sessions/%5BsessionId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/sessions` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/sessions/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/tasks` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/tasks/route.ts) |
| `/api/workspaces/[wsId]/members` | DELETE, GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/workspaces/%5BwsId%5D/members/route.ts) |
| `/api/workspaces/[wsId]` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/api/workspaces/%5BwsId%5D/route.ts) |
| `/serwist/[path]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/tasks/src/app/serwist/%5Bpath%5D/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# teach: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/teach

Source entry points and route ownership for the teach workspace.

Runtime: **Next.js App Router**. Source: [apps/teach](https://github.com/tutur3u/platform/blob/main/apps/teach). Package: `@tuturuuu/teach`.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/[locale]/[wsId]/assignments` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/assignments/page.tsx) |
| `/[locale]/[wsId]/attendance` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/attendance/page.tsx) |
| `/[locale]/[wsId]/courses/[courseId]/[lessonId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/courses/%5BcourseId%5D/%5BlessonId%5D/page.tsx) |
| `/[locale]/[wsId]/courses/[courseId]/[lessonId]/vocabulary` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/courses/%5BcourseId%5D/%5BlessonId%5D/vocabulary/page.tsx) |
| `/[locale]/[wsId]/courses/[courseId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/courses/%5BcourseId%5D/page.tsx) |
| `/[locale]/[wsId]/courses` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/courses/page.tsx) |
| `/[locale]/[wsId]/education` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/education/$dashboard$/page.tsx) |
| `/[locale]/[wsId]/education/attempts/[attemptId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/education/attempts/%5BattemptId%5D/page.tsx) |
| `/[locale]/[wsId]/education/attempts` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/education/attempts/page.tsx) |
| `/[locale]/[wsId]/education/courses/[courseId]/builder` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/education/courses/%5BcourseId%5D/builder/page.tsx) |
| `/[locale]/[wsId]/education/courses/[courseId]/modules/[moduleId]/content` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/education/courses/%5BcourseId%5D/modules/%5BmoduleId%5D/content/page.tsx) |
| `/[locale]/[wsId]/education/courses/[courseId]/modules/[moduleId]/extra-content` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/education/courses/%5BcourseId%5D/modules/%5BmoduleId%5D/extra-content/page.tsx) |
| `/[locale]/[wsId]/education/courses/[courseId]/modules/[moduleId]/flashcards` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/education/courses/%5BcourseId%5D/modules/%5BmoduleId%5D/flashcards/page.tsx) |
| `/[locale]/[wsId]/education/courses/[courseId]/modules/[moduleId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/education/courses/%5BcourseId%5D/modules/%5BmoduleId%5D/page.tsx) |
| `/[locale]/[wsId]/education/courses/[courseId]/modules/[moduleId]/quiz-sets` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/education/courses/%5BcourseId%5D/modules/%5BmoduleId%5D/quiz-sets/page.tsx) |
| `/[locale]/[wsId]/education/courses/[courseId]/modules/[moduleId]/quizzes/new` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/education/courses/%5BcourseId%5D/modules/%5BmoduleId%5D/quizzes/new/page.tsx) |
| `/[locale]/[wsId]/education/courses/[courseId]/modules/[moduleId]/quizzes` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/education/courses/%5BcourseId%5D/modules/%5BmoduleId%5D/quizzes/page.tsx) |
| `/[locale]/[wsId]/education/courses/[courseId]/modules/[moduleId]/resources` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/education/courses/%5BcourseId%5D/modules/%5BmoduleId%5D/resources/page.tsx) |
| `/[locale]/[wsId]/education/courses/[courseId]/modules/[moduleId]/youtube-links` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/education/courses/%5BcourseId%5D/modules/%5BmoduleId%5D/youtube-links/page.tsx) |
| `/[locale]/[wsId]/education/courses/[courseId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/education/courses/%5BcourseId%5D/page.tsx) |
| `/[locale]/[wsId]/education/courses` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/education/courses/page.tsx) |
| `/[locale]/[wsId]/education/flashcards` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/education/flashcards/page.tsx) |
| `/[locale]/[wsId]/education/library/flashcards` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/education/library/flashcards/page.tsx) |
| `/[locale]/[wsId]/education/library` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/education/library/page.tsx) |
| `/[locale]/[wsId]/education/library/quiz-sets` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/education/library/quiz-sets/page.tsx) |
| `/[locale]/[wsId]/education/library/quizzes` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/education/library/quizzes/page.tsx) |
| `/[locale]/[wsId]/education/quiz-sets/[setId]/linked-modules` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/education/quiz-sets/%5BsetId%5D/linked-modules/page.tsx) |
| `/[locale]/[wsId]/education/quiz-sets/[setId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/education/quiz-sets/%5BsetId%5D/page.tsx) |
| `/[locale]/[wsId]/education/quiz-sets` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/education/quiz-sets/page.tsx) |
| `/[locale]/[wsId]/education/quizzes` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/education/quizzes/page.tsx) |
| `/[locale]/[wsId]/metrics` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/metrics/page.tsx) |
| `/[locale]/[wsId]/modules/[moduleId]/[lessonId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/modules/%5BmoduleId%5D/%5BlessonId%5D/page.tsx) |
| `/[locale]/[wsId]/modules/[moduleId]/[lessonId]/vocabulary` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/modules/%5BmoduleId%5D/%5BlessonId%5D/vocabulary/page.tsx) |
| `/[locale]/[wsId]/modules/[moduleId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/modules/%5BmoduleId%5D/page.tsx) |
| `/[locale]/[wsId]/modules/[moduleId]/tests/[testId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/modules/%5BmoduleId%5D/tests/%5BtestId%5D/page.tsx) |
| `/[locale]/[wsId]/modules` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/modules/page.tsx) |
| `/[locale]/[wsId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/page.tsx) |
| `/[locale]/[wsId]/reports` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/reports/page.tsx) |
| `/[locale]/[wsId]/settings` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/settings/page.tsx) |
| `/[locale]/[wsId]/todo` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/todo/page.tsx) |
| `/[locale]/dashboard` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/dashboard/page.tsx) |
| `/[locale]/login` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/login/page.tsx) |
| `/[locale]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/page.tsx) |
| `/[locale]/verify-token` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/%5Blocale%5D/verify-token/page.tsx) |
| `/api/ai/course` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/ai/course/route.ts) |
| `/api/ai/objects/flashcards` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/ai/objects/flashcards/route.ts) |
| `/api/ai/objects/quizzes/explanation` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/ai/objects/quizzes/explanation/route.ts) |
| `/api/ai/objects/quizzes` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/ai/objects/quizzes/route.ts) |
| `/api/ai/quiz` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/ai/quiz/route.ts) |
| `/api/auth/logout` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/auth/logout/route.ts) |
| `/api/auth/refresh-app-session` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/auth/refresh-app-session/route.ts) |
| `/api/auth/verify-app-token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/auth/verify-app-token/route.ts) |
| `/api/build-info` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/build-info/route.ts) |
| `/api/v1/tulearn/bootstrap` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/tulearn/bootstrap/route.ts) |
| `/api/v1/vocabulary/details` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/vocabulary/details/route.ts) |
| `/api/v1/vocabulary/images` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/vocabulary/images/route.ts) |
| `/api/v1/vocabulary/suggestions` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/vocabulary/suggestions/route.ts) |
| `/api/v1/workspaces/[wsId]/course-modules/[moduleId]/quiz-sets` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/course-modules/%5BmoduleId%5D/quiz-sets/route.ts) |
| `/api/v1/workspaces/[wsId]/course-modules/[moduleId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/course-modules/%5BmoduleId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/course-modules/[moduleId]/vocabulary` | GET, PATCH, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/course-modules/%5BmoduleId%5D/vocabulary/route.ts) |
| `/api/v1/workspaces/[wsId]/course-modules` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/course-modules/route.ts) |
| `/api/v1/workspaces/[wsId]/courses/[courseId]/module-order` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/courses/%5BcourseId%5D/module-order/route.ts) |
| `/api/v1/workspaces/[wsId]/courses/[courseId]/modules` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/courses/%5BcourseId%5D/modules/route.ts) |
| `/api/v1/workspaces/[wsId]/courses/[courseId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/courses/%5BcourseId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/courses` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/courses/route.ts) |
| `/api/v1/workspaces/[wsId]/education/access` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/education/access/route.ts) |
| `/api/v1/workspaces/[wsId]/education/attempts/[attemptId]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/education/attempts/%5BattemptId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/education/attempts` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/education/attempts/route.ts) |
| `/api/v1/workspaces/[wsId]/flashcards/[flashcardId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/flashcards/%5BflashcardId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/flashcards` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/flashcards/route.ts) |
| `/api/v1/workspaces/[wsId]/quiz-sets/[setId]/linked-modules` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/quiz-sets/%5BsetId%5D/linked-modules/route.ts) |
| `/api/v1/workspaces/[wsId]/quiz-sets/[setId]/modules/[moduleId]` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/quiz-sets/%5BsetId%5D/modules/%5BmoduleId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/quiz-sets/[setId]/modules` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/quiz-sets/%5BsetId%5D/modules/route.ts) |
| `/api/v1/workspaces/[wsId]/quiz-sets/[setId]/quizzes` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/quiz-sets/%5BsetId%5D/quizzes/route.ts) |
| `/api/v1/workspaces/[wsId]/quiz-sets/[setId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/quiz-sets/%5BsetId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/quiz-sets` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/quiz-sets/route.ts) |
| `/api/v1/workspaces/[wsId]/quizzes/[quizId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/quizzes/%5BquizId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/quizzes` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/quizzes/route.ts) |
| `/api/v1/workspaces/[wsId]/teach/courses/[courseId]/attendance` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/teach/courses/%5BcourseId%5D/attendance/route.ts) |
| `/api/v1/workspaces/[wsId]/teach/courses/[courseId]/indicators` | GET, PATCH, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/teach/courses/%5BcourseId%5D/indicators/route.ts) |
| `/api/v1/workspaces/[wsId]/teach/courses/[courseId]/members/[userId]` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/teach/courses/%5BcourseId%5D/members/%5BuserId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/teach/courses/[courseId]/members` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/teach/courses/%5BcourseId%5D/members/route.ts) |
| `/api/v1/workspaces/[wsId]/teach/courses/[courseId]/modules/[moduleId]/quizzes/submissions/[userId]/ai-review` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/teach/courses/%5BcourseId%5D/modules/%5BmoduleId%5D/quizzes/submissions/%5BuserId%5D/ai-review/route.ts) |
| `/api/v1/workspaces/[wsId]/teach/courses/[courseId]/modules/[moduleId]/quizzes/submissions/[userId]` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/teach/courses/%5BcourseId%5D/modules/%5BmoduleId%5D/quizzes/submissions/%5BuserId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/teach/courses/[courseId]/modules/[moduleId]/quizzes/submissions` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/teach/courses/%5BcourseId%5D/modules/%5BmoduleId%5D/quizzes/submissions/route.ts) |
| `/api/v1/workspaces/[wsId]/teach/courses/[courseId]/posts` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/teach/courses/%5BcourseId%5D/posts/route.ts) |
| `/api/v1/workspaces/[wsId]/teach/courses/[courseId]/reports` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/teach/courses/%5BcourseId%5D/reports/route.ts) |
| `/api/v1/workspaces/[wsId]/teach/courses/[courseId]/student-performance/[userId]/send-report` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/teach/courses/%5BcourseId%5D/student-performance/%5BuserId%5D/send-report/route.ts) |
| `/api/v1/workspaces/[wsId]/teach/courses/[courseId]/student-performance` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/teach/courses/%5BcourseId%5D/student-performance/route.ts) |
| `/api/v1/workspaces/[wsId]/teach/courses/[courseId]/student-performance/send-bulk-report` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/teach/courses/%5BcourseId%5D/student-performance/send-bulk-report/route.ts) |
| `/api/v1/workspaces/[wsId]/teach/courses/[courseId]/tests/[testId]/questions` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/teach/courses/%5BcourseId%5D/tests/%5BtestId%5D/questions/route.ts) |
| `/api/v1/workspaces/[wsId]/teach/courses/[courseId]/tests/[testId]/submissions/[attemptId]/ai-feedback` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/teach/courses/%5BcourseId%5D/tests/%5BtestId%5D/submissions/%5BattemptId%5D/ai-feedback/route.ts) |
| `/api/v1/workspaces/[wsId]/teach/courses/[courseId]/tests/[testId]/submissions/[attemptId]` | GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/teach/courses/%5BcourseId%5D/tests/%5BtestId%5D/submissions/%5BattemptId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/teach/courses/[courseId]/tests/[testId]/submissions` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/teach/courses/%5BcourseId%5D/tests/%5BtestId%5D/submissions/route.ts) |
| `/api/v1/workspaces/[wsId]/teach/courses/[courseId]/tests` | GET, PATCH, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/teach/courses/%5BcourseId%5D/tests/route.ts) |
| `/api/v1/workspaces/[wsId]/teach/dashboard-stats` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/teach/dashboard-stats/route.ts) |
| `/api/v1/workspaces/[wsId]/teach/todo` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/teach/todo/route.ts) |
| `/api/v1/workspaces/[wsId]/teach/users` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/teach/users/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/module-groups/[moduleGroupId]/module-order` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/module-groups/%5BmoduleGroupId%5D/module-order/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/module-groups/[moduleGroupId]/modules` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/module-groups/%5BmoduleGroupId%5D/modules/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/module-groups/[moduleGroupId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/module-groups/%5BmoduleGroupId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/module-groups/order` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/module-groups/order/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/module-groups` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/module-groups/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/module-order` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/module-order/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/modules` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/teach/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/modules/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# tools: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/tools

Source entry points and route ownership for the tools workspace.

Runtime: **Next.js App Router**. Source: [apps/tools](https://github.com/tutur3u/platform/blob/main/apps/tools). Package: `@tuturuuu/tools`.

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# track: routes
Source: https://docs.tuturuuu.com/reference/repository/routes/track

Source entry points and route ownership for the track workspace.

Runtime: **Next.js App Router**. Source: [apps/track](https://github.com/tutur3u/platform/blob/main/apps/track). Package: `@tuturuuu/track`.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/[locale]/verify-token` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/%5Blocale%5D/$auth$/verify-token/page.tsx) |
| `/[locale]/[wsId]/history` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/history/page.tsx) |
| `/[locale]/[wsId]/management` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/management/page.tsx) |
| `/[locale]/[wsId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/page.tsx) |
| `/[locale]/[wsId]/requests` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/requests/page.tsx) |
| `/[locale]/[wsId]/timer` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/timer/page.tsx) |
| `/api/auth/logout` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/auth/logout/route.ts) |
| `/api/auth/refresh-app-session` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/auth/refresh-app-session/route.ts) |
| `/api/auth/verify-app-token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/auth/verify-app-token/route.ts) |
| `/api/build-info` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/build-info/route.ts) |
| `/api/time-tracking/export` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/time-tracking/export/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/credits` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/ai/credits/route.ts) |
| `/api/v1/workspaces/[wsId]/avatar` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/avatar/route.ts) |
| `/api/v1/workspaces/[wsId]/avatar/upload-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/avatar/upload-url/route.ts) |
| `/api/v1/workspaces/[wsId]/settings/[configId]` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/settings/%5BconfigId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/settings` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/settings/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/analytics` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/analytics/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/break-types/[breakTypeId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/break-types/%5BbreakTypeId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/break-types` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/break-types/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/breaks` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/breaks/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/categories/[categoryId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/categories/%5BcategoryId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/categories/copy` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/categories/copy/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/categories` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/categories/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/goals/[goalId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/goals/%5BgoalId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/goals` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/goals/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/quick-start` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/quick-start/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/requests/[id]/activity` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/requests/%5Bid%5D/activity/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/requests/[id]/comments/[commentId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/requests/%5Bid%5D/comments/%5BcommentId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/requests/[id]/comments` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/requests/%5Bid%5D/comments/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/requests/[id]/image-urls` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/requests/%5Bid%5D/image-urls/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/requests/[id]` | PATCH, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/requests/%5Bid%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/requests` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/requests/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/requests/upload-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/requests/upload-url/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/requests/users` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/requests/users/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/sessions/[sessionId]/breaks/active` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/sessions/%5BsessionId%5D/breaks/active/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/sessions/[sessionId]/move` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/sessions/%5BsessionId%5D/move/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/sessions/[sessionId]` | DELETE, GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/sessions/%5BsessionId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/sessions` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/sessions/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/stats/period` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/stats/period/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/stats/summary` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/stats/summary/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/templates` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/templates/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/threshold` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/threshold/route.ts) |
| `/api/workspaces/[wsId]` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/track/src/app/api/workspaces/%5BwsId%5D/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# web: routes (1/5)
Source: https://docs.tuturuuu.com/reference/repository/routes/web-1

Source entry points and route ownership for the web workspace.

Runtime: **Next.js App Router**. Source: [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web). Package: `@tuturuuu/web`.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/.well-known/[...slug]` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/.well-known/%5B...slug%5D/route.ts) |
| `/[locale]/add-account` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$auth$/add-account/page.tsx) |
| `/[locale]/auth/recovery/confirm` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$auth$/auth/recovery/confirm/route.ts) |
| `/[locale]/auth/recovery` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$auth$/auth/recovery/page.tsx) |
| `/[locale]/login` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$auth$/login/page.tsx) |
| `/[locale]/signup` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$auth$/signup/page.tsx) |
| `/[locale]/sso/consent` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$auth$/sso/consent/page.tsx) |
| `/[locale]/verify-token` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$auth$/verify-token/page.tsx) |
| `/[locale]/[wsId]/datasets` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/$ai$/datasets/$default$/page.tsx) |
| `/[locale]/[wsId]/datasets/[datasetId]/api-references` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/$ai$/datasets/%5BdatasetId%5D/api-references/page.tsx) |
| `/[locale]/[wsId]/datasets/[datasetId]/explore` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/$ai$/datasets/%5BdatasetId%5D/explore/page.tsx) |
| `/[locale]/[wsId]/datasets/[datasetId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/$ai$/datasets/%5BdatasetId%5D/page.tsx) |
| `/[locale]/[wsId]/datasets/[datasetId]/settings` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/$ai$/datasets/%5BdatasetId%5D/settings/page.tsx) |
| `/[locale]/[wsId]/models` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/$ai$/models/page.tsx) |
| `/[locale]/[wsId]/pipelines` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/$ai$/pipelines/$default$/page.tsx) |
| `/[locale]/[wsId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/$dashboard$/page.tsx) |
| `/[locale]/[wsId]/personal-journal` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/$dashboard$/personal-journal/page.tsx) |
| `/[locale]/[wsId]/api-keys/[keyId]/usage-logs` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/$workspace-settings$/api-keys/%5BkeyId%5D/usage-logs/page.tsx) |
| `/[locale]/[wsId]/api-keys` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/$workspace-settings$/api-keys/page.tsx) |
| `/[locale]/[wsId]/billing` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/$workspace-settings$/billing/page.tsx) |
| `/[locale]/[wsId]/billing/success` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/$workspace-settings$/billing/success/page.tsx) |
| `/[locale]/[wsId]/inquiries` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/$workspace-settings$/inquiries/page.tsx) |
| `/[locale]/[wsId]/members` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/$workspace-settings$/members/page.tsx) |
| `/[locale]/[wsId]/roles` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/$workspace-settings$/roles/page.tsx) |
| `/[locale]/[wsId]/secrets` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/$workspace-settings$/secrets/page.tsx) |
| `/[locale]/[wsId]/settings/notifications` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/$workspace-settings$/settings/notifications/page.tsx) |
| `/[locale]/[wsId]/settings` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/$workspace-settings$/settings/page.tsx) |
| `/[locale]/[wsId]/settings/reports` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/$workspace-settings$/settings/reports/page.tsx) |
| `/[locale]/[wsId]/sso` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/$workspace-settings$/sso/page.tsx) |
| `/[locale]/[wsId]/usage` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/$workspace-settings$/usage/page.tsx) |
| `/[locale]/[wsId]/ai/executions` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/ai/executions/page.tsx) |
| `/[locale]/[wsId]/ai/spark` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/ai/spark/page.tsx) |
| `/[locale]/[wsId]/ai-chat/[chatId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/ai-chat/%5BchatId%5D/page.tsx) |
| `/[locale]/[wsId]/ai-chat/chatbots` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/ai-chat/chatbots/page.tsx) |
| `/[locale]/[wsId]/ai-chat/my-chatbots/new` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/ai-chat/my-chatbots/new/page.tsx) |
| `/[locale]/[wsId]/ai-chat/my-chatbots` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/ai-chat/my-chatbots/page.tsx) |
| `/[locale]/[wsId]/ai-chat/new` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/ai-chat/new/page.tsx) |
| `/[locale]/[wsId]/ai-chat` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/ai-chat/page.tsx) |
| `/[locale]/[wsId]/calendar` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/calendar/page.tsx) |
| `/[locale]/[wsId]/changelog` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/changelog/page.tsx) |
| `/[locale]/[wsId]/crawlers` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/crawlers/$default$/page.tsx) |
| `/[locale]/[wsId]/crawlers/uncrawled` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/crawlers/$default$/uncrawled/page.tsx) |
| `/[locale]/[wsId]/crawlers/[crawlerId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/crawlers/%5BcrawlerId%5D/page.tsx) |
| `/[locale]/[wsId]/cron/executions` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/cron/executions/page.tsx) |
| `/[locale]/[wsId]/cron/jobs/[jobId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/cron/jobs/%5BjobId%5D/page.tsx) |
| `/[locale]/[wsId]/cron/jobs` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/cron/jobs/page.tsx) |
| `/[locale]/[wsId]/cron` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/cron/page.tsx) |
| `/[locale]/[wsId]/diet` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/diet/page.tsx) |
| `/[locale]/[wsId]/documents/[documentId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/documents/%5BdocumentId%5D/page.tsx) |
| `/[locale]/[wsId]/documents` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/documents/page.tsx) |
| `/[locale]/[wsId]/epm/collections/[collectionId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/epm/collections/%5BcollectionId%5D/page.tsx) |
| `/[locale]/[wsId]/epm/entries/[entryId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/epm/entries/%5BentryId%5D/page.tsx) |
| `/[locale]/[wsId]/epm` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/epm/page.tsx) |
| `/[locale]/[wsId]/external-projects` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/external-projects/page.tsx) |
| `/[locale]/[wsId]/feedback` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/feedback/page.tsx) |
| `/[locale]/[wsId]/habits/[[...slug]]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/habits/%5B%5B...slug%5D%5D/page.tsx) |
| `/[locale]/[wsId]/hive` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/hive/page.tsx) |
| `/[locale]/[wsId]/integrations/discord` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/integrations/discord/page.tsx) |
| `/[locale]/[wsId]/integrations` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/integrations/page.tsx) |
| `/[locale]/[wsId]/inventory/[[...slug]]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/inventory/%5B%5B...slug%5D%5D/page.tsx) |
| `/[locale]/[wsId]/link-shortener/[linkId]/analytics` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/link-shortener/%5BlinkId%5D/analytics/page.tsx) |
| `/[locale]/[wsId]/link-shortener` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/link-shortener/page.tsx) |
| `/[locale]/[wsId]/memories` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/memories/page.tsx) |
| `/[locale]/[wsId]/metrics` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/metrics/page.tsx) |
| `/[locale]/[wsId]/mind/boards/[boardId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/mind/boards/%5BboardId%5D/page.tsx) |
| `/[locale]/[wsId]/mind` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/mind/page.tsx) |
| `/[locale]/[wsId]/mira` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/mira/page.tsx) |
| `/[locale]/[wsId]/notes` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/notes/page.tsx) |
| `/[locale]/[wsId]/notifications` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/notifications/page.tsx) |
| `/[locale]/[wsId]/polls` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/polls/page.tsx) |
| `/[locale]/[wsId]/progress` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/progress/page.tsx) |
| `/[locale]/[wsId]/qr-generator` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/qr-generator/page.tsx) |
| `/[locale]/[wsId]/queues` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/queues/$default$/page.tsx) |
| `/[locale]/[wsId]/readings` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/readings/page.tsx) |
| `/[locale]/[wsId]/tasks/[[...slug]]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/tasks/%5B%5B...slug%5D%5D/page.tsx) |
| `/[locale]/[wsId]/whiteboards/[boardId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/whiteboards/%5BboardId%5D/page.tsx) |
| `/[locale]/[wsId]/whiteboards` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/whiteboards/page.tsx) |
| `/[locale]/[wsId]/workforce` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/workforce/page.tsx) |
| `/[locale]/[wsId]/workouts` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/workouts/page.tsx) |
| `/[locale]/[wsId]/workspace-setup` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$dashboard$/%5BwsId%5D/workspace-setup/page.tsx) |
| `/[locale]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/$landing$/page.tsx) |
| `/[locale]/about` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/about/page.tsx) |
| `/[locale]/acceptable-use` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/acceptable-use/page.tsx) |
| `/[locale]/account/delete` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/account/delete/page.tsx) |
| `/[locale]/ai/chats/[chatId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/ai/chats/%5BchatId%5D/page.tsx) |
| `/[locale]/blog` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/blog/page.tsx) |
| `/[locale]/branding` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/branding/page.tsx) |
| `/[locale]/calendar/meet-together/[[...slug]]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/calendar/meet-together/%5B%5B...slug%5D%5D/page.tsx) |
| `/[locale]/careers` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/careers/page.tsx) |
| `/[locale]/changelog/[slug]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/changelog/%5Bslug%5D/page.tsx) |
| `/[locale]/changelog` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/changelog/page.tsx) |
| `/[locale]/community-guidelines` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/community-guidelines/page.tsx) |
| `/[locale]/contact` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/contact/page.tsx) |
| `/[locale]/contributors` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/contributors/page.tsx) |
| `/[locale]/docs` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/docs/page.tsx) |
| `/[locale]/documents/[documentId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/documents/%5BdocumentId%5D/page.tsx) |
| `/[locale]/download` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/download/page.tsx) |
| `/[locale]/facebook-mockup` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/facebook-mockup/page.tsx) |
| `/[locale]/invite/[code]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/invite/%5Bcode%5D/page.tsx) |
| `/[locale]/legal/dpa` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/legal/dpa/page.tsx) |
| `/[locale]/legal/sla` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/legal/sla/page.tsx) |
| `/[locale]/legal/subprocessors` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/legal/subprocessors/page.tsx) |
| `/[locale]/logout` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/logout/page.tsx) |
| `/[locale]/meet` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/meet/page.tsx) |
| `/[locale]/meet/plans/[planId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/meet/plans/%5BplanId%5D/page.tsx) |
| `/[locale]/meet-together` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/meet-together/page.tsx) |
| `/[locale]/meet-together/plans/[planId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/meet-together/plans/%5BplanId%5D/page.tsx) |
| `/[locale]/models` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/models/page.tsx) |
| `/[locale]/onboarding` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/onboarding/page.tsx) |
| `/[locale]/partners` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/partners/page.tsx) |
| `/[locale]/pricing` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/pricing/page.tsx) |
| `/[locale]/privacy` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/privacy/page.tsx) |
| `/[locale]/products/ai` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/products/ai/page.tsx) |
| `/[locale]/products/calendar` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/products/calendar/page.tsx) |
| `/[locale]/products/chat` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/products/chat/page.tsx) |
| `/[locale]/products/crm` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/products/crm/page.tsx) |
| `/[locale]/products/documents` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/products/documents/page.tsx) |
| `/[locale]/products/drive` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/products/drive/page.tsx) |
| `/[locale]/products/finance` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/products/finance/page.tsx) |
| `/[locale]/products/forms` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/products/forms/page.tsx) |
| `/[locale]/products/hive` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/products/hive/page.tsx) |
| `/[locale]/products/inventory` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/products/inventory/page.tsx) |
| `/[locale]/products/lms` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/products/lms/page.tsx) |
| `/[locale]/products/mail` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/products/mail/page.tsx) |
| `/[locale]/products/meet-together` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/products/meet-together/page.tsx) |
| `/[locale]/products` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/products/page.tsx) |
| `/[locale]/products/qr` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/products/qr/page.tsx) |
| `/[locale]/products/storefront` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/products/storefront/page.tsx) |
| `/[locale]/products/tasks` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/products/tasks/page.tsx) |
| `/[locale]/products/track` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/products/track/page.tsx) |
| `/[locale]/products/workflows` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/products/workflows/page.tsx) |
| `/[locale]/qr-generator` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/qr-generator/page.tsx) |
| `/[locale]/security/bug-bounty` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/security/bug-bounty/page.tsx) |
| `/[locale]/security` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/security/page.tsx) |
| `/[locale]/security/policy` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/security/policy/page.tsx) |
| `/[locale]/share/[type]/[resourceId]/modules/[moduleId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/share/%5Btype%5D/%5BresourceId%5D/modules/%5BmoduleId%5D/page.tsx) |
| `/[locale]/share/[type]/[resourceId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/share/%5Btype%5D/%5BresourceId%5D/page.tsx) |
| `/[locale]/solutions/construction` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/solutions/construction/page.tsx) |
| `/[locale]/solutions/education` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/solutions/education/page.tsx) |
| `/[locale]/solutions/healthcare` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/solutions/healthcare/page.tsx) |
| `/[locale]/solutions/hospitality` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/solutions/hospitality/page.tsx) |
| `/[locale]/solutions/manufacturing` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/solutions/manufacturing/page.tsx) |
| `/[locale]/solutions/pharmacies` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/solutions/pharmacies/page.tsx) |
| `/[locale]/solutions/realestate` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/solutions/realestate/page.tsx) |
| `/[locale]/solutions/restaurants` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/solutions/restaurants/page.tsx) |
| `/[locale]/solutions/retail` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/solutions/retail/page.tsx) |
| `/[locale]/terms` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/terms/page.tsx) |
| `/[locale]/u/[username]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/u/%5Busername%5D/page.tsx) |
| `/[locale]/users/[handle]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/users/%5Bhandle%5D/page.tsx) |
| `/[locale]/visualizations/horse-racing` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/visualizations/horse-racing/page.tsx) |
| `/[locale]/women-in-tech` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/$marketing$/women-in-tech/page.tsx) |
| `/[locale]/games/farm` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/games/farm/page.tsx) |
| `/[locale]/pitch` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/pitch/page.tsx) |
| `/[locale]/portfolio` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/portfolio/page.tsx) |
| `/[locale]/shared/task/[shareCode]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/shared/task/%5BshareCode%5D/page.tsx) |
| `/[locale]/shared/task-boards/[code]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/shared/task-boards/%5Bcode%5D/page.tsx) |
| `/[locale]/shared/user-profile/[code]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/shared/user-profile/%5Bcode%5D/page.tsx) |
| `/[locale]/ui/components/[componentId]` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/ui/components/%5BcomponentId%5D/page.tsx) |
| `/[locale]/ui/components` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/ui/components/page.tsx) |
| `/[locale]/ui/contributing` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/ui/contributing/page.tsx) |
| `/[locale]/ui` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/ui/page.tsx) |
| `/[locale]/ui/setup` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/%5Blocale%5D/ui/setup/page.tsx) |
| `/~offline` | Page | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/~offline/page.tsx) |
| `/~recover-browser-state` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/~recover-browser-state/route.ts) |
| `/api/[wsId]/crawlers/domains` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/%5BwsId%5D/crawlers/domains/route.ts) |
| `/api/[wsId]/crawlers/list` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/%5BwsId%5D/crawlers/list/route.ts) |
| `/api/[wsId]/crawlers/uncrawled` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/%5BwsId%5D/crawlers/uncrawled/route.ts) |
| `/api/ai/chat/delete-file` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/ai/chat/delete-file/route.ts) |
| `/api/ai/chat/file-urls` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/ai/chat/file-urls/route.ts) |
| `/api/ai/chat/google/new` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/ai/chat/google/new/route.ts) |
| `/api/ai/chat/google` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/ai/chat/google/route.ts) |
| `/api/ai/chat/google/summary` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/ai/chat/google/summary/route.ts) |
| `/api/ai/chat/live-messages` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/ai/chat/live-messages/route.ts) |
| `/api/ai/chat/new` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/ai/chat/new/route.ts) |
| `/api/ai/chat/restore` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/ai/chat/restore/route.ts) |
| `/api/ai/chat` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/ai/chat/route.ts) |
| `/api/ai/chat/signed-read-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/ai/chat/signed-read-url/route.ts) |
| `/api/ai/chat/summary` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/ai/chat/summary/route.ts) |
| `/api/ai/chat/upload-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/ai/chat/upload-url/route.ts) |
| `/api/ai/chatgpt/new` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/ai/chatgpt/new/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# web: routes (2/5)
Source: https://docs.tuturuuu.com/reference/repository/routes/web-2

Source entry points and route ownership for the web workspace.

Runtime: **Next.js App Router**. Source: [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web). Package: `@tuturuuu/web`.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/api/ai/chatgpt` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/ai/chatgpt/route.ts) |
| `/api/ai/executions` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/ai/executions/route.ts) |
| `/api/ai/generate` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/ai/generate/route.ts) |
| `/api/ai/meetings/summary` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/ai/meetings/summary/route.ts) |
| `/api/ai/meetings/transcription` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/ai/meetings/transcription/route.ts) |
| `/api/ai/objects/year-plan` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/ai/objects/year-plan/route.ts) |
| `/api/ai/temp-auth/revoke` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/ai/temp-auth/revoke/route.ts) |
| `/api/ai/temp-auth/token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/ai/temp-auth/token/route.ts) |
| `/api/auth/callback` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/auth/callback/route.ts) |
| `/api/auth/dev-login` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/auth/dev-login/route.ts) |
| `/api/auth/dev-session` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/auth/dev-session/route.ts) |
| `/api/auth/generate-app-tokens` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/auth/generate-app-tokens/route.ts) |
| `/api/auth/logout` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/auth/logout/route.ts) |
| `/api/auth/me` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/auth/me/route.ts) |
| `/api/auth/me/session` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/auth/me/session/route.ts) |
| `/api/auth/mfa/totp/assurance-level` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/auth/mfa/totp/assurance-level/route.ts) |
| `/api/auth/mfa/totp/challenge` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/auth/mfa/totp/challenge/route.ts) |
| `/api/auth/mfa/totp/challenge/verify` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/auth/mfa/totp/challenge/verify/route.ts) |
| `/api/auth/mfa/totp/factors/[factorId]` | DELETE, GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/auth/mfa/totp/factors/%5BfactorId%5D/route.ts) |
| `/api/auth/mfa/totp/factors/[factorId]/verify` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/auth/mfa/totp/factors/%5BfactorId%5D/verify/route.ts) |
| `/api/auth/mfa/totp/factors` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/auth/mfa/totp/factors/route.ts) |
| `/api/auth/verify-app-token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/auth/verify-app-token/route.ts) |
| `/api/build-info` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/build-info/route.ts) |
| `/api/cli/auth/refresh` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/cli/auth/refresh/route.ts) |
| `/api/cli/auth/start` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/cli/auth/start/route.ts) |
| `/api/cli/auth/verify` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/cli/auth/verify/route.ts) |
| `/api/cron/ai/sync-models` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/cron/ai/sync-models/route.ts) |
| `/api/cron/discord/daily-report` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/cron/discord/daily-report/route.ts) |
| `/api/cron/discord/wol/daily/remind` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/cron/discord/wol/daily/remind/route.ts) |
| `/api/cron/finance/exchange-rates` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/cron/finance/exchange-rates/route.ts) |
| `/api/cron/process-immediate-notifications` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/cron/process-immediate-notifications/route.ts) |
| `/api/cron/process-notification-batches` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/cron/process-notification-batches/route.ts) |
| `/api/cron/process-post-email-queue` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/cron/process-post-email-queue/route.ts) |
| `/api/cron/process-report-automation` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/cron/process-report-automation/route.ts) |
| `/api/cron/process-topic-announcement-queue` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/cron/process-topic-announcement-queue/route.ts) |
| `/api/cron/tasks/deadline-reminders` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/cron/tasks/deadline-reminders/route.ts) |
| `/api/email/unsubscribe` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/email/unsubscribe/route.ts) |
| `/api/health` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/health/route.ts) |
| `/api/invite/[code]` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/invite/%5Bcode%5D/route.ts) |
| `/api/notifications/send-immediate` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/notifications/send-immediate/route.ts) |
| `/api/reports` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/reports/route.ts) |
| `/api/reports/upload-url` | DELETE, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/reports/upload-url/route.ts) |
| `/api/share/course/[courseId]` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/share/course/%5BcourseId%5D/route.ts) |
| `/api/sync-logs` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/sync-logs/route.ts) |
| `/api/time-tracking/export` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/time-tracking/export/route.ts) |
| `/api/trpc/[trpc]` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/trpc/%5Btrpc%5D/route.ts) |
| `/api/users/search` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/users/search/route.ts) |
| `/api/v1/admin/ai/memory/backfill-mira` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/admin/ai/memory/backfill-mira/route.ts) |
| `/api/v1/admin/external-apps` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/admin/external-apps/route.ts) |
| `/api/v1/admin/external-project-audits` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/admin/external-project-audits/route.ts) |
| `/api/v1/admin/external-project-bindings/[workspaceId]` | GET, HEAD, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/admin/external-project-bindings/%5BworkspaceId%5D/route.ts) |
| `/api/v1/admin/external-project-bindings` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/admin/external-project-bindings/route.ts) |
| `/api/v1/admin/external-projects/[canonicalId]` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/admin/external-projects/%5BcanonicalId%5D/route.ts) |
| `/api/v1/admin/external-projects` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/admin/external-projects/route.ts) |
| `/api/v1/ai/chats/[chatId]` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/ai/chats/%5BchatId%5D/route.ts) |
| `/api/v1/ai/chats` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/ai/chats/route.ts) |
| `/api/v1/ai/whitelist/me` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/ai/whitelist/me/route.ts) |
| `/api/v1/assistant/live/token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/assistant/live/token/route.ts) |
| `/api/v1/assistant/live/tools/execute` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/assistant/live/tools/execute/route.ts) |
| `/api/v1/assistant/live/turns` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/assistant/live/turns/route.ts) |
| `/api/v1/aurora/forecast` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/aurora/forecast/route.ts) |
| `/api/v1/aurora/health` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/aurora/health/route.ts) |
| `/api/v1/aurora/ml-metrics` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/aurora/ml-metrics/route.ts) |
| `/api/v1/aurora/statistical-metrics` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/aurora/statistical-metrics/route.ts) |
| `/api/v1/auth/accounts/[accountId]` | DELETE, OPTIONS | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/auth/accounts/%5BaccountId%5D/route.ts) |
| `/api/v1/auth/accounts/current` | OPTIONS, PATCH, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/auth/accounts/current/route.ts) |
| `/api/v1/auth/accounts/logout` | OPTIONS, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/auth/accounts/logout/route.ts) |
| `/api/v1/auth/accounts/logout-all` | OPTIONS, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/auth/accounts/logout-all/route.ts) |
| `/api/v1/auth/accounts` | GET, HEAD, OPTIONS | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/auth/accounts/route.ts) |
| `/api/v1/auth/accounts/switch` | OPTIONS, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/auth/accounts/switch/route.ts) |
| `/api/v1/auth/app-token/exchange` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/auth/app-token/exchange/route.ts) |
| `/api/v1/auth/app-token/invitation-decision` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/auth/app-token/invitation-decision/route.ts) |
| `/api/v1/auth/colab/verify` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/auth/colab/verify/route.ts) |
| `/api/v1/auth/cross-app-return` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/auth/cross-app-return/route.ts) |
| `/api/v1/auth/cross-app-session/refresh` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/auth/cross-app-session/refresh/route.ts) |
| `/api/v1/auth/cross-app-token/verify` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/auth/cross-app-token/verify/route.ts) |
| `/api/v1/auth/mfa/devices` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/auth/mfa/devices/route.ts) |
| `/api/v1/auth/mfa/mobile/approvals` | GET, OPTIONS | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/auth/mfa/mobile/approvals/route.ts) |
| `/api/v1/auth/mfa/mobile/challenges/[challengeId]/approve` | OPTIONS, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/auth/mfa/mobile/challenges/%5BchallengeId%5D/approve/route.ts) |
| `/api/v1/auth/mfa/mobile/challenges/[challengeId]` | GET, OPTIONS | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/auth/mfa/mobile/challenges/%5BchallengeId%5D/route.ts) |
| `/api/v1/auth/mfa/mobile/challenges` | OPTIONS, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/auth/mfa/mobile/challenges/route.ts) |
| `/api/v1/auth/mobile/password-login` | OPTIONS, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/auth/mobile/password-login/route.ts) |
| `/api/v1/auth/mobile/send-otp` | OPTIONS, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/auth/mobile/send-otp/route.ts) |
| `/api/v1/auth/mobile/verify-otp` | OPTIONS, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/auth/mobile/verify-otp/route.ts) |
| `/api/v1/auth/otp/send` | OPTIONS, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/auth/otp/send/route.ts) |
| `/api/v1/auth/otp/settings` | GET, HEAD, OPTIONS | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/auth/otp/settings/route.ts) |
| `/api/v1/auth/otp/verify` | OPTIONS, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/auth/otp/verify/route.ts) |
| `/api/v1/auth/password-login` | OPTIONS, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/auth/password-login/route.ts) |
| `/api/v1/auth/qr-login/challenges/[challengeId]/approve` | OPTIONS, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/auth/qr-login/challenges/%5BchallengeId%5D/approve/route.ts) |
| `/api/v1/auth/qr-login/challenges/[challengeId]` | GET, OPTIONS | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/auth/qr-login/challenges/%5BchallengeId%5D/route.ts) |
| `/api/v1/auth/qr-login/challenges` | OPTIONS, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/auth/qr-login/challenges/route.ts) |
| `/api/v1/auth/recovery/consume` | OPTIONS, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/auth/recovery/consume/route.ts) |
| `/api/v1/calendar/auth/accounts` | DELETE, GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/calendar/auth/accounts/route.ts) |
| `/api/v1/cms/workspaces` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/cms/workspaces/route.ts) |
| `/api/v1/devboxes/agents/events` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/devboxes/agents/events/route.ts) |
| `/api/v1/devboxes/agents/heartbeat` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/devboxes/agents/heartbeat/route.ts) |
| `/api/v1/devboxes/agents/playground-files` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/devboxes/agents/playground-files/route.ts) |
| `/api/v1/devboxes/agents/poll` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/devboxes/agents/poll/route.ts) |
| `/api/v1/devboxes/agents/register` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/devboxes/agents/register/route.ts) |
| `/api/v1/devboxes/agents/shutdown` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/devboxes/agents/shutdown/route.ts) |
| `/api/v1/devboxes/cache/prune` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/devboxes/cache/prune/route.ts) |
| `/api/v1/devboxes/cache` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/devboxes/cache/route.ts) |
| `/api/v1/devboxes/env` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/devboxes/env/route.ts) |
| `/api/v1/devboxes/leases/[leaseId]/release` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/devboxes/leases/%5BleaseId%5D/release/route.ts) |
| `/api/v1/devboxes/leases` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/devboxes/leases/route.ts) |
| `/api/v1/devboxes/previews` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/devboxes/previews/route.ts) |
| `/api/v1/devboxes/runs/[runId]/logs` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/devboxes/runs/%5BrunId%5D/logs/route.ts) |
| `/api/v1/devboxes/runs/[runId]` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/devboxes/runs/%5BrunId%5D/route.ts) |
| `/api/v1/devboxes/runs/[runId]/stop` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/devboxes/runs/%5BrunId%5D/stop/route.ts) |
| `/api/v1/devboxes/runs` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/devboxes/runs/route.ts) |
| `/api/v1/devboxes/runs/stop-by-key` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/devboxes/runs/stop-by-key/route.ts) |
| `/api/v1/documents/[documentId]` | DELETE, GET, HEAD, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/documents/%5BdocumentId%5D/route.ts) |
| `/api/v1/documents` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/documents/route.ts) |
| `/api/v1/exchange-rates` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/exchange-rates/route.ts) |
| `/api/v1/external-ai/audio/speech` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/external-ai/audio/speech/route.ts) |
| `/api/v1/external-ai/chat/completions` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/external-ai/chat/completions/route.ts) |
| `/api/v1/infrastructure/internal-accounts/address-migrations/adopt-retained` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/infrastructure/internal-accounts/address-migrations/adopt-retained/route.ts) |
| `/api/v1/infrastructure/internal-accounts/address-migrations/inspect` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/infrastructure/internal-accounts/address-migrations/inspect/route.ts) |
| `/api/v1/infrastructure/internal-accounts/address-migrations/migrate` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/infrastructure/internal-accounts/address-migrations/migrate/route.ts) |
| `/api/v1/infrastructure/internal-accounts/address-migrations/prepare` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/infrastructure/internal-accounts/address-migrations/prepare/route.ts) |
| `/api/v1/infrastructure/internal-accounts/address-migrations/retained-inspect` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/infrastructure/internal-accounts/address-migrations/retained-inspect/route.ts) |
| `/api/v1/infrastructure/internal-accounts/employees/[userId]/reconcile` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/infrastructure/internal-accounts/employees/%5BuserId%5D/reconcile/route.ts) |
| `/api/v1/infrastructure/internal-accounts/employees/[userId]/restore` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/infrastructure/internal-accounts/employees/%5BuserId%5D/restore/route.ts) |
| `/api/v1/infrastructure/internal-accounts/employees/[userId]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/infrastructure/internal-accounts/employees/%5BuserId%5D/route.ts) |
| `/api/v1/infrastructure/internal-accounts/employees/operations/[operationId]/cli-recovery` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/infrastructure/internal-accounts/employees/operations/%5BoperationId%5D/cli-recovery/route.ts) |
| `/api/v1/infrastructure/internal-accounts/employees/operations/[operationId]/rejection` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/infrastructure/internal-accounts/employees/operations/%5BoperationId%5D/rejection/route.ts) |
| `/api/v1/infrastructure/internal-accounts/employees/operations/[operationId]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/infrastructure/internal-accounts/employees/operations/%5BoperationId%5D/route.ts) |
| `/api/v1/infrastructure/internal-accounts/employees` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/infrastructure/internal-accounts/employees/route.ts) |
| `/api/v1/inquiries/[id]/media-urls` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/inquiries/%5Bid%5D/media-urls/route.ts) |
| `/api/v1/inquiries/[id]` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/inquiries/%5Bid%5D/route.ts) |
| `/api/v1/inquiries` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/inquiries/route.ts) |
| `/api/v1/integrations/discord/available-members` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/integrations/discord/available-members/route.ts) |
| `/api/v1/integrations/discord/members` | DELETE, GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/integrations/discord/members/route.ts) |
| `/api/v1/integrations/discord` | DELETE, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/integrations/discord/route.ts) |
| `/api/v1/integrations/external-chat/events/batch` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/integrations/external-chat/events/batch/route.ts) |
| `/api/v1/integrations/external-chat/events` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/integrations/external-chat/events/route.ts) |
| `/api/v1/integrations/external-chat/pairing/verify` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/integrations/external-chat/pairing/verify/route.ts) |
| `/api/v1/integrations/external-chat/widget.js` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/integrations/external-chat/widget.js/route.ts) |
| `/api/v1/link-shortener/[linkId]/analytics` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/link-shortener/%5BlinkId%5D/analytics/route.ts) |
| `/api/v1/link-shortener/[linkId]/password` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/link-shortener/%5BlinkId%5D/password/route.ts) |
| `/api/v1/link-shortener/shorten` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/link-shortener/shorten/route.ts) |
| `/api/v1/live/session` | DELETE, GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/live/session/route.ts) |
| `/api/v1/live/token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/live/token/route.ts) |
| `/api/v1/live/tools/execute` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/live/tools/execute/route.ts) |
| `/api/v1/live/usage` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/live/usage/route.ts) |
| `/api/v1/meet/plans/[planId]/availability` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/meet/plans/%5BplanId%5D/availability/route.ts) |
| `/api/v1/meet/plans/[planId]/finalization` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/meet/plans/%5BplanId%5D/finalization/route.ts) |
| `/api/v1/meet/plans/[planId]` | DELETE, GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/meet/plans/%5BplanId%5D/route.ts) |
| `/api/v1/meet/plans` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/meet/plans/route.ts) |
| `/api/v1/meetings/[meetingId]/collaboration/preview/[port]/[[...path]]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/meetings/%5BmeetingId%5D/collaboration/preview/%5Bport%5D/%5B%5B...path%5D%5D/route.ts) |
| `/api/v1/meetings/[meetingId]/collaboration` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/meetings/%5BmeetingId%5D/collaboration/route.ts) |
| `/api/v1/mira/achievements` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/mira/achievements/route.ts) |
| `/api/v1/mira/achievements/unlock` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/mira/achievements/unlock/route.ts) |
| `/api/v1/mira/focus/[id]` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/mira/focus/%5Bid%5D/route.ts) |
| `/api/v1/mira/focus/complete` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/mira/focus/complete/route.ts) |
| `/api/v1/mira/focus/history` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/mira/focus/history/route.ts) |
| `/api/v1/mira/focus` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/mira/focus/route.ts) |
| `/api/v1/mira/focus/start` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/mira/focus/start/route.ts) |
| `/api/v1/mira/memories` | DELETE, GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/mira/memories/route.ts) |
| `/api/v1/mira/pet/feed` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/mira/pet/feed/route.ts) |
| `/api/v1/mira/pet` | GET, HEAD, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/mira/pet/route.ts) |
| `/api/v1/mira/soul` | GET, HEAD, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/mira/soul/route.ts) |
| `/api/v1/mira/token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/mira/token/route.ts) |
| `/api/v1/mira/xp` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/mira/xp/route.ts) |
| `/api/v1/mobile/version-check` | GET, HEAD, OPTIONS | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/mobile/version-check/route.ts) |
| `/api/v1/native-integrity/challenge` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/native-integrity/challenge/route.ts) |
| `/api/v1/native-integrity/enroll` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/native-integrity/enroll/route.ts) |
| `/api/v1/notifications/[id]/metadata` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/notifications/%5Bid%5D/metadata/route.ts) |
| `/api/v1/notifications/[id]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/notifications/%5Bid%5D/route.ts) |
| `/api/v1/notifications/account-preferences` | GET, HEAD, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/notifications/account-preferences/route.ts) |
| `/api/v1/notifications/mail-thread` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/notifications/mail-thread/route.ts) |
| `/api/v1/notifications/preferences` | GET, HEAD, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/notifications/preferences/route.ts) |
| `/api/v1/notifications/push-devices` | DELETE, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/notifications/push-devices/route.ts) |
| `/api/v1/notifications` | GET, HEAD, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/notifications/route.ts) |
| `/api/v1/notifications/unread-count` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/notifications/unread-count/route.ts) |
| `/api/v1/nova/me/team` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/nova/me/team/route.ts) |
| `/api/v1/platform/users/[userId]/roles` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/platform/users/%5BuserId%5D/roles/route.ts) |
| `/api/v1/product-feedback/[id]/media` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/product-feedback/%5Bid%5D/media/route.ts) |
| `/api/v1/product-feedback/[id]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/product-feedback/%5Bid%5D/route.ts) |
| `/api/v1/product-feedback/eligibility` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/product-feedback/eligibility/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# web: routes (3/5)
Source: https://docs.tuturuuu.com/reference/repository/routes/web-3

Source entry points and route ownership for the web workspace.

Runtime: **Next.js App Router**. Source: [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web). Package: `@tuturuuu/web`.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/api/v1/product-feedback/receipts/[key]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/product-feedback/receipts/%5Bkey%5D/route.ts) |
| `/api/v1/product-feedback` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/product-feedback/route.ts) |
| `/api/v1/proxy/tuturuuu` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/proxy/tuturuuu/route.ts) |
| `/api/v1/public/pricing` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/public/pricing/route.ts) |
| `/api/v1/public/user-profile-links/[code]/avatar` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/public/user-profile-links/%5Bcode%5D/avatar/route.ts) |
| `/api/v1/public/user-profile-links/[code]/submit` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/public/user-profile-links/%5Bcode%5D/submit/route.ts) |
| `/api/v1/rate-limit-appeals` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/rate-limit-appeals/route.ts) |
| `/api/v1/realtime/channels` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/realtime/channels/route.ts) |
| `/api/v1/realtime/documents/checkpoint` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/realtime/documents/checkpoint/route.ts) |
| `/api/v1/realtime/programming/checkpoint` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/realtime/programming/checkpoint/route.ts) |
| `/api/v1/realtime/session` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/realtime/session/route.ts) |
| `/api/v1/sso/saml/[clientId]/metadata` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/sso/saml/%5BclientId%5D/metadata/route.ts) |
| `/api/v1/sso/saml/[clientId]/sso` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/sso/saml/%5BclientId%5D/sso/route.ts) |
| `/api/v1/sso/transactions/[transactionId]/decision` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/sso/transactions/%5BtransactionId%5D/decision/route.ts) |
| `/api/v1/storage/analytics` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/storage/analytics/route.ts) |
| `/api/v1/storage/delete` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/storage/delete/route.ts) |
| `/api/v1/storage/download/[...path]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/storage/download/%5B...path%5D/route.ts) |
| `/api/v1/storage/folders` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/storage/folders/route.ts) |
| `/api/v1/storage/guarded-download/[token]` | GET, HEAD, OPTIONS | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/storage/guarded-download/%5Btoken%5D/route.ts) |
| `/api/v1/storage/list` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/storage/list/route.ts) |
| `/api/v1/storage/share` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/storage/share/route.ts) |
| `/api/v1/storage/share-batch` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/storage/share-batch/route.ts) |
| `/api/v1/storage/upload` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/storage/upload/route.ts) |
| `/api/v1/storage/upload-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/storage/upload-url/route.ts) |
| `/api/v1/topic-announcement-verifications/[token]` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/topic-announcement-verifications/%5Btoken%5D/route.ts) |
| `/api/v1/user/onboarding-progress` | GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/user/onboarding-progress/route.ts) |
| `/api/v1/user/profile` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/user/profile/route.ts) |
| `/api/v1/users/calendar-settings` | GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/calendar-settings/route.ts) |
| `/api/v1/users/chatgpt` | DELETE, GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/chatgpt/route.ts) |
| `/api/v1/users/me/avatar` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/me/avatar/route.ts) |
| `/api/v1/users/me/avatar/upload` | OPTIONS, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/me/avatar/upload/route.ts) |
| `/api/v1/users/me/avatar/upload-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/me/avatar/upload-url/route.ts) |
| `/api/v1/users/me/banner` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/me/banner/route.ts) |
| `/api/v1/users/me/banner/upload` | OPTIONS, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/me/banner/upload/route.ts) |
| `/api/v1/users/me/banner/upload-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/me/banner/upload-url/route.ts) |
| `/api/v1/users/me/board-list-overrides` | DELETE, GET, HEAD, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/me/board-list-overrides/route.ts) |
| `/api/v1/users/me/configs/[configId]` | DELETE, GET, HEAD, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/me/configs/%5BconfigId%5D/route.ts) |
| `/api/v1/users/me/default-workspace` | GET, HEAD, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/me/default-workspace/route.ts) |
| `/api/v1/users/me/delete` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/me/delete/route.ts) |
| `/api/v1/users/me/email` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/me/email/route.ts) |
| `/api/v1/users/me/full-name` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/me/full-name/route.ts) |
| `/api/v1/users/me/hidden-workspaces` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/me/hidden-workspaces/route.ts) |
| `/api/v1/users/me/hive-access` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/me/hive-access/route.ts) |
| `/api/v1/users/me/identities/[identityId]` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/me/identities/%5BidentityId%5D/route.ts) |
| `/api/v1/users/me/identities/link/[provider]` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/me/identities/link/%5Bprovider%5D/route.ts) |
| `/api/v1/users/me/identities` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/me/identities/route.ts) |
| `/api/v1/users/me/password/reauth` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/me/password/reauth/route.ts) |
| `/api/v1/users/me/password` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/me/password/route.ts) |
| `/api/v1/users/me/playgrounds/[projectId]/collaboration` | GET, POST, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/me/playgrounds/%5BprojectId%5D/collaboration/route.ts) |
| `/api/v1/users/me/playgrounds/[projectId]/preview/[port]/[[...path]]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/me/playgrounds/%5BprojectId%5D/preview/%5Bport%5D/%5B%5B...path%5D%5D/route.ts) |
| `/api/v1/users/me/playgrounds/[projectId]` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/me/playgrounds/%5BprojectId%5D/route.ts) |
| `/api/v1/users/me/playgrounds/[projectId]/runs/[runId]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/me/playgrounds/%5BprojectId%5D/runs/%5BrunId%5D/route.ts) |
| `/api/v1/users/me/playgrounds/[projectId]/runs` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/me/playgrounds/%5BprojectId%5D/runs/route.ts) |
| `/api/v1/users/me/playgrounds` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/me/playgrounds/route.ts) |
| `/api/v1/users/me/profile` | GET, HEAD, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/me/profile/route.ts) |
| `/api/v1/users/me/workspaces/[wsId]/configs/[configId]` | GET, HEAD, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/me/workspaces/%5BwsId%5D/configs/%5BconfigId%5D/route.ts) |
| `/api/v1/users/sessions/[sessionId]` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/sessions/%5BsessionId%5D/route.ts) |
| `/api/v1/users/sessions` | DELETE, GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/users/sessions/route.ts) |
| `/api/v1/webhooks/ai-agents/[adapter]/[channelId]` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/webhooks/ai-agents/%5Badapter%5D/%5BchannelId%5D/route.ts) |
| `/api/v1/webhooks/sepay/[token]` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/webhooks/sepay/%5Btoken%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/credits` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/ai/credits/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/memory/export` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/ai/memory/export/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/memory/items/[memoryId]` | DELETE, GET, HEAD, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/ai/memory/items/%5BmemoryId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/memory/items` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/ai/memory/items/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/memory/settings` | GET, HEAD, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/ai/memory/settings/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/model-favorites` | GET, HEAD, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/ai/model-favorites/route.ts) |
| `/api/v1/workspaces/[wsId]/ai/prompts/[promptId]` | DELETE, GET, HEAD, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/ai/prompts/%5BpromptId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/api-keys/[keyId]/rotate` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/api-keys/%5BkeyId%5D/rotate/route.ts) |
| `/api/v1/workspaces/[wsId]/api-keys/[keyId]` | DELETE, GET, HEAD, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/api-keys/%5BkeyId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/api-keys/[keyId]/usage-logs` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/api-keys/%5BkeyId%5D/usage-logs/route.ts) |
| `/api/v1/workspaces/[wsId]/api-keys/roles` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/api-keys/roles/route.ts) |
| `/api/v1/workspaces/[wsId]/api-keys` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/api-keys/route.ts) |
| `/api/v1/workspaces/[wsId]/avatar` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/avatar/route.ts) |
| `/api/v1/workspaces/[wsId]/avatar/upload-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/avatar/upload-url/route.ts) |
| `/api/v1/workspaces/[wsId]/calendar-settings` | GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/calendar-settings/route.ts) |
| `/api/v1/workspaces/[wsId]/chat/channels/[channelId]/messages` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/chat/channels/%5BchannelId%5D/messages/route.ts) |
| `/api/v1/workspaces/[wsId]/chat/channels/[channelId]/participants` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/chat/channels/%5BchannelId%5D/participants/route.ts) |
| `/api/v1/workspaces/[wsId]/chat/channels/[channelId]/typing` | DELETE, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/chat/channels/%5BchannelId%5D/typing/route.ts) |
| `/api/v1/workspaces/[wsId]/chat/channels` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/chat/channels/route.ts) |
| `/api/v1/workspaces/[wsId]/chat/conversations/[conversationId]/ai-observability` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/chat/conversations/%5BconversationId%5D/ai-observability/route.ts) |
| `/api/v1/workspaces/[wsId]/chat/conversations/[conversationId]/ai-settings` | GET, HEAD, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/chat/conversations/%5BconversationId%5D/ai-settings/route.ts) |
| `/api/v1/workspaces/[wsId]/chat/conversations/[conversationId]/attachments/[attachmentId]` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/chat/conversations/%5BconversationId%5D/attachments/%5BattachmentId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/chat/conversations/[conversationId]/attachments/upload-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/chat/conversations/%5BconversationId%5D/attachments/upload-url/route.ts) |
| `/api/v1/workspaces/[wsId]/chat/conversations/[conversationId]/external-context` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/chat/conversations/%5BconversationId%5D/external-context/route.ts) |
| `/api/v1/workspaces/[wsId]/chat/conversations/[conversationId]/link-previews` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/chat/conversations/%5BconversationId%5D/link-previews/route.ts) |
| `/api/v1/workspaces/[wsId]/chat/conversations/[conversationId]/messages/[messageId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/chat/conversations/%5BconversationId%5D/messages/%5BmessageId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/chat/conversations/[conversationId]/messages` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/chat/conversations/%5BconversationId%5D/messages/route.ts) |
| `/api/v1/workspaces/[wsId]/chat/conversations/[conversationId]/reactions` | GET, POST, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/chat/conversations/%5BconversationId%5D/reactions/route.ts) |
| `/api/v1/workspaces/[wsId]/chat/conversations/[conversationId]/read` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/chat/conversations/%5BconversationId%5D/read/route.ts) |
| `/api/v1/workspaces/[wsId]/chat/conversations/[conversationId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/chat/conversations/%5BconversationId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/chat/conversations/[conversationId]/shared-content` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/chat/conversations/%5BconversationId%5D/shared-content/route.ts) |
| `/api/v1/workspaces/[wsId]/chat/conversations/[conversationId]/title` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/chat/conversations/%5BconversationId%5D/title/route.ts) |
| `/api/v1/workspaces/[wsId]/chat/conversations` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/chat/conversations/route.ts) |
| `/api/v1/workspaces/[wsId]/chat/directory` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/chat/directory/route.ts) |
| `/api/v1/workspaces/[wsId]/chat/friend-requests/[requestId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/chat/friend-requests/%5BrequestId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/chat/friend-requests` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/chat/friend-requests/route.ts) |
| `/api/v1/workspaces/[wsId]/chat/reactions/retire` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/chat/reactions/retire/route.ts) |
| `/api/v1/workspaces/[wsId]/chat/realtime` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/chat/realtime/route.ts) |
| `/api/v1/workspaces/[wsId]/chat/search` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/chat/search/route.ts) |
| `/api/v1/workspaces/[wsId]/consolidate-users` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/consolidate-users/route.ts) |
| `/api/v1/workspaces/[wsId]/crawl` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/crawl/route.ts) |
| `/api/v1/workspaces/[wsId]/crawlers` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/crawlers/route.ts) |
| `/api/v1/workspaces/[wsId]/crawlers/status` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/crawlers/status/route.ts) |
| `/api/v1/workspaces/[wsId]/cron/jobs/[jobId]` | DELETE, GET, HEAD, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/cron/jobs/%5BjobId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/cron/jobs` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/cron/jobs/route.ts) |
| `/api/v1/workspaces/[wsId]/datasets/[datasetId]/cells` | DELETE, GET, HEAD, POST, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/datasets/%5BdatasetId%5D/cells/route.ts) |
| `/api/v1/workspaces/[wsId]/datasets/[datasetId]/columns/[columnId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/datasets/%5BdatasetId%5D/columns/%5BcolumnId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/datasets/[datasetId]/columns` | DELETE, GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/datasets/%5BdatasetId%5D/columns/route.ts) |
| `/api/v1/workspaces/[wsId]/datasets/[datasetId]/columns/sync` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/datasets/%5BdatasetId%5D/columns/sync/route.ts) |
| `/api/v1/workspaces/[wsId]/datasets/[datasetId]/duplicates/detect` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/datasets/%5BdatasetId%5D/duplicates/detect/route.ts) |
| `/api/v1/workspaces/[wsId]/datasets/[datasetId]/duplicates/remove` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/datasets/%5BdatasetId%5D/duplicates/remove/route.ts) |
| `/api/v1/workspaces/[wsId]/datasets/[datasetId]/full` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/datasets/%5BdatasetId%5D/full/route.ts) |
| `/api/v1/workspaces/[wsId]/datasets/[datasetId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/datasets/%5BdatasetId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/datasets/[datasetId]/rows/clear` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/datasets/%5BdatasetId%5D/rows/clear/route.ts) |
| `/api/v1/workspaces/[wsId]/datasets/[datasetId]/rows` | DELETE, GET, HEAD, POST, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/datasets/%5BdatasetId%5D/rows/route.ts) |
| `/api/v1/workspaces/[wsId]/datasets/[datasetId]/rows/sync` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/datasets/%5BdatasetId%5D/rows/sync/route.ts) |
| `/api/v1/workspaces/[wsId]/datasets` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/datasets/route.ts) |
| `/api/v1/workspaces/[wsId]/deleted` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/deleted/route.ts) |
| `/api/v1/workspaces/[wsId]/documents/[documentId]` | DELETE, GET, HEAD, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/documents/%5BdocumentId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/documents` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/documents/route.ts) |
| `/api/v1/workspaces/[wsId]/encryption/fix` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/encryption/fix/route.ts) |
| `/api/v1/workspaces/[wsId]/encryption/migrate` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/encryption/migrate/route.ts) |
| `/api/v1/workspaces/[wsId]/encryption` | DELETE, GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/encryption/route.ts) |
| `/api/v1/workspaces/[wsId]/external-apps/cron/executions` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-apps/cron/executions/route.ts) |
| `/api/v1/workspaces/[wsId]/external-apps/cron/jobs/[jobKey]/executions` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-apps/cron/jobs/%5BjobKey%5D/executions/route.ts) |
| `/api/v1/workspaces/[wsId]/external-apps/cron/jobs/[jobKey]` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-apps/cron/jobs/%5BjobKey%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/external-apps/cron/jobs/[jobKey]/run-now` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-apps/cron/jobs/%5BjobKey%5D/run-now/route.ts) |
| `/api/v1/workspaces/[wsId]/external-apps/cron` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-apps/cron/route.ts) |
| `/api/v1/workspaces/[wsId]/external-apps/cron/setup` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-apps/cron/setup/route.ts) |
| `/api/v1/workspaces/[wsId]/external-apps/drive/finalize` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-apps/drive/finalize/route.ts) |
| `/api/v1/workspaces/[wsId]/external-apps/drive/read-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-apps/drive/read-url/route.ts) |
| `/api/v1/workspaces/[wsId]/external-apps/drive` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-apps/drive/route.ts) |
| `/api/v1/workspaces/[wsId]/external-apps/drive/upload-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-apps/drive/upload-url/route.ts) |
| `/api/v1/workspaces/[wsId]/external-apps/members/[userId]/role` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-apps/members/%5BuserId%5D/role/route.ts) |
| `/api/v1/workspaces/[wsId]/external-apps/members/access` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-apps/members/access/route.ts) |
| `/api/v1/workspaces/[wsId]/external-apps/members/default-admin` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-apps/members/default-admin/route.ts) |
| `/api/v1/workspaces/[wsId]/external-apps/members/invitations` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-apps/members/invitations/route.ts) |
| `/api/v1/workspaces/[wsId]/external-apps/members` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-apps/members/route.ts) |
| `/api/v1/workspaces/[wsId]/external-chat/config` | GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-chat/config/route.ts) |
| `/api/v1/workspaces/[wsId]/external-chat/credentials` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-chat/credentials/route.ts) |
| `/api/v1/workspaces/[wsId]/external-chat/sync` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-chat/sync/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/assets/[assetId]` | DELETE, GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/assets/%5BassetId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/assets/[assetId]/webgl/[...assetPath]` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/assets/%5BassetId%5D/webgl/%5B...assetPath%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/assets/import-jobs/[jobId]/process` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/assets/import-jobs/%5BjobId%5D/process/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/assets/import-jobs/[jobId]` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/assets/import-jobs/%5BjobId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/assets/import-jobs` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/assets/import-jobs/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/assets` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/assets/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/assets/upload-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/assets/upload-url/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/blocks/[blockId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/blocks/%5BblockId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/blocks` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/blocks/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/collections/[collectionId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/collections/%5BcollectionId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/collections` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/collections/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/delivery` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/delivery/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/email-policy` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/email-policy/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/emails` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/emails/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/entries/[entryId]/bundle` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/entries/%5BentryId%5D/bundle/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/entries/[entryId]/duplicate` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/entries/%5BentryId%5D/duplicate/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/entries/[entryId]/publish` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/entries/%5BentryId%5D/publish/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/entries/[entryId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/entries/%5BentryId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/entries/batch` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/entries/batch/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/entries/bulk` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/entries/bulk/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/entries/bundle` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/entries/bundle/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/entries` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/entries/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/field-definitions/[fieldDefinitionId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/field-definitions/%5BfieldDefinitionId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/field-definitions` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/field-definitions/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/import` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/import/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/members/access` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/members/access/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/members/enhanced` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/members/enhanced/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/members/invite` | PATCH, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/members/invite/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/members/roles/[roleId]/members/[userId]` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/members/roles/%5BroleId%5D/members/%5BuserId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/members/roles/[roleId]/members` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/members/roles/%5BroleId%5D/members/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/members/roles/[roleId]` | DELETE, GET, HEAD, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/members/roles/%5BroleId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/members/roles/default` | GET, HEAD, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/members/roles/default/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/members/roles` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/members/roles/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/members` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/members/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/relation-definitions/[relationDefinitionId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/relation-definitions/%5BrelationDefinitionId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/relation-definitions` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/relation-definitions/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/setup` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/setup/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/storage` | DELETE, GET, HEAD, PATCH, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/storage/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# web: routes (4/5)
Source: https://docs.tuturuuu.com/reference/repository/routes/web-4

Source entry points and route ownership for the web workspace.

Runtime: **Next.js App Router**. Source: [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web). Package: `@tuturuuu/web`.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/api/v1/workspaces/[wsId]/external-projects/storage-analytics` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/storage-analytics/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/submissions/[entryId]` | PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/submissions/%5BentryId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/submissions` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/submissions/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/summary` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/summary/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/sync/apply` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/sync/apply/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/sync/diff` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/sync/diff/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/sync/snapshot` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/sync/snapshot/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/webgl-packages/extract-callback` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/webgl-packages/extract-callback/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/webgl-packages/finalize` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/webgl-packages/finalize/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/webgl-packages/upload` | OPTIONS, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/webgl-packages/upload/route.ts) |
| `/api/v1/workspaces/[wsId]/external-projects/webgl-packages/upload-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/external-projects/webgl-packages/upload-url/route.ts) |
| `/api/v1/workspaces/[wsId]/group-tags/[tagId]` | DELETE, GET, HEAD, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/group-tags/%5BtagId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/group-tags/[tagId]/user-groups/[groupId]` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/group-tags/%5BtagId%5D/user-groups/%5BgroupId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/group-tags/[tagId]/user-groups` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/group-tags/%5BtagId%5D/user-groups/route.ts) |
| `/api/v1/workspaces/[wsId]/group-tags` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/group-tags/route.ts) |
| `/api/v1/workspaces/[wsId]/integrations/sepay/disconnect` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/integrations/sepay/disconnect/route.ts) |
| `/api/v1/workspaces/[wsId]/integrations/sepay/endpoints/[id]/rotate` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/integrations/sepay/endpoints/%5Bid%5D/rotate/route.ts) |
| `/api/v1/workspaces/[wsId]/integrations/sepay/endpoints/[id]` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/integrations/sepay/endpoints/%5Bid%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/integrations/sepay/endpoints` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/integrations/sepay/endpoints/route.ts) |
| `/api/v1/workspaces/[wsId]/integrations/sepay/oauth/callback` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/integrations/sepay/oauth/callback/route.ts) |
| `/api/v1/workspaces/[wsId]/integrations/sepay/oauth/start` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/integrations/sepay/oauth/start/route.ts) |
| `/api/v1/workspaces/[wsId]/integrations/sepay/provision-webhooks` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/integrations/sepay/provision-webhooks/route.ts) |
| `/api/v1/workspaces/[wsId]/integrations/sepay/sync-bank-accounts` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/integrations/sepay/sync-bank-accounts/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/merges` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/inventory/merges/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/offline-mutations` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/inventory/offline-mutations/route.ts) |
| `/api/v1/workspaces/[wsId]/inventory/sales-periods/merges` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/inventory/sales-periods/merges/route.ts) |
| `/api/v1/workspaces/[wsId]/lettin/drive-copy/finalize-upload` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/lettin/drive-copy/finalize-upload/route.ts) |
| `/api/v1/workspaces/[wsId]/lettin/drive-copy/upload-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/lettin/drive-copy/upload-url/route.ts) |
| `/api/v1/workspaces/[wsId]/logo` | DELETE, GET, HEAD, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/logo/route.ts) |
| `/api/v1/workspaces/[wsId]/logo/upload-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/logo/upload-url/route.ts) |
| `/api/v1/workspaces/[wsId]/meet/plans` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/meet/plans/route.ts) |
| `/api/v1/workspaces/[wsId]/meetings/[meetingId]/assistant/personal` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/meetings/%5BmeetingId%5D/assistant/personal/route.ts) |
| `/api/v1/workspaces/[wsId]/meetings/[meetingId]/assistant/review` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/meetings/%5BmeetingId%5D/assistant/review/route.ts) |
| `/api/v1/workspaces/[wsId]/meetings/[meetingId]/assistant` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/meetings/%5BmeetingId%5D/assistant/route.ts) |
| `/api/v1/workspaces/[wsId]/meetings/[meetingId]/costs` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/meetings/%5BmeetingId%5D/costs/route.ts) |
| `/api/v1/workspaces/[wsId]/meetings/[meetingId]/realtime-token` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/meetings/%5BmeetingId%5D/realtime-token/route.ts) |
| `/api/v1/workspaces/[wsId]/meetings/[meetingId]/record` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/meetings/%5BmeetingId%5D/record/route.ts) |
| `/api/v1/workspaces/[wsId]/meetings/[meetingId]/recordings/[sessionId]/chunks` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/meetings/%5BmeetingId%5D/recordings/%5BsessionId%5D/chunks/route.ts) |
| `/api/v1/workspaces/[wsId]/meetings/[meetingId]/recordings/[sessionId]/play` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/meetings/%5BmeetingId%5D/recordings/%5BsessionId%5D/play/route.ts) |
| `/api/v1/workspaces/[wsId]/meetings/[meetingId]/recordings/[sessionId]` | DELETE, PATCH, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/meetings/%5BmeetingId%5D/recordings/%5BsessionId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/meetings/[meetingId]/recordings/[sessionId]/upload` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/meetings/%5BmeetingId%5D/recordings/%5BsessionId%5D/upload/route.ts) |
| `/api/v1/workspaces/[wsId]/meetings/[meetingId]/recordings` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/meetings/%5BmeetingId%5D/recordings/route.ts) |
| `/api/v1/workspaces/[wsId]/meetings/[meetingId]/review` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/meetings/%5BmeetingId%5D/review/route.ts) |
| `/api/v1/workspaces/[wsId]/meetings/[meetingId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/meetings/%5BmeetingId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/meetings/[meetingId]/stream` | GET, HEAD, PATCH, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/meetings/%5BmeetingId%5D/stream/route.ts) |
| `/api/v1/workspaces/[wsId]/meetings` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/meetings/route.ts) |
| `/api/v1/workspaces/[wsId]/members/batch-invite` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/members/batch-invite/route.ts) |
| `/api/v1/workspaces/[wsId]/members` | DELETE, GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/members/route.ts) |
| `/api/v1/workspaces/[wsId]/Mention` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/Mention/route.ts) |
| `/api/v1/workspaces/[wsId]/mobile/module-flags` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/mobile/module-flags/route.ts) |
| `/api/v1/workspaces/[wsId]/mobile-activity` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/mobile-activity/route.ts) |
| `/api/v1/workspaces/[wsId]/notes/[noteId]/convert-to-project` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/notes/%5BnoteId%5D/convert-to-project/route.ts) |
| `/api/v1/workspaces/[wsId]/notes/[noteId]/recovery` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/notes/%5BnoteId%5D/recovery/route.ts) |
| `/api/v1/workspaces/[wsId]/notes/[noteId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/notes/%5BnoteId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/notes/[noteId]/transfer` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/notes/%5BnoteId%5D/transfer/route.ts) |
| `/api/v1/workspaces/[wsId]/notes` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/notes/route.ts) |
| `/api/v1/workspaces/[wsId]/notes/voice-jobs/[jobId]` | DELETE, GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/notes/voice-jobs/%5BjobId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/notes/voice-jobs` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/notes/voice-jobs/route.ts) |
| `/api/v1/workspaces/[wsId]/personal-journal/[entryId]` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/personal-journal/%5BentryId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/personal-journal` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/personal-journal/route.ts) |
| `/api/v1/workspaces/[wsId]/posts/bootstrap` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/posts/bootstrap/route.ts) |
| `/api/v1/workspaces/[wsId]/posts/filter-options` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/posts/filter-options/route.ts) |
| `/api/v1/workspaces/[wsId]/posts/force-send` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/posts/force-send/route.ts) |
| `/api/v1/workspaces/[wsId]/posts/permissions` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/posts/permissions/route.ts) |
| `/api/v1/workspaces/[wsId]/posts` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/posts/route.ts) |
| `/api/v1/workspaces/[wsId]/posts/status` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/posts/status/route.ts) |
| `/api/v1/workspaces/[wsId]/profile-activity` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/profile-activity/route.ts) |
| `/api/v1/workspaces/[wsId]/programming/problems/[problemId]` | GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/programming/problems/%5BproblemId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/programming/problems` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/programming/problems/route.ts) |
| `/api/v1/workspaces/[wsId]/roles/[roleId]/members/[userId]` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/roles/%5BroleId%5D/members/%5BuserId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/roles/[roleId]/members` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/roles/%5BroleId%5D/members/route.ts) |
| `/api/v1/workspaces/[wsId]/roles/[roleId]` | DELETE, GET, HEAD, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/roles/%5BroleId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/roles/[roleId]/wallets/[walletId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/roles/%5BroleId%5D/wallets/%5BwalletId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/roles/[roleId]/wallets` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/roles/%5BroleId%5D/wallets/route.ts) |
| `/api/v1/workspaces/[wsId]/roles/default` | GET, HEAD, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/roles/default/route.ts) |
| `/api/v1/workspaces/[wsId]/roles/options` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/roles/options/route.ts) |
| `/api/v1/workspaces/[wsId]/roles` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/roles/route.ts) |
| `/api/v1/workspaces/[wsId]` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/settings/[configId]` | GET, HEAD, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/settings/%5BconfigId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/settings/approvals/pending-summary` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/settings/approvals/pending-summary/route.ts) |
| `/api/v1/workspaces/[wsId]/settings/configs` | GET, HEAD, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/settings/configs/route.ts) |
| `/api/v1/workspaces/[wsId]/settings/members` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/settings/members/route.ts) |
| `/api/v1/workspaces/[wsId]/settings/permissions/check` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/settings/permissions/check/route.ts) |
| `/api/v1/workspaces/[wsId]/settings/permissions` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/settings/permissions/route.ts) |
| `/api/v1/workspaces/[wsId]/settings/permissions/setup-status` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/settings/permissions/setup-status/route.ts) |
| `/api/v1/workspaces/[wsId]/settings` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/settings/route.ts) |
| `/api/v1/workspaces/[wsId]/slides/[slideId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/slides/%5BslideId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/slides` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/slides/route.ts) |
| `/api/v1/workspaces/[wsId]/sso/clients/[clientId]/activation` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/sso/clients/%5BclientId%5D/activation/route.ts) |
| `/api/v1/workspaces/[wsId]/sso/clients/[clientId]/assignments` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/sso/clients/%5BclientId%5D/assignments/route.ts) |
| `/api/v1/workspaces/[wsId]/sso/clients/[clientId]` | GET, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/sso/clients/%5BclientId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/sso/clients` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/sso/clients/route.ts) |
| `/api/v1/workspaces/[wsId]/storage/analytics` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/storage/analytics/route.ts) |
| `/api/v1/workspaces/[wsId]/storage/auto-extract` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/storage/auto-extract/route.ts) |
| `/api/v1/workspaces/[wsId]/storage/export/[token]/[...assetPath]` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/storage/export/%5Btoken%5D/%5B...assetPath%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/storage/export-links` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/storage/export-links/route.ts) |
| `/api/v1/workspaces/[wsId]/storage/finalize-upload` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/storage/finalize-upload/route.ts) |
| `/api/v1/workspaces/[wsId]/storage/folders` | DELETE, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/storage/folders/route.ts) |
| `/api/v1/workspaces/[wsId]/storage/list` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/storage/list/route.ts) |
| `/api/v1/workspaces/[wsId]/storage/migrate` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/storage/migrate/route.ts) |
| `/api/v1/workspaces/[wsId]/storage/object/[id]` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/storage/object/%5Bid%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/storage/object` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/storage/object/route.ts) |
| `/api/v1/workspaces/[wsId]/storage/rename` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/storage/rename/route.ts) |
| `/api/v1/workspaces/[wsId]/storage/rollout-state` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/storage/rollout-state/route.ts) |
| `/api/v1/workspaces/[wsId]/storage/share` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/storage/share/route.ts) |
| `/api/v1/workspaces/[wsId]/storage/upload` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/storage/upload/route.ts) |
| `/api/v1/workspaces/[wsId]/storage/upload-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/storage/upload-url/route.ts) |
| `/api/v1/workspaces/[wsId]/templates/[templateId]/background-url` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/templates/%5BtemplateId%5D/background-url/route.ts) |
| `/api/v1/workspaces/[wsId]/templates/[templateId]` | DELETE, GET, HEAD, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/templates/%5BtemplateId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/templates/[templateId]/shares` | DELETE, GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/templates/%5BtemplateId%5D/shares/route.ts) |
| `/api/v1/workspaces/[wsId]/templates/[templateId]/use` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/templates/%5BtemplateId%5D/use/route.ts) |
| `/api/v1/workspaces/[wsId]/templates/background` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/templates/background/route.ts) |
| `/api/v1/workspaces/[wsId]/templates` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/templates/route.ts) |
| `/api/v1/workspaces/[wsId]/templates/upload-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/templates/upload-url/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracker/stats` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/time-tracker/stats/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/analytics` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/analytics/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/break-types/[breakTypeId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/break-types/%5BbreakTypeId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/break-types` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/break-types/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/breaks` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/breaks/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/categories/[categoryId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/categories/%5BcategoryId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/categories/copy` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/categories/copy/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/categories` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/categories/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/goals/[goalId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/goals/%5BgoalId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/goals` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/goals/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/quick-start` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/quick-start/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/requests/[id]/activity` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/requests/%5Bid%5D/activity/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/requests/[id]/comments/[commentId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/requests/%5Bid%5D/comments/%5BcommentId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/requests/[id]/comments` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/requests/%5Bid%5D/comments/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/requests/[id]/image-urls` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/requests/%5Bid%5D/image-urls/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/requests/[id]` | PATCH, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/requests/%5Bid%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/requests` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/requests/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/requests/upload-url` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/requests/upload-url/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/requests/users` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/requests/users/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/sessions/[sessionId]/breaks/active` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/sessions/%5BsessionId%5D/breaks/active/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/sessions/[sessionId]/move` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/sessions/%5BsessionId%5D/move/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/sessions/[sessionId]` | DELETE, GET, HEAD, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/sessions/%5BsessionId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/sessions` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/sessions/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/stats/period` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/stats/period/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/templates` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/templates/route.ts) |
| `/api/v1/workspaces/[wsId]/time-tracking/threshold` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/time-tracking/threshold/route.ts) |
| `/api/v1/workspaces/[wsId]/topic-announcements/announcements/[announcementId]/attachments/[attachmentId]` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/topic-announcements/announcements/%5BannouncementId%5D/attachments/%5BattachmentId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/topic-announcements/announcements/[announcementId]/cancel-schedule` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/topic-announcements/announcements/%5BannouncementId%5D/cancel-schedule/route.ts) |
| `/api/v1/workspaces/[wsId]/topic-announcements/announcements/[announcementId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/topic-announcements/announcements/%5BannouncementId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/topic-announcements/announcements/[announcementId]/schedule` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/topic-announcements/announcements/%5BannouncementId%5D/schedule/route.ts) |
| `/api/v1/workspaces/[wsId]/topic-announcements/announcements/[announcementId]/send` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/topic-announcements/announcements/%5BannouncementId%5D/send/route.ts) |
| `/api/v1/workspaces/[wsId]/topic-announcements/attachments/upload` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/topic-announcements/attachments/upload/route.ts) |
| `/api/v1/workspaces/[wsId]/topic-announcements/contacts/[contactId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/topic-announcements/contacts/%5BcontactId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/topic-announcements/contacts/[contactId]/verify` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/topic-announcements/contacts/%5BcontactId%5D/verify/route.ts) |
| `/api/v1/workspaces/[wsId]/topic-announcements/contacts` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/topic-announcements/contacts/route.ts) |
| `/api/v1/workspaces/[wsId]/topic-announcements/import` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/topic-announcements/import/route.ts) |
| `/api/v1/workspaces/[wsId]/topic-announcements/preview` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/topic-announcements/preview/route.ts) |
| `/api/v1/workspaces/[wsId]/topic-announcements` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/topic-announcements/route.ts) |
| `/api/v1/workspaces/[wsId]/topic-announcements/send-bulk` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/topic-announcements/send-bulk/route.ts) |
| `/api/v1/workspaces/[wsId]/topic-announcements/templates/[templateId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/topic-announcements/templates/%5BtemplateId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/topic-announcements/templates` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/topic-announcements/templates/route.ts) |
| `/api/v1/workspaces/[wsId]/tutoring/export` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/tutoring/export/route.ts) |
| `/api/v1/workspaces/[wsId]/tutoring/policy` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/tutoring/policy/route.ts) |
| `/api/v1/workspaces/[wsId]/tutoring/queue` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/tutoring/queue/route.ts) |
| `/api/v1/workspaces/[wsId]/tutoring/sessions/[id]/mark` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/tutoring/sessions/%5Bid%5D/mark/route.ts) |
| `/api/v1/workspaces/[wsId]/tutoring/sessions/[id]/message-preview` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/tutoring/sessions/%5Bid%5D/message-preview/route.ts) |
| `/api/v1/workspaces/[wsId]/tutoring/sessions/[id]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/tutoring/sessions/%5Bid%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/tutoring/sessions` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/tutoring/sessions/route.ts) |
| `/api/v1/workspaces/[wsId]/tutoring/teachers` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/tutoring/teachers/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/attendance` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/attendance/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/count` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/count/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/group-checks/[postId]/email` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/group-checks/%5BpostId%5D/email/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/group-checks/[postId]/logs` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/group-checks/%5BpostId%5D/logs/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/group-checks/[postId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/group-checks/%5BpostId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/group-checks` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/group-checks/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/indicators/[indicatorId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/indicators/%5BindicatorId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/indicators/categories/[categoryId]` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/indicators/categories/%5BcategoryId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/indicators/categories` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/indicators/categories/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/indicators` | GET, HEAD, PATCH, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/indicators/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/managers` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/managers/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/members/[userId]/feedbacks` | DELETE, GET, HEAD, POST, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/members/%5BuserId%5D/feedbacks/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/members/[userId]` | DELETE | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/members/%5BuserId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/members/[userId]/vitals` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/members/%5BuserId%5D/vitals/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/members` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/members/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/posts/[postId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/posts/%5BpostId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/posts/[postId]/status` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/posts/%5BpostId%5D/status/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# web: routes (5/5)
Source: https://docs.tuturuuu.com/reference/repository/routes/web-5

Source entry points and route ownership for the web workspace.

Runtime: **Next.js App Router**. Source: [apps/web](https://github.com/tutur3u/platform/blob/main/apps/web). Package: `@tuturuuu/web`.

| URL pattern | Page or HTTP methods | Source |
| - | - | - |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/posts` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/posts/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]` | DELETE, GET, HEAD, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/[groupId]/storage` | DELETE, GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/%5BgroupId%5D/storage/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/activity-logs` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/activity-logs/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/count` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/count/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/sessions/[sessionId]/reconcile` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/sessions/%5BsessionId%5D/reconcile/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/sessions/[sessionId]` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/sessions/%5BsessionId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/sessions/group-summaries` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/sessions/group-summaries/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/sessions/occurrences` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/sessions/occurrences/route.ts) |
| `/api/v1/workspaces/[wsId]/user-groups/sessions` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-groups/sessions/route.ts) |
| `/api/v1/workspaces/[wsId]/user-profile-links/[linkId]` | DELETE, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-profile-links/%5BlinkId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/user-profile-links` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-profile-links/route.ts) |
| `/api/v1/workspaces/[wsId]/user-profile-links/users` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/user-profile-links/users/route.ts) |
| `/api/v1/workspaces/[wsId]/users/[userId]/attendance` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/%5BuserId%5D/attendance/route.ts) |
| `/api/v1/workspaces/[wsId]/users/[userId]/emails` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/%5BuserId%5D/emails/route.ts) |
| `/api/v1/workspaces/[wsId]/users/[userId]/follow-up` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/%5BuserId%5D/follow-up/route.ts) |
| `/api/v1/workspaces/[wsId]/users/[userId]/referral-discounts` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/%5BuserId%5D/referral-discounts/route.ts) |
| `/api/v1/workspaces/[wsId]/users/[userId]/referrals` | DELETE, GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/%5BuserId%5D/referrals/route.ts) |
| `/api/v1/workspaces/[wsId]/users/[userId]` | DELETE, GET, HEAD, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/%5BuserId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/users/[userId]/user-groups` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/%5BuserId%5D/user-groups/route.ts) |
| `/api/v1/workspaces/[wsId]/users/approvals/logs` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/approvals/logs/route.ts) |
| `/api/v1/workspaces/[wsId]/users/approvals` | GET, HEAD, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/approvals/route.ts) |
| `/api/v1/workspaces/[wsId]/users/attendance/export` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/attendance/export/route.ts) |
| `/api/v1/workspaces/[wsId]/users/audit-logs/backfill` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/audit-logs/backfill/route.ts) |
| `/api/v1/workspaces/[wsId]/users/audit-logs` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/audit-logs/route.ts) |
| `/api/v1/workspaces/[wsId]/users/avatar` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/avatar/route.ts) |
| `/api/v1/workspaces/[wsId]/users/bulk-import` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/bulk-import/route.ts) |
| `/api/v1/workspaces/[wsId]/users/count` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/count/route.ts) |
| `/api/v1/workspaces/[wsId]/users/database` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/database/route.ts) |
| `/api/v1/workspaces/[wsId]/users/duplicates/detect` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/duplicates/detect/route.ts) |
| `/api/v1/workspaces/[wsId]/users/feedbacks` | DELETE, GET, HEAD, POST, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/feedbacks/route.ts) |
| `/api/v1/workspaces/[wsId]/users/fields/[fieldId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/fields/%5BfieldId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/users/fields` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/fields/route.ts) |
| `/api/v1/workspaces/[wsId]/users/groups/featured-counts` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/groups/featured-counts/route.ts) |
| `/api/v1/workspaces/[wsId]/users/groups/possible-excluded` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/groups/possible-excluded/route.ts) |
| `/api/v1/workspaces/[wsId]/users/groups` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/groups/route.ts) |
| `/api/v1/workspaces/[wsId]/users/links/repair` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/links/repair/route.ts) |
| `/api/v1/workspaces/[wsId]/users/me` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/me/route.ts) |
| `/api/v1/workspaces/[wsId]/users/merge/bulk` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/merge/bulk/route.ts) |
| `/api/v1/workspaces/[wsId]/users/merge` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/merge/route.ts) |
| `/api/v1/workspaces/[wsId]/users/reports/[reportId]/delivery` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/reports/%5BreportId%5D/delivery/route.ts) |
| `/api/v1/workspaces/[wsId]/users/reports/[reportId]/generate` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/reports/%5BreportId%5D/generate/route.ts) |
| `/api/v1/workspaces/[wsId]/users/reports/[reportId]/logs` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/reports/%5BreportId%5D/logs/route.ts) |
| `/api/v1/workspaces/[wsId]/users/reports/[reportId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/reports/%5BreportId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/users/reports/groups/[groupId]/bulk-export` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/reports/groups/%5BgroupId%5D/bulk-export/route.ts) |
| `/api/v1/workspaces/[wsId]/users/reports/groups/[groupId]/dashboard` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/reports/groups/%5BgroupId%5D/dashboard/route.ts) |
| `/api/v1/workspaces/[wsId]/users/reports/groups` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/reports/groups/route.ts) |
| `/api/v1/workspaces/[wsId]/users/reports` | GET, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/reports/route.ts) |
| `/api/v1/workspaces/[wsId]/users/reports/schedules` | GET, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/reports/schedules/route.ts) |
| `/api/v1/workspaces/[wsId]/users` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/users/route.ts) |
| `/api/v1/workspaces/[wsId]/wallets/[walletId]/roles/[roleId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/wallets/%5BwalletId%5D/roles/%5BroleId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/wallets/[walletId]/roles` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/wallets/%5BwalletId%5D/roles/route.ts) |
| `/api/v1/workspaces/[wsId]/wallets` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/wallets/route.ts) |
| `/api/v1/workspaces/[wsId]/whiteboards/[boardId]/image-url` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/whiteboards/%5BboardId%5D/image-url/route.ts) |
| `/api/v1/workspaces/[wsId]/whiteboards/[boardId]` | DELETE, GET, HEAD, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/whiteboards/%5BboardId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/whiteboards` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/whiteboards/route.ts) |
| `/api/v1/workspaces/[wsId]/workforce/users/[userId]` | DELETE, GET, HEAD, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/workforce/users/%5BuserId%5D/route.ts) |
| `/api/v1/workspaces/[wsId]/workforce/users` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/%5BwsId%5D/workforce/users/route.ts) |
| `/api/v1/workspaces/limits` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/limits/route.ts) |
| `/api/v1/workspaces/personal` | PATCH, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/personal/route.ts) |
| `/api/v1/workspaces` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/route.ts) |
| `/api/v1/workspaces/team` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v1/workspaces/team/route.ts) |
| `/api/v2/workspaces/[wsId]/migrate/[module]` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v2/workspaces/%5BwsId%5D/migrate/%5Bmodule%5D/route.ts) |
| `/api/v2/workspaces/[wsId]` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/v2/workspaces/%5BwsId%5D/route.ts) |
| `/api/workspaces/[wsId]/accept-invite` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/workspaces/%5BwsId%5D/accept-invite/route.ts) |
| `/api/workspaces/[wsId]/categories/[categoryId]` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/workspaces/%5BwsId%5D/categories/%5BcategoryId%5D/route.ts) |
| `/api/workspaces/[wsId]/decline-invite` | POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/workspaces/%5BwsId%5D/decline-invite/route.ts) |
| `/api/workspaces/[wsId]/invite-links/[linkId]` | DELETE, GET, HEAD, PATCH | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/workspaces/%5BwsId%5D/invite-links/%5BlinkId%5D/route.ts) |
| `/api/workspaces/[wsId]/invite-links` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/workspaces/%5BwsId%5D/invite-links/route.ts) |
| `/api/workspaces/[wsId]/invite-status` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/workspaces/%5BwsId%5D/invite-status/route.ts) |
| `/api/workspaces/[wsId]/members/enhanced` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/workspaces/%5BwsId%5D/members/enhanced/route.ts) |
| `/api/workspaces/[wsId]/members/invite` | GET, PATCH, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/workspaces/%5BwsId%5D/members/invite/route.ts) |
| `/api/workspaces/[wsId]/members/profile` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/workspaces/%5BwsId%5D/members/profile/route.ts) |
| `/api/workspaces/[wsId]/members` | DELETE, GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/workspaces/%5BwsId%5D/members/route.ts) |
| `/api/workspaces/[wsId]` | DELETE, GET, HEAD, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/workspaces/%5BwsId%5D/route.ts) |
| `/api/workspaces/[wsId]/secrets/[secretId]` | DELETE, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/workspaces/%5BwsId%5D/secrets/%5BsecretId%5D/route.ts) |
| `/api/workspaces/[wsId]/secrets` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/workspaces/%5BwsId%5D/secrets/route.ts) |
| `/api/workspaces/[wsId]/tags/[tagId]` | DELETE, GET, HEAD, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/workspaces/%5BwsId%5D/tags/%5BtagId%5D/route.ts) |
| `/api/workspaces/[wsId]/tags` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/workspaces/%5BwsId%5D/tags/route.ts) |
| `/api/workspaces/[wsId]/tags/stats` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/workspaces/%5BwsId%5D/tags/stats/route.ts) |
| `/api/workspaces/[wsId]/transfers` | PATCH, POST, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/workspaces/%5BwsId%5D/transfers/route.ts) |
| `/api/workspaces/[wsId]/users/[userId]` | DELETE, GET, HEAD, PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/workspaces/%5BwsId%5D/users/%5BuserId%5D/route.ts) |
| `/api/workspaces/[wsId]/users/indicators/groups/migrate` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/workspaces/%5BwsId%5D/users/indicators/groups/migrate/route.ts) |
| `/api/workspaces/[wsId]/users/indicators/migrate` | PUT | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/workspaces/%5BwsId%5D/users/indicators/migrate/route.ts) |
| `/api/workspaces/[wsId]/users` | GET, HEAD, POST | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/workspaces/%5BwsId%5D/users/route.ts) |
| `/api/workspaces/invitations` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/workspaces/invitations/route.ts) |
| `/api/workspaces` | GET, HEAD | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/api/workspaces/route.ts) |
| `/native-integrity/turnstile` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/native-integrity/turnstile/route.ts) |
| `/serwist/[path]` | GET | [Implementation](https://github.com/tutur3u/platform/blob/main/apps/web/src/app/serwist/%5Bpath%5D/route.ts) |

[All apps and services](/reference/repository/catalog). [Versions](/reference/repository/versions).

# Versions and toolchain
Source: https://docs.tuturuuu.com/reference/repository/versions

Repository runtime pins, framework versions, workspace releases, and dependency references.

This reference reflects the checked-in manifests and lockfile for maintained workspaces. It describes the versions Tuturuuu uses, rather than asserting that every dependency is the newest upstream release. A package range is not a deployed version. Install with the pinned Bun version and `bun install --frozen-lockfile`; release artifacts and deployment evidence establish what is running. Rust/TanStack Start are paused and excluded from refreshes.

## Runtime pins

## Frameworks and tooling

| Dependency | Declared ranges | Locked resolutions |
| - | - | - |
| `next` | `16.3.5`, `>=16.3.0`, `^16.4.0` | `16.4.2` |
| `react` | `19.2.8`, `>=19.2.7`, `^19.2.8`, `~19.2.8` | `19.2.8` |
| `react-dom` | `>=19.2.7`, `^19.2.8`, `~19.2.8` | `19.2.8` |
| `typescript` | `7.0.2` | `7.0.2` |
| `tailwindcss` | `^4.3.3` | `4.3.3` |
| `ai` | `^7.0.148` | `7.0.148` |
| `@tanstack/react-start` | `1.169.3` | `1.168.60`, `1.169.3` |
| `@tanstack/react-router` | `1.170.45` | `1.170.41`, `1.170.45` |
| `@tanstack/react-query` | `5.104.5`, `^5.101.2`, `^5.104.5` | `5.104.5` |
| `vite` | `^8.3.5`, `npm:@voidzero-dev/vite-plus-core@1.3.0` | `8.3.5` |
| `vitest` | `5.0.0`, `5.0.5`, `^5.0.5` | `5.0.5` |
| `turbo` | `^2.11.10` | `2.11.10` |
| `@biomejs/biome` | `2.5.13`, `^2.5.13` | `2.5.13` |
| `effect` | `^3.22.3` | `3.22.3` |
| `zod` | `4.6.7`, `^4.6.7` | `4.1.11`, `4.6.5`, `4.6.7` |
| `wrangler` | `4.151.2`, `4.152.0`, `^4.152.0` | `4.151.0`, `4.151.2`, `4.152.0` |
| `supabase` | `2.117.0` | `2.117.0` |

## Complete dependency reference

* [npm dependency versions 1](/reference/repository/dependencies-1)
* [npm dependency versions 2](/reference/repository/dependencies-2)
* [npm dependency versions 3](/reference/repository/dependencies-3)
* [npm dependency versions 4](/reference/repository/dependencies-4)
* [Python locked dependencies 1](/reference/repository/python-dependencies-1)
* [Python locked dependencies 2](/reference/repository/python-dependencies-2)
* [Dart locked dependencies 1](/reference/repository/dart-dependencies-1)
* [Dart locked dependencies 2](/reference/repository/dart-dependencies-2)
* [Dart locked dependencies 3](/reference/repository/dart-dependencies-3)
* [Dart locked dependencies 4](/reference/repository/dart-dependencies-4)

Python resolutions live in [apps/discord/uv.lock](https://github.com/tutur3u/platform/blob/main/apps/discord/uv.lock); Dart resolutions in [apps/mobile/pubspec.lock](https://github.com/tutur3u/platform/blob/main/apps/mobile/pubspec.lock). Their manifest requirements are separate from npm package ranges.

## Workspace release versions

Release Please owns version changes; do not manually align independently released packages.

{workspace.name || 'Unnamed Workspace'}

Workspace Details

Workspace Settings

{workspace.name || 'Unnamed Workspace'}

Hello, World!

` to `

` | Headings | `

Title

Welcome!

Card Title

Card Title

Hello, World!

Welcome, {name}!

{name}

Tasks

About Us

Users

Blog Post: {slug}

My Blog

{post.title}

AI Flashcard Generator

{list.name}

Welcome, {user.email}

Tasks

Something went wrong!