docs(web-shared): document the @kilocode/web-shared specifier

Replace the @/ fallback and shadowing rule in packages/web-shared/AGENTS.md
and apps/ai-gateway/AGENTS.md, and point comments that name web-shared
modules at their new specifiers.

Author: chrarnoldus

apps/ai-gateway/AGENTS.md

@@ -11,8 +11,8 @@ Next.js app that serves the AI gateway API on its own. It is not deployed yet;
   move under `/api/v1` too; the latter becomes `/api/v1/systemone`.
 - Route files are thin facades over handlers in `packages/web-shared`. Keep the
   `apps/web` `maxDuration` and `withRestTiming` usage, with route patterns that
-  match this app's paths. See `packages/web-shared/AGENTS.md` for how `@/`
-  imports resolve.
+  match this app's paths. Import handlers as `@kilocode/web-shared/<path>`;
+  `@/` resolves only to this app's `src`. See `packages/web-shared/AGENTS.md`.
 - Handlers that depend on the path accept both apps' paths: the LLM proxy's path
   validation and the blocked-client check in `src/proxy.ts` for
   `/api/v1/fim/completions`.

apps/web/src/app/admin/components/OrganizationAdmin/OrganizationAdminServiceFeeExemption.dialog-state.ts

@@ -5,7 +5,7 @@
  */
 
 // Mirrors ORGANIZATION_SERVICE_FEE_EXEMPTION_REASON_* in
-// @/lib/service-fees/organization-exemptions, which is server-only and cannot
+// @kilocode/web-shared/lib/service-fees/organization-exemptions, which is server-only and cannot
 // be imported from a client component. The router remains the enforcement
 // boundary; these only drive client-side enablement and hints.
 export const SERVICE_FEE_EXEMPTION_REASON_MIN_LENGTH = 3;

apps/web/src/lib/auth/passkey.ts

@@ -37,7 +37,7 @@ import { db } from '@kilocode/web-shared/lib/drizzle';
  * can satisfy the associated-domain/credential binding the browser or platform
  * authenticator created against `app.kilo.ai`.
  *
- * Resolved per ceremony rather than at module load: `@/lib/user/server` imports
+ * Resolved per ceremony rather than at module load: `@kilocode/web-shared/lib/user/server` imports
  * this module for the sign-in provider, so importing it must not require a
  * WebAuthn configuration. A process without a relying party still loads the
  * route graph and only fails when a ceremony actually runs.

apps/web/src/lib/data-export/db.ts

@@ -9,7 +9,7 @@ import { z } from 'zod';
  * Client for the data export database: a separate, read-only Postgres instance
  * loaded out of band to back the user data export feature.
  *
- * Three things make this deliberately different from `@/lib/drizzle`:
+ * Three things make this deliberately different from `@kilocode/web-shared/lib/drizzle`:
  *
  * 1. It is lazy. The primary pool is created at import time because the app
  *    cannot serve a single request without it. This database is optional, so

apps/web/src/lib/kiloclaw/kilo-chat-internal-client.ts

