akanjs 3.0.0-beta.2 → 3.0.0-beta.21

package/ui/recipe/factory.ts

@@ -2,30 +2,9 @@ import type { ClassNameValue as ClassValue } from "tailwind-merge";
 import { createTV } from "tailwind-variants";
 import { colorTokens, radiusTokens } from "../../client/cn";
 
-/**
- * recipe 팩토리 모듈 — 변형 팩토리를 만드는 **인프라**. **서버-안전** (절대 `"use client"` 금지).
- * 실제 recipe 정의는 이 폴더의 형제 파일 하나당 하나씩 둔다 — 프레임워크는 `./<name>Recipe.ts`,
- * 각 앱은 `apps/<app>/ui/Recipe/<name>.ts`.
- */
-
 export const tv = createTV({ twMergeConfig: { extend: { theme: { color: colorTokens, radius: radiusTokens } } } });
 
-/**
- * recipe 팩토리 — `tv({...})` 인스턴스를 받아 겉을 `(변형, className?)` 2-인자로 노출하고,
- * className 병합(cn)을 안으로 숨긴다. 타입은 넘겨받은 tv 인스턴스에서 그대로 추론되어 변형 타입이
- * 정확히 보존된다. 반환은 순수 className 문자열이라 서버-안전.
- *
- *   export const xRecipe = recipe(tv({ base, variants }));
- *   xRecipe({ variant: "primary" }, "w-full")            // cn 불필요
- *
- * 2번째 인자는 `ClassNameValue` — 문자열 하나만이 아니라 **배열·중첩 배열·falsy 값**을 그대로 받는다.
- * 여러 클래스를 합칠 때 `cn(...)` 으로 감쌀 이유가 없다(모르면 감싸게 되는데, cn 을 몰아내려고 만든
- * 2-인자 계약이 거기서 새어나간다):
- *
- *   xRecipe({}, ["h-full", className])                   // ✅ cn 불필요
- *   xRecipe({}, ["h-full", isWide && "w-full"])          // ✅ falsy 는 무시됨
- *   xRecipe({}, cn("h-full", className))                 // ❌ 불필요한 래핑
- */
+/** `className` takes arrays and falsy values and is merged inside, so never wrap it in `cn()`. */
 export const recipe =
   <P extends object>(styles: (props?: P) => string) =>
   (variants?: Omit<P, "class" | "className">, className?: ClassValue): string =>

package/ui/recipe/index.ts

@@ -1,17 +1,4 @@
-/**
- * recipe 레이어 — 프리미티브의 스타일 recipe(변형)를 모으는 **서버-안전** 폴더.
- * **여기엔 절대 `"use client"` 를 붙이지 않는다.** 팩토리(`recipe`/`tv`)는 `./factory` 에 있다.
- *
- * 구조: recipe 하나당 파일 하나(`<name>Recipe.ts`), 이 index 는 재수출만 한다. 앱도 같은 구조를
- * `apps/<app>/ui/Recipe/` 에서 계승한다.
- *
- * 호출 규격: `xRecipe(변형객체, 커스텀클래스?)`. 두 번째 인자 className 은 recipe 안에서 tailwind-merge 로
- * 자동 병합되므로 호출부에서 `cn(...)` 으로 감쌀 필요가 없다. 문자열 하나만이 아니라 배열도 받는다:
- *   buttonRecipe({ variant: "primary" }, "w-full rounded-2xl")   // ✅ cn 불필요
- *   buttonRecipe({ variant: "primary" }, ["h-full", className])  // ✅ 배열 — 여기서도 cn 불필요
- *
- * 레이어: styles.css(토큰) → recipe(변형) → 컴포넌트(동작).
- */
+
 export { type BadgeVariants, badgeRecipe } from "./badgeRecipe";
 export { type ButtonVariants, buttonRecipe } from "./buttonRecipe";
 export { recipe, tv } from "./factory";

