refactor: update documentation titles and summaries for clarity and consistency

Author: LadyBluenotes

packages/start-skills/manifest.json

@@ -5,15 +5,25 @@
     "v1": {
       "index": "skills/v1/index.md",
       "files": [
-        "skills/v1/adapters.md",
+        "skills/v1/authentication.md",
+        "skills/v1/databases.md",
         "skills/v1/deployment.md",
         "skills/v1/environment-config.md",
+        "skills/v1/error-boundaries.md",
+        "skills/v1/execution-model.md",
         "skills/v1/file-structure.md",
         "skills/v1/index.md",
         "skills/v1/middleware.md",
+        "skills/v1/observability.md",
+        "skills/v1/path-aliases.md",
+        "skills/v1/routing.md",
         "skills/v1/router-integration.md",
+        "skills/v1/selective-ssr.md",
+        "skills/v1/server-entry-point.md",
         "skills/v1/server-functions.md",
+        "skills/v1/server-routes.md",
         "skills/v1/start-setup.md",
+        "skills/v1/static-prerendering.md",
         "skills/v1/streaming-ssr.md"
       ]
     }

packages/start-skills/skills/topics.json

@@ -2,11 +2,21 @@
   "index.md",
   "start-setup.md",
   "file-structure.md",
+  "routing.md",
   "router-integration.md",
-  "adapters.md",
+  "path-aliases.md",
+  "execution-model.md",
+  "server-entry-point.md",
+  "environment-config.md",
   "server-functions.md",
+  "server-routes.md",
+  "databases.md",
   "middleware.md",
   "streaming-ssr.md",
-  "environment-config.md",
+  "selective-ssr.md",
+  "static-prerendering.md",
+  "error-boundaries.md",
+  "authentication.md",
+  "observability.md",
   "deployment.md"
 ]

packages/start-skills/skills/v1/adapters.md

@@ -0,0 +1,34 @@
+---
+id: authentication
+title: Authentication
+versions:
+  - latest
+summary: Define auth boundaries and implement login flows.
+resources:
+  - https://tanstack.com/start/latest/docs/overview
+---
+
+# Authentication
+
+Purpose:
+
+- Define authentication boundaries and implement login flows.
+
+Scope:
+
+- Use when planning sessions, cookies, providers, or token storage.
+
+Guidelines:
+
+- Keep auth checks in middleware or server functions, not client-only code.
+- Use `@skills/router/authenticated-routes` for route guards and redirects.
+- Align session storage with the chosen adapter runtime.
+
+Examples:
+
+```ts
+export const login = serverFn(async (input) => {
+  const user = await verifyCredentials(input)
+  return createSession(user)
+})
+```

packages/start-skills/skills/v1/authentication.md

@@ -0,0 +1,33 @@
+---
+id: databases
+title: Databases
+versions:
+  - latest
+summary: Access databases safely in Start apps.
+resources:
+  - https://tanstack.com/start/latest/docs/overview
+---
+
+# Databases
+
+Purpose:
+
+- Keep database access on the server while keeping types aligned.
+
+Scope:
+
+- Use when introducing database clients or query layers.
+
+Guidelines:
+
+- Initialize database clients in server-only modules.
+- Expose data through server functions or `@skills/router/loaders`.
+- Align connection pooling with the adapter runtime.
+
+Examples:
+
+```ts
+export const listProjects = serverFn(async () => {
+  return db.project.findMany()
+})
+```

packages/start-skills/skills/v1/databases.md

@@ -1,15 +1,14 @@
 ---
 id: deployment
-title: Start Deployment
+title: Deployment
 versions:
   - latest
-  - ">=1 <2"
-summary: Deploy Start apps with the right adapter and build outputs.
+summary: Deploy Start apps to hosting targets.
 resources:
   - https://tanstack.com/start/latest/docs/overview
 ---
 
-# Start Deployment
+# Deployment
 
 Purpose:
 
@@ -22,5 +21,5 @@ Scope:
 Guidelines:
 
 - Confirm adapter compatibility with the hosting provider.