@@ -52,7 +52,7 @@ function getKiloChatBaseUrl(): string {
   // environment that has not provisioned the new var yet keeps working rather
   // than repeating a wrong-config outage; a follow-up removes the fallback once
   // KILO_CHAT_INTERNAL_URL is confirmed on every project. Read process.env
-  // directly rather than importing from `@/lib/constants`: those constants are
+  // directly rather than importing from `@kilocode/web-shared/lib/constants`: those constants are
   // marked required at import time, which crashes test setups if a var is
   // unset. This server-only client should fail loudly only when actually called.
   let raw = process.env.KILO_CHAT_INTERNAL_URL;

apps/web/src/routers/active-sessions-router.test.ts

@@ -23,12 +23,12 @@ import type { createCallerForUser as CreateCallerForUser } from '@/routers/test-
 // `.env.test` sets SESSION_INGEST_WORKER_URL to '' (shared fixture used by
 // other test files too — do not change it here). `createCallerForUser`'s
 // import chain (test-utils -> trpc/init -> ...) transitively loads
-// `@/lib/config.server`, whose `SESSION_INGEST_WORKER_URL` export is a plain
+// `@kilocode/web-shared/lib/config.server`, whose `SESSION_INGEST_WORKER_URL` export is a plain
 // `const` computed once, the first time that module is evaluated. Static
 // ES `import` statements are always hoisted above every other statement by
 // the transform, so a statically-imported `createCallerForUser` would pull
 // in the real ('') value before any `process.env` assignment written below
-// it could run — and a `jest.mock('@/lib/config.server', ...)` registered
+// it could run — and a `jest.mock('@kilocode/web-shared/lib/config.server', ...)` registered
 // after that first (real) load cannot retroactively change the value
 // active-sessions-router.ts already captured. A dynamic `import()` executes
 // exactly where it is awaited (not hoisted), so resolving it in `beforeAll`

apps/web/src/routers/github-pr-review-router.test.ts

@@ -14,7 +14,7 @@ jest.mock('@/lib/integrations/platforms/github/user-token-client', () => ({
 
 // P1-A-08c: the PR operation ledger. The router admits / settles /
 // marks-reconcile-pending through `@kilocode/db/operation-ledger`. Both it and
-// `@/lib/drizzle` are mocked so the ledger tests can assert admission, settle,
+// `@kilocode/web-shared/lib/drizzle` are mocked so the ledger tests can assert admission, settle,
 // replay, and reconcile orchestration without a database. The analytics
 // identity comes from `ctx.user`, which carries no email here, so it falls
 // back to the user id.

apps/web/src/routers/user-exports-router.test.ts

@@ -19,7 +19,7 @@ import { __test__, userExportsRouter } from '@/routers/user-exports-router';
 import { createTestOrganization } from '@/tests/helpers/organization.helper';
 import { insertTestUser } from '@/tests/helpers/user.helper';
 
-// Partial mocks: `@/lib/email` also exports the template registry that sibling
+// Partial mocks: `@kilocode/web-shared/lib/email` also exports the template registry that sibling
 // routers read at import time, so the real module must stay intact.
 jest.mock('@kilocode/web-shared/lib/email', () => {
   const actual: Record<string, unknown> = jest.requireActual('@kilocode/web-shared/lib/email');

apps/web/src/tests/helpers/fake-r2.helper.ts

@@ -32,9 +32,9 @@ export function createFakeR2Client() {
 export type FakeR2Client = ReturnType<typeof createFakeR2Client>;
 
 /**
- * Replacement for `@/lib/r2/client` whose `createR2Client` always returns the
+ * Replacement for `@kilocode/web-shared/lib/r2/client` whose `createR2Client` always returns the
  * same fake and records the credentials it was created with. Retrieve the fake
- * with `jest.requireMock<FakeR2ClientModule>('@/lib/r2/client').fakeR2`.
+ * with `jest.requireMock<FakeR2ClientModule>('@kilocode/web-shared/lib/r2/client').fakeR2`.
  */
 export function createFakeR2ClientModule() {
   const fakeR2 = createFakeR2Client();

packages/web-shared/AGENTS.md

@@ -1,20 +1,20 @@
 # web-shared
 
-Server code shared by `apps/web` and `apps/ai-gateway`. The code was moved out of
-`apps/web/src` without changing its `@/` import specifiers.
+Server code shared by `apps/web` and `apps/ai-gateway`, consumed from source.
 
 ## Module resolution
 
-- Consumers map `@/*` to their own `src/*` first and to `packages/web-shared/src/*`
-  second. Keep both entries in sync in every tsconfig, the web Jest config, the
-  `@kilocode/trpc` rollup resolver, and the Storybook webpack alias.
-- A path must exist in only one of `apps/web/src` and `packages/web-shared/src`.
-  A duplicate silently shadows the web-shared file inside `apps/web`.
+- Import modules from this package as `@kilocode/web-shared/<path>`, which maps
+  to `src/<path>`, both from consumers and inside this package. Every consumer
+  tsconfig, the web Jest config, the `@kilocode/trpc` rollup resolver, and the
+  Storybook webpack alias map that specifier. There is no `exports` map:
+  specifiers are extensionless, so resolution relies on those mappings.
+- `@/` in a consumer means that consumer's own `src`; it never resolves here.
 - Runtime code here must only import from this package. `pnpm --filter
   @kilocode/web-shared typecheck` enforces that with `tsconfig.lib.json`, which
-  resolves `@/*` to this package only and excludes tests.
-- Tests run under the `apps/web` Jest config and may import `apps/web` test
-  helpers; `tsconfig.json` falls back to `apps/web/src` for editors and linting.
+  excludes tests and does not map `@/` at all.
+- Tests run under the `apps/web` Jest config and may import `apps/web` modules
+  and test helpers through `@/`, which `tsconfig.json` maps to `apps/web/src`.
 - Declare every npm import in `package.json` with the same version as
   `apps/web`, including the optional peers that make pnpm resolve the same
   `next` and `@sentry/nextjs` instances as `apps/web`. Two instances of `next`