docs(agent): Harness-style agent knowledge split

.planning/codebase/README.md

@@ -11,7 +11,9 @@
 | **코드 분석 (현재)** | `.planning/codebase/` | 이 폴더 - AI 생성 |
 | **설계 의도** | `specs/` | 기능 명세 및 화면 설계 |
 | **구현 문서** | `docs/` | 구현된 API, 스키마, 가이드 |
-| **빠른 참조** | `CLAUDE.md` | 프로젝트 개요 및 진입점 |
+| **에이전트 참조 (표·인벤토리)** | `docs/agent/` | 라우트, API, 훅, 디자인 시스템 목록 |
+| **맵 (짧은 진입)** | `CLAUDE.md` | 요약 규칙 및 위 문서로의 링크 |
+| **한국어 에이전트 맵** | `AGENT.md` | 작업 유형별로 열 문서 안내 |
 
 ---
 

AGENTS.md

@@ -0,0 +1,6 @@
+# Agents
+
+This repository uses **[CLAUDE.md](CLAUDE.md)** as the short entry map (rules and links).
+
+- **Inventories** (routes, `/api/v1/*`, hooks, design system): [`docs/agent/README.md`](docs/agent/README.md)
+- **Korean agent map**: [`AGENT.md`](AGENT.md)

README.md

@@ -126,7 +126,9 @@ Expo 54 React Native.
 
 ## Documentation
 
-- **[CLAUDE.md](CLAUDE.md)** — conventions, routes, commands, design system
+- **[CLAUDE.md](CLAUDE.md)** — short map (rules, links)
+- **[AGENT.md](AGENT.md)** — Korean agent entry point
+- **[docs/agent/](docs/agent/)** — route/API/hook/design-system inventories for agents
 - **[docs/BACKEND-ONBOARDING.md](docs/BACKEND-ONBOARDING.md)** — API server in the monorepo
 - **[packages/api-server/docker/stack/README.md](packages/api-server/docker/stack/README.md)** — Docker Compose stack (api, ai, meili, redis, searxng), deploy script
 - **`packages/api-server/`** — Rust API docs, ADRs, `AGENTS.md`

docs/README.md

@@ -19,6 +19,7 @@
 | DB 스키마 사용법 | `docs/database/` | 실제 사용 패턴 |
 | API 엔드포인트 | `docs/api/` | 구현된 API 문서 |
 | 디자인 시스템 | `docs/design-system/` | UI 토큰 및 컴포넌트 |
+| 에이전트 참조 (LLM) | `docs/agent/` | 라우트/API/훅/DS 인벤토리 (맵은 루트 `CLAUDE.md`) |
 | TypeScript 타입 | `specs/shared/data-models.md` | 설계 의도 타입 정의 |
 | 기능 명세 | `specs/{bundle}/spec.md` | 요구사항 및 설계 |
 | 화면 설계 | `specs/{bundle}/screens/` | UI/UX 명세 |

docs/agent/README.md

@@ -0,0 +1,19 @@
+# Agent reference (`docs/agent/`)
+
+버전 관리되는 **에이전트·LLM용 참조** 모음입니다. 루트 [`CLAUDE.md`](../../CLAUDE.md)는 짧은 **맵**만 두고, 표·인벤토리·긴 트리는 이 폴더에 둡니다.
+
+## When to read what
+
+| Task | Document |
+|------|----------|
+| 패키지 구조, 명령어, 로컬 deps / 포트 | [monorepo.md](monorepo.md) |
+| 웹 라우트·기능 영역 | [web-routes-and-features.md](web-routes-and-features.md) |
+| Next.js `app/api/v1/*` 라우트 표 | [api-v1-routes.md](api-v1-routes.md) |
+| 훅 목록, 스토어·주요 경로 | [web-hooks-and-stores.md](web-hooks-and-stores.md) |
+| 디자인 시스템 import·컴포넌트 인벤토리 | [design-system-llm.md](design-system-llm.md) |
+| 아키텍처·컨벤션·스택 심층 | [`.planning/codebase/`](../../.planning/codebase/) |
+| 디자인 토큰·UI 상세 | [`docs/design-system/`](../design-system/) |
+
+## Rust API crate
+
+`packages/api-server` 전용 가이드는 [`packages/api-server/AGENT.md`](../../packages/api-server/AGENT.md)를 사용합니다.

