docs: seed Golden Context

.bito.yaml

@@ -0,0 +1,17 @@
+suggestion_mode: comprehensive
+post_description: true
+post_changelist: true
+exclude_files: 'Gemfile.lock'
+exclude_draft_pr: false
+secret_scanner_feedback: true
+linters_feedback: true
+repo_level_guidelines_enabled: true
+sequence_diagram_enabled: true
+custom_guidelines:
+  general:
+    - name: 'Review Posture'
+      path: './.bito/guidelines/review-posture.txt'
+    - name: 'Repo Truth And Alignment'
+      path: './.bito/guidelines/repo-truth-and-boundaries.txt'
+    - name: 'Domain Invariants'
+      path: './.bito/guidelines/domain-invariants.txt'

.bito/guidelines/domain-invariants.txt

@@ -0,0 +1,34 @@
+Critical invariants for the contentful.rb Ruby SDK:
+
+READ-ONLY SDK
+- This library wraps the Content Delivery API only. Never add write, create, update, or delete operations — those belong to contentful-management.rb.
+
+SNAKE_CASE DEFAULT
+- All public field accessors and hash keys must use snake_case by default. Support.snakify must always receive @configuration[:use_camel_case] as its second argument — missing this flag causes camelCase fields to be inaccessible when use_camel_case: true is set (this has been a recurring bug).
+
+RESOURCE REGISTRATION
+- Every new resource type must be added to ResourceBuilder::DEFAULT_RESOURCE_MAPPING and BUILDABLES in resource_builder.rb, or it will not be instantiated from API responses.
+
+INCLUDE RESOLUTION DEPTH
+- Never remove or bypass max_include_resolution_depth when resolving linked resources. Content models can be circular; this cap prevents infinite recursion and stack overflow.
+
+REUSE_ENTRIES + CACHING INCOMPATIBILITY
+- reuse_entries: true must not be enabled alongside caching frameworks (Rails.cache, etc.). Document this clearly in any feature that interacts with entry hydration or marshalling.
+
+MARSHALLING
+- BaseResource#marshal_dump excludes the logger (file handles can't be serialized). Do not add non-serializable objects to @configuration without a corresponding marshal_dump exclusion.
+
+BUNDLER VERSION
+- All scripts and CI commands must use bundle _2.3.26_ install, not bare bundle install. The devcontainer pins this version for reproducibility.
+
+NO ENV VARS
+- The library reads no environment variables. All configuration is explicit via Client.new(...). Do not introduce ENV reads.
+
+MASTER BRANCH
+- The default branch is master, not main. CI workflows and merge rules target master.
+
+CONTENT TYPE CACHE SCOPE
+- ContentTypeCache is a global, module-level cache. In multi-space applications, cache_get/set is keyed by space_id:content_type_id. Be aware of potential collisions if two spaces happen to use the same content type ID.
+
+RUBOCOP SCOPE
+- RuboCop is configured to lint lib/ only. spec/, examples/, Gemfile, Rakefile, and contentful.gemspec are excluded. Do not add RuboCop enforcement to spec files.

.bito/guidelines/repo-truth-and-boundaries.txt

@@ -0,0 +1,9 @@
+Use the repository's written documentation as review context and check whether the change matches the documented intent.
+
+- Start from README.md, ARCHITECTURE.md, AGENTS.md, CONTRIBUTING.md, and docs/ADRs/ for architectural context.
+- Check whether code, tests, and documentation all tell the same story. Flag mismatches between implementation and the documented architecture or ADRs.
+- Treat AGENTS.md as the authoritative guide for sharp edges and invariants. If a change violates an invariant documented there, flag it.
+- If CI or another required check already enforces a merge rule, do not ask for duplicate PR template sections or manual checklists.
+- Ask for an ADR update when a change is architecture-significant: new resource type, new client configuration option, new HTTP dependency, change to the resource hierarchy, or new external API endpoint.
+- Distinguish the public client API and resource interface (used by gem consumers) from internal implementation details. Public-facing changes require extra scrutiny and CHANGELOG entries.
+- New resource types must be registered in ResourceBuilder::DEFAULT_RESOURCE_MAPPING and BUILDABLES, or they will silently not be built.

.bito/guidelines/review-posture.txt