-- Validate SSR streaming requirements and response limits.
+- Validate SSR requirements with `@skills/router/ssr-loaders`.
 - Ensure server functions are deployed to the correct runtime.

packages/start-skills/skills/v1/deployment.md

@@ -1,26 +1,40 @@
 ---
 id: environment-config
-title: Start Environment Config
+title: Environment
 versions:
   - latest
-  - ">=1 <2"
-summary: Manage environment variables and secrets for Start runtimes.
+summary: Configure environment variables and runtime helpers.
 resources:
   - https://tanstack.com/start/latest/docs/overview
 ---
 
-# Start Environment Config
+# Environment
 
 Purpose:
 
-- Keep secrets and runtime settings consistent across environments.
+- Define environment variables and runtime helpers safely.
 
 Scope:
 
-- Use when wiring environment variables for adapters and server functions.
+- Use when wiring environment variables, secrets, and runtime helpers.
 
 Guidelines:
 
 - Validate required environment variables at startup.
 - Keep secrets server-only and never expose them to client bundles.
-- Coordinate per-environment overrides with the deployment target.
+- Keep environment helpers in server entry files or server functions.
+- Validate helpers against the selected adapter runtime.
+
+Examples:
+
+```ts
+const requireEnv = (key: string) => {
+  const value = process.env[key]
+  if (!value) throw new Error(`Missing ${key}`)
+  return value
+}
+
+export const env = {
+  databaseUrl: requireEnv('DATABASE_URL'),
+}
+```

packages/start-skills/skills/v1/environment-config.md

@@ -0,0 +1,26 @@
+---
+id: error-boundaries
+title: Error Handling
+versions:
+  - latest
+summary: Handle runtime and hydration errors safely.
+resources:
+  - https://tanstack.com/start/latest/docs/overview
+---
+
+# Error Handling
+
+Purpose:
+
+- Define how errors surface during server rendering and hydration.
+
+Scope:
+
+- Use when handling runtime failures and hydration mismatches.
+
+Guidelines:
+
+- Capture server errors in middleware or server functions.
+- Use `@skills/router/error-boundaries` for route-level UI fallback.
+- Pair 404 handling with `@skills/router/not-found-boundaries`.
+- Ensure server-rendered data matches client expectations.

packages/start-skills/skills/v1/error-boundaries.md

@@ -0,0 +1,38 @@
+---
+id: execution-model
+title: Execution Model
+versions:
+  - latest
+summary: Understand where Start code executes.
+resources:
+  - https://tanstack.com/start/latest/docs/overview
+---
+
+# Execution Model
+
+Purpose:
+
+- Clarify what runs on the server, client, or both.
+
+Scope:
+
+- Use when debugging execution context and data flow.
+
+Guidelines:
+
+- Keep server-only logic in entry points and server functions.
+- Use server functions or `@skills/router/loaders` for data fetching.
+- Avoid importing server-only modules in client entry files.
+- Avoid relying on browser-only APIs during SSR.
+
+Examples:
+
+```ts
+// server-only module
+export async function readSecrets() {
+  return loadFromVault()
+}
+
+// server function uses the server-only module
+export const getSession = serverFn(async () => readSecrets())
+```

packages/start-skills/skills/v1/execution-model.md

@@ -1,15 +1,14 @@
 ---
 id: file-structure
-title: Start File Structure
+title: File Structure
 versions:
   - latest
-  - ">=1 <2"
 summary: Organize Start entry points, routes, and shared modules.
 resources:
   - https://tanstack.com/start/latest/docs/overview
 ---
 
-# Start File Structure
+# File Structure
 
 Purpose:
 
@@ -23,4 +22,21 @@ Guidelines:
 
 - Keep entry files and route modules minimal and focused.
 - Separate shared utilities, server-only helpers, and client-only components.
+- Group runtime-only code (server functions, middleware, server routes) together.
 - Use `@skills/router/file-based-routing` if you lean on Router file routing.
+
+Examples:
+
+```
+app/
+  routes/
+    index.tsx
+    settings.tsx
+  entry-client.tsx
+  entry-server.tsx
+server/
+  routes/
+  middleware/
+shared/
+  formatting.ts
+```