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/package/lib/version/VersionGraph.ts

@@ -1,5 +1,5 @@
-import { ExtendedVersion, VersionRange } from "../../../base/lib/exver"
-import * as T from "../../../base/lib/types"
+import { ExtendedVersion, VersionRange } from '../../../base/lib/exver'
+import * as T from '../../../base/lib/types'
 import {
   InitFn,
   InitKind,
@@ -8,9 +8,9 @@ import {
   UninitFn,
   UninitScript,
   UninitScriptOrFn,
-} from "../../../base/lib/inits"
-import { Graph, Vertex, once } from "../util"
-import { IMPOSSIBLE, VersionInfo } from "./VersionInfo"
+} from '../../../base/lib/inits'
+import { Graph, Vertex, once } from '../util'
+import { IMPOSSIBLE, VersionInfo } from './VersionInfo'
 
 export async function getDataVersion(effects: T.Effects) {
   const versionStr = await effects.getDataVersion()
@@ -30,11 +30,11 @@ export async function setDataVersion(
 }
 
 function isExver(v: ExtendedVersion | VersionRange): v is ExtendedVersion {
-  return "satisfies" in v
+  return 'satisfies' in v
 }
 
 function isRange(v: ExtendedVersion | VersionRange): v is VersionRange {
-  return "satisfiedBy" in v
+  return 'satisfiedBy' in v
 }
 
 export function overlaps(
@@ -64,7 +64,7 @@ export class VersionGraph<CurrentVersion extends string>
   private constructor(
     readonly current: VersionInfo<CurrentVersion>,
     versions: Array<VersionInfo<any>>,
-    private readonly preInstall?: InitScriptOrFn<"install">,
+    private readonly preInstall?: InitScriptOrFn<'install'>,
     private readonly uninstall?: UninitScript | UninitFn,
   ) {
     this.graph = once(() => {
@@ -86,7 +86,7 @@ export class VersionGraph<CurrentVersion extends string>
       for (let version of [current, ...versions]) {
         const v = ExtendedVersion.parse(version.options.version)
         const vertex = graph.addVertex(v, [], [])
-        const flavor = v.flavor || ""
+        const flavor = v.flavor || ''
         if (!flavorMap[flavor]) {
           flavorMap[flavor] = []
         }
@@ -109,11 +109,11 @@ export class VersionGraph<CurrentVersion extends string>
             let range
             if (prev) {
               graph.addEdge(version.options.migrations.up, prev[2], vertex)
-              range = VersionRange.anchor(">=", prev[0]).and(
-                VersionRange.anchor("<", v),
+              range = VersionRange.anchor('>=', prev[0]).and(
+                VersionRange.anchor('<', v),
               )
             } else {
-              range = VersionRange.anchor("<", v)
+              range = VersionRange.anchor('<', v)
             }
             const vRange = graph.addVertex(range, [], [])
             graph.addEdge(version.options.migrations.up, vRange, vertex)
@@ -123,11 +123,11 @@ export class VersionGraph<CurrentVersion extends string>
             let range
             if (prev) {
               graph.addEdge(version.options.migrations.down, vertex, prev[2])
-              range = VersionRange.anchor(">=", prev[0]).and(
-                VersionRange.anchor("<", v),
+              range = VersionRange.anchor('>=', prev[0]).and(
+                VersionRange.anchor('<', v),
               )
             } else {
-              range = VersionRange.anchor("<", v)
+              range = VersionRange.anchor('<', v)
             }
             const vRange = graph.addVertex(range, [], [])
             graph.addEdge(version.options.migrations.down, vertex, vRange)
@@ -173,7 +173,7 @@ export class VersionGraph<CurrentVersion extends string>
     /**
      * A script to run only on fresh install
      */
-    preInstall?: InitScriptOrFn<"install">
+    preInstall?: InitScriptOrFn<'install'>
     /**
      * A script to run only on uninstall
      */
@@ -211,8 +211,8 @@ export class VersionGraph<CurrentVersion extends string>
                   acc +
                   (prev && prev != x.from.metadata.toString()
                     ? ` (as ${prev})`
-                    : "") +
-                  " -> " +
+                    : '') +
+                  ' -> ' +
                   x.to.metadata.toString(),
                 prev: x.to.metadata.toString(),
               }),
@@ -246,7 +246,7 @@ export class VersionGraph<CurrentVersion extends string>
           acc.or(
             isRange(x.metadata)
               ? x.metadata
-              : VersionRange.anchor("=", x.metadata),
+              : VersionRange.anchor('=', x.metadata),
           ),
         VersionRange.none(),
       )
@@ -263,7 +263,7 @@ export class VersionGraph<CurrentVersion extends string>
           acc.or(
             isRange(x.metadata)
               ? x.metadata
-              : VersionRange.anchor("=", x.metadata),
+              : VersionRange.anchor('=', x.metadata),
           ),
         VersionRange.none(),
       )
@@ -279,9 +279,9 @@ export class VersionGraph<CurrentVersion extends string>
         to: this.currentVersion(),
       })
     } else {
-      kind = "install" // implied by !dataVersion
+      kind = 'install' // implied by !dataVersion
       if (this.preInstall)
-        if ("init" in this.preInstall) await this.preInstall.init(effects, kind)
+        if ('init' in this.preInstall) await this.preInstall.init(effects, kind)
         else await this.preInstall(effects, kind)
       await effects.setDataVersion({ version: this.current.options.version })
     }
