@take-out/docs 0.0.42

package/package-json.md

@@ -0,0 +1,115 @@
+---
+name: package-json
+description: Package.json structure guide. INVOKE WHEN: 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/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@take-out/docs",
+  "version": "0.0.42",
+  "description": "Documentation files for Takeout starter kit",
+  "type": "module",
+  "files": [
+    "*.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/react-native-navigation-flow.md

@@ -0,0 +1,184 @@
+---
+name: react-native-navigation-flow
+description: React Native navigation and mobile routing guide for One framework. INVOKE WHEN: 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

@@ -0,0 +1,147 @@
+---
+name: scripts
+description: Scripts guide for tko CLI automation. INVOKE WHEN: 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
+
+# alternate category syntax
+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.

package/sync-prompt.md

@@ -0,0 +1,208 @@
+---
+name: sync-prompt
+description: Intelligent sync guide for updating forked Takeout with upstream changes while preserving customizations. INVOKE WHEN: sync, upstream sync, fork sync, merging upstream, git merge, tamagui/takeout3, upstream changes, update from takeout, takeout updates.
+---
+
+# Takeout Repository Sync Prompt
+
+You are helping sync a fork of the Takeout starter kit with the latest upstream changes.
+
+## Context
+
+This application was forked from Takeout, a full-stack starter kit for building production-ready apps. The upstream repository is at `git@github.com:tamagui/takeout3.git`.
+
+## Your Task
+
+Intelligently sync the latest Takeout changes into this repository while preserving all user customizations.
+
+## Process
+
+### 1. Clone Upstream Repository
+
+Clone the upstream Takeout repository to a temporary directory:
+
+```bash
+git clone git@github.com:tamagui/takeout3.git /tmp/takeout-upstream
+cd /tmp/takeout-upstream
+```
+
+### 2. Identify Last Synced Commit
+
+Compare the current repository with the upstream to determine the last commit that was synced from Takeout. You can do this by:
+
+- Checking git history for merge commits from upstream
+- Comparing file contents and commit messages
+- Looking for a `.takeout` marker file (if it exists) that contains the last synced commit SHA
+
+Create or update a `.takeout` file in the project root with the current HEAD SHA after syncing.
+
+### 3. Analyze New Commits
+
+Starting from the last synced commit, go through each new commit in the upstream repository:
+
+```bash
+git log --oneline <last-synced-commit>..HEAD
+```
+
+For each commit:
+
+1. **Read the commit message and diff** to understand what changed
+2. **Categorize the change**:
+   - Infrastructure/tooling updates (build scripts, CI/CD, etc.)
+   - Feature additions or enhancements
+   - Bug fixes
+   - Dependency updates
+   - Documentation updates
+   - Breaking changes
+
+3. **Determine if it's applicable** to this repository:
+   - Does this repository still contain the code being modified?
+   - Has the user customized this area significantly?
+   - Is this a core Takeout feature or something the user likely removed?
+
+### 4. Apply Changes Intelligently
+
+For each applicable change:
+
+**If the code still exists and hasn't been heavily customized:**
+- Apply the change directly, preserving user modifications where possible
+- Use three-way merge strategies when conflicts arise
+
+**If the code has been customized:**
+- Pause and ask the user:
+  - Show them the upstream change
+  - Show them their current code
+  - Ask if they want to: (a) apply the change, (b) skip it, (c) manually merge it, or (d) see more details
+
+**If the code doesn't exist anymore:**
+- Skip the change (user likely removed this feature intentionally)
+- Optionally mention it in a summary at the end
+
+### 5. Handle Package Ejection
+
+Check if the user has ejected from the monorepo setup:
+
+```bash
+# If ./packages directory doesn't exist, they've ejected
+```
+
+**If ejected:**
+- DO NOT copy any changes from `./packages/*` directories
+- Instead, at the end of syncing, check the latest `@take-out/*` package versions in the upstream `package.json`
+- Run: `bun add @take-out/cli@^X.X.X @take-out/helpers@^X.X.X` (etc.) with the latest versions
+
+**If NOT ejected:**
+- Sync changes to `./packages/*` normally
+- Preserve any local modifications to these packages
+
+### 6. Handle Special Cases
+
+**Environment variables:**
+- Never overwrite `.env` or `.env.local`
+- For new variables in `.env.development`, notify the user but don't auto-add
+
+**Configuration files:**
+- `package.json`: Merge dependencies carefully, don't overwrite user's custom scripts/config
+- `tsconfig.json`, `.oxfmtrc.jsonc`, `.oxlintrc.json`: Merge carefully, preserving user customizations
+- `app.config.ts`: Never overwrite (contains user's app identity)
+
+**Database migrations:**
+- Always apply new migrations in `./migrations/*`
+- Never modify existing migrations
+
+**Generated files:**
+- Skip `src/data/generated/*` (these are auto-generated)
+- Skip `node_modules/`, `.vxrn/`, `dist/`, etc.
+
+### 7. Pause for Decisions
+
+Stop and ask the user whenever:
+- A change conflicts with their customizations
+- A breaking change is detected
+- Multiple valid approaches exist for merging a change
+- The change affects core app functionality they've modified
+- You're uncertain about the best approach
+
+When pausing, provide:
+- Clear explanation of the situation
+- The upstream change details
+- Their current code
+- Recommended options with pros/cons
+- A way to skip and continue
+
+### 8. Summary and Completion
+
+After processing all commits:
+
+1. Create a summary document showing:
+   - Commits applied successfully
+   - Changes skipped (with reasons)
+   - Manual interventions made
+   - New package versions (if ejected)
+   - Any recommended follow-up actions
+
+2. Update the `.takeout` marker file with the new HEAD SHA
+
+3. Run post-sync checks:
+   ```bash
+   bun install
+   bun lint:fix
+   bun tko check types
+   ```
+
+4. If checks fail, report the errors and suggest fixes
+
+## Important Guidelines
+
+- **Preserve user intent**: When in doubt, preserve the user's changes over upstream changes
+- **Be transparent**: Always explain what you're doing and why
+- **Ask questions**: Better to pause and ask than to make a wrong assumption
+- **Test incrementally**: After significant changes, suggest running tests
+- **Document decisions**: Keep track of choices made for future reference
+- **Respect customizations**: Recognize that users forked Takeout to make it their own
+
+## Example Decision Points
+
+**Example 1: Upstream updates a component the user has heavily customized**
+```
+⚠️  Decision needed: Upstream updated ButtonSimple component
+
+Upstream changes:
+- Added new 'variant' prop
+- Changed default styling
+- Fixed accessibility issue
+
+Your current code:
+- Custom 'theme' prop added
+- Completely different styling approach
+- Same accessibility issue present
+
+Options:
+a) Skip upstream changes (keep your customizations)
+b) Apply only the accessibility fix
+c) Manually merge all changes
+d) Show me the full diff
+
+What would you like to do? [a/b/c/d]
+```
+
+**Example 2: New dependency in upstream**
+```
+ℹ️  Upstream added new dependency: @tamagui/animate-presence@1.0.0
+
+This is used in the new modal animations feature. You don't currently have
+any modals in your app.
+
+Options:
+a) Add dependency and related code (prepare for future use)
+b) Skip (you can add it later if needed)
+
+What would you like to do? [a/b]
+```
+
+## Final Notes
+
+- This is a **intelligent sync**, not a blind merge
+- The goal is to **keep you up-to-date** while **respecting your customizations**
+- When uncertain, **always ask** before making changes
+- Keep a **detailed log** of all changes for review