package/ui/recipe/inputRecipe.ts

@@ -1,6 +1,6 @@
 import { recipe, tv } from "./factory";
 
-/** 입력 표면 look — Input/TextArea/Select 가 공유하는 필드 셸. kind 로 한 줄 필드(field)/멀티라인(area), tone 으로 강조/오류 상태를 고른다. */
+/** 입력 표면 look — Input/TextArea/DatePicker 가 공유하는 필드 셸. kind 로 한 줄 필드(field)/멀티라인(area), tone 으로 강조/오류 상태를 고른다. */
 export const inputRecipe = recipe(
   tv({
     base: "w-full rounded-field border border-input bg-background text-foreground focus:border-primary focus:outline-none",
@@ -13,7 +13,7 @@ export const inputRecipe = recipe(
         error: "border-destructive focus:border-destructive",
       },
     },
-
+    
     compoundVariants: [
       { kind: "field", size: "xs", class: "h-6" },
       { kind: "field", size: "sm", class: "h-8" },

package/ui/sliceNamesOf.ts

@@ -0,0 +1,26 @@
+import { capitalize } from "akanjs/common";
+import { sliceKeysOf } from "../store/sliceKeys";
+
+export const sliceNamesOf = (model: string, sliceName: string) => {
+  const Model = capitalize(model);
+  const { state, action } = sliceKeysOf(model);
+  const names = {
+    ...state,
+    ...action,
+    model,
+    modelId: `${model}Id`,
+    modelObjList: `${model}ObjList`,
+    modelObjInsight: `${model}ObjInsight`,
+    newModel: `new${Model}`,
+    editModel: `edit${Model}`,
+    viewModel: `view${Model}`,
+    removeModel: `remove${Model}`,
+    setViewOfModel: `setViewOf${Model}`,
+    exportCsvOfModel: `exportCsvOf${Model}`,
+    exportJsonOfModel: `exportJsonOf${Model}`,
+  };
+  const namesOfSlice = Object.fromEntries(
+    Object.entries(names).map(([key, name]) => [key, sliceName.replace(model, name)]),
+  ) as typeof names;
+  return { names, namesOfSlice };
+};

package/ui/styles.css

@@ -349,7 +349,7 @@ body.akan-mobile-document {
 /*
  * The in-page agent's `highlight` tool: a ring that draws the eye, holds, and fades, on the app's own primary
  * token. It holds through the middle because a person has to find it after the scroll — a symmetric fade reads as
- * a flicker. `StoreSurfaceSource.highlightMs` mirrors this duration.
+ * a flicker. `ScreenFlash.ringMs` mirrors this duration.
  */
 @keyframes akanAgentHighlight {
   0% {
@@ -373,6 +373,200 @@ body.akan-mobile-document {
   animation: akanAgentHighlight 2.4s ease-in-out;
 }
 
+/*
+ * The receipt beside a control the agent just drove, as opposed to one it was asked to point at: shorter, and a
+ * wash of the primary token behind the outline so it reads at a glance without the user hunting for the ring.
+ * `ScreenFlash.actingMs` mirrors this duration.
+ */
+@keyframes akanAgentActing {
+  0% {
+    outline-color: color-mix(in oklab, var(--color-primary) 0%, transparent);
+    background-color: color-mix(in oklab, var(--color-primary) 0%, transparent);
+  }
+  20% {
+    outline-color: var(--color-primary);
+    background-color: color-mix(in oklab, var(--color-primary) 14%, transparent);
+  }
+  100% {
+    outline-color: color-mix(in oklab, var(--color-primary) 0%, transparent);
+    background-color: color-mix(in oklab, var(--color-primary) 0%, transparent);
+  }
+}
+
+.akan-agent-acting {
+  outline: 2px solid var(--color-primary);
+  outline-offset: 2px;
+  border-radius: var(--radius-field, 0.25rem);
+  animation: akanAgentActing 1s ease-out;
+}
+
+/*
+ * The agent's pointer. Positioned by a transform on the element's own centre, so the two children draw relative to
+ * a point rather than a box — `i` is the arrow and `b` the tap ripple.
+ */
+.akan-agent-cursor {
+  position: fixed;
+  top: 0;
+  left: 0;
+  z-index: 2147483001;
+  pointer-events: none;
+  opacity: 0;
+  transition:
+    transform 320ms cubic-bezier(0.22, 0.61, 0.36, 1),
+    opacity 200ms ease-out;
+}
+
+.akan-agent-cursor-shown {
+  opacity: 1;
+}
+
+/* No travel for the first placement: the pointer has nowhere to have come from. */
+.akan-agent-cursor-placing {
+  transition: opacity 200ms ease-out;
+}
+
+/* The tip sits on the transform's own point, so the pointer lands on the control's centre rather than beside it. */
+.akan-agent-cursor > i {
+  position: absolute;
+  display: block;
+  width: 14px;
+  height: 20px;
+  background: var(--color-primary);
+  clip-path: polygon(0 0, 0 72%, 24% 55%, 40% 92%, 58% 84%, 42% 48%, 70% 46%);
+  filter: drop-shadow(0 1px 2px rgb(0 0 0 / 0.45));
+}
+
+.akan-agent-cursor > b {
+  position: absolute;
+  display: block;
+  width: 2rem;
+  height: 2rem;
+  margin: -1rem 0 0 -1rem;
+  border-radius: 9999px;
+  border: 2px solid var(--color-primary);
+  opacity: 0;
+}
+
+.akan-agent-cursor-tap > b {
+  animation: akanAgentTap 450ms ease-out;
+}
+
+/*
+ * Between two calls of one turn the model is writing, which takes longer than a pointer sitting still reads as.
+ * The arrow gives way to a spinner in place, so the pause is the agent thinking rather than the pointer stuck.
+ */
+.akan-agent-cursor-thinking > i {
+  opacity: 0;
+}
+
+.akan-agent-cursor-thinking > b {
+  width: 1.125rem;
+  height: 1.125rem;
+  margin: -0.5625rem 0 0 -0.5625rem;
+  opacity: 1;
+  border-color: color-mix(in oklab, var(--color-primary) 25%, transparent);
+  border-top-color: var(--color-primary);
+  animation: akanAgentThinking 700ms linear infinite;
+}
+
+@keyframes akanAgentThinking {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+/*
+ * The pointer holds still while a reveal scrolls the page under it, exactly as a person's does — so on its own the
+ * stillness reads as a pointer that came loose. The chevron is what says the scroll is the agent's, and it points
+ * the way the view is travelling.
+ */
+.akan-agent-cursor::after {
+  content: "";
+  position: absolute;
+  top: 22px;
+  left: 1px;
+  width: 9px;
+  height: 9px;
+  border-right: 2px solid var(--color-primary);
+  border-bottom: 2px solid var(--color-primary);
+  opacity: 0;
+  transform: rotate(45deg);
+}
+
+.akan-agent-cursor-scrolling::after {
+  animation: akanAgentScrollDown 800ms ease-in-out infinite;
+}
+
+.akan-agent-cursor-scrolling-up::after {
+  animation-name: akanAgentScrollUp;
+}
+
+.akan-agent-cursor-thinking::after {
+  animation: none;
+  opacity: 0;
+}
+
+@keyframes akanAgentScrollDown {
+  0% {
+    transform: rotate(45deg) translate(-4px, -4px);
+    opacity: 0;
+  }
+  45% {
+    opacity: 1;
+  }
+  100% {
+    transform: rotate(45deg) translate(4px, 4px);
+    opacity: 0;
+  }
+}
+
+@keyframes akanAgentScrollUp {
+  0% {
+    transform: rotate(225deg) translate(-4px, -4px);
+    opacity: 0;
+  }
+  45% {
+    opacity: 1;
+  }
+  100% {
+    transform: rotate(225deg) translate(4px, 4px);
+    opacity: 0;
+  }
+}
+
+@keyframes akanAgentTap {
+  0% {
+    transform: scale(0.2);
+    opacity: 0.9;
+  }
+  100% {
+    transform: scale(1);
+    opacity: 0;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .akan-agent-acting,
+  .akan-agent-highlight {
+    animation-duration: 0.01ms;
+  }
+
+  /* The pointer still appears and still taps — what goes is the glide, which is the part that is motion. */
+  .akan-agent-cursor {
+    transition: opacity 200ms ease-out;
+  }
+
+  /* The chevron holds its direction instead of sliding: the way the view is going is the part that carries. */
+  .akan-agent-cursor-scrolling::after {
+    animation: none;
+    opacity: 1;
+  }
+
+  .akan-agent-cursor-scrolling-up::after {
+    transform: rotate(225deg);
+  }
+}
+
 @keyframes spin {
   0% {
     transform: rotate(0deg);

package/ui/triggerSlot.tsx

@@ -15,18 +15,8 @@ interface TriggerSlotOptions {
   as?: "div" | "span";
 }
 
-/**
- * Puts a disclosure's click and aria state onto the element the caller handed in, rather than wrapping it.
- *
- * Reach for this **only when an attribute has to ride the caller's own control** — `aria-expanded` /
- * `aria-haspopup` on a wrapper names a box rather than the button a screen reader activates. Everywhere else
- * the framework wraps instead: a wrapper works with any node, and a clone is silently inert on a component
- * that does not forward `className` / `onClick` (every `ModelProps` component, whose `onClick` takes the model
- * rather than the event).
- *
- * The caller's own `onClick` runs first and can call `preventDefault()` to stop the surface from acting. A
- * trigger that is not a single element has nothing to clone onto, so it keeps a host element.
- */
+/** Clones a disclosure's click and aria state onto the caller's element; the caller's `onClick` runs first and may
+ *  `preventDefault()`. Only for aria that must ride the caller's control: a clone is inert on one not forwarding it. */
 export const triggerSlot = (
   trigger: ReactNode,
   { className, onClick, as: Host = "div", ...attrs }: TriggerSlotOptions & { [key: string]: unknown },

package/vendor/@akanjs/native/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Akan Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/vendor/@akanjs/native/README.ko.md

@@ -0,0 +1,88 @@
+# @akanjs/native
+
+Akan.js의 네이티브 런타임입니다. 앱의 CSR 빌드(번들을 인라인한 HTML 파일 하나와 `public/`)를 iOS,
+Android, macOS, Windows, Linux 앱으로 만듭니다. Capacitor, Xcode 프로젝트, Gradle, CocoaPods는 쓰지
+않습니다.
+
+이 패키지는 akanjs 내부용입니다. 따로 배포하지 않습니다(`private: true`).
+- akanjs가 이 패키지를 `dist/vendor/`로 복사합니다.
+- 앱은 `akanjs/native` 래퍼를 씁니다.
+- akanjs devkit은 빌드 API를 부릅니다.
+
+문서에서는 줄여서 akan-native라고 부릅니다.
+
+## 구성
+
+| 부분 | 위치 | 하는 일 |
+|---|---|---|
+| 페이지 런타임 | `packages/core`, `packages/react` | WebView 안의 브리지 클라이언트, `definePlugin`, env, React 훅 |
+| 플러그인 | `plugins/<id>` | 41개. TypeScript API, 웹 대체 구현, Swift·Kotlin·데스크톱 코드를 `native-plugin.json`이 기술합니다 |
+| iOS 셸 | `native/ios` | Swift: WKWebView, `app://` 스킴 핸들러, 응답형 브리지 |
+| Android 셸 | `native/android` | Kotlin: WebView, MessagePort 브리지, 에셋 서버. push(FCM)와 iap(Play Billing) 모듈용 Maven 잠금도 여기 있습니다 |
+| 데스크톱 셸 | `native/desktop`, `packages/desktop` | Rust cdylib(TAO + WRY, C ABI). 플러그인 호스트는 Bun Worker에서 돕니다 |
+| 빌드 도구 | `packages/cli` | 설정, 프로그램 빌드 API, 플랫폼별 빌더. Swift는 `swiftc`로, Android는 aapt2·kotlinc·d8·apksigner로, 데스크톱은 cargo와 `bun build --compile`로 빌드합니다 |
+
+## 진입점
+
+| import | 내용 |
+|---|---|
+| `@akanjs/native/api` | akanjs devkit용 빌드 API: `build`, `run`, `dev`, `release`, `validateConfig` ([docs/api.md](docs/api.md)) |
+| `@akanjs/native/config` | `defineConfig`와 설정 타입 |
+| `@akanjs/native/core` | 페이지 런타임: `platform`, `env`, `AkanNativeError`, `fileBlob`, `definePlugin` |
+| `@akanjs/native/react` | `useLiveValue`, `usePluginEvent` |
+| `@akanjs/native/plugins/<id>` | 플러그인의 페이지 API. 예: `@akanjs/native/plugins/camera` |
+| `@akanjs/native/desktop` | 데스크톱 플러그인 코드용 `defineDesktopPlugin` |
+
+설정의 플러그인은 내장 id(`"camera"`)나 플러그인 폴더의 절대경로로 적습니다. akanjs는 절대경로를 넘깁니다.
+
+## akanjs에 넣을 때
+
+- 패키지 안의 모듈은 서로 상대 경로로 import합니다. 그래서 복사본은 그대로 동작합니다. 고쳐 써야 하는 것은 akanjs 쪽의 `@akanjs/native/...` import뿐입니다.
+- 패키지 루트는 `package.json`이 아니라 `native/android/maven.lock.json`을 찾아 올라가며 정합니다.
+  - 복사할 때 `package.json`, `tsconfig.json`, `docs/`, `scripts/`, `examples/`, 모든 `test/` 폴더는 빼도 됩니다.
+  - 반드시 남길 것: `packages/*/src`, `packages/core/vectors`(debug 빌드가 넣습니다), `test/`를 뺀 `plugins/*`, `native/`
+- 빌드 산출물은 패키지 밖에 둡니다.
+  - 앱 빌드는 부르는 쪽이 넘기는 `outDir`에 둡니다(기본 `<앱>/.akan/native/build/<platform>`).
+  - 툴체인, 키, 캐시는 `~/.akan/native`(`AKAN_NATIVE_HOME`)에 둡니다.
+  - Cargo 빌드는 `~/.akan/native/cache/desktop-target`(`CARGO_TARGET_DIR`)에 둡니다.
+
+## 필요한 것
+
+- Bun 1.4 이상
+- iOS: Xcode 26 이상. 앱은 iOS 16 이상에서 돕니다.
+- Android: Android SDK(build-tools 35 이상, 37 권장, platform 36)와 JDK 21(Android Studio의 JBR도 됩니다). SDK 라이선스는 직접 수락해야 합니다. 앱은 Android 10(API 29) 이상에서 돕니다.
+- 데스크톱: rustup으로 설치한 Rust. 버전은 `native/desktop/rust-toolchain.toml`에 고정되어 있습니다.
+- kotlinc, bundletool, 고정한 Maven 라이브러리는 `~/.akan/native`로 받습니다. 받을 때 각각 고정된 SHA-256으로 검사합니다. Android SDK 라이선스는 대신 수락하지 않습니다.
+
+## 개발
+
+```sh
+bun install
+bun test                                     # TypeScript 테스트
+bun run typecheck
+bun scripts/native-vectors.ts                # 공유 벡터를 Swift·Kotlin 커널로 실행
+CARGO_TARGET_DIR=~/.akan/native/cache/desktop-target/dev cargo test --manifest-path native/desktop/Cargo.toml
+
+bun run akan-native doctor                   # 툴체인: 고정 버전과 찾은 것 비교
+bun run akan-native test macos --app examples/sample     # 샘플 앱 셀프 테스트(ios, android, web도)
+bun run akan-native test android --app examples/sample --avd <이름>
+bun scripts/vm/linux.ts bun run akan-native test linux --app examples/sample   # Docker 안의 Linux
+bun scripts/vm/windows.ts test               # SSH로 붙는 VM의 Windows
+```
+
+`bun run akan-native`은 이 패키지를 개발할 때 쓰는 CLI입니다(셀프 테스트, 툴체인, doctor, 플러그인
+코드 생성). 앱 빌드는 `akan`과 API로 합니다.
+
+## 문서
+
+- [docs/api.md](docs/api.md): akanjs devkit이 부르는 빌드 API
+- [docs/architecture.md](docs/architecture.md): 셸, 브리지 프로토콜, 보안 계층, 빌드와 서명
+- [docs/plugins.md](docs/plugins.md): 플러그인과 플랫폼별 지원
+- [docs/plugin-authoring.md](docs/plugin-authoring.md): 플러그인 작성법
+- [docs/requirements.md](docs/requirements.md): 요구사항과 결정
+- [docs/testing-windows-linux.md](docs/testing-windows-linux.md): Mac에서 Windows·Linux 테스트하기
+- [docs/move-checklist.md](docs/move-checklist.md): akanjs로 옮기기 전 확인(`bun scripts/move-check.ts`)
+
+## 라이선스
+
+MIT입니다. [LICENSE](LICENSE)를 보세요. 서드파티 소프트웨어는 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)에 있습니다.

package/vendor/@akanjs/native/README.md

@@ -0,0 +1,93 @@
+# @akanjs/native
+
+The native runtime of Akan.js. It turns an app's CSR build (one HTML file with the bundle inlined,
+plus `public/`) into iOS, Android, macOS, Windows and Linux apps, without Capacitor, Xcode projects,
+Gradle or CocoaPods.
+
+This package is internal to akanjs. It is not published on its own (`private: true`): akanjs copies it
+into its `dist/vendor/` folder, apps use the `akanjs/native` wrapper, and the akanjs devkit calls the
+build API. The docs call it akan-native for short.
+
+## What it contains
+
+| Part | Where | What it does |
+|---|---|---|
+| Page runtime | `packages/core`, `packages/react` | The bridge client in the WebView, `definePlugin`, env, React hooks |
+| Plugins | `plugins/<id>` | 41 plugins: a TypeScript API, a web fallback, and Swift, Kotlin or desktop code, described by `native-plugin.json` |
+| iOS shell | `native/ios` | Swift: WKWebView, the `app://` scheme handler, the reply bridge |
+| Android shell | `native/android` | Kotlin: WebView, MessagePort bridge, asset server, the pinned Maven lock for the push (FCM) and iap (Play Billing) modules |
+| Desktop shell | `native/desktop`, `packages/desktop` | Rust cdylib (TAO + WRY behind a C ABI) with Bun running the plugin host in a Worker |
+| Build tools | `packages/cli` | Config, the programmatic build API, and one builder per platform. Swift is compiled with `swiftc`, Android with aapt2, kotlinc, d8 and apksigner, and the desktop app with cargo and `bun build --compile` |
+
+## Entry points
+
+| Import | Contents |
+|---|---|
+| `@akanjs/native/api` | The build API for the akanjs devkit: `build`, `run`, `dev`, `release`, `validateConfig` ([docs/api.md](docs/api.md)) |
+| `@akanjs/native/config` | `defineConfig` and the config types |
+| `@akanjs/native/core` | The page runtime: `platform`, `env`, `AkanNativeError`, `fileBlob`, `definePlugin` |
+| `@akanjs/native/react` | `useLiveValue`, `usePluginEvent` |
+| `@akanjs/native/plugins/<id>` | A plugin's page API, for example `@akanjs/native/plugins/camera` |
+| `@akanjs/native/desktop` | `defineDesktopPlugin` for desktop plugin code |
+
+Plugins are named in the config by builtin id (`"camera"`) or by the absolute path of a plugin
+folder. akanjs passes absolute paths.
+
+## Embedding in akanjs
+
+- Inside the package, modules import each other by relative path. A copy therefore works without
+  rewriting. Only akanjs's own `@akanjs/native/...` imports need rewriting.
+- The package root is found by walking up to `native/android/maven.lock.json`, not through
+  `package.json`. The copy may leave out `package.json`, `tsconfig.json`, `docs/`, `scripts/`,
+  `examples/` and every `test/` folder. It must keep:
+  - `packages/*/src`
+  - `packages/core/vectors` (debug builds embed them)
+  - `plugins/*` without `test/`
+  - `native/`
+- Build output stays outside the package:
+  - the app's build goes to the `outDir` the caller passes (default `<app>/.akan/native/build/<platform>`)
+  - toolchains, keys and caches go to `~/.akan/native` (`AKAN_NATIVE_HOME`)
+  - Cargo builds go to `~/.akan/native/cache/desktop-target` (`CARGO_TARGET_DIR`)
+
+## Requirements
+
+- Bun 1.4 or later
+- iOS: Xcode 26 or later. Apps run on iOS 16 and later.
+- Android: the Android SDK (build-tools 35 or later, 37 recommended; platform 36) with its licenses
+  accepted by you, and JDK 21 (Android Studio's JBR works). Apps run on Android 10 (API 29) and later.
+- Desktop: Rust through rustup (the version is pinned in `native/desktop/rust-toolchain.toml`).
+- kotlinc, bundletool and the pinned Maven libraries are downloaded into `~/.akan/native`, each checked
+  against a pinned SHA-256. The Android SDK licenses are never accepted for you.
+
+## Developing
+
+```sh
+bun install
+bun test                                     # TypeScript tests
+bun run typecheck
+bun scripts/native-vectors.ts                # shared vectors against the Swift and Kotlin kernels
+CARGO_TARGET_DIR=~/.akan/native/cache/desktop-target/dev cargo test --manifest-path native/desktop/Cargo.toml
+
+bun run akan-native doctor                   # toolchains, pinned versions against what is found
+bun run akan-native test macos --app examples/sample     # the sample app's self-test (ios, android, web too)
+bun run akan-native test android --app examples/sample --avd <name>
+bun scripts/vm/linux.ts bun run akan-native test linux --app examples/sample   # Linux in Docker
+bun scripts/vm/windows.ts test               # Windows in a VM over SSH
+```
+
+`bun run akan-native` is the development CLI for this package (self-tests, toolchains, doctor, plugin
+code generation). Apps build through `akan` and the API instead.
+
+## Documents
+
+- [docs/api.md](docs/api.md): the build API that the akanjs devkit calls
+- [docs/architecture.md](docs/architecture.md): shells, bridge protocol, security layers, build and signing
+- [docs/plugins.md](docs/plugins.md): plugins and their platform support
+- [docs/plugin-authoring.md](docs/plugin-authoring.md): writing a plugin
+- [docs/requirements.md](docs/requirements.md): requirements and decisions
+- [docs/testing-windows-linux.md](docs/testing-windows-linux.md): testing Windows and Linux from a Mac
+- [docs/move-checklist.md](docs/move-checklist.md): checks before a move into akanjs (`bun scripts/move-check.ts`)
+
+## License
+
+MIT, see [LICENSE](LICENSE). Third-party software is listed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).