@@ -302,7 +302,7 @@ export class VersionGraph<CurrentVersion extends string>
       }
     } else {
       if (this.uninstall)
-        if ("uninit" in this.uninstall)
+        if ('uninit' in this.uninstall)
           await this.uninstall.uninit(effects, target)
         else await this.uninstall(effects, target)
     }

sdk/package/lib/version/VersionInfo.ts

@@ -1,7 +1,7 @@
-import { ValidateExVer } from "../../../base/lib/exver"
-import * as T from "../../../base/lib/types"
+import { ValidateExVer } from '../../../base/lib/exver'
+import * as T from '../../../base/lib/types'
 
-export const IMPOSSIBLE: unique symbol = Symbol("IMPOSSIBLE")
+export const IMPOSSIBLE: unique symbol = Symbol('IMPOSSIBLE')
 
 export type VersionOptions<Version extends string> = {
   /** The exver-compliant version number */
@@ -60,30 +60,30 @@ export class VersionInfo<Version extends string> {
 }
 
 function __type_tests() {
-  const version: VersionInfo<"1.0.0:0"> = VersionInfo.of({
-    version: "1.0.0:0",
-    releaseNotes: "",
+  const version: VersionInfo<'1.0.0:0'> = VersionInfo.of({
+    version: '1.0.0:0',
+    releaseNotes: '',
     migrations: {},
   })
-    .satisfies("#other:1.0.0:0")
-    .satisfies("#other:2.0.0:0")
+    .satisfies('#other:1.0.0:0')
+    .satisfies('#other:2.0.0:0')
     // @ts-expect-error
-    .satisfies("#other:2.f.0:0")
+    .satisfies('#other:2.f.0:0')
 
-  let a: VersionInfo<"1.0.0:0"> = version
+  let a: VersionInfo<'1.0.0:0'> = version
   // @ts-expect-error
-  let b: VersionInfo<"1.0.0:3"> = version
+  let b: VersionInfo<'1.0.0:3'> = version
 
   VersionInfo.of({
     // @ts-expect-error
-    version: "test",
-    releaseNotes: "",
+    version: 'test',
+    releaseNotes: '',
     migrations: {},
   })
   VersionInfo.of({
     // @ts-expect-error
-    version: "test" as string,
-    releaseNotes: "",
+    version: 'test' as string,
+    releaseNotes: '',
     migrations: {},
   })
 }

sdk/package/lib/version/index.ts

@@ -1,2 +1,2 @@
-export * from "./VersionGraph"
-export * from "./VersionInfo"
+export * from './VersionGraph'
+export * from './VersionInfo'