@take-out/docs 0.0.52 → 0.0.57

package/package-json.md

@@ -1,115 +0,0 @@
----
-name: takeout-package-json
-description: Package.json structure guide. package.json, package configuration, scripts section, npm scripts, env vars, environment variables, workspaces, monorepo, trustedDependencies, dependencies.
----
-
-# package.json
-
-this project uses a single root package.json with workspaces for internal
-packages. understanding its structure helps avoid common mistakes.
-
-we use bun generally for scripts we write, and we try and create high level
-groups for scripts that we then run with the `tko` helper.
-
-## scripts section
-
-scripts are minimal - most commands use the takeout cli (`tko`).
-
-### patterns
-
-**prefer `tko` over direct commands:**
-
-```json
-"check": "tko check",
-"build": "tko run build",
-"clean": "tko run clean"
-```
-
-**use `tko run` for parallel execution:**
-
-```json
-"dev": "tko run run one:dev watch dev-tunnel-if-exist"
-```
-
-### adding new scripts
-
-if this repo has a `./packages/scripts` - this is for scripts that are shared
-between all users of Takeout, basically any script that is useful beyond being a
-demo/example specifically for this repo. but otherwise you want to just put
-scripts into `./scripts`.
-
-example - adding a port check before dev:
-
-```bash
-# create the script
-echo '#!/usr/bin/env bun
-/**
- * @description Ensure a port is available
- */
-// implementation...' > scripts/ensure-port.ts
-
-# use via tko
-bun tko ensure-port 8081
-```
-
-## env section
-
-the `env` object defines environment variables for the project. this is used by
-`bun tko env:update` to generate typed env files.
-
-```json
-"env": {
-  "AWS_ACCESS_KEY_ID": "",
-  "BETTER_AUTH_SECRET": true,
-  "CLOUDFLARE_R2_ENDPOINT": "http://minio:9000/chat"
-}
-```
-
-values:
-
-- `""` - optional, no default
-- `"value"` - optional with default value
-- `true` - required, must be set in .env files
-
-**never modify `/src/server/env-server.ts` directly** - it's auto-generated from
-this section.
-
-to add a new env var:
-
-1. add to `env` section in package.json
-2. run `bun env:update`
-3. optionally add example value to `.env.development`
-
-## trustedDependencies
-
-allow postinstall scripts for specific packages:
-
-```json
-"trustedDependencies": [
-  "@rocicorp/zero-sqlite3"
-]
-```
-
-## takeout section
-
-project-specific metadata for onboarding script etc:
-
-```json
-"takeout": {
-  "onboarded": false
-}
-```
-
-## common mistakes
-
-1. **adding scripts that should be in `./scripts/`** - if it's project-specific
-   logic, put it in scripts folder
-
-2. **modifying env-server.ts directly** - always use `env` section +
-   `bun env:update`
-
-3. **using full paths when tko works** - prefer `tko check types` over
-   `bun ./scripts/check/types.ts`
-
-4. **forgetting workspace:\* for internal packages** - always use `workspace:*`
-   for packages in `./packages/*`

package/react-native-navigation-flow.md

