feat: add Collection.ForkCount for lineage-wide fork counting (#475)

* docs(13): capture phase context

* docs(state): record phase 13 context session

* docs(13): research collection ForkCount implementation

* docs(phase-13): add validation strategy

* docs(13): create phase plan for Collection.ForkCount

* feat(13-01): add ForkCount to Collection interface with HTTP and embedded implementations

- Add ForkCount(ctx) (int, error) to Collection interface
- HTTP impl issues GET to /fork_count and decodes JSON {count: n}
- Embedded impl returns explicit unsupported error

* test(13-01): add ForkCount unit tests for HTTP and embedded paths

- HTTP happy path: server returns {"count":5}, assert result == 5
- HTTP error path: server returns 500, assert error returned
- Embedded path: assert unsupported error message

* docs(13-01): complete Collection ForkCount interface and implementations plan

- Add 13-01-SUMMARY.md with execution results
- Update STATE.md position and metrics
- Update ROADMAP.md progress

* docs(13-02): add ForkCount section to collection forking docs

- Add "Checking Fork Count" section with Python and Go code examples
- Add ForkCount row to Fork API Reference table
- Add lineage-wide semantics note to Notes section

* feat(13-02): add runnable Fork + ForkCount example

- Create examples/v2/fork_count/main.go demonstrating Fork followed by ForkCount
- Show lineage-wide semantics where source and fork report same count
- Use run() pattern to satisfy gocritic exitAfterDefer lint rule

* docs(13-02): complete ForkCount documentation and example plan

- Add 13-02-SUMMARY.md with task results and deviations
- Update STATE.md with plan progress and metrics
- Update ROADMAP.md with phase 13 completion status
- Mark FC-05, FC-06 requirements complete

* docs(phase-13): complete phase execution

* docs(phase-13): evolve PROJECT.md after phase completion

* Fix cloud-only fork count docs and example

* Polish fork count docs and example comments

* docs(13): ship phase 13 — PR #475

Author: tazarov

.planning/PROJECT.md

@@ -71,4 +71,4 @@ Go applications can use Chroma and embedding providers through a stable, portabl
 | Pivot Phase 7 from vLLM/Nemotron to VoyageAI | vLLM lacks NVOmniEmbedModel support; VoyageAI multimodal validates portability with text/image/video | ✓ Good |
 
 ---
-*Last updated: 2026-03-28 — Phase 12 (SDK auto-wiring research) complete: verified auto-wiring behavior across Python, JS, Rust, and chroma-go SDKs. All Go-specific enhancements documented as deliberate; no removals recommended.*
+*Last updated: 2026-03-28 — Phase 13 (Collection ForkCount) complete: added ForkCount method to Collection interface with HTTP and embedded implementations, unit tests, documentation, and runnable example.*

.planning/REQUIREMENTS.md

@@ -67,6 +67,15 @@
 - [x] **FORK-03**: Shared EFs are wrapped in a `sync.Once`-based close-once adapter that makes `Close()` idempotent as defence-in-depth
 - [x] **FORK-04**: Tests cover Fork + Close lifecycle including idempotent close, use-after-close errors, and ownership gating without panics
 
+### Collection ForkCount
+
+- [ ] **FC-01**: `pkg/api/v2.Collection` interface includes `ForkCount(ctx context.Context) (int, error)`
+- [ ] **FC-02**: HTTP implementation issues `GET .../fork_count` and decodes `{"count": n}` using strict struct with `json:"count"` tag
+- [ ] **FC-03**: Embedded/local implementation returns explicit unsupported error matching existing Fork/Search pattern
+- [ ] **FC-04**: Tests cover HTTP happy path, HTTP failure path, and embedded unsupported path
+- [x] **FC-05**: Forking docs page includes ForkCount section with Go and Python examples and API reference row
+- [x] **FC-06**: Runnable Fork + ForkCount example exists under `examples/v2/`
+
 ## v2 Requirements
 
 ### Provider Adoption
@@ -127,12 +136,18 @@
 | FORK-02 | Phase 11 | Complete |
 | FORK-03 | Phase 11 | Complete |
 | FORK-04 | Phase 11 | Planned |
+| FC-01 | Phase 13 | Planned |
+| FC-02 | Phase 13 | Planned |
+| FC-03 | Phase 13 | Planned |
+| FC-04 | Phase 13 | Planned |
+| FC-05 | Phase 13 | Planned |
+| FC-06 | Phase 13 | Planned |
 
 **Coverage:**
-- v1 requirements: 35 total
-- Mapped to phases: 35
+- v1 requirements: 41 total
+- Mapped to phases: 41
 - Unmapped: 0
 
 ---
 *Requirements defined: 2026-03-18*
-*Last updated: 2026-03-26 -- added FORK-01/02/03/04 for phase 11*
+*Last updated: 2026-03-28 -- added FC-01/02/03/04/05/06 for phase 13*

.planning/ROADMAP.md

@@ -26,7 +26,7 @@ This roadmap initializes GSD planning for the current brownfield milestone focus
 - [x] **Phase 10: Code Cleanups** - Extract shared path safety utilities, fix *context.Context anti-pattern, add registry test cleanup, fix resolveMIME for URL-backed sources. (issues #456, #461, #466, #469) (completed 2026-03-26)
 - [x] **Phase 11: Fork Double-Close Bug** - Fix EF pointer sharing in Fork() that causes double-close on client.Close(). (issue #454) (completed 2026-03-26)
 - [x] **Phase 12: SDK Auto-Wiring Research** - Trace contentEmbeddingFunction auto-wiring behavior in official Chroma SDKs. (issue #455) (completed 2026-03-28)
-- [ ] **Phase 13: Collection.ForkCount** - Add ForkCount endpoint support for upstream /fork_count API. (issue #460)
+- [x] **Phase 13: Collection.ForkCount** - Add ForkCount endpoint support for upstream /fork_count API. (issue #460) (completed 2026-03-28)
 - [ ] **Phase 14: Delete with Limit** - Add delete-with-limit support for upstream limit parameter. (issue #439)
 - [ ] **Phase 15: OpenRouter Embeddings Compatibility** - Add first-class OpenRouter support via provider preferences and encoding_format. (issue #438)
 - [ ] **Phase 16: Twelve Labs Embedding Function** - Add Twelve Labs multimodal embedding provider. (issue #190)
@@ -177,7 +177,7 @@ Plans:
 | 10. Code Cleanups | 2/2 | Complete    | 2026-03-26 |
 | 11. Fork Double-Close Bug | 2/2 | Complete    | 2026-03-26 |
 | 12. SDK Auto-Wiring Research | 1/1 | Complete    | 2026-03-28 |
-| 13. Collection.ForkCount | 0/0 | Not started | - |
+| 13. Collection.ForkCount | 2/2 | Complete    | 2026-03-28 |
 | 14. Delete with Limit | 0/0 | Not started | - |
 | 15. OpenRouter Embeddings | 0/0 | Not started | - |
 | 16. Twelve Labs EF | 0/0 | Not started | - |
@@ -257,10 +257,10 @@ Plans:
   3. Embedded/local behavior returns an explicit unsupported error.
   4. Tests cover HTTP happy path, failure path, and embedded unsupported path.
   5. Forking docs mention the new method.
-**Plans:** 0 plans
+**Plans:** 2/2 plans complete
 
 Plans:
-- [ ] TBD (run /gsd:plan-phase 13 to break down)
+- [x] TBD (run /gsd:plan-phase 13 to break down) (completed 2026-03-28)
 
 ### Phase 14: Delete with Limit
 **Goal:** Add limit parameter support to collection delete operations, matching upstream Chroma PRs #6573/#6582.

.planning/STATE.md

@@ -2,14 +2,14 @@
 gsd_state_version: 1.0
 milestone: v0.4.1
 milestone_name: Provider-Neutral Multimodal Foundations
-status: Ready to plan
-stopped_at: Phase 12 context gathered
-last_updated: "2026-03-28T13:06:51.466Z"
+status: "Phase 13 shipped — PR #475"
+stopped_at: Completed 13-02-PLAN.md
+last_updated: "2026-03-29T14:41:08.046Z"
 progress:
   total_phases: 18
-  completed_phases: 12
-  total_plans: 27
-  completed_plans: 27
+  completed_phases: 13
+  total_plans: 29
+  completed_plans: 29
 ---
 
 # Project State
@@ -23,7 +23,7 @@ See: .planning/PROJECT.md (updated 2026-03-18)
 
 ## Current Position
 
-Phase: 13
+Phase: 14
 Plan: Not started
 
 ## Performance Metrics
@@ -70,6 +70,8 @@ Plan: Not started
 | Phase 10 P02 | 7min | 2 tasks | 6 files |
 | Phase 11 P01 | 3min | 2 tasks | 4 files |
 | Phase 11 P02 | 1min | 1 tasks | 1 files |
+| Phase 13 P01 | 2min | 2 tasks | 5 files |
+| Phase 13 P02 | 2min | 2 tasks | 2 files |
 
 ## Accumulated Context
 
@@ -121,6 +123,8 @@ Recent decisions affecting current work:
 - [Phase 11]: Forked collections get close-once wrapped copies of parent EFs, preventing double-close even if ownsEF check is bypassed
 - [Phase 11]: Use atomic.Int32 close counters in mocks to verify exact call counts without race conditions
 - [Phase 11]: Test ownership gating via direct struct construction - no server required
+- [Phase 13]: Follow IndexingStatus GET+JSON pattern for ForkCount HTTP implementation
+- [Phase 13]: Use run() pattern in fork_count example to satisfy gocritic exitAfterDefer lint rule
 
 ### Roadmap Evolution
 
@@ -153,6 +157,6 @@ None.
 
 ## Session
 
-**Last Date:** 2026-03-28T09:27:37.840Z
-**Stopped At:** Phase 12 context gathered
-**Resume File:** .planning/phases/12-sdk-auto-wiring-research/12-CONTEXT.md
+**Last Date:** 2026-03-28T15:25:22.491Z
+**Stopped At:** Completed 13-02-PLAN.md
+**Resume File:** None