@@ -0,0 +1,8 @@
+Review this pull request like the tech lead of the contentful.rb Ruby SDK project.
+
+- This is a public-facing gem used by thousands of Ruby developers. Treat the public API surface (Client config options, resource class interfaces, field accessors) with extra scrutiny — breaking changes require a major semver bump and a migration guide.
+- Prefer a few high-signal findings to a long list of minor or style-only comments. RuboCop handles style; focus on behavior, contracts, runtime correctness, and documentation issues.
+- Keep feedback actionable: explain why it matters, how it would surface in practice, and the clearest next step.
+- If a concern is only a risk or assumption rather than a confirmed bug, say that clearly and explain what evidence would confirm it.
+- If you find no issues, say so explicitly and call out any residual uncertainty that still deserves human attention.
+- Do not ask for duplicate PR template sections, checklists, or manual validation acknowledgements when CI already enforces that policy.

AGENTS.md

@@ -0,0 +1,56 @@
+# Agent Guide
+
+<!-- Generated by seed-golden-context | Last updated: 2026-05-05 -->
+
+Read this file first. It tells you where to find context in this repo.
+
+## Quick Reference
+
+| What you need | Where to look |
+|---|---|
+| What this library does | [README.md](./README.md) |
+| How this repo is structured | [ARCHITECTURE.md](./ARCHITECTURE.md) |
+| How to build/test/run | [CONTRIBUTING.md](./CONTRIBUTING.md) |
+| Why decisions were made | [docs/ADRs/](./docs/ADRs/) |
+| Active specs/work | [docs/specs/](./docs/specs/) |
+| PR review rules | [.bito/guidelines/](./.bito/guidelines/) |
+| Release process | [RELEASE.md](./RELEASE.md) and ARCHITECTURE.md → Operational Knowledge |
+
+## Sharp Edges & Invariants
+
+- **Read-only SDK.** This library wraps the CDA (Content Delivery API) only — no write operations. All management operations belong to `contentful-management.rb`.
+- **`snake_case` is the default.** All field accessors and hash keys are `snake_case` unless `use_camel_case: true` is set. Internal `Support.snakify` must be called with `@configuration[:use_camel_case]` consistently — missing this flag is a known source of bugs (see ADR 002).
+- **`max_include_resolution_depth` prevents infinite recursion.** Do not remove or bypass this cap when resolving linked resources — content models can be circular.
+- **`reuse_entries: true` is incompatible with caching.** Rails.cache and similar caching layers can cause marshal/stack errors when this option is enabled. Do not enable both.
+- **No environment variables.** The library reads no `ENV` vars. All configuration is passed via `Contentful::Client.new(...)`.
+- **`ContentTypeCache` is global and mutable.** `ContentTypeCache.cache_get/set` is keyed by `space_id:content_type_id`. In multi-tenant or multi-space apps, cache collisions are possible if two spaces share content type IDs.
+- **Bundler version is pinned.** CI and devcontainer use Bundler `2.3.26`. Use `bundle _2.3.26_ install` — `bundle install` alone may use a different version.
+- **`master` is the main branch** — not `main`. PRs and CI are wired to `master`.
+- **No CD pipeline.** Releases are manual via `bundle exec rake release`. Do not auto-push tags or publish gems without following the release checklist in RELEASE.md.
+- **RuboCop excludes `spec/`, `examples/`, and config files.** Only `lib/` is linted. Do not run RuboCop manually on spec files expecting passing output.
+
+## Key Conventions
+
+- **Commit format:** No enforced format; conventional-style (`feat:`, `fix:`, `chore:`) preferred per recent history
+- **Branch strategy:** `master` + feature branches; open PRs to `master`
+- **Test location:** `spec/` — mirrors `lib/contentful/` one spec file per source file
+- **Ruby style:** `snake_case` methods and variables, `frozen_string_literal: true` on all `lib/` files
+- **HTTP mocking:** VCR + WebMock — never make live API calls in tests
+
+## Integration Points
+
+**Upstream (this repo consumes):**
+- Contentful CDA (`cdn.contentful.com`) — REST API for reading Spaces, Entries, Assets, ContentTypes, Locales, TaxonomyConcepts
+- Contentful CPA (`preview.contentful.com`) — same interface, returns draft content
+
+**Downstream (consumes this repo):**
+- End-user Ruby apps (Rails, Sinatra, scripts) — via `gem 'contentful'` in their Gemfile
+- `contentful-management.rb` — sibling SDK for write operations (separate gem, separate repo)
+- `rich-text-renderer.rb` — Ruby renderer for RichText field values (separate gem)
+
+## Build & Quality
+
+```bash
+# Quick verification loop (same as CI)
+bundle _2.3.26_ install && bundle exec rake rspec_rubocop
+```