docs/agent/api-v1-routes.md

@@ -0,0 +1,75 @@
+# Next.js API routes (`/api/v1/*`)
+
+`packages/web/app/api/v1/` 기준. 메서드·경로 추가 시 이 파일과 실제 라우트 핸들러를 함께 갱신합니다.
+
+## Posts & content
+
+| Route                            | Methods  | Description                   |
+| -------------------------------- | -------- | ----------------------------- |
+| `/api/v1/posts`                  | GET      | List posts with pagination    |
+| `/api/v1/posts/with-solution`    | GET      | Posts with solution data      |
+| `/api/v1/posts/with-solutions`   | GET      | Posts with multiple solutions |
+| `/api/v1/posts/extract-metadata` | POST     | Extract metadata from URL     |
+| `/api/v1/posts/analyze`          | POST     | AI image analysis             |
+| `/api/v1/posts/upload`           | POST     | Upload post image             |
+| `/api/v1/posts/[postId]`         | GET      | Single post detail            |
+| `/api/v1/posts/[postId]/spots`   | GET/POST | Spots for a post              |
+| `/api/v1/posts/[postId]/likes`   | POST     | Like/unlike a post            |
+| `/api/v1/posts/[postId]/saved`   | POST     | Save/unsave a post            |
+| `/api/v1/post-magazines/[id]`    | GET      | Post magazine data            |
+
+## Solutions & spots
+
+| Route                                  | Methods   | Description                  |
+| -------------------------------------- | --------- | ---------------------------- |
+| `/api/v1/solutions/convert-affiliate`  | POST      | Convert affiliate links      |
+| `/api/v1/solutions/[solutionId]`       | GET/PATCH | Solution CRUD                |
+| `/api/v1/solutions/[solutionId]/adopt` | POST      | Adopt a solution             |
+| `/api/v1/solutions/extract-metadata`   | POST      | Solution metadata extraction |
+| `/api/v1/spots/[spotId]`               | GET/PATCH | Spot CRUD                    |
+| `/api/v1/spots/[spotId]/solutions`     | GET/POST  | Solutions for spot           |
+
+## Users & profile
+
+| Route                           | Methods | Description          |
+| ------------------------------- | ------- | -------------------- |
+| `/api/v1/users/me`              | GET     | Current user profile |
+| `/api/v1/users/me/activities`   | GET     | User activities      |
+| `/api/v1/users/me/stats`        | GET     | User statistics      |
+| `/api/v1/users/[userId]`        | GET     | User by ID           |
+| `/api/v1/badges`                | GET     | All badges           |
+| `/api/v1/badges/me`             | GET     | User's earned badges |
+| `/api/v1/rankings`              | GET     | Global rankings      |
+| `/api/v1/rankings/me`           | GET     | User's ranking       |
+
+## Behavioral intelligence
+
+| Route                | Methods | Description                                                |
+| -------------------- | ------- | ---------------------------------------------------------- |
+| `/api/v1/events`     | POST    | Track behavior events (dwell time, scroll depth, clicks)   |
+| `/api/v1/categories` | GET     | Category list                                              |
+
+## Virtual try-on (VTON)
+
+| Route                | Methods | Description           |
+| -------------------- | ------- | --------------------- |
+| `/api/v1/vton`       | POST    | Submit VTON job       |
+| `/api/v1/vton/items` | GET     | VTON-compatible items   |
+
+## Admin dashboard
+
+| Route                                 | Methods | Description              |
+| ------------------------------------- | ------- | ------------------------ |
+| `/api/v1/admin/dashboard/stats`       | GET     | Dashboard statistics     |
+| `/api/v1/admin/dashboard/chart`       | GET     | Dashboard charts         |
+| `/api/v1/admin/dashboard/today`       | GET     | Today's activity         |
+| `/api/v1/admin/ai-cost/kpi`           | GET     | AI cost KPIs             |
+| `/api/v1/admin/ai-cost/chart`         | GET     | AI cost charts           |
+| `/api/v1/admin/audit`                 | GET     | Audit logs               |
+| `/api/v1/admin/audit/[requestId]`     | GET     | Single audit entry       |
+| `/api/v1/admin/pipeline`              | GET     | Pipeline status          |
+| `/api/v1/admin/pipeline/[pipelineId]` | GET     | Single pipeline          |
+| `/api/v1/admin/server-logs`           | GET     | Server logs              |
+| `/api/v1/admin/server-logs/stream`    | GET     | Server logs (SSE stream) |
+
+Rust REST API와의 관계는 [`.planning/codebase/INTEGRATIONS.md`](../../.planning/codebase/INTEGRATIONS.md) 및 `packages/api-server` 문서를 참고합니다.

