add documentation for ai agents (#3115)

* add documentation for ai agents

* docs: consolidate CLAUDE.md and CONTRIBUTING.md, add style guidelines

- Refactor CLAUDE.md to reference CONTRIBUTING.md for build/test/format info
- Expand CONTRIBUTING.md with comprehensive build targets, env vars, and testing
- Add code style guidelines section with conventional commits
- Standardize SDK prettier config to use single quotes (matching web)
- Add project-level Claude Code settings to disable co-author attribution

* style(sdk): apply prettier with single quotes

Run prettier across sdk/base and sdk/package to apply the
standardized quote style (single quotes matching web).

* docs: add USER.md for per-developer TODO filtering

- Add agents/USER.md to .gitignore (contains user identifier)
- Document session startup flow in CLAUDE.md:
  - Create USER.md if missing, prompting for identifier
  - Filter TODOs by @username tags
  - Offer relevant TODOs on session start

* docs: add i18n documentation task to agent TODOs

* docs: document i18n ID patterns in core/

Add agents/i18n-patterns.md covering rust-i18n setup, translation file
format, t!() macro usage, key naming conventions, and locale selection.
Remove completed TODO item and add reference in CLAUDE.md.

* chore: clarify that all builds work on any OS with Docker

sdk/base/lib/dependencies/dependencies.ts

@@ -1,11 +1,11 @@
-import { ExtendedVersion, VersionRange } from "../exver"
+import { ExtendedVersion, VersionRange } from '../exver'
 import {
   PackageId,
   HealthCheckId,
   DependencyRequirement,
   CheckDependenciesResult,
-} from "../types"
-import { Effects } from "../Effects"
+} from '../types'
+import { Effects } from '../Effects'
 
 export type CheckDependencies<DependencyId extends PackageId = PackageId> = {
   infoFor: (packageId: DependencyId) => {
@@ -73,11 +73,11 @@ export async function checkDependencies<
   }
   const runningSatisfied = (packageId: DependencyId) => {
     const dep = infoFor(packageId)
-    return dep.requirement.kind !== "running" || dep.result.isRunning
+    return dep.requirement.kind !== 'running' || dep.result.isRunning
   }
   const tasksSatisfied = (packageId: DependencyId) =>
     Object.entries(infoFor(packageId).result.tasks).filter(
-      ([_, t]) => t?.active && t.task.severity === "critical",
+      ([_, t]) => t?.active && t.task.severity === 'critical',
     ).length === 0
   const healthCheckSatisfied = (
     packageId: DependencyId,
@@ -86,17 +86,17 @@ export async function checkDependencies<
     const dep = infoFor(packageId)
     if (
       healthCheckId &&
-      (dep.requirement.kind !== "running" ||
+      (dep.requirement.kind !== 'running' ||
         !dep.requirement.healthChecks.includes(healthCheckId))
     ) {
       throw new Error(`Unknown HealthCheckId ${healthCheckId}`)
     }
     const errors =
-      dep.requirement.kind === "running"
+      dep.requirement.kind === 'running'
         ? dep.requirement.healthChecks
             .map((id) => [id, dep.result.healthChecks[id] ?? null] as const)
             .filter(([id, _]) => (healthCheckId ? id === healthCheckId : true))
-            .filter(([_, res]) => res?.result !== "success")
+            .filter(([_, res]) => res?.result !== 'success')
         : []
     return errors.length === 0
   }
@@ -138,7 +138,7 @@ export async function checkDependencies<
   }
   const throwIfRunningNotSatisfied = (packageId: DependencyId) => {
     const dep = infoFor(packageId)
-    if (dep.requirement.kind === "running" && !dep.result.isRunning) {
+    if (dep.requirement.kind === 'running' && !dep.result.isRunning) {
       throw new Error(`${dep.result.title || packageId} is not running`)
     }
     return null
@@ -146,11 +146,11 @@ export async function checkDependencies<
   const throwIfTasksNotSatisfied = (packageId: DependencyId) => {
     const dep = infoFor(packageId)
     const reqs = Object.entries(dep.result.tasks)
-      .filter(([_, t]) => t?.active && t.task.severity === "critical")
+      .filter(([_, t]) => t?.active && t.task.severity === 'critical')
       .map(([id, _]) => id)
     if (reqs.length) {
       throw new Error(
-        `The following action requests have not been fulfilled: ${reqs.join(", ")}`,
+        `The following action requests have not been fulfilled: ${reqs.join(', ')}`,
       )
     }
     return null
@@ -162,27 +162,27 @@ export async function checkDependencies<
     const dep = infoFor(packageId)
     if (
       healthCheckId &&
-      (dep.requirement.kind !== "running" ||
+      (dep.requirement.kind !== 'running' ||
         !dep.requirement.healthChecks.includes(healthCheckId))
     ) {
       throw new Error(`Unknown HealthCheckId ${healthCheckId}`)
     }
     const errors =
-      dep.requirement.kind === "running"
+      dep.requirement.kind === 'running'
         ? dep.requirement.healthChecks
             .map((id) => [id, dep.result.healthChecks[id] ?? null] as const)
             .filter(([id, _]) => (healthCheckId ? id === healthCheckId : true))
-            .filter(([_, res]) => res?.result !== "success")
+            .filter(([_, res]) => res?.result !== 'success')
         : []
     if (errors.length) {
       throw new Error(
         errors
           .map(([id, e]) =>
             e
-              ? `Health Check ${e.name} of ${dep.result.title || packageId} failed with status ${e.result}${e.message ? `: ${e.message}` : ""}`
+              ? `Health Check ${e.name} of ${dep.result.title || packageId} failed with status ${e.result}${e.message ? `: ${e.message}` : ''}`
               : `Health Check ${id} of ${dep.result.title} does not exist`,
           )
-          .join("; "),
+          .join('; '),
       )
     }
     return null
@@ -209,7 +209,7 @@ export async function checkDependencies<
             return []
           })
           if (err.length) {
-            throw new Error(err.join("; "))
+            throw new Error(err.join('; '))
           }
           return null
         })()

sdk/base/lib/dependencies/setupDependencies.ts

@@ -1,27 +1,27 @@
-import * as T from "../types"
-import { once } from "../util"
+import * as T from '../types'
+import { once } from '../util'
 
 export type RequiredDependenciesOf<Manifest extends T.SDKManifest> = {
-  [K in keyof Manifest["dependencies"]]: Exclude<
-    Manifest["dependencies"][K],
+  [K in keyof Manifest['dependencies']]: Exclude<
+    Manifest['dependencies'][K],
     undefined
-  >["optional"] extends false
+  >['optional'] extends false
     ? K
     : never
-}[keyof Manifest["dependencies"]]
+}[keyof Manifest['dependencies']]
 export type OptionalDependenciesOf<Manifest extends T.SDKManifest> = Exclude<
-  keyof Manifest["dependencies"],
+  keyof Manifest['dependencies'],
   RequiredDependenciesOf<Manifest>
 >
 
 type DependencyRequirement =
   | {
-      kind: "running"
+      kind: 'running'
       healthChecks: Array<T.HealthCheckId>
       versionRange: string
     }
   | {
-      kind: "exists"
+      kind: 'exists'
       versionRange: string
     }
 type Matches<T, U> = T extends U ? (U extends T ? null : never) : never