@@ -1,184 +0,0 @@
----
-name: takeout-react-native-navigation-flow
-description: React Native navigation and mobile routing guide for One framework. React Native navigation, native navigation, useRouter, useParams on native, drawer layout, drawer navigation, mobile routing, One framework routing, screen transitions, navigation flow.
----
-
-# React Native Navigation Flow
-
-## Overview
-
-This app uses the One framework instead of React Navigation. One provides
-unified routing for both web and React Native platforms using a file-based
-routing system.
-
-## Navigation Architecture
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                    App Entry Point                       │
-│              (One Framework Bootstrap)                   │
-└────────────────────┬────────────────────────────────────┘
-                     │
-                     ↓
-┌─────────────────────────────────────────────────────────┐
-│                 app/_layout.tsx                          │
-│   • SafeAreaProvider                                     │
-│   • TamaguiProvider (Theme)                             │
-│   • SchemeProvider (Color Scheme)                       │
-│   • DataProvider (Zero sync)                            │
-│   • AuthEffects                                         │
-│   • <Slot /> (renders current route)                    │
-└────────────────────┬────────────────────────────────────┘
-                     │
-                     ↓
-┌─────────────────────────────────────────────────────────┐
-│            app/(chat)/_layout.native.tsx                 │
-│   • Drawer Layout (slide menu)                          │
-│   • Server/Channel Context Providers                    │
-│   • Safe Area Insets                                    │
-│   • <Slot /> (renders chat routes)                      │
-└────────────────────┬────────────────────────────────────┘
-                     │
-                     ↓
-        ┌────────────┴────────────┬─────────────┐
-        │                         │             │
-        ↓                         ↓             ↓
-┌───────────────┐       ┌─────────────┐ ┌──────────────┐
-│ index.tsx     │       │ [serverId]/ │ │ private/     │
-│ (Home Page)   │       │ (Channels)  │ │ (DMs)        │
-└───────────────┘       └─────────────┘ └──────────────┘
-```
-
-## Navigation Components
-
-### 1. Slot Component
-
-- From `one` framework
-- Renders the current route content
-- Similar to React Router's `<Outlet />`
-
-### 2. Drawer Component
-
-- From `react-native-drawer-layout`
-- Provides sliding sidebar on mobile
-- Contains server list and channels
-
-### 3. Navigation Hooks
-
-```typescript
-// get current route parameters
-const params = useParams()
-const { serverId, channelId } = useServerParams()
-
-// programmatic navigation
-const router = useRouter()
-router.navigate(`/${serverId}/${channelId}`)
-
-// current pathname (web only)
-const pathname = usePathname() // must check isWeb first
-```
-
-## Navigation Flow Examples
-
-### 1. App Launch Flow
-
-```
-App Start → Check Auth →
-  ├─ Authenticated → Redirect to last visited page
-  └─ Not Authenticated → Show home page
-```
-
-### 2. Server Navigation Flow
-
-```
-User taps server →
-  Update context (serverId) →
-  Navigate to default channel →
-  Close drawer →
-  Render channel messages
-```
-
-### 3. Deep Link Flow
-
-```
-Deep link received →
-  Parse URL parameters →
-  Navigate to specific message/thread →
-  Scroll to message
-```
-
-## Platform-Specific Behaviors
-
-### React Native
-
-- Drawer navigation for sidebar
-- Safe area handling
-- Touch-based interactions
-- No browser history API
-
-### Web
-
-- Fixed sidebar (responsive)
-- Browser history navigation
-- URL-based routing
-- Keyboard shortcuts
-
-## Context Flow
-
-```
-┌─────────────────────────┐
-│   Navigation Event      │
-│ (tap, link, redirect)   │
-└───────────┬─────────────┘
-            │
-            ↓
-┌─────────────────────────┐
-│  Update URL/Route       │
-│  (One Framework)        │
-└───────────┬─────────────┘
-            │
-            ↓
-┌─────────────────────────┐
-│  Update Contexts        │
-│  • CurrentServerId      │
-│  • CurrentChannelId     │
-│  • CurrentThreadId      │
-└───────────┬─────────────┘
-            │
-            ↓
-┌─────────────────────────┐
-│  Re-render Components   │
-│  • Sidebar highlights   │
-│  • Message list         │
-│  • Header info          │
-└─────────────────────────┘
-```
-
-## Key Files
-
-1. Navigation Setup
-
-   - `/app/_layout.tsx` - Root layout
-   - `/app/(chat)/_layout.native.tsx` - Native chat layout
-   - `/src/interface/app/Link.tsx` - Link component wrapper
-
-2. Navigation Helpers
-
-   - `/src/features/channel/getChannelLink.ts`
-   - `/src/features/message/getMessageLink.ts`
-   - `/src/features/server/useServerParams.ts`
-
-3. Context Providers
-   - `/src/context/CurrentServerId.tsx`
-   - `/src/context/CurrentChannelId.tsx`
-   - `/src/context/CurrentThreadId.tsx`
-
-## Important Notes
-
-1. No React Navigation: This app uses One framework's built-in routing, not
-   React Navigation
-2. File-based Routing: Routes are determined by file structure in `/app`
-3. Platform Parity: Same routing code works on both web and native
-4. Context-based State: Navigation state is managed through React Context
-5. URL-driven: Even on native, routing is URL-based (though not visible to
-   users)

package/scripts.md

@@ -1,144 +0,0 @@
----
-name: takeout-scripts
-description: Scripts guide for tko CLI automation. scripts, CLI scripts, ./scripts/ directory, tko commands, tko run, parallel execution, script management, bun scripts, npm scripts, automation.
----
-
-# scripts
-
-the takeout cli (`tko`) provides a smart script runner that auto-discovers
-scripts from two locations:
-
-1. **local scripts** in `./scripts/` - project-specific scripts
-2. **built-in scripts** in `@take-out/scripts` package - shared utilities
-
-local scripts override built-in ones with the same name.
-
-## running scripts
-
-```bash
-# run a script directly
-bun tko ensure-port 8081
-bun tko clean
-
-# run scripts in a category
-bun tko web build
-bun tko aws health
-```
-
-## creating scripts
-
-scripts are `.ts` files in `./scripts/`. add a `@description` comment for
-documentation:
-
-```ts
-#!/usr/bin/env bun
-
-/**
- * @description Ensure a port is available
- */
-
-const port = process.argv[2]
-// ... implementation
-```
-
-use `bun tko script new <path>` to scaffold a new script:
-
-```bash
-bun tko script new check/ports
-# creates ./scripts/check/ports.ts
-```
-
-## script organization
-
-```
-scripts/
-├── build-initial.ts      # top-level scripts
-├── node.ts
-├── aws/                   # category folders
-│   ├── configure.ts
-│   └── health.ts
-├── check/
-│   ├── dependencies.ts
-│   └── types.ts
-├── ci/
-│   ├── release.ts
-│   └── check.ts
-└── web/
-    ├── build.ts
-    └── serve.ts
-```
-
-## helpers directory
-
-scripts can share code via `./scripts/helpers/` (or category-level helpers).
-this directory is excluded from script discovery.
-
-```
-scripts/
-├── helpers/              # shared code, not runnable
-│   └── docker.ts
-├── ci/
-│   └── helpers/          # ci-specific helpers
-│       └── deploy.ts
-```
-
-## listing available scripts
-
-```bash
-# show all available scripts
-bun tko
-
-# show scripts in a category
-bun tko script aws
-
-# list built-in commands
-bun tko --help
-```
-
-## built-in commands vs scripts
-
-built-in commands are always available:
-
-- `tko onboard` - setup wizard
-- `tko docs` - view documentation
-- `tko env:setup` - setup environment
-- `tko run` - run scripts in parallel
-- `tko script` - manage scripts
-
-everything else routes to the script runner.
-
-## parallel execution
-
-use `tko run` to run multiple scripts in parallel:
-
-```bash
-# run three scripts in parallel
-bun tko run build lint typecheck
-
-# in package.json
-"dev": "tko run run one:dev watch dev-tunnel-if-exist"
-```
-
-## script metadata
-
-scripts can define metadata via jsdoc comments:
-
-```ts
-/**
- * @description Build docker image for web
- * @args --tag, --push
- */
-```
-
-this metadata is cached in `~/.takeout/script-cache.json` for fast lookups.
-
-## ejecting built-in scripts
-
-to customize a built-in script, eject it to your local scripts folder:
-
-```bash
-bun tko script eject
-```
-
-this copies scripts from `@take-out/scripts` to `./scripts/`, letting you modify
-them while keeping the same command interface.