docs/agent/design-system-llm.md

@@ -0,0 +1,112 @@
+# v2.0 Design System (LLM quick reference)
+
+Implementation: `packages/web/lib/design-system/`. Human-facing 토큰·패턴 상세는 [docs/design-system/](../design-system/)를 SSOT로 둡니다.
+
+## Import path
+
+All design system components are exported from a single barrel import:
+
+```typescript
+import {
+  // Typography
+  Heading,
+  Text,
+  // Inputs
+  Input,
+  SearchInput,
+  // Cards
+  Card,
+  CardHeader,
+  CardContent,
+  CardFooter,
+  CardSkeleton,
+  ProductCard,
+  GridCard,
+  FeedCardBase,
+  ProfileHeaderCard,
+  // Headers & Footer
+  DesktopHeader,
+  MobileHeader,
+  DesktopFooter,
+  // Tokens
+  typography,
+  colors,
+  spacing,
+  shadows,
+  borderRadius,
+  zIndex,
+} from "@/lib/design-system";
+```
+
+## Component usage guide
+
+| Component       | Use Case            | Example                                              |
+| --------------- | ------------------- | ---------------------------------------------------- |
+| **Heading**     | Page/section titles | `<Heading variant="h2">Title</Heading>`              |
+| **Text**        | Body text, captions | `<Text variant="small">Description</Text>`           |
+| **Card**        | Generic container   | `<Card variant="elevated" size="md">...</Card>`      |
+| **ProductCard** | Product display     | `<ProductCard image={url} title="..." price="$99"/>` |
+| **Input**       | Form inputs         | `<Input variant="search" leftIcon={<Search/>}/>`     |
+
+## Design token reference
+
+Access design tokens directly for custom styling:
+
+```typescript
+import { typography, spacing, colors } from "@/lib/design-system/tokens";
+
+// Typography
+typography.sizes.h1; // Font size for h1
+responsiveTypography.pageTitle; // Responsive title sizing
+
+// Spacing (4px base unit)
+spacing[4]; // 16px
+spacing[8]; // 32px
+
+// Colors (CSS variable references)
+colors.primary;
+colors.muted;
+```
+
+## Further documentation
+
+- **[docs/design-system/](../design-system/)** — Design token documentation
+- **[.planning/codebase/](../../.planning/codebase/)** — Architecture and conventions
+
+## Component inventory
+
+Located in `lib/design-system/`:
+
+| Component                            | Purpose                                              |
+| ------------------------------------ | ---------------------------------------------------- |
+| **tokens.ts**                        | Design tokens (colors, spacing, typography, shadows) |
+| **Heading, Text**                    | Typography components with size variants             |
+| **Input, SearchInput**               | Form inputs with variants                            |
+| **Card Family**                      | Base card + Header/Content/Footer + Skeleton         |
+| **ProductCard**                      | Product card with image & description                |
+| **GridCard**                         | Grid layout card variant                             |
+| **FeedCardBase**                     | Social feed card variant                             |
+| **ProfileHeaderCard**                | Profile header card                                  |
+| **DesktopHeader**                    | Desktop navigation header                            |
+| **MobileHeader**                     | Mobile navigation with bottom sheet                  |
+| **DesktopFooter**                    | Desktop footer with links                            |
+| **ActionButton**                     | Interactive action button                            |
+| **ArtistCard**                       | Artist/celebrity display card                        |
+| **Badge**                            | Badge/tag display                                    |
+| **BottomSheet**                      | Mobile bottom sheet                                  |
+| **Divider**                          | Section divider                                      |
+| **GuestButton**                      | Guest action button                                  |
+| **Hotspot**                          | Interactive hotspot marker                           |
+| **LeaderItem**                       | Leaderboard/ranking item                             |
+| **LoadingSpinner**                   | Loading state indicator                              |
+| **LoginCard**                        | Login prompt card                                    |
+| **NavBar, NavItem**                  | Navigation components                                |
+| **OAuthButton**                      | OAuth provider button                                |
+| **RankingItem**                      | Ranking display item                                 |
+| **SectionHeader**                    | Section title header                                 |
+| **ShopCarouselCard**                 | Shop item carousel card                              |
+| **SpotCard, SpotDetail, SpotMarker** | Spot interaction components                          |
+| **StatCard**                         | Statistics display card                              |
+| **StepIndicator**                    | Multi-step progress indicator                        |
+| **Tabs**                             | Tab navigation                                       |
+| **Tag**                              | Categorization tag                                   |

