@alneas/appkit-react 0.1.0 → 0.2.0

package/llms-full.txt

@@ -2,39 +2,109 @@
 
 # Appkit React
 
-React 19 forms, validation and record views connected to application-owned adapters.
+React 19 components, schema-driven forms and record views for business applications.
 
-## Why
+[npm](https://www.npmjs.com/package/@alneas/appkit-react) · [Documentation](https://tech-docs.alneas.com/appkit/appkit-react/) · [GitHub](https://github.com/dataarthub/appkit) · [Change history](https://github.com/dataarthub/appkit/blob/main/packages/appkit-react/CHANGELOG.md)
 
-Feature subpaths keep provider decisions visible while installation uses just two npm packages. Align schemas with validation and record operations; retain application control over data writes.
+## Elevator Pitch
 
-## Highlights
+Turn a JSON Schema into a form with validation and connect saves to your own backend. Combine forms with record tables, shared UI primitives and AI proposal review interfaces.
 
-- `@alneas/appkit-react/ui`: [Compose React UI and shared providers](docs/ui.md).
-- `@alneas/appkit-react/tools`: [Build schema forms and record tables](docs/tools.md).
-- `@alneas/appkit-react/ai`: [Review AI proposals in React](docs/ai.md).
+## Why & Value
+
+Use React when your application needs the presentation layer for Appkit's schema and record contracts. You provide the authenticated data adapter and server rules; the form uses that adapter and reports the save result to your UI.
+
+React depends on [Appkit Core](https://www.npmjs.com/package/@alneas/appkit-core). Install Core directly as well when your own code imports its types or functions, as the example below does. For backend-only validation, storage or graph calculations, use Core alone.
+
+## Key Highlights
+
+- **Schema forms and record tables:** build input, filtering and CRUD views around shared record contracts. [Tools guide](docs/tools.md)
+- **React UI primitives:** compose buttons, dialogs, shared providers and hooks. [UI guide](docs/ui.md)
+- **AI interfaces:** connect chat and proposal review to explicit application approval and execution boundaries. [AI guide](docs/ai.md)
+- **Explicit integration:** import styles and supply host providers and data adapters. [Complete form recipe](docs/request-form.md)
 
 ## Quickstart
 
-Use an existing React 19 application with React DOM 19.
+### Requirements and installation
+
+Use an existing React application. The package declares Node.js **24 or later** and requires React and React DOM **`^19.2.3`**. It provides ESM, CommonJS and TypeScript declarations.
 
 ```bash
-bun add @alneas/appkit-react
+npm install @alneas/appkit-react @alneas/appkit-core react@^19.2.3 react-dom@^19.2.3 @tanstack/react-query@5.104.4
+# Or use bun add with the same package names and versions.
 ```
 
+The example directly imports TanStack Query, so it is listed explicitly. Import Appkit CSS once at your application's stylesheet entry point. `FormView` also requires `QueryClientProvider` and `DataAccessProvider`; a standalone `Button` does not require those data providers. Install optional chart, barcode, QR or AI peers only for their corresponding features; see [the export reference](docs/exports.md).
+
+### Render and save a request form
+
+This component accepts your application's `DataAccessAdapter`. Implement that adapter for your backend and pass it as the `adapter` prop; no demo backend or credentials are included.
+
 ```tsx
-import {Button} from '@alneas/appkit-react/ui';
+import { useState, type ComponentProps } from 'react';
+import type { DataAccessAdapter } from '@alneas/appkit-core/data';
+import { QueryClientProvider } from '@tanstack/react-query';
+import {
+  createQueryClient,
+  DataAccessProvider,
+} from '@alneas/appkit-react/tools/data-access/react';
+import { FormView } from '@alneas/appkit-react/tools/form';
 import '@alneas/appkit-react/styles';
-export function SaveButton() {return <Button>Save</Button>;}
+
+const schema: ComponentProps<typeof FormView>['schema'] = {
+  type: 'object',
+  properties: {
+    name: { type: 'string', title: 'Name', minLength: 2 },
+    reason: { type: 'string', title: 'Reason', 'x-ui': { widget: 'textarea' } },
+  },
+  required: ['name'],
+};
+
+export function RequestForm({ adapter }: { adapter: DataAccessAdapter }) {
+  const [client] = useState(createQueryClient);
+  const [saved, setSaved] = useState('');
+
+  return (
+    <QueryClientProvider client={client}>
+      <DataAccessProvider adapter={adapter}>
+        <FormView
+          testId="persistence"
+          collection="records"
+          mode="create"
+          schema={schema}
+          validation={{
+            emptyStrings: 'preserve',
+            locale: 'en',
+            cast: { numericMode: 'strict' },
+          }}
+          onSuccess={record => setSaved(JSON.stringify(record))}
+        />
+        <output aria-label="Persisted">{saved}</output>
+      </DataAccessProvider>
+    </QueryClientProvider>
+  );
+}
 ```
 
-## Next steps
+The form renders Name and Reason fields. A name shorter than two characters should fail validation. A successful save displays the record returned by your adapter. Your backend must enforce authorization, business rules and concurrency; browser validation is only the UI boundary. If your application already has a shared Query client, reuse its provider instead of adding another one. See the [complete recipe](docs/request-form.md) for failure and retry checks.
+
+## Next Steps
 
-[Public exports and optional peers](docs/exports.md) · [Contributing](../../CONTRIBUTING.md) · [Releasing](../../RELEASING.md)
+- [Schema forms and record tables](docs/tools.md): the business UI entry points.
+- [UI primitives and providers](docs/ui.md): components and shared host setup.
+- [Public exports and optional peers](docs/exports.md): exact feature paths and additional dependencies.
+- [AI integration and security](docs/ai.md): proposal review and execution boundaries.
+- [Migration guide](docs/migration.md): moving from the earlier separate packages.
 
-[Complete request form](docs/request-form.md). FormView requires collection, QueryClientProvider and DataAccessProvider.
+### For coding agents
 
-Compiled CSS license texts are retained in `THIRD_PARTY_NOTICES.md`.
+Start with the [agent instructions](https://github.com/dataarthub/appkit/blob/main/packages/appkit-react/consumer-ai/SKILL.md), then use the [API catalog](https://github.com/dataarthub/appkit/blob/main/packages/appkit-react/consumer-ai/api-index.json) and [full documentation](https://github.com/dataarthub/appkit/blob/main/packages/appkit-react/llms-full.txt). Installed packages include these files under `consumer-ai/` and `llms-full.txt`; their locations are also listed in the `appkit.agent` manifest field.
+
+### Contributing and license
+
+[Contributing](https://github.com/dataarthub/appkit/blob/main/CONTRIBUTING.md) · [Releasing](https://github.com/dataarthub/appkit/blob/main/RELEASING.md) · [MIT license](https://github.com/dataarthub/appkit/blob/main/packages/appkit-react/LICENSE)
+
+Third-party license texts retained from the compiled CSS are included in [THIRD_PARTY_NOTICES.md](https://github.com/dataarthub/appkit/blob/main/packages/appkit-react/THIRD_PARTY_NOTICES.md), also shipped in the package root.
 
 
 ---
@@ -44,8 +114,11 @@ Compiled CSS license texts are retained in `THIRD_PARTY_NOTICES.md`.
 ---
 title: "Review AI proposals in React"
 description: "React proposal review and generative UI bindings"
+sidebar:
+  order: 2
 archetype: how-to
-project: tools
+project: appkit
+tags: ["appkit", "ai"]
 ---
 
 # Review AI proposals in React
@@ -79,6 +152,36 @@ Type-check this example in your application. See [the export reference](exports.
 
 React proposal review and generative UI bindings. The optional chat transport requires the ai SDK peer. Proposals do not authorize execution or stored-record changes.
 
+## Prompt injection and review permissions
+
+Transport text, tool-call arguments, retrieved files and tool outputs are untrusted. The optional `ai` peer is needed only by the SDK chat binding; a chat transport never approves or executes a tool. Keep provider secrets in a server-owned endpoint.
+
+Use the [Core validation and approval sequence](../../appkit-core/docs/ai.md) before presenting a proposal. Display the exact immutable target and arguments, require explicit approval for writes or sensitive disclosure, and invalidate approval when the call, session or registration changes. The server must independently enforce resource permissions, concurrency and durable idempotency at execution time. A React component, assistant message or SDK tool-output event is not authorization.
+
+Render registered components only, keep React text rendering escaped, and project minimal validated outputs. Do not evaluate generated code or embed arbitrary model HTML. Cancellation cannot roll back completed writes; reconcile uncertain effects before retrying. See [Core error recovery](../../appkit-core/docs/ai-errors.md).
+
+## Application review controls
+
+These host-owned controls consume the application's pending snapshot. Supply the Core example's controller or equivalent server-backed application flow. `onSettled` refreshes application state. No provider, database or theme provider is required just to render these controls; the larger application retains its documented providers and explicit styles.
+
+```tsx
+import {useState} from 'react';
+/** Host-owned review controls; rendering or receiving a tool event never grants permission. */
+export function RenameToolReview({example,pending,onSettled}:{
+ example:{approve:(id:string)=>Promise<unknown>;reject:(id:string)=>void};
+ pending:{approvalId:string;recordId:string;name:string}|null;onSettled:()=>void;
+}){
+ const [busy,setBusy]=useState(false),[failure,setFailure]=useState(false);
+ if(!pending)return null;
+ return <section aria-label="Review proposed rename">
+  <p>Rename record {pending.recordId} to {pending.name}</p>
+  <button disabled={busy} onClick={async()=>{setBusy(true);setFailure(false);try{await example.approve(pending.approvalId);}catch{setFailure(true);}finally{setBusy(false);onSettled();}}}>Approve</button>
+  <button disabled={busy} onClick={()=>{example.reject(pending.approvalId);onSettled();}}>Reject</button>
+  {failure&&<p role="alert">Execution could not complete. Check the application outcome before retrying.</p>}
+ </section>;
+}
+```
+
 
 ---
 
@@ -87,8 +190,11 @@ React proposal review and generative UI bindings. The optional chat transport re
 ---
 title: "Public exports and optional peers"
 description: "Exact install package, public import subpaths and optional peer requirements."
+sidebar:
+  order: 10
 archetype: reference
-project: tools
+project: appkit
+tags: ["appkit", "exports"]
 ---
 
 # Public exports and optional peers
@@ -144,6 +250,7 @@ bun add @alneas/appkit-react
 | `@alneas/appkit-react/tools/styles` | CSS |
 | `@alneas/appkit-react/ai-instructions` | Metadata |
 | `@alneas/appkit-react/package-context.json` | Metadata |
+| `@alneas/appkit-react/api-index.json` | Metadata |
 
 ## Optional peers
 
@@ -168,45 +275,392 @@ Install an optional peer only when using its feature. Core entry loading does no
 ---
 title: "Appkit React"
 description: "Unified React 19 business UI toolkit: accessible primitives, schema-driven forms, data tables, and AI chat interfaces"
+sidebar:
+  order: 1
 archetype: explanation
-project: tools
+project: appkit
+tags: ["appkit", "overview"]
 ---
 
 # Appkit React
 
-React 19 forms, validation and record views connected to application-owned adapters.
+React 19 components, schema-driven forms and record views for business applications.
 
-## Why
+[npm](https://www.npmjs.com/package/@alneas/appkit-react) · [Documentation](https://tech-docs.alneas.com/appkit/appkit-react/) · [GitHub](https://github.com/dataarthub/appkit) · [Change history](https://github.com/dataarthub/appkit/blob/main/packages/appkit-react/CHANGELOG.md)
 
-Feature subpaths keep provider decisions visible while installation uses just two npm packages. Align schemas with validation and record operations; retain application control over data writes.
+## Elevator Pitch
 
-## Highlights
+Turn a JSON Schema into a form with validation and connect saves to your own backend. Combine forms with record tables, shared UI primitives and AI proposal review interfaces.
 
-- `@alneas/appkit-react/ui`: [Compose React UI and shared providers](ui.md).
-- `@alneas/appkit-react/tools`: [Build schema forms and record tables](tools.md).
-- `@alneas/appkit-react/ai`: [Review AI proposals in React](ai.md).
+## Why & Value
+
+Use React when your application needs the presentation layer for Appkit's schema and record contracts. You provide the authenticated data adapter and server rules; the form uses that adapter and reports the save result to your UI.
+
+React depends on [Appkit Core](https://www.npmjs.com/package/@alneas/appkit-core). Install Core directly as well when your own code imports its types or functions, as the example below does. For backend-only validation, storage or graph calculations, use Core alone.
+
+## Key Highlights
+
+- **Schema forms and record tables:** build input, filtering and CRUD views around shared record contracts. [Tools guide](tools.md)
+- **React UI primitives:** compose buttons, dialogs, shared providers and hooks. [UI guide](ui.md)
+- **AI interfaces:** connect chat and proposal review to explicit application approval and execution boundaries. [AI guide](ai.md)
+- **Explicit integration:** import styles and supply host providers and data adapters. [Complete form recipe](request-form.md)
 
 ## Quickstart
 
-Use an existing React 19 application with React DOM 19.
+### Requirements and installation
+
+Use an existing React application. The package declares Node.js **24 or later** and requires React and React DOM **`^19.2.3`**. It provides ESM, CommonJS and TypeScript declarations.
 
 ```bash
-bun add @alneas/appkit-react
+npm install @alneas/appkit-react @alneas/appkit-core react@^19.2.3 react-dom@^19.2.3 @tanstack/react-query@5.104.4
+# Or use bun add with the same package names and versions.
 ```
 
+The example directly imports TanStack Query, so it is listed explicitly. Import Appkit CSS once at your application's stylesheet entry point. `FormView` also requires `QueryClientProvider` and `DataAccessProvider`; a standalone `Button` does not require those data providers. Install optional chart, barcode, QR or AI peers only for their corresponding features; see [the export reference](exports.md).
+
+### Render and save a request form
+
+This component accepts your application's `DataAccessAdapter`. Implement that adapter for your backend and pass it as the `adapter` prop; no demo backend or credentials are included.
+
 ```tsx
-import {Button} from '@alneas/appkit-react/ui';
+import { useState, type ComponentProps } from 'react';
+import type { DataAccessAdapter } from '@alneas/appkit-core/data';
+import { QueryClientProvider } from '@tanstack/react-query';
+import {
+  createQueryClient,
+  DataAccessProvider,
+} from '@alneas/appkit-react/tools/data-access/react';
+import { FormView } from '@alneas/appkit-react/tools/form';
 import '@alneas/appkit-react/styles';
-export function SaveButton() {return <Button>Save</Button>;}
+
+const schema: ComponentProps<typeof FormView>['schema'] = {
+  type: 'object',
+  properties: {
+    name: { type: 'string', title: 'Name', minLength: 2 },
+    reason: { type: 'string', title: 'Reason', 'x-ui': { widget: 'textarea' } },
+  },
+  required: ['name'],
+};
+
+export function RequestForm({ adapter }: { adapter: DataAccessAdapter }) {
+  const [client] = useState(createQueryClient);
+  const [saved, setSaved] = useState('');
+
+  return (
+    <QueryClientProvider client={client}>
+      <DataAccessProvider adapter={adapter}>
+        <FormView
+          testId="persistence"
+          collection="records"
+          mode="create"
+          schema={schema}
+          validation={{
+            emptyStrings: 'preserve',
+            locale: 'en',
+            cast: { numericMode: 'strict' },
+          }}
+          onSuccess={record => setSaved(JSON.stringify(record))}
+        />
+        <output aria-label="Persisted">{saved}</output>
+      </DataAccessProvider>
+    </QueryClientProvider>
+  );
+}
 ```
 
-## Next steps
+The form renders Name and Reason fields. A name shorter than two characters should fail validation. A successful save displays the record returned by your adapter. Your backend must enforce authorization, business rules and concurrency; browser validation is only the UI boundary. If your application already has a shared Query client, reuse its provider instead of adding another one. See the [complete recipe](request-form.md) for failure and retry checks.
+
+## Next Steps
+
+- [Schema forms and record tables](tools.md): the business UI entry points.
+- [UI primitives and providers](ui.md): components and shared host setup.
+- [Public exports and optional peers](exports.md): exact feature paths and additional dependencies.
+- [AI integration and security](ai.md): proposal review and execution boundaries.
+- [Migration guide](migration.md): moving from the earlier separate packages.
+
+### For coding agents
+
+Start with the [agent instructions](https://github.com/dataarthub/appkit/blob/main/packages/appkit-react/consumer-ai/SKILL.md), then use the [API catalog](https://github.com/dataarthub/appkit/blob/main/packages/appkit-react/consumer-ai/api-index.json) and [full documentation](https://github.com/dataarthub/appkit/blob/main/packages/appkit-react/llms-full.txt). Installed packages include these files under `consumer-ai/` and `llms-full.txt`; their locations are also listed in the `appkit.agent` manifest field.
 
-[Public exports and optional peers](exports.md) · [Contributing](../../../CONTRIBUTING.md) · [Releasing](../../../RELEASING.md)
+### Contributing and license
 
-[Complete request form](request-form.md). FormView requires collection, QueryClientProvider and DataAccessProvider.
+[Contributing](https://github.com/dataarthub/appkit/blob/main/CONTRIBUTING.md) · [Releasing](https://github.com/dataarthub/appkit/blob/main/RELEASING.md) · [MIT license](https://github.com/dataarthub/appkit/blob/main/packages/appkit-react/LICENSE)
+
+Third-party license texts retained from the compiled CSS are included in [THIRD_PARTY_NOTICES.md](https://github.com/dataarthub/appkit/blob/main/packages/appkit-react/THIRD_PARTY_NOTICES.md), also shipped in the package root.
+
+
+---
+
+<!-- docs/migration.md -->
+
+---
+title: "Migrate from app-core and react-tools"
+description: "Choose between the restricted package rename and the public Appkit 0.1.0 subset, then update dependencies, imports, providers and behavior checks."
+sidebar:
+  order: 20
+archetype: how-to
+project: appkit
+tags: ["migration", "core", "react"]
+---
+
+# Migrate from app-core and react-tools
+
+## Prerequisites
+
+This guide starts with applications using `@dataarthub/app-core` and
+`@dataarthub/react-tools`. The public destination is `@alneas/appkit-core@0.1.0`
+and `@alneas/appkit-react@0.1.0`. A public version number is independent of the
+legacy private package versions; `0.1.0` is not an in-place downgrade.
+
+Use Node.js 24.0.0 or later. Public React requires React and React DOM matching
+`^19.2.3`. Keep the application's existing lockfile and a working revision before
+changing dependencies. Inventory feature imports and runtime behavior first.
+
+## Public import
+
+Install the two package names. Import framework-free APIs from
+`@alneas/appkit-core/data`, `/storage`, `/japan`, `/graph` or `/ai`, and React
+features from `@alneas/appkit-react/ui`, `/tools` or `/ai`. Full import targets
+appear in the tables below and the [Core export reference](../../appkit-core/docs/exports.md)
+and [React export reference](exports.md).
+
+## Step-by-Step Implementation
+
+### 1. Choose the migration route
+
+| Route | Destination | What to change |
+| --- | --- | --- |
+| Keep the restricted product and its extensions | `@dataarthub/appkit-core` and `@dataarthub/appkit-react` on GitHub Packages | Rename the package prefix; check each used subpath and named export against that private release. |
+| Adopt the independently usable public subset | `@alneas/appkit-core` and `@alneas/appkit-react` on npm | Move each API to its feature subpath, review behavior differences and replace any feature outside the public exports. |
+
+These are different distributions. Replacing `@dataarthub` with `@alneas` does
+not preserve the full legacy product. If an API is absent from the public export
+references, retain its restricted implementation or choose an application-owned
+replacement before removing the old dependency.
+
+For the restricted rename, the intended prefix changes are:
+
+| Old | New restricted package |
+| --- | --- |
+| `@dataarthub/app-core` | `@dataarthub/appkit-core` |
+| `@dataarthub/react-tools` | `@dataarthub/appkit-react` |
 
-Compiled CSS license texts are retained in `THIRD_PARTY_NOTICES.md`.
+For example, `/schema/core` remains a Core subpath and `/form` remains a React
+subpath on that route. Select versions actually available to your GitHub Packages
+account; a version in a source manifest does not establish that it is published.
+The public install commands and compatibility claims below apply to the public
+route only. This guide does not certify a private release or its consumers.
+
+### 2. Install the public packages and keep registry scopes separate
+
+For a React application using the form recipe:
+
+```bash
+bun add --exact @alneas/appkit-core@0.1.0 @alneas/appkit-react@0.1.0 react@19.2.3 react-dom@19.2.3 @tanstack/react-query@5.104.4
+```
+
+A server-only application needs only `@alneas/appkit-core@0.1.0` plus its selected
+adapter's dependencies. Install feature-specific peers from the export references;
+root installation does not configure a database, storage endpoint or AI provider.
+
+If both distributions remain in the application, retain scoped registry routing:
+
+```ini
+@alneas:registry=https://registry.npmjs.org
+@dataarthub:registry=https://npm.pkg.github.com
+```
+
+Keep GitHub Packages authentication in the application's existing secret-managed
+configuration. An entirely public consumer does not need GitHub Packages credentials.
+Do not change the default registry to GitHub Packages for the public packages.
+Do not replace registry dependencies with sibling source aliases or tarball overrides.
+
+### 3. Move React imports to feature subpaths
+
+The following are destination entry points to inspect, not a claim that every
+symbol in an old barrel is available at the new entry.
+
+| Legacy import | Public destination |
+| --- | --- |
+| `@dataarthub/react-tools/ui` | `@alneas/appkit-react/ui` |
+| `@dataarthub/react-tools/core` | `@alneas/appkit-react/tools/core` |
+| `@dataarthub/react-tools/form` | `@alneas/appkit-react/tools/form` |
+| `@dataarthub/react-tools/data-table` | `@alneas/appkit-react/tools/data-table` |
+| `@dataarthub/react-tools/data-access/react` | `@alneas/appkit-react/tools/data-access/react` |
+| `@dataarthub/react-tools/filter` | `@alneas/appkit-react/tools/filter` |
+| `@dataarthub/react-tools/pane` | `@alneas/appkit-react/tools/pane` |
+| `@dataarthub/react-tools/workflow` | `@alneas/appkit-react/tools/workflow` |
+| `@dataarthub/react-tools/calendar` | `@alneas/appkit-react/tools/calendar` |
+| `@dataarthub/react-tools/kanban` | `@alneas/appkit-react/tools/kanban` |
+| `@dataarthub/react-tools/gantt` | `@alneas/appkit-react/tools/gantt` |
+| `@dataarthub/react-tools/chart` | `@alneas/appkit-react/tools/chart` |
+| `@dataarthub/react-tools/barcode` | `@alneas/appkit-react/tools/barcode` |
+| `@dataarthub/react-tools/file-browser` | `@alneas/appkit-react/tools/file-browser` |
+| `@dataarthub/react-tools/error` | `@alneas/appkit-react/tools/error` |
+| `@dataarthub/react-tools/i18n` | `@alneas/appkit-react/tools/i18n` |
+| `@dataarthub/react-tools/proposal` | `@alneas/appkit-react/ai/proposal` |
+| `@dataarthub/react-tools/action` | `@alneas/appkit-react/ai/action` |
+| `@dataarthub/react-tools/generative-ui` | `@alneas/appkit-react/ai/generative-ui` |
+| `@dataarthub/react-tools/styles` | `@alneas/appkit-react/styles` |
+
+Apply the same `/tools/` destination pattern for the public `sidebar`, `header`,
+`splash`, `priority-queue` and `editable-table` entries. Private authentication
+composition is not replaced by the public `/tools/auth` helper entry.
+
+Before:
+
+```diff
+-import { FormView } from '@dataarthub/react-tools/form';
+-import '@dataarthub/react-tools/styles';
++import { FormView } from '@alneas/appkit-react/tools/form';
++import '@alneas/appkit-react/styles';
+```
+
+Import the public stylesheet once at the application boundary. There is no public
+`/dist/react-tools.css`, `/theme.css`, `/base.css` or `/globals.css` compatibility
+export. Review your own CSS overrides against the resulting UI; an import change
+does not prove visual equivalence.
+
+### 4. Separate framework-free Core imports from React bindings
+
+| Legacy Core import | Public destination / decision |
+| --- | --- |
+| `@dataarthub/app-core/schema` | `@alneas/appkit-core/data/schema` |
+| `@dataarthub/app-core/schema/core` | `@alneas/appkit-core/data/schema/core` |
+| `@dataarthub/app-core/schema/compiler` | `@alneas/appkit-core/data/schema/compiler` |
+| `@dataarthub/app-core/schema/server` | `@alneas/appkit-core/data/schema/server` (server only) |
+| `@dataarthub/app-core/data-access` | `@alneas/appkit-core/data` (common contracts/services) |
+| `@dataarthub/app-core/data-access/types` | `@alneas/appkit-core/data/types` |
+| `@dataarthub/app-core/data-access/sqlite` | `@alneas/appkit-core/data/sqlite` |
+| `@dataarthub/app-core/data-access/d1` | `@alneas/appkit-core/data/d1` |
+| `@dataarthub/app-core/storage` | `@alneas/appkit-core/storage`; review adapter configuration |
+| `@dataarthub/app-core/storage/local-adapter` | `@alneas/appkit-core/storage/server`; review constructor options |
+| `@dataarthub/app-core/storage/types` | Type imports from `@alneas/appkit-core/storage` |
+| `@dataarthub/app-core/proposal` | `@alneas/appkit-core/ai/proposal` |
+| `@dataarthub/app-core/action` | `@alneas/appkit-core/ai/action` |
+| `@dataarthub/app-core/generative-ui` | `@alneas/appkit-core/ai/generative-ui` |
+| `@dataarthub/app-core/ai` | `@alneas/appkit-core/ai/ai-chat` for conversation/chat APIs; check each symbol |
+| `@dataarthub/app-core/agent-output` | `@alneas/appkit-core/ai/agent-output` |
+| `@dataarthub/app-core/encoding` | `@alneas/appkit-core/data/encoding` |
+| `@dataarthub/app-core/content` | `@alneas/appkit-core/data/content`; Git Markdown uses `@alneas/appkit-core/data/content/git-markdown` |
+| `@dataarthub/app-core/editor` | `@alneas/appkit-core/data/editor` (JSON/upload helpers, not editor UI) |
+| `@dataarthub/app-core/excel` | Generic adapters: `@alneas/appkit-core/data/excel`; Japanese templates: `@alneas/appkit-core/japan/excel` |
+| `@dataarthub/app-core/csv` | Choose generic `@alneas/appkit-core/data/csv` or Japanese defaults in `@alneas/appkit-core/japan/csv` |
+| `@dataarthub/app-core/finance` | Generic calculations: `@alneas/appkit-core/data/finance`; Japanese invoice rules: `@alneas/appkit-core/japan/finance` |
+| `@dataarthub/app-core/edi` | Generic contracts: `@alneas/appkit-core/data/edi`; Japanese document conversion: `@alneas/appkit-core/japan/edi` |
+| `@dataarthub/app-core/pdf` | Generic data: `@alneas/appkit-core/data/pdf`; Japanese presets: `@alneas/appkit-core/japan/pdf`; neither replaces React PDF rendering |
+| `@dataarthub/app-core/legal-document` | `@alneas/appkit-core/japan/legal-document` |
+| `@dataarthub/app-core/notifications` | Choose `@alneas/appkit-core/data/notifications` or `@alneas/appkit-core/japan/notifications` |
+| `@dataarthub/app-core/google-calendar` | `@alneas/appkit-core/data/google-calendar` |
+
+Framework-free imports formerly reached through `@dataarthub/react-tools` should
+also move to Core, not to an assumed matching React export. Provider-specific
+record adapters have explicit entries such as `@alneas/appkit-core/data/supabase`
+and `@alneas/appkit-core/data/neon`; install their peers separately. Keep backend
+SDKs, filesystem access and credentials out of browser entry modules.
+
+The public Core root exports namespaces (`data`, `storage`, `japan`, `graph`, `ai`,
+`us`). It does not reproduce the old flat Core barrel. Prefer named feature imports:
+
+```typescript
+import { createAjvValidator } from '@alneas/appkit-core/data/schema/core';
+import { CSVGenerator } from '@alneas/appkit-core/japan/csv';
+import type { DataAccessAdapter } from '@alneas/appkit-core/data/types';
+
+export const validate = createAjvValidator({ locale: 'ja' });
+export const csv = new CSVGenerator();
+export function loadRecords(adapter: DataAccessAdapter) {
+  return adapter.find('records', {});
+}
+```
+
+### 5. Reconnect providers and review behavior
+
+Use the [complete request-form recipe](request-form.md) for a working form with
+`QueryClientProvider`, `DataAccessProvider`, a stable query client, `collection`,
+`schema`, `mode` and the explicit validation policy. `onSave` does not remove these
+provider requirements. A private `AppProvider` is not exported by public Appkit;
+compose the needed public providers in the host application instead.
+
+Import related hooks and providers from the same distribution, keep one compatible
+React runtime and query context, and declare dependencies you import directly.
+An application can pass its own compatible adapter to public UI without moving
+its database or replacing its backend implementation.
+
+Review these contracts before switching traffic:
+
+- **Validation:** explicitly choose locale, empty-string handling, numeric casting
+  and JSON Schema draft. Verify invalid input and omitted/default values, rather
+  than assuming legacy localized defaults survive a generic import.
+- **Regional formatting:** generic helpers and Japanese presets have different
+  responsibilities. Preserve CSV date formatting, invoice rounding, tax and
+  document output with representative fixtures when changing the chosen entry.
+- **Storage:** check constructor options, object keys, URL generation and failure
+  behavior against your configured adapter. The public storage layer uses
+  Web-standard signing/runtime APIs; do not assume an old SDK client constructor
+  or compliance wrapper is interchangeable.
+- **Persistence:** changing imports does not move records, run migrations or change
+  authorization. Keep connection configuration and existing data in place; verify
+  read/create/update/delete and failure handling against your application's adapter.
+- **AI:** use Core for proposal validation/contracts and React for review UI.
+  Structured API checks and this migration example do not establish that an AI
+  coding agent can migrate an arbitrary application correctly.
+
+### 6. Remove legacy dependencies after the cutover
+
+For an application that has migrated every legacy import to the public subset:
+
+```bash
+bun remove @dataarthub/react-tools @dataarthub/app-core
+```
+
+Keep restricted dependencies still used by private features. Update TypeScript,
+bundler and test aliases, mocks, CSS imports and AI instruction references along
+with application imports. Remove obsolete source/tarball overrides and regenerate
+the application's own lockfile with its package manager.
+
+Public AI entry points are `@alneas/appkit-core/ai-instructions` and
+`@alneas/appkit-react/ai-instructions`, with machine context at each package's
+`/package-context.json`. The legacy `dist/ai/setup.mjs` is not a public setup CLI.
+The private `compliance/prepare.mjs` is also not shipped by the public packages.
+Review the public packages' `LICENSE` files and React's `THIRD_PARTY_NOTICES.md`;
+keep notices for any retained private or application dependencies in scope.
+
+## Verification
+
+In the consuming application:
+
+1. Search source, tests and configuration for `@dataarthub/app-core` and
+   `@dataarthub/react-tools`. Each remaining use must be intentional.
+2. Run the application's TypeScript check with its normal module resolution.
+   Confirm each moved symbol exists, not just the destination subpath.
+3. Run the production build and open the migrated screens. Verify providers,
+   styles, validation, locale and optional integration loading.
+4. Exercise only the changed feature boundaries: real form persistence, adapter
+   failures and relevant document/CSV output. Reuse unchanged integration evidence
+   where its inputs still match; avoid production-data writes as a migration probe.
+5. Review the dependency tree for legacy leftovers or duplicate React/query
+   contexts, then keep the migration diff and application checks together.
+
+Expected result: the application resolves the selected published packages without
+source aliases, type-checks, and retains its tested behavior through explicit
+adapters/providers. Appkit's `0.1.0` release checks covered isolated public package
+consumers, declarations and the request-form recipe; they do not certify your
+application, private extensions or every hosted provider. This guide's import
+example is checked separately; no complete legacy application migration is claimed.
+
+## Troubleshooting / Common Pitfalls
+
+| Symptom | What to check |
+| --- | --- |
+| Package installation returns 401/404 | Public packages use npm; retained restricted packages need the correct GitHub scope and credentials. |
+| `Package subpath is not defined by exports` | Use the complete new feature path; there is no blanket compatibility alias for old subpaths or `dist/*`. |
+| A named export disappeared | Root barrels differ. Locate the actual symbol in the export reference; some features remain restricted. |
+| Missing query/data-access context | Use the paired public providers in the complete form recipe and check for duplicate dependency instances. |
+| UI renders without styling | Import `@alneas/appkit-react/styles` at the application boundary. |
+| Dates, validation or documents changed | Choose explicit locale/validation settings and the appropriate generic or Japanese preset entry. |
+| A browser build pulls in backend code | Move filesystem/SDK/credential imports to server modules and use explicit feature entries. |
+| A legacy provider/editor/PDF component has no public equivalent | Retain the restricted distribution or replace that feature explicitly; a namespace rename is insufficient. |
 
 
 ---
@@ -216,8 +670,11 @@ Compiled CSS license texts are retained in `THIRD_PARTY_NOTICES.md`.
 ---
 title: "Save a schema-driven request form"
 description: "Wire a schema to an application-owned adapter with retained input on failure."
+sidebar:
+  order: 3
 archetype: how-to
-project: tools
+project: appkit
+tags: ["appkit", "request-form"]
 ---
 
 # Save a schema-driven request form
@@ -279,8 +736,11 @@ Keep QueryClientProvider and DataAccessProvider, including when using onSave. Au
 ---
 title: "Build schema forms and record tables"
 description: "Schema-driven forms, tables, filters and CRUD views"
+sidebar:
+  order: 4
 archetype: how-to
-project: tools
+project: appkit
+tags: ["appkit", "tools"]
 ---
 
 # Build schema forms and record tables
@@ -325,8 +785,11 @@ See [save a schema-driven request form](request-form.md) for the complete provid
 ---
 title: "Compose React UI and shared providers"
 description: "React 19 primitives, theme providers and hooks"
+sidebar:
+  order: 5
 archetype: how-to
-project: tools
+project: appkit
+tags: ["appkit", "ui"]
 ---
 
 # Compose React UI and shared providers

package/llms.txt

@@ -2,10 +2,14 @@
 
 Install @alneas/appkit-react; import its explicit feature subpaths.
 
+- [Agent instructions](consumer-ai/SKILL.md)
+- [API catalog](consumer-ai/api-index.json)
+
 - [README.md](README.md)
 - [docs/ai.md](docs/ai.md)
 - [docs/exports.md](docs/exports.md)
 - [docs/index.md](docs/index.md)
+- [docs/migration.md](docs/migration.md)
 - [docs/request-form.md](docs/request-form.md)
 - [docs/tools.md](docs/tools.md)
 - [docs/ui.md](docs/ui.md)