docs(tech-specs): address PR #695 review feedback

- Keep @stackflow/compat-await-push: no v2 replacement, independent utility, active usage
- Reflect docs accuracy fixes: ActivityLoaderArgs import path, Link animate default, urlPatternOptions removal, ref type
- Add resolving-circular-reference deletion, write-plugin lifecycle hook fix, plugin-history-sync v2 update
- Consolidate loader-api into preloading, simplify structured-activity examples, fix line highlighting
- Add README cleanup for @stackflow/link (remove plugin-preload references)
- Add versioned-docs.md tech spec (v1/v2 docs coexistence, separate PR)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: tonyfromundefined

.tech-specs/future-to-stable-migration.md

@@ -99,14 +99,19 @@ stackflow({
 - `extensions/link/src/stable/` 디렉토리 전체
 - `extensions/link/src/future/` 디렉토리 → 내용을 `src/`로 이동
 
-### 1.3 `@stackflow/compat-await-push` (패키지 삭제)
+### 1.3 `@stackflow/compat-await-push` (유지)
 
-**현재 상태:** Old API의 `await push()` 패턴을 지원하는 호환 레이어
-**변경 계획:** 패키지 전체 삭제 (deprecated)
+**현재 상태:** `receive(push(...))` 패턴(다른 Activity에서 데이터를 돌려받는 패턴)을 제공하는 유틸리티 패키지. `resolveMap` 기반 순수 Promise 패턴으로 구현되어 있어 Stackflow 내부 API(stable/future)와 독립적으로 동작
+**변경 계획:** **삭제하지 않고 유지**
 
-**삭제 대상:**
-- `extensions/compat-await-push/` 디렉토리 전체
-- 워크스페이스 설정에서 제거
+**유지 사유:**
+- Future API(v2)에 `receive(push(...))` 패턴을 대체하는 공식 API가 없음
+- Stackflow 내부 API를 import하지 않는 독립 유틸리티 (v1/v2 양쪽과 호환)
+- 조직 내 다수의 활성 프로젝트가 의존 중
+- 삭제 시 해당 패턴을 사용하는 사용자의 마이그레이션 경로 부재
+
+**후속 작업(별도 트랙):**
+- 향후 v2 공식 API로 대체하는 설계 필요 시 별도 RFC/스펙으로 다룬다
 
 ### 1.4 `@stackflow/plugin-preload` (패키지 삭제)
 
@@ -175,7 +180,7 @@ stackflow({
 | `@stackflow/link` | `@stackflow/link` (내용 변경) |
 | `@stackflow/link/stable` | 삭제 |
 | `@stackflow/link/future` | 삭제 (`@stackflow/link`로 통합) |
-| `@stackflow/compat-await-push` | 삭제 |
+| `@stackflow/compat-await-push` | **유지** (독립 유틸리티) |
 | `@stackflow/plugin-preload` | 삭제 (`usePrepare`로 대체) |
 | `@stackflow/plugin-map-initial-activity` | 삭제 (`config.initialActivity`로 대체) |
 
@@ -285,32 +290,31 @@ declare module "@stackflow/config" {
 
 ### Phase 3: 패키지 삭제
 
-10. `@stackflow/compat-await-push` - 패키지 삭제, 워크스페이스에서 제거
-11. `@stackflow/plugin-preload` - 패키지 삭제, 워크스페이스에서 제거
-12. `@stackflow/plugin-map-initial-activity` - 패키지 삭제, 워크스페이스에서 제거
+10. `@stackflow/plugin-preload` - 패키지 삭제, 워크스페이스에서 제거
+11. `@stackflow/plugin-map-initial-activity` - 패키지 삭제, 워크스페이스에서 제거
 
 ### Phase 4: 데모 앱 업데이트
 
-13. `demo/` - import 경로에서 `/future` 제거
-14. `demo/` - `compat-await-push`, `plugin-preload`, `plugin-map-initial-activity` 의존성 제거
+12. `demo/` - import 경로에서 `/future` 제거
+13. `demo/` - `plugin-preload`, `plugin-map-initial-activity` 의존성 제거
 
 ### Phase 5: 문서 업데이트
 
-13. Future API 문서를 메인 문서로 통합
-14. Get Started / Advanced 문서 재작성
-15. 마이그레이션 가이드 작성
-16. 네비게이션 구조 업데이트
+14. Future API 문서를 메인 문서로 통합
+15. Get Started / Advanced 문서 재작성
+16. 마이그레이션 가이드 작성
+17. 네비게이션 구조 업데이트
 
 ### Phase 6: 빌드 설정 정리
 
-17. `esbuild.config.js` - stable/future 분리 빌드 제거
-18. `tsconfig.json` - 관련 경로 설정 정리
+18. `esbuild.config.js` - stable/future 분리 빌드 제거
+19. `tsconfig.json` - 관련 경로 설정 정리
 
 ### Phase 7: 버전 및 릴리스
 
-19. Changeset 생성 (major bump)
-20. CHANGELOG 업데이트
-21. npm deprecate 실행 (`@stackflow/compat-await-push`, `@stackflow/plugin-preload`, `@stackflow/plugin-map-initial-activity`)
+20. Changeset 생성 (major bump)
+21. CHANGELOG 업데이트
+22. npm deprecate 실행 (`@stackflow/plugin-preload`, `@stackflow/plugin-map-initial-activity`)
 
 ---
 
@@ -323,7 +327,6 @@ integrations/react/src/future/            # 코드 이동 후 삭제
 integrations/react/src/__internal__/      # 디렉토리 전체 (필요한 코드는 통합 후)
 extensions/link/src/stable/               # 디렉토리 전체
 extensions/link/src/future/               # 코드 이동 후 삭제
-extensions/compat-await-push/             # 패키지 전체
 extensions/plugin-preload/                # 패키지 전체
 extensions/plugin-map-initial-activity/   # 패키지 전체
 docs/pages/api-references/future-api/     # 문서 이동 후 삭제
@@ -357,4 +360,5 @@ docs/pages/docs/migration-v2.ko.mdx       # 마이그레이션 가이드 (한국
 - **`@stackflow/config` 필수 의존성화** — 기존에는 Future API 사용자만 필요했으나 이제 필수
 - **모듈 선언 패턴 강제** — `declare module "@stackflow/config"` 패턴이 표준이 됨
 - **`__internal__` 코드 제거** — stable/future 양쪽에서 공유하던 내부 유틸리티를 제거하고 필요한 부분만 future 소스에 직접 통합
-- **삭제 패키지 3개** — `compat-await-push`, `plugin-preload`, `plugin-map-initial-activity` 삭제 후 npm deprecate 실행
+- **삭제 패키지 2개** — `plugin-preload`, `plugin-map-initial-activity` 삭제 후 npm deprecate 실행
+- **`@stackflow/compat-await-push` 유지** — `receive(push(...))` 패턴을 제공하며 Stackflow 내부 API와 독립적으로 동작하는 순수 유틸리티. v2에 대체 API가 없고 다수의 프로젝트에서 사용 중이므로 이번 마이그레이션에서는 유지. 향후 공식 대체 API가 설계되면 별도 트랙에서 다룬다

.tech-specs/tasks/01-delete-deprecated-packages.md

@@ -4,20 +4,19 @@
 
 ## 목적
 
-Stable API에서만 사용되거나 Future API에 내장된 기능으로 대체된 패키지 3개를 삭제한다.
+Future API에 내장된 기능으로 대체된 패키지 2개를 삭제한다.
 
-## 삭제 대상
-
-### 1. `@stackflow/compat-await-push`
+> **Note:** 초기 계획에서는 `@stackflow/compat-await-push`도 삭제 대상이었으나, 다음 사유로 **유지**한다.
+>
+> - `receive(push(...))` 패턴을 대체할 공식 API가 v2에 없음
+> - Stackflow 내부 API에 의존하지 않는 독립 유틸리티 (`resolveMap` 기반 Promise 패턴) — v1/v2 양쪽과 호환
+> - 조직 내 다수 활성 프로젝트가 의존 중
+>
+> 향후 v2 공식 대체 API가 설계되면 별도 트랙으로 다룬다.
 
-- **경로:** `extensions/compat-await-push/`
-- **이유:** Old API의 `await push()` 패턴 호환 레이어. Future API에서는 사용하지 않음
-- **작업:**
-  - `extensions/compat-await-push/` 디렉토리 전체 삭제
-  - 루트 `package.json` 워크스페이스 설정에서 제거 (해당하는 경우)
-  - 다른 패키지의 dependency/peerDependency에서 참조 제거
+## 삭제 대상
 
-### 2. `@stackflow/plugin-preload`
+### 1. `@stackflow/plugin-preload`
 
 - **경로:** `extensions/plugin-preload/`
 - **이유:** Future API의 `usePrepare()` 훅으로 대체
@@ -28,7 +27,7 @@ Stable API에서만 사용되거나 Future API에 내장된 기능으로 대체
   - 플러그인 문서 삭제: `docs/pages/api-references/plugins/plugin-preload.{en,ko}.mdx`
   - `docs/pages/api-references/plugins/_meta.{en,ko}.json`에서 항목 제거
 
-### 3. `@stackflow/plugin-map-initial-activity`
+### 2. `@stackflow/plugin-map-initial-activity`
 
 - **경로:** `extensions/plugin-map-initial-activity/`
 - **이유:** Future API의 `config.initialActivity`로 대체

.tech-specs/tasks/04-link-promote-future.md

@@ -60,10 +60,19 @@ export * from "./stable";
 
 - `esbuild.config.js` — stable/future 분리 빌드 엔트리포인트 제거
 
+### 7. `extensions/link/README.md` 업데이트
+
+`README.md`에서 삭제된 `@stackflow/plugin-preload` 관련 내용을 정리한다.
+
+- L7, L9-10, L20 등에서 `plugin-preload`를 peer dependency로 안내하는 부분 제거
+- v2 사용법에 맞춰 설치/사용 예시를 `import { Link } from "@stackflow/link"` 기반으로 업데이트
+- preload 관련 예시는 `usePrepare()` 기반으로 변경 또는 문서 링크만 유지
+
 ## 확인 사항
 
 - [ ] `yarn typecheck` 통과
 - [ ] `yarn build` 통과
 - [ ] `import { Link } from "@stackflow/link"` 가 future의 Link를 가리킴
 - [ ] `@stackflow/link/stable` import 시 에러
 - [ ] `@stackflow/link/future` import 시 에러
+- [ ] `extensions/link/README.md`에서 `plugin-preload` 언급이 모두 정리됨

.tech-specs/tasks/06-update-docs.md

@@ -15,13 +15,18 @@ Future API 문서를 메인 문서로 통합하고, 기존 문서를 새 API에
 - `docs/pages/api-references/future-api/_meta.{en,ko}.json`
 
 **이동:**
-- `future-api/loader-api.{en,ko}.mdx` → `docs/pages/docs/get-started/` 또는 `docs/pages/docs/advanced/`
 - `future-api/code-splitting.{en,ko}.mdx` → `docs/pages/docs/advanced/`
 - `future-api/api-pipelining.{en,ko}.mdx` → `docs/pages/docs/advanced/`
 - `future-api/api-pipelining-diagram-1.png` → 함께 이동
 - `future-api/config.{en,ko}.mdx` → `docs/pages/api-references/` 또는 get-started에 통합
 - `future-api/changes.{en,ko}.mdx` → 마이그레이션 가이드 작성 시 참고 자료로 활용
 
+**Loader API 문서 통합:**
+- `future-api/loader-api.{en,ko}.mdx` 와 `docs/pages/docs/advanced/preloading.{en,ko}.mdx` 의 내용이 상당 부분 중복됨
+- `loader-api.{en,ko}.mdx` 는 삭제하고, `preloading.{en,ko}.mdx` 에 내용을 통합
+- `preloading.{en,ko}.mdx` 제목을 "Loader API"로 변경
+- `_meta.{en,ko}.json`에서 `loader-api` 항목 제거, `preloading` 항목 라벨을 "Loader API"로 변경
+
 **최종 삭제:**
 - `docs/pages/api-references/future-api/` 디렉토리 전체
 
@@ -30,13 +35,11 @@ Future API 문서를 메인 문서로 통합하고, 기존 문서를 새 API에
 **`docs/pages/api-references/_meta.{en,ko}.json`:**
 - `"future-api"` 항목 제거
 - 필요시 `"config"` 항목 추가
+- **KO 전용:** `@stackflow/config` 엔트리 라벨을 `설정`으로 번역
 
 **`docs/pages/docs/advanced/_meta.{en,ko}.json`:**
 - `"code-splitting"`, `"api-pipelining"` 항목 추가
 
-**`docs/pages/docs/get-started/_meta.{en,ko}.json`:**
-- `"loader-api"` 항목 추가 (또는 advanced에 배치)
-
 ### 3. Get Started 문서 재작성
 
 | 문서 | 변경 내용 |
@@ -52,8 +55,29 @@ Future API 문서를 메인 문서로 통합하고, 기존 문서를 새 API에
 | 문서 | 변경 내용 |
 |------|----------|
 | `history-sync` | Config 기반 라우트 설정으로 변경 (route를 config에 선언) |
-| `preloading` | `usePrepare()` 기반으로 전면 재작성, plugin-preload 언급 제거 |
-| `write-plugin` | 필요시 업데이트 |
+| `preloading` | `usePrepare()` + Loader API 기반으로 전면 재작성, plugin-preload 언급 제거, 제목을 "Loader API"로 변경 |
+| `write-plugin` | lifecycle hook 이름 수정 + 오타 교정 (아래 별도 항목) |
+
+**`plugin-history-sync` 문서 v2 업데이트:**
+- `docs/pages/api-references/plugins/plugin-history-sync.{en,ko}.mdx` 가 v1 API 패턴을 그대로 사용 중
+  - `const { Stack, useFlow } = stackflow({ activities: { ... } })` 형태 → config-first 패턴으로
+  - `routes` 옵션은 이제 `defineConfig()` 의 activity 선언에서 지정
+- v2 config-first 패턴으로 전면 업데이트
+
+**`resolving-circular-reference` 문서 삭제:**
+- v2에서는 `useFlow` 를 `@stackflow/react`에서 직접 import 하므로 순환참조 문제가 발생하지 않음
+- 해당 문서가 참조하는 `useActions` API 는 v2에 존재하지 않음
+- 삭제 대상:
+  - `docs/pages/docs/advanced/resolving-circular-reference.en.mdx`
+  - `docs/pages/docs/advanced/resolving-circular-reference.ko.mdx`
+  - `docs/pages/docs/advanced/_meta.{en,ko}.json` 에서 해당 항목 제거
+
+**`write-plugin` 문서 수정:**
+- 존재하지 않는 lifecycle hook `initialPushedEvent` → `overrideInitialEvents` 로 교정
+  - `docs/pages/docs/advanced/write-plugin.en.mdx:261, 272`
+  - `docs/pages/docs/advanced/write-plugin.ko.mdx:269, 280`
+- `write-plugin.ko.mdx:262` 오타 교정
+  - `G현재 스택의 상태를 가져올 수 있어��` → `현재 스택의 상태를 가져올 수 있어요`
 
 ### 5. 플러그인 문서 정리
 
@@ -62,8 +86,20 @@ Future API 문서를 메인 문서로 통합하고, 기존 문서를 새 API에
 - `docs/pages/api-references/plugins/plugin-map-initial-activity.{en,ko}.mdx`
 - `_meta.{en,ko}.json`에서 해당 항목 제거
 
-**수정:**
-- `plugins/link.{en,ko}.mdx` — `createLinkComponent` 제거, 직접 `import { Link }` 패턴으로 변경
+**`plugins/link.{en,ko}.mdx` 수정:**
+- `createLinkComponent` 제거, 직접 `import { Link } from "@stackflow/link"` 패턴으로 변경
+- **`animate` prop 기본값 설명 수정**
+  - 현재: "If not provided, it defaults to no animation."
+  - 실제 소스 (`extensions/link/src/Link.tsx:89-99`): `animate`가 undefined/null이면 빈 옵션 `{}`가 push/replace에 전달되어 **기본 애니메이션이 적용**됨
+  - 수정 방향: "If not provided, the default animation is applied (same as `animate: true`)."
+- **`urlPatternOptions` prop 제거**
+  - 실제 `LinkProps` (`extensions/link/src/Link.tsx:24-31`)에는 존재하지 않는 prop
+  - `urlPatternOptions` 는 `config.historySync` 에서 내부적으로 사용되는 옵션이며 사용자 prop이 아님
+  - 문서에서 해당 prop 설명 전체 삭제 (en/ko L47)
+- **`ref` 타입 정정**
+  - 현재: `React.ForwardedRef<HTMLAnchorElement>`
+  - 실제 소스: `React.RefObject<HTMLAnchorElement>`
+  - `link.en.mdx:48`, `link.ko.mdx:48` 수정
 
 ### 6. 마이그레이션 가이드 작성
 
@@ -75,10 +111,49 @@ Future API 문서를 메인 문서로 통합하고, 기존 문서를 새 API에
 - v1 → v2 마이그레이션 단계별 안내
 - API 대응표 (Before/After)
 - `changes.{en,ko}.mdx` 내용 통합 및 확장
-- 삭제된 패키지 대체 방법
+- 삭제된 패키지 대체 방법 (`plugin-preload` → `usePrepare`, `plugin-map-initial-activity` → `config.initialActivity`)
 - 타입 시스템 변경 (컴포넌트 Props → Config Register)
 
-### 7. 문서 내 "Future API" 언급 일괄 제거
+**작성 시 주의점:**
+- "Before" 예시가 묵시적 파일 경로(`./stackflow`) 에 의존하지 않도록, `stackflow()` 팩토리에서 `useFlow`를 destructuring하여 export하는 전체 맥락을 보여줄 것
+- API 대응표에서도 `./stackflow` 표기 대신 `stackflow()` 팩토리 반환값임을 명시
+  - Before: `| `useFlow()` from `./stackflow` | `useFlow()` from `@stackflow/react` |`
+  - After: `| `useFlow()` (returned from `stackflow()` factory) | `useFlow()` from `@stackflow/react` |`
+
+### 7. Loader API 관련 문서 import 경로 수정
+
+여러 문서에서 `ActivityLoaderArgs`를 `@stackflow/react`에서 import하도록 안내하고 있으나, 이 타입은 `@stackflow/config`에서만 export된다.
+
+**소스 근거:**
+- `config/src/index.ts:4` — `export * from "./ActivityLoaderArgs"`
+- `integrations/react/src/loader/useLoaderData.ts:1` — `import type { ActivityLoaderArgs } from "@stackflow/config"` (내부 사용만, re-export 없음)
+
+**수정 대상:**
+| 파일 | 라인 | 수정 방향 |
+|------|------|----------|
+| `docs/pages/docs/advanced/loader-api.en.mdx` | L6 | `ActivityLoaderArgs`는 `@stackflow/config`에서 import |
+| `docs/pages/docs/advanced/loader-api.ko.mdx` | L6 | 동일 |
+| `docs/pages/docs/advanced/preloading.en.mdx` | L12 | 동일 |
+| `docs/pages/docs/advanced/preloading.ko.mdx` | L12 | 동일 |
+
+**수정안 (예시):**
+```tsx
+import type { ActivityLoaderArgs } from "@stackflow/config";
+import { useLoaderData } from "@stackflow/react";
+```
+
+> 참고: 위 4.의 "Loader API 문서 통합" 작업 시 `loader-api.*.mdx` 는 삭제되므로, 통합 대상인 `preloading.*.mdx` 의 import 경로를 위 기준으로 맞춘다.
+
+### 8. `structured-activity` 문서 개선
+
+- `content` 컴포넌트 예시를 단순화 — `useActivityParams` 대신 매개변수로 `params` 를 직접 받도록 변경
+- 페이지 말미의 "API" 섹션은 별도 API 레퍼런스 페이지를 신설할 계획이므로 이번 PR에서 제거
+- Line highlighting 정정 (EN/KO 모두)
+  - Loading State (`Article.tsx`): `{3,7}` → `{2,6}` (빈 줄/닫는 괄호가 아니라 import와 `loading:` 줄 강조)
+  - Layout (`Article.tsx`): `{3,4,8,9}` → `{2,7}` (import와 `layout:` 줄 강조)
+  - With Loader API (`stackflow.config.ts`): `{8}` → `{2,9}` (`route`가 아니라 `import articleLoader`와 `loader:` 줄 강조)
+
+### 9. 문서 내 "Future API" 언급 일괄 제거
 
 모든 문서에서:
 - "Future API" → 그냥 API (또는 제거)
@@ -92,3 +167,7 @@ Future API 문서를 메인 문서로 통합하고, 기존 문서를 새 API에
 - [ ] 깨진 링크 없음
 - [ ] EN/KO 양쪽 동기화
 - [ ] "future" 또는 "/future" 문자열이 문서에 남아있지 않음
+- [ ] `ActivityLoaderArgs` import 경로가 `@stackflow/config` 로 일관되게 수정됨
+- [ ] `@stackflow/link` API 레퍼런스가 실제 `LinkProps` 시그니처와 일치
+- [ ] `resolving-circular-reference` 문서 및 `_meta` 항목이 모두 제거됨
+- [ ] `write-plugin` 의 lifecycle hook 이름이 실제 API와 일치 (`overrideInitialEvents`)

.tech-specs/tasks/07-changesets-release.md

@@ -16,11 +16,12 @@ Major bump 대상 패키지:
 - `@stackflow/core` — 메이저 버전 동기화 (변경 없지만 2.0 생태계 통일)
 - `@stackflow/config` — 메이저 버전 동기화
 
+> **Note:** `@stackflow/compat-await-push`는 이번 마이그레이션에서 삭제하지 않으므로 deprecate 대상이 아니다.
+
 ### 2. npm deprecate 대상
 
 릴리스 후 실행:
 ```bash
-npm deprecate @stackflow/compat-await-push "Removed in Stackflow 2.0. Use event-based patterns instead."
 npm deprecate @stackflow/plugin-preload "Removed in Stackflow 2.0. Use usePrepare() from @stackflow/react instead."
 npm deprecate @stackflow/plugin-map-initial-activity "Removed in Stackflow 2.0. Use config.initialActivity instead."
 ```
@@ -32,7 +33,6 @@ npm deprecate @stackflow/plugin-map-initial-activity "Removed in Stackflow 2.0.
 - **BREAKING:** `@stackflow/react` — `./stable`, `./future` 하위 경로 제거
 - **BREAKING:** `@stackflow/link` — `createLinkComponent` 제거, `Link` 직접 import
 - **BREAKING:** `@stackflow/link` — `./stable`, `./future` 하위 경로 제거
-- **REMOVED:** `@stackflow/compat-await-push` 패키지 삭제
 - **REMOVED:** `@stackflow/plugin-preload` 패키지 삭제
 - **REMOVED:** `@stackflow/plugin-map-initial-activity` 패키지 삭제
 - **NEW:** `useLoaderData`, `useConfig`, `usePrepare`, `lazy`, `structuredActivityComponent` 기본 제공