docs/agent/monorepo.md

@@ -0,0 +1,134 @@
+# Monorepo overview & commands
+
+Paths are relative to the repository root unless noted.
+
+## Layout
+
+```text
+decoded-monorepo/
+├── package.json          # Root — bun workspaces, Turborepo
+├── turbo.json            # Build orchestration (build/dev/lint/test)
+├── bunfig.toml           # Bun config (hoisted strategy)
+├── packages/
+│   ├── web/              # Next.js 16 frontend (main app)
+│   ├── shared/           # Shared types, hooks, Supabase queries
+│   ├── mobile/           # Expo 54 React Native app
+│   ├── api-server/       # Rust/Axum API (Cargo workspace; not a bun workspace member)
+│   └── ai-server/        # Python AI / gRPC (uv; former decoded-ai repo)
+├── .planning/            # GSD workflow artifacts
+├── docs/agent/           # Agent reference (this folder)
+└── CLAUDE.md             # Short map → links here
+```
+
+- **Package manager**: bun 1.3.10+ (not yarn/npm)
+- **Orchestration**: Turborepo
+- **API server (Rust)**: `packages/api-server` — `cargo` (not bun workspaces)
+- **AI server (Python)**: `packages/ai-server` — `uv`; thin `package.json` scripts for Turborepo only
+
+## Tech stack (summary)
+
+상세·버전 고정은 [`.planning/codebase/STACK.md`](../../.planning/codebase/STACK.md)를 SSOT로 둡니다.
+
+- **Frontend**: Next.js 16.x, React 19.x, TypeScript 5.9.x
+- **Styling**: Tailwind CSS, tailwind-merge, @tailwindcss/typography
+- **State**: Zustand, TanStack React Query
+- **Backend (app)**: Supabase (PostgreSQL, Auth, Storage)
+- **Rust API**: Axum, SeaORM, tokio
+- **AI**: Python, gRPC to `ai-server`
+- **Node**: 22 LTS 권장
+- **Lint/format**: ESLint 10 flat config, Prettier
+
+## `packages/web` structure
+
+```text
+packages/web/
+├── app/                    # Next.js App Router pages
+│   ├── @modal/             # Parallel route for modals
+│   ├── api/v1/             # API routes (posts, solutions, users, categories, spots, events, admin, vton, badges, rankings)
+│   ├── admin/              # Admin dashboard (ai-cost, ai-audit, pipeline-logs, server-logs)
+│   ├── debug/              # Debug tools (supabase)
+│   ├── editorial/          # Daily editorial page
+│   ├── explore/            # Explore grid view
+│   ├── feed/               # Social feed
+│   ├── images/             # Image discovery & detail
+│   ├── login/              # OAuth authentication
+│   ├── magazine/           # Personal magazine (editorial issue viewer)
+│   ├── posts/              # Post detail
+│   ├── profile/            # User profile with activity, badges, tries, collections
+│   ├── request/            # Upload & AI detection flow
+│   ├── search/             # Full-screen search overlay
+│   └── lab/                # Experimental features
+├── lib/
+│   ├── api/                # API client functions
+│   ├── components/         # Feature-based components
+│   ├── design-system/      # v2.0 Design System
+│   ├── hooks/              # Custom React hooks
+│   ├── stores/             # Zustand state stores
+│   ├── supabase/           # Supabase client + queries
+│   └── utils/              # Utility functions
+└── __tests__/              # Test files
+
+packages/shared/
+├── supabase/
+│   ├── client.ts
+│   ├── types.ts
+│   └── queries/
+
+specs/                      # Feature specifications
+docs/                       # Documentation
+.planning/                  # GSD workflow artifacts
+```
+
+더 넓은 트리는 [`.planning/codebase/STRUCTURE.md`](../../.planning/codebase/STRUCTURE.md)를 참고합니다.
+
+## Commands
+
+```bash
+# Monorepo (from root)
+bun run dev             # Development server (JS packages via Turborepo)
+bun run dev:api-server  # Rust API (cargo watch)
+bun run dev:ai-server   # Python AI server (uv)
+bun run build           # Production build (via Turborepo)
+bun run lint            # ESLint (and package scripts where configured)
+bun run ci:local        # 로컬 CI (pre-push 와 동일: web + api-server; ai-server 는 RUN_AI_SERVER_CI=1 일 때만)
+# 훅: 저장소 루트에서 `just hook` → core.hooksPath=.githooks
+
+# Split local dev: Meilisearch·Redis·SearXNG = Docker first, then:
+bun run dev:local-deps       # Docker deps only (see scripts/local-deps-up.sh)
+bun run dev:local-fe         # Next only (same as dev:web)
+bun run dev:local-be         # API + AI together; logs -> .logs/local/api.log & ai.log (tail -f in other terminals)
+# Local host env templates: packages/api-server/.env.dev.example , packages/ai-server/.dev.env.example
+# Port alignment (호스트 실행): MEILISEARCH_URL=http://localhost:7700 ; AI_SERVER_GRPC_URL=http://localhost:50052 (AI APP_ENV=dev)
+#   API API_SERVER_GRPC_PORT must equal AI API_SERVER_GRPC_PORT ; 레거시 GRPC_PORT / GRPC_BACKEND_* 도 아직 지원. AI Redis localhost:6303 + SEARXNG localhost:4000 with local-deps
+# just local-help            # prints tail -f hints (root Justfile)
+
+# Web package only
+cd packages/web
+bun run dev           # Next.js dev server
+bun run build         # Next.js production build
+bun run lint          # ESLint
+bun run format        # Prettier formatting
+bun run typecheck     # TypeScript (tsc --noEmit)
+
+# Frontend CI만 실행
+just ci-web                         # lint + format + tsc
+SKIP_FE_CI=1 git push               # 긴급 시 web CI 건너뛰기
+
+# API server (Rust)
+cd packages/api-server
+cargo build           # Build API server
+cargo run             # Run API server
+cargo test            # Run tests
+
+# AI server (Python)
+cd packages/ai-server
+uv sync
+uv run python -m src.main
+# or: bun run dev:ai-server  # from monorepo root
+```
+
+## Environment
+
+- Web: copy `packages/web/.env.local.example` → `.env.local` (gitignored).
+- Never commit secrets or full `.env` files.
+- Supabase required for data/auth in typical dev flows.