mym0404 · mym0404 · Feb 17, 2026 · Feb 17, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,85 @@
+# PROJECT KNOWLEDGE BASE
+
+**Generated:** 2026-02-17 17:22 KST
+**Commit:** 99f3c53
+**Branch:** main
+
+## OVERVIEW
+React Native Naver Map library with Fabric-only architecture. Single repo owns TypeScript API, iOS/Android native layers, example app, docs site, and Expo config plugin.
+
+## STRUCTURE
+```text
+.
+├── src/                 # Public TS API, Fabric specs, shared types
+├── ios/                 # Objective-C++ Fabric implementation
+├── android/             # Kotlin implementation + codegen interfaces
+├── example/             # RN example app for runtime verification
+├── docs/                # Next.js + Fumadocs documentation site
+├── expo-config-plugin/  # Expo plugin source built to ./build
+├── script/              # Repo automation (codegen, lint, release)
+└── CLAUDE.md            # Project-wide detailed engineering rules
+```
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| Public API export surface | `src/index.tsx` | First file to update for new public symbols |
+| Add native prop/command | `src/spec/` | Spec change requires `pnpm codegen` |
+| JS component behavior | `src/component/` | Wrapper logic and prop shaping |
+| iOS implementation | `ios/` | `RNCNaverMapView*.mm`, `Overlay/*` |
+| Android implementation | `android/src/main/java/...` | ViewManager, wrapper, overlay managers |
+| Example runtime validation | `example/src/` | Validate map behavior after changes |
+| Docs content and app | `docs/content/`, `docs/src/` | Do not edit generated docs outputs |
+| Expo plugin behavior | `expo-config-plugin/src/index.ts` | Build output consumed via `app.plugin.js` |
+| Release and automation | `script/` | codegen, native lint/format, release flow |
+
+## CODE MAP
+LSP symbol indexing was unavailable during generation. Use directory AGENTS files for local maps.
+
+## CONVENTIONS
+- New Architecture only: Fabric is mandatory in v2.x; no Bridge fallback.
+- `src/spec` is the source of truth for native interfaces; keep TS/iOS/Android in sync.
+- Any native feature change must be implemented on both iOS and Android unless explicitly platform-scoped.
+- Run `pnpm codegen` after spec changes.
+- Run `pnpm run t` as the default pre-PR validation command.
+- Root Biome config intentionally excludes `docs/**`; docs has its own config.
+- Workspace packages are `example` and `docs`; Expo plugin is built from root script.
+
+## ANTI-PATTERNS (THIS PROJECT)
+- Adding or modifying Bridge-era patterns.
+- Editing generated artifacts as source (`lib/**`, `docs/.next/**`, `docs/.source/**`, `expo-config-plugin/build/**`).
+- Spec changes without regenerated codegen outputs and native parity updates.
+- Native-only behavior changes without matching JS/spec contract updates.
+- Committing API keys or secrets from example app configuration files.
+
+## UNIQUE STYLES
+- Color props flow through React Native color processing and native `Int32` props.
+- iOS Fabric views use emitter casting + null guard before event emission.
+- Android managers follow codegen delegate patterns and centralized event utility helpers.
+- Public docs and examples are bilingual-oriented; metadata files often have `meta` and `meta.ko` pairs.
+
+## COMMANDS
+```bash
+pnpm run t
+pnpm typecheck
+pnpm format
+
+pnpm codegen
+pnpm codegen:ios
+pnpm codegen:android
+
+pnpm build
+pnpm build:docs
+pnpm build:expo-config-plugin
+pnpm prepack
+
+pnpm ci:ios
+pnpm ci:android
+pnpm turbo:ios
+pnpm turbo:android
+```
+
+## NOTES
+- Example app requires Naver key setup before realistic runtime checks.
+- CI injects dummy secret files for build jobs; local workflows should not rely on those.
+- When unsure, read `CLAUDE.md` first, then nearest subdirectory `AGENTS.md`.
diff --git a/android/AGENTS.md b/android/AGENTS.md
@@ -0,0 +1,40 @@
+# ANDROID KNOWLEDGE BASE
+
+## OVERVIEW
+`android/` contains Kotlin map and overlay managers plus New Architecture codegen integration.
+
+## STRUCTURE
+```text
+android/
+├── src/main/java/com/mjstudio/reactnativenavermap/  # Runtime managers/views/events
+├── src/newarch/                                      # Codegen manager specs
+├── build.gradle                                      # Library build config
+└── gradle/                                           # Gradle wrapper/config
+```
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| Package registration | `.../RNCNaverMapPackage.kt` | Manager/module registration |
+| Map view behavior | `.../mapview/*` | Wrapper, manager, lifecycle hooks |
+| Overlay behavior | `.../overlay/*` | Overlay-specific managers/views |
+| Event utilities | `.../util/ViewEventEmitter.kt` | Central event emission helpers |
+| Codegen interfaces | `src/newarch/*Spec.kt` | Generated manager interfaces |
+
+## CONVENTIONS
+- Keep manager implementations aligned with generated spec interfaces.
+- Use shared event utility helpers for event dispatch.
+- Preserve lifecycle handling patterns in wrappers/attached views.
+- Maintain naming parity with TS spec command/event definitions.
+- Keep overlay managers consistent with existing manager/delegate patterns.
+
+## ANTI-PATTERNS
+- Manual ad-hoc command routing that drifts from codegen specs.
+- Emitting events outside established utility path.
+- Android-only behavior changes without TS/spec and iOS review.
+- Editing build/generated outputs as source of truth.
+
+## VALIDATION
+- Run `pnpm codegen` when spec changes.
+- Run `pnpm run t` from repo root.
+- For Android-impacting changes, run `pnpm ci:android` or `pnpm turbo:android`.
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
@@ -0,0 +1,37 @@
+# DOCS KNOWLEDGE BASE
+
+## OVERVIEW
+`docs/` is a standalone Next.js + Fumadocs site for library documentation.
+
+## STRUCTURE
+```text
+docs/
+├── content/docs/   # MDX content and metadata (meta + meta.ko)
+├── src/            # Next app routes and doc rendering logic
+├── source.config.ts
+└── package.json
+```
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| Content pages | `content/docs/**/*.mdx` | User-facing docs text |
+| Sidebar/order metadata | `content/docs/**/meta*.json` | Navigation and i18n metadata |
+| Rendering and routing | `src/app/`, `src/lib/source.ts` | Next + Fumadocs integration |
+| Search API | `src/app/api/search/route.ts` | Docs search endpoint |
+
+## CONVENTIONS
+- Keep content updates in `content/docs/` and app logic in `src/`.
+- Maintain bilingual metadata parity where `meta` and `meta.ko` pairs exist.
+- Use docs-local tooling (`docs/package.json`, `docs/biome.json`) for docs-specific behavior.
+- Treat generated docs artifacts as build output, not source.
+
+## ANTI-PATTERNS
+- Editing `docs/.next/**` or `docs/.source/**` manually.
+- Changing root Biome rules to fix docs linting; docs has local config.
+- Breaking metadata structure used by Fumadocs source generation.
+
+## VALIDATION
+- Run `pnpm build:docs` from repo root.
+- For local docs iteration from repo root, run `pnpm docs:dev`.
+- For local docs iteration, run `cd docs && pnpm dev`.
diff --git a/example/AGENTS.md b/example/AGENTS.md
@@ -0,0 +1,34 @@
+# EXAMPLE APP KNOWLEDGE BASE
+
+## OVERVIEW
+`example/` is the runtime verification app for manual behavior checks across iOS and Android.
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| App entry | `index.js`, `src/App.tsx` | Runtime startup and screen flow |
+| Feature screens | `src/screens/` | Behavior verification scenarios |
+| Shared example UI | `src/components/` | Demo-only UI helpers |
+| Android app config | `android/` | Manifest, Gradle, local SDK config |
+| iOS app config | `ios/` | Podfile, Xcode project settings |
+
+## CONVENTIONS
+- Use example screens to verify library behavior after API/native changes.
+- Keep example-specific logic in `example/`; do not move demo logic into library source.
+- Prefer root wrapper commands (`pnpm ios`, `pnpm android`, `pnpm dev`) for consistent context.
+- Treat map API keys and secret config files as local-only values.
+
+## ANTI-PATTERNS
+- Committing real API keys or secret files.
+- Using example app code as public library API surface.
+- Changing example native settings without checking root CI commands.
+- Treating example-only behavior as canonical library behavior.
+
+## VALIDATION
+- Run `pnpm ios` and/or `pnpm android` from repo root.
+- For quick checks, run `pnpm dev` and validate changed screens.
+
+## NOTES
+- Example behavior is a verification aid, not a compatibility guarantee by itself.
+- Keep setup instructions aligned with `CONTRIBUTING.md` and `CLAUDE.md`.
+- Prefer minimal demo changes that isolate the library behavior under review.
diff --git a/expo-config-plugin/AGENTS.md b/expo-config-plugin/AGENTS.md
@@ -0,0 +1,32 @@
+# EXPO PLUGIN KNOWLEDGE BASE
+
+## OVERVIEW
+`expo-config-plugin/` implements Expo config integration for Naver Map keys and permissions.
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| Plugin source | `src/index.ts` | iOS/Android config mutation logic |
+| Build config | `tsconfig.json` | Compiles `src` to `build` |
+| Runtime entry link | `../app.plugin.js` | Consumes `build/index.js` |
+
+## CONVENTIONS
+- Edit plugin behavior only in `src/index.ts`.
+- Keep iOS and Android config key mapping logically paired.
+- Rebuild plugin output after source changes.
+- Keep plugin options stable and backward compatible where possible.
+
+## ANTI-PATTERNS
+- Editing `build/**` directly as source.
+- Updating `app.plugin.js` target without rebuilding plugin output.
+- Platform-specific config changes without cross-platform review.
+
+## VALIDATION
+- Run `pnpm build:expo-config-plugin` from repo root.
+- Run `pnpm run t` for baseline checks.
+
+## NOTES
+- Keep plugin defaults explicit and documented for both platforms.
+- Confirm output is refreshed before local Expo app checks.
+- Changes here can affect install-time behavior, not only runtime map rendering.
+- Use conservative option evolution; avoid breaking config names.
diff --git a/ios/AGENTS.md b/ios/AGENTS.md
@@ -0,0 +1,39 @@
+# IOS KNOWLEDGE BASE
+
+## OVERVIEW
+`ios/` contains Objective-C++ Fabric implementation for map view, overlays, and native utilities.
+
+## STRUCTURE
+```text
+ios/
+├── RNCNaverMapView*.{h,mm}  # Main map Fabric view + implementation
+├── Overlay/                 # Overlay component views
+├── Module/                  # Native module utilities
+└── Util/                    # Shared iOS helper code
+```
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| Map commands/props | `RNCNaverMapView.mm`, `RNCNaverMapViewImpl.mm` | Command and camera behavior |
+| Overlay behavior | `Overlay/*/*.mm` | One folder per overlay type |
+| Native module methods | `Module/RNCNaverMapUtil.mm` | Turbo/utility functions |
+| Shared helpers | `Util/` | Color/image/bridge helpers |
+
+## CONVENTIONS
+- Follow Fabric component lifecycle (`initWithFrame`, `updateProps`).
+- Cast and null-check event emitters before emitting events.
+- Keep command names aligned with TS spec command list.
+- Clean up asynchronous image loaders/cancelers on teardown.
+- Keep overlay implementation patterns consistent across overlay folders.
+
+## ANTI-PATTERNS
+- Bridge-era fallback logic in v2.x paths.
+- Event emission without emitter validity checks.
+- iOS-only behavioral changes without TS/spec and Android parity review.
+- Editing generated code instead of source implementation files.
+
+## VALIDATION
+- Run `pnpm codegen` when spec changes.
+- Run `pnpm run t` from repo root.
+- Run `pnpm pod` or `pnpm pod:update` when Pod state changes.
diff --git a/script/AGENTS.md b/script/AGENTS.md
@@ -0,0 +1,37 @@
+# SCRIPT KNOWLEDGE BASE
+
+## OVERVIEW
+`script/` contains repo automation for codegen, native lint/format, and release orchestration.
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| Codegen flow | `codegen.mjs` | Generates iOS/Android codegen artifacts |
+| iOS lint/format | `clang-lint.sh`, `clang-format.sh` | Objective-C/C++ style checks |
+| Android lint/format | `ktlint-lint.sh`, `ktlint-format.sh` | Kotlin style checks |
+| Release flow | `release.sh` | Release prechecks and publish flow |
+
+## CONVENTIONS
+- Keep scripts deterministic and CI-safe where possible.
+- Preserve root-script contract used by `package.json` commands.
+- Keep shell tooling scoped to target file globs used by lefthook.
+- Any release flow change must preserve validation before publish.
+
+## RELEASE NOTES
+- `release.sh` validates with `pnpm run t` and `pnpm prepack` before invoking `release-it`.
+- Treat release execution as environment-dependent; do not assume fully non-interactive CI mode unless explicitly configured.
+
+## ANTI-PATTERNS
+- Introducing script behavior that bypasses `pnpm run t` for release.
+- Hardcoding local machine-only paths.
+- Expanding scripts to start long-running dev servers.
+
+## VALIDATION
+- Run `pnpm run t`.
+- For release script changes, dry-run expected command sequence locally.
+
+## NOTES
+- Keep shell scripts readable and short; split complex logic into helper functions.
+- Align script names with package script intent for discoverability.
+- Prefer explicit failure messages when a prerequisite is missing.
+- Avoid adding script behavior that mutates unrelated workspace state.
diff --git a/src/AGENTS.md b/src/AGENTS.md
@@ -0,0 +1,41 @@
+# SRC KNOWLEDGE BASE
+
+## OVERVIEW
+`src/` owns the public TypeScript surface and the JS-to-native contract for Fabric components.
+
+## STRUCTURE
+```text
+src/
+├── index.tsx      # Public exports (API boundary)
+├── component/     # JS wrapper components
+├── spec/          # React Native codegen specs
+├── types/         # Public domain types
+├── internal/      # Internal helpers, constants, assertions
+└── util/          # Public utility surface
+```
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| Expose new public symbol | `src/index.tsx` | Keep export surface intentional |
+| Add native prop/command | `src/spec/` | Update spec first, then native code |
+| Update JS wrapper behavior | `src/component/` | Keep shape conversion consistent |
+| Add/modify public type | `src/types/` | Treat as user-facing contract |
+| Shared helper changes | `src/internal/` | Avoid leaking internals to API |
+
+## CONVENTIONS
+- Prefer named exports; avoid default export for new TS modules.
+- Keep public API edits localized in `src/index.tsx`.
+- Treat `src/spec/*` as canonical interface definitions.
+- Convert color props via RN color processing before native handoff.
+- Keep component wrappers thin; avoid embedding platform business logic in TS wrappers.
+
+## ANTI-PATTERNS
+- Changing `src/component` props without matching `src/spec` and native updates.
+- Editing generated declarations under `lib/**` instead of `src/**`.
+- Introducing `any`/type suppression for contract mismatches.
+- Exporting unstable internals directly from `src/index.tsx`.
+
+## VALIDATION
+- Spec changes: run `pnpm codegen`.
+- Source changes: run `pnpm run t`.
diff --git a/src/component/AGENTS.md b/src/component/AGENTS.md
@@ -0,0 +1,33 @@
+# COMPONENT KNOWLEDGE BASE
+
+## OVERVIEW
+`src/component/` wraps Fabric native specs into ergonomic React components.
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| Map view behavior | `NaverMapView.tsx` | Main wrapper and command bridge |
+| Overlay wrappers | `NaverMap*Overlay.tsx` | Marker, path, polygon, etc. |
+| Prop conversion patterns | Existing overlay components | Follow established conversion flow |
+
+## CONVENTIONS
+- Keep wrappers declarative and predictable.
+- Normalize/transform props before passing to native components.
+- Preserve existing prop naming and semantics unless API change is explicit.
+- Reuse shared helpers/constants instead of duplicating conversion logic.
+- When adding commands, align wrapper method names with spec commands.
+
+## ANTI-PATTERNS
+- Embedding platform-specific branching in wrappers when spec/native can model it.
+- Ad-hoc magic values repeated across overlays.
+- Silent behavior changes without matching docs and example updates.
+- Direct imports from generated `lib/**` paths.
+
+## VALIDATION
+- Run `pnpm run t`.
+- Smoke-check changed behavior via `example/src/screens/*`.
+
+## NOTES
+- Keep wrapper APIs friendly, but preserve spec-level naming consistency.
+- If wrapper behavior changes, update docs/examples in the same PR.
+- When uncertain, prefer explicit prop mapping over implicit coercion.