[codex] extract authentication packages

.cursorrules

@@ -41,8 +41,11 @@ const { mutate } = useActorMutation({
 - **Callbacks**: `onCanisterError` (not calling it just `onError` when referring to canister logic errors).
 
 ## Documentation
-- Refer to `llms.txt` in the root directory for a comprehensive API overview and high-level concepts.
+- Refer to `llms.txt` in the root directory for compact package/task routing.
+- Refer to `llms-full.txt` for a longer API overview and task-oriented AI guide.
 - Refer to `/docs` for detailed guides and examples.
+- Refer to `skill-packages/ic-reactor-packages/SKILL.md` for package ownership, exports, generated artifacts, and verification workflows.
+- Refer to `skill-packages/ic-reactor-hooks/SKILL.md` for React hook, query/mutation factory, and cache invalidation patterns.
 
 ## Tech Stack
 - TypeScript

.github/copilot-instructions.md

@@ -8,6 +8,20 @@ Follow these repository-specific patterns when suggesting code:
 - Prefer small, explicit changes over large custom abstractions.
 - Keep TypeScript types accurate and inferable.
 - Do not hand-edit generated files unless the user explicitly asks.
+- For package ownership, exports, generated artifacts, or verification workflow questions, use `skill-packages/ic-reactor-packages/SKILL.md`.
+- For React hook/factory implementation questions, use `skill-packages/ic-reactor-hooks/SKILL.md`.
+
+## Package Ownership
+
+- `packages/core` owns framework-agnostic runtime behavior: `ClientManager`, `Reactor`, `DisplayReactor`, and query-cache integration.
+- `packages/react` owns React hooks, query/mutation factories, `defineReactor`, and `useActorMethod`.
+- `packages/auth` owns Internet Identity auth state, auth client loading, and identity attributes.
+- `packages/auth-react` owns React hooks over the auth managers.
+- `packages/candid` owns runtime Candid fetching/parsing adapters and dynamic reactors.
+- `packages/parser` owns the Rust/WASM Candid parser.
+- `packages/codegen` owns declaration, reactor, client, and hook generation.
+- `packages/cli` owns the `ic-reactor` executable and config schema.
+- `packages/vite-plugin` owns Vite integration, `.did` watching, and environment-cookie injection.
 
 ## React Hook Patterns (Important)
 
@@ -52,7 +66,19 @@ Follow these repository-specific patterns when suggesting code:
 
 - `packages/react/src/`
 - `packages/react/README.md`
+- `packages/auth/README.md`
+- `packages/auth-react/README.md`
 - `examples/all-in-one-demo/src/lib/factories.ts`
 - `examples/tanstack-router/src/canisters/ledger/hooks/`
 - `AGENTS.md`
+- `llms.txt`
+- `llms-full.txt`
 - `skill-packages/ic-reactor-hooks/SKILL.md`
+- `skill-packages/ic-reactor-packages/SKILL.md`
+
+## Verification
+
+- Package builds: `pnpm build`
+- Package tests: `pnpm test`
+- Root type check used by CI: `pnpm exec tsc --noEmit`
+- Example type checks: `pnpm typecheck:examples`

.github/workflows/ci.yml

@@ -47,17 +47,63 @@ jobs:
           targets: wasm32-unknown-unknown
 
       - name: Install dependencies
-        run: pnpm install --frozen-lockfile
+        run: pnpm install --frozen-lockfile --filter '!./examples/**'
 
       - name: Format check
         run: pnpm format:check
 
-      - name: Build packages (excluding parser)
+      - name: Build packages
         run: pnpm build
 
       - name: Type check
         run: pnpm exec tsc --noEmit
 
+  typecheck-examples:
+    name: Type Check Examples
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+
+      - name: Setup pnpm
+        run: |
+          corepack enable
+          corepack prepare pnpm@10.30.3 --activate
+          pnpm --version
+
+      - name: Get pnpm store path
+        id: pnpm-store
+        run: echo "path=$(pnpm store path)" >> "$GITHUB_OUTPUT"
+
+      - name: Cache pnpm store
+        uses: actions/cache@v5
+        with:
+          path: ${{ steps.pnpm-store.outputs.path }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: wasm32-unknown-unknown
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      # Examples import the @ic-reactor/* packages through the workspace symlinks,
+      # so they must be built before type-checking the examples.
+      - name: Build packages
+        run: pnpm build
+
+      - name: Type check examples
+        run: pnpm typecheck:examples
+
   test:
     name: Test
     runs-on: ubuntu-latest
@@ -94,7 +140,7 @@ jobs:
           targets: wasm32-unknown-unknown
 
       - name: Install dependencies
-        run: pnpm install --frozen-lockfile
+        run: pnpm install --frozen-lockfile --filter '!./examples/**'
 
       - name: Build packages (excluding parser)
         run: pnpm build
@@ -138,7 +184,7 @@ jobs:
           targets: wasm32-unknown-unknown
 
       - name: Install dependencies
-        run: pnpm install --frozen-lockfile
+        run: pnpm install --frozen-lockfile --filter '!./examples/**'
 
       - name: Cache Rust dependencies
         uses: actions/cache@v5

.github/workflows/release.yml

@@ -20,6 +20,8 @@ jobs:
         workspace:
           - packages/core
           - packages/react
+          - packages/auth
+          - packages/auth-react
           - packages/candid
     steps:
       - name: Checkout

.github/workflows/sync-examples.yml

@@ -0,0 +1,95 @@
+name: Sync Example Versions
+
+# After a successful Release (tag push that published the packages to npm), bump
+# the pinned @ic-reactor/* versions in every example so a standalone
+# StackBlitz/CodeSandbox install resolves the just-released version. Inside this
+# workspace the examples keep linking to the local packages/* regardless.
+on:
+  workflow_run:
+    workflows: ["Release"]
+    types: [completed]
+  # Allow manually re-syncing (e.g. after a hotfix) from the Actions tab.
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to sync examples to (defaults to root package.json version)"
+        required: false
+        type: string
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  sync:
+    name: Sync & open PR
+    runs-on: ubuntu-latest
+    # Only run when the triggering Release workflow succeeded (workflow_dispatch
+    # has no workflow_run payload, so the conclusion check passes through).
+    if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          # Check out main so the PR branches from the default branch rather than
+          # the tag that triggered the release.
+          ref: main
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+
+      - name: Setup pnpm
+        run: |
+          corepack enable
+          corepack prepare pnpm@10.30.3 --activate
+          pnpm --version
+
+      - name: Get pnpm store path
+        id: pnpm-store
+        run: echo "path=$(pnpm store path)" >> "$GITHUB_OUTPUT"
+
+      - name: Cache pnpm store
+        uses: actions/cache@v5
+        with:
+          path: ${{ steps.pnpm-store.outputs.path }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+
+      - name: Resolve target version
+        id: version
+        run: |
+          if [ -n "${{ inputs.version }}" ]; then
+            VERSION="${{ inputs.version }}"
+          else
+            VERSION="$(node -p "require('./package.json').version")"
+          fi
+          echo "value=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Syncing examples to $VERSION"
+
+      - name: Sync example versions
+        run: pnpm sync:examples "${{ steps.version.outputs.value }}"
+
+      - name: Install to refresh lockfile
+        run: pnpm install --lockfile-only
+
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v7
+        with:
+          commit-message: "chore(examples): sync @ic-reactor/* to v${{ steps.version.outputs.value }}"
+          branch: chore/sync-examples-v${{ steps.version.outputs.value }}
+          delete-branch: true
+          title: "chore(examples): sync @ic-reactor/* to v${{ steps.version.outputs.value }}"
+          body: |
+            Automated sync of the pinned `@ic-reactor/*` versions in `examples/*`
+            to **v${{ steps.version.outputs.value }}** after the latest release.
+
+            This keeps standalone StackBlitz/CodeSandbox installs (which resolve
+            from npm outside the workspace) on the just-published version. Inside
+            the workspace the examples still link to the local `packages/*`.
+          labels: |
+            examples
+            automated

AGENTS.md

@@ -7,6 +7,39 @@ A skill is a set of local instructions to follow that is stored in a `SKILL.md`
 ### Available skills
 
 - `ic-reactor-hooks`: Create, refactor, and document Reactor hook integrations for this repo, including `createActorHooks`, query/mutation factories, `useActorMethod`, and generated hooks. Use when implementing or explaining hook usage inside React components versus imperative usage outside React. (file: `skill-packages/ic-reactor-hooks/SKILL.md`)
+- `ic-reactor-packages`: Inspect, modify, review, or document the IC Reactor monorepo package architecture, package ownership, exports, tsconfig/project references, generated artifacts, dependency boundaries, and package verification workflows. Use when deciding which package owns a behavior or when work spans package metadata/build/test/release readiness. (file: `skill-packages/ic-reactor-packages/SKILL.md`)
+
+## Package map
+
+Use this map before editing so you can start in the package that owns the behavior:
+
+| Package                   | Owns                                                                                              | Look here first                                                                                   |
+| ------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `@ic-reactor/core`        | Framework-agnostic runtime: `ClientManager`, `Reactor`, `DisplayReactor`, query-cache integration | `packages/core/src/`, `packages/core/tests/`                                                      |
+| `@ic-reactor/react`       | React hook factories, reusable query/mutation objects, `defineReactor`, `useActorMethod`          | `packages/react/src/`, `packages/react/tests/`, `skill-packages/ic-reactor-hooks/SKILL.md`        |
+| `@ic-reactor/auth`        | Internet Identity auth state, auth client loading, identity attributes                            | `packages/auth/src/`, `packages/auth/tests/`                                                      |
+| `@ic-reactor/auth-react`  | React hooks over `@ic-reactor/auth` managers                                                      | `packages/auth-react/src/`, `packages/auth-react/tests/`                                          |
+| `@ic-reactor/candid`      | Runtime Candid fetching/parsing adapters and dynamic reactors                                     | `packages/candid/src/`, `packages/candid/METADATA_REACTOR_GUIDE.md`                               |
+| `@ic-reactor/parser`      | Rust/WASM Candid parser package                                                                   | `packages/parser/src/`, `packages/parser/tests/`                                                  |
+| `@ic-reactor/codegen`     | Shared declaration/reactor/client generation pipeline                                             | `packages/codegen/src/`, `packages/codegen/src/*.test.ts`                                         |
+| `@ic-reactor/cli`         | `ic-reactor` command-line interface and config schema                                             | `packages/cli/src/`, `packages/cli/schema.json`                                                   |
+| `@ic-reactor/vite-plugin` | Vite integration, `.did` watching, environment-cookie injection                                   | `packages/vite-plugin/src/`, `examples/vite-plugin-demo/`, `examples/vite-environment-variables/` |
+
+## Verification commands
+
+- Package builds: `pnpm build`
+- Package tests: `pnpm test`
+- Root type check used by CI: `pnpm exec tsc --noEmit`
+- Example type checks: `pnpm typecheck:examples`
+- Docs build: `pnpm docs:build`
+- Dependency audit: `corepack pnpm audit --audit-level moderate`
+
+Generated outputs under `dist`, `.dfx`, `.icp`, `.mops`, `target`, `.next`, `.astro`, and `*.tsbuildinfo` are normally build artifacts. Do not hand-edit generated hook files; change the generator, wrapper, or source `.did` instead.
+
+## AI context files
+
+- `llms.txt`: compact package/task routing manifest
+- `llms-full.txt`: longer AI-friendly API and task guide
 
 ### How to use skills
 
@@ -27,9 +60,9 @@ A skill is a set of local instructions to follow that is stored in a `SKILL.md`
 
 These skills are designed to work across multiple AI agent platforms. Each skill includes agent-specific metadata in `agents/`:
 
-| Agent Platform     | Metadata File         | Project Discovery File              |
-| ------------------ | --------------------- | ----------------------------------- |
-| OpenAI Codex       | `agents/openai.yaml`  | `AGENTS.md` (this file)             |
-| Claude / Anthropic | `agents/claude.yaml`  | `CLAUDE.md`                         |
-| GitHub Copilot     | `agents/copilot.yaml` | `.github/copilot-instructions.md`   |
-| Cursor             | —                     | `.cursorrules`                      |
+| Agent Platform     | Metadata File         | Project Discovery File            |
+| ------------------ | --------------------- | --------------------------------- |
+| OpenAI Codex       | `agents/openai.yaml`  | `AGENTS.md` (this file)           |
+| Claude / Anthropic | `agents/claude.yaml`  | `CLAUDE.md`                       |
+| GitHub Copilot     | `agents/copilot.yaml` | `.github/copilot-instructions.md` |
+| Cursor             | —                     | `.cursorrules`                    |

CLAUDE.md

@@ -10,17 +10,38 @@ This file provides context for Claude-based AI agents working in the IC Reactor
 
 - `@ic-reactor/core` — Low-level API for managing actors, agents, and query caching
 - `@ic-reactor/react` — High-level React hooks and context providers
+- `@ic-reactor/auth` — Internet Identity auth state and identity attributes
+- `@ic-reactor/auth-react` — React hooks for `@ic-reactor/auth`
 - `@ic-reactor/candid` — Dynamic Candid parsing and runtime reactors
+- `@ic-reactor/parser` — Rust/WASM Candid parser used by candid and codegen flows
+- `@ic-reactor/codegen` — Shared declaration/reactor/client generation pipeline
 - `@ic-reactor/cli` — Code generation for declarations + typed hooks/reactors
 - `@ic-reactor/vite-plugin` — Watch-mode code generation for Vite projects
 
+## Package Ownership Map
+
+Start in the package that owns the behavior:
+
+| Package                   | Primary files                                                                                     |
+| ------------------------- | ------------------------------------------------------------------------------------------------- |
+| `@ic-reactor/core`        | `packages/core/src/`, `packages/core/tests/`                                                      |
+| `@ic-reactor/react`       | `packages/react/src/`, `packages/react/tests/`, `skill-packages/ic-reactor-hooks/SKILL.md`        |
+| `@ic-reactor/auth`        | `packages/auth/src/`, `packages/auth/tests/`                                                      |
+| `@ic-reactor/auth-react`  | `packages/auth-react/src/`, `packages/auth-react/tests/`                                          |
+| `@ic-reactor/candid`      | `packages/candid/src/`, `packages/candid/METADATA_REACTOR_GUIDE.md`                               |
+| `@ic-reactor/parser`      | `packages/parser/src/`, `packages/parser/tests/`                                                  |
+| `@ic-reactor/codegen`     | `packages/codegen/src/`, `packages/codegen/src/*.test.ts`                                         |
+| `@ic-reactor/cli`         | `packages/cli/src/`, `packages/cli/schema.json`                                                   |
+| `@ic-reactor/vite-plugin` | `packages/vite-plugin/src/`, `examples/vite-plugin-demo/`, `examples/vite-environment-variables/` |
+
 ## Skills
 
 Skills are structured instruction sets stored in `skill-packages/`. When a task matches a skill's description, load the skill's `SKILL.md` and follow its workflow.
 
 ### Available Skills
 
 - **`ic-reactor-hooks`**: Create, refactor, and document Reactor hook integrations, including `createActorHooks`, query/mutation factories, `useActorMethod`, and generated hooks. Use when implementing or explaining hook usage inside React components versus imperative usage outside React. (file: `skill-packages/ic-reactor-hooks/SKILL.md`)
+- **`ic-reactor-packages`**: Inspect, modify, review, or document package ownership, exports, tsconfig/project references, generated artifacts, dependency boundaries, and verification workflows across the IC Reactor monorepo. Use when deciding which package owns behavior or when work spans package metadata/build/test/release readiness. (file: `skill-packages/ic-reactor-packages/SKILL.md`)
 
 ### How to Use Skills
 
@@ -72,13 +93,17 @@ Skills are structured instruction sets stored in `skill-packages/`. When a task
 pnpm install    # Install dependencies
 pnpm build      # Build all packages
 pnpm test       # Run all tests
+pnpm exec tsc --noEmit # Root type check used by CI
+pnpm typecheck:examples # Type-check example apps
 pnpm format     # Format code with Prettier
 ```
 
 ## Key File References
 
-- `llms.txt` — Comprehensive AI-friendly API guide
+- `llms.txt` — Compact AI routing manifest
+- `llms-full.txt` — Longer AI-friendly API and task guide
 - `skill-packages/ic-reactor-hooks/SKILL.md` — Hook patterns skill
+- `skill-packages/ic-reactor-packages/SKILL.md` — Package ownership and verification skill
 - `packages/react/src/` — React package source
 - `packages/react/README.md` — React package docs
 - `examples/all-in-one-demo/src/lib/factories.ts` — Factory pattern examples