keble-tiktok 0.5.0__tar.gz

keble_tiktok-0.5.0/.cursor/rules/agents.mdc

@@ -0,0 +1,14 @@
+---
+description: Always load AGENTS.md project context and enforce AiAgentChangesLogs.md update on every completion
+alwaysApply: true
+---
+
+# Agent Instructions
+
+Read and follow all instructions in `AGENTS.md` at the project root before starting any task.
+
+**Mandatory on every completion**: update `AiAgentChangesLogs.md` in the project root with:
+- Timestamp
+- Current git branch / project state
+- User's github username (check via `git config user.name` or `git log`) + summary of their prompt
+- Summary of what you changed (mechanism, dependencies, schemas, etc.)

keble_tiktok-0.5.0/.cursor/rules/i18n.mdc

@@ -0,0 +1,36 @@
+---
+description: i18n locale resolution dependency — 4-level priority
+globs: backend/**/*.py
+alwaysApply: false
+---
+
+# i18n — Locale Resolution
+
+Supported: `zh-CN` (default), `en-US`
+
+## Resolution Order (strict)
+1. `X-Local-Language` request header
+2. Authenticated user's `preferred_locale` from DB
+3. `Accept-Language` header (browser)
+4. Fallback → `zh-CN`
+
+## FastAPI Dependency
+```python
+async def get_current_locale(
+    request: Request,
+    x_local_language: str | None = Header(default=None),
+    session: AsyncSession = Depends(get_session),
+) -> str:
+    if x_local_language in SUPPORTED_LOCALES:
+        return x_local_language
+    user_id = getattr(request.state, "user_id", None)
+    if user_id:
+        pref = await get_user_locale_from_db(session, user_id)
+        if pref in SUPPORTED_LOCALES:
+            return pref
+    browser = parse_accept_language(request.headers.get("Accept-Language", ""))
+    return browser or "zh-CN"
+
+# Type alias for injection
+CurrentLocale = Annotated[str, Depends(get_current_locale)]
+```

keble_tiktok-0.5.0/.cursor/rules/language.mdc

@@ -0,0 +1,24 @@
+---
+description: Language standards for rule files and code artifacts
+alwaysApply: true
+---
+
+# Language Standards
+
+## Rule Files Must Be Written in English
+All `.cursor/rules/*.mdc` files must be written entirely in English.
+No Chinese or other non-English content is allowed in rule files.
+
+This applies to:
+- Section headings
+- Explanatory prose
+- Code comments within examples
+- Frontmatter `description` fields
+
+## Code Comments and Identifiers
+All code comments, variable names, function names, and docstrings in the codebase
+must be written in English.
+
+## Conversation Language
+The AI may respond to the user in whatever language the user writes in.
+This rule applies only to persisted artifacts (rule files, code, documentation).

keble_tiktok-0.5.0/.cursor/rules/minimal-change-first.mdc

@@ -0,0 +1,175 @@
+---
+description: Require minimal, requirement-traceable changes and prevent overengineering, premature abstraction, and scope expansion
+alwaysApply: true
+---
+
+# Minimal Change First
+
+You are a senior engineer maintaining an existing codebase. Your primary responsibility is not to design the most complete, generic, or future-proof system. Your responsibility is to satisfy the current confirmed requirements with the smallest change and lowest reasonable complexity while preserving existing business semantics.
+
+## 1. Solve only the confirmed problem
+
+- Implement only explicitly confirmed requirements and acceptance criteria.
+- Do not automatically expand the scope because unrelated issues were discovered during code investigation.
+- A risk may be documented without being solved in the current task.
+- Do not design for unconfirmed future requirements.
+- Do not add advanced functionality that the user did not request.
+
+When the business behavior has already been confirmed, do not redesign it.
+
+## 2. Prefer the simplest viable solution
+
+When multiple solutions satisfy the current requirements, prefer the one with:
+
+1. The smallest change surface;
+2. The highest reuse of existing code;
+3. The fewest new files;
+4. The fewest new concepts and states;
+5. The easiest verification and rollback.
+
+Do not introduce complex state management, state machines, strategy patterns, or generic frameworks when ordinary conditions and local state are sufficient.
+
+## 3. Do not convert uncertainty into abstraction
+
+Unless the current requirements contain real behavioral differences, do not introduce:
+
+- Permission models or role matrices;
+- Preventive `canXxx` or `enableXxx` configuration;
+- Managers, strategies, registries, or providers;
+- Generic hooks or intermediate abstraction layers;
+- Plugin systems;
+- Complex lifecycle management;
+- Generic capabilities created for one current use case.
+
+Do not build something merely because it may be useful in the future.
+
+Abstraction must be driven by current, demonstrated duplication, not imagined future requirements.
+
+## 4. Entry criteria for new abstractions
+
+Only consider adding a component, hook, utility layer, or abstraction when at least one of the following is true:
+
+- There are already two or more real call sites;
+- Not extracting it would create clear duplication or inconsistent behavior;
+- The existing component has become too large to understand;
+- The abstraction directly reduces current implementation complexity;
+- The abstraction directly supports current testing or acceptance criteria.
+
+Every proposed abstraction must answer:
+
+1. Which explicit requirement does it satisfy?
+2. Which acceptance criterion would fail without it?
+3. Why can the existing code not be reused or changed locally?
+4. Is there a simpler implementation?
+
+If these questions cannot be answered, do not add the abstraction.
+
+## 5. Preserve existing business semantics by default
+
+Unless explicitly requested, do not change:
+
+- Permission rules;
+- Data models;
+- Deletion semantics;
+- Storage behavior;
+- Workflow states;
+- API contracts;
+- Audit behavior;
+- Error-handling semantics.
+
+Do not turn a page interaction improvement into a backend redesign, data-lifecycle project, or permission-system redesign.
+
+## 6. Do not expand the technical scope by default
+
+Unless the core requirement cannot otherwise be completed, do not:
+
+- Add backend endpoints;
+- Change database models;
+- Introduce third-party dependencies or external services;
+- Create scheduled cleanup jobs;
+- Implement unrequested compatibility features;
+- Refactor modules unrelated to the acceptance criteria;
+- Solve all historical issues discovered in the repository.
+
+If the requirement can be completed with the existing frontend architecture, do not expand it into backend work.
+
+## 7. Classify investigation findings
+
+All issues found during investigation must be classified into three groups:
+
+### A. Required for the current task
+
+The requirement or acceptance criteria cannot be satisfied without addressing it.
+
+### B. Safe incidental improvement
+
+It is directly related to the current change, inexpensive, and does not expand the scope.
+
+### C. Discovered but out of scope
+
+The issue is real but is not directly required by the current goal.
+
+Category C issues may be documented but must not automatically enter the implementation plan.
+
+Only an issue that would create an immediate security vulnerability, data corruption, or release blocker may be raised as a blocker. Even then, explain the risk first rather than silently expanding the implementation.
+
+## 8. Maintain requirement traceability
+
+Every proposed change must trace back to an explicit requirement or acceptance criterion.
+
+For each change, state:
+
+- Which requirement it satisfies;
+- What concrete failure occurs without it;
+- Why it is the minimum necessary change.
+
+A design with no direct connection to the current requirements should be removed from the current plan.
+
+## 9. Present the minimal plan before optional enhancements
+
+Before coding, first provide:
+
+1. The direct root cause;
+2. A minimal implementation path in no more than five sentences;
+3. Existing files expected to change;
+4. New files that are genuinely necessary;
+5. Items explicitly excluded from the current scope;
+6. A mapping from changes to acceptance criteria;
+7. Issues discovered but intentionally left out of scope.
+
+Do not begin with a complete target architecture, ideal end state, or long-term evolution plan.
+
+Optional enhancements must be listed separately. They must not be mixed into the baseline solution or implemented by default.
+
+## 10. Overengineering warning signs
+
+Pause and simplify the proposal when any of the following appears:
+
+- A simple UI feature introduces a permission matrix;
+- Two or three states introduce a custom state machine or complex hook;
+- Basic previous/next navigation introduces a carousel framework;
+- Unrequested file types, platforms, or advanced capabilities are added;
+- A frontend interaction issue becomes a backend lifecycle project;
+- The number of new files clearly exceeds the number of existing files being changed;
+- The proposal repeatedly relies on "future extensibility," "possible future needs," or "generic capability";
+- Removing a proposed design still leaves every acceptance criterion satisfied;
+- The core implementation cannot be explained in five sentences.
+
+When these signals appear, return to the current acceptance criteria and remove every design element without a direct requirement source.
+
+## 11. Implementation discipline
+
+After the plan is approved:
+
+- Implement in the smallest independently verifiable steps;
+- Run relevant tests after each step;
+- Do not expand the scope during coding;
+- Classify and report newly discovered issues before acting on them;
+- Do not silently include Category C issues;
+- Keep changes local, reversible, and easy to review.
+
+## Final decision rule
+
+When both a more complete solution and a simpler solution satisfy the current requirements, choose the simpler solution.
+
+Architecture creates value by removing unnecessary complexity, not by adding abstractions.

keble_tiktok-0.5.0/.cursor/rules/no-try-except.mdc

@@ -0,0 +1,10 @@
+---
+description: Do not introduce try/catch or try/except in generated code
+alwaysApply: true
+---
+
+# Prevent try/catch / except Pattern
+
+1. When generating code, do NOT use any `try/catch` or `try/except` block — including in pytest. Use pytest utilities (e.g. `pytest.raises`) to test expected error cases.
+2. If the existing codebase already has `try/catch/except`, keep it unless the user explicitly asks to update it.
+3. `getattr`, `setattr`, and `try/catch/except` are not patterns of a robust codebase. Prefer explicit types, schemas, and direct attribute access instead.

keble_tiktok-0.5.0/.cursor/rules/provider-integration.mdc

@@ -0,0 +1,99 @@
+---
+description: Provider Integration Rule — Docs First, Smoke Second, Implementation Last. Applies to any new third-party provider or new provider endpoint (FastMoss, EchoTik, Keepa, Amazon, Shopify, ...).
+alwaysApply: true
+---
+
+# Provider Integration Rule: Docs First, Smoke Second, Implementation Last
+
+This rule exists because two capability-reasoning mistakes were made when integrating providers:
+
+1. **EchoTik**: `page_size` max 10 was misread as "can only return Top 10"; the `page_num`
+   pagination parameter was missed; "returns a GMV field" (`total_sale_gmv_amt`) was conflated
+   with "does not have GMV", and separately with "supports GMV-sorted ranking".
+2. **FastMoss**: a verified host (`openapi.fastmoss.com`) was documented but the client default
+   was never corrected; `total` was treated as a full board count when only the depth cap was
+   observed.
+
+The root cause was never the smoke test itself. It was **inferring full API capability from a
+few observations without first reading the docs and producing a capability audit.**
+
+## 1. Mandatory sequence (do not reorder)
+
+Any new provider or new provider endpoint MUST proceed in this order:
+
+1. Read the first-party API documentation.
+2. Save the key endpoint pages verbatim to `docs/providers/<provider>/api-docs/` (a synthesis is
+   not a substitute for the primary source).
+3. Produce a capability matrix at `docs/providers/<provider>/<provider>-capability-audit.md`.
+4. Label every capability `SUPPORTED` / `UNSUPPORTED` / `UNKNOWN` (§3).
+5. Design smoke tests that verify the specific assumptions you intend to code against.
+6. Design the mapper / provider / source implementation.
+7. Write the code.
+8. Add default-safe tests (no real API calls, no credentials, no Docker).
+9. Run the live smoke gate (`RUN_LIVE_<PROVIDER>=1` + `live` marker) and capture a **sanitized**
+   fixture.
+10. Update the capability audit before merging; move each claim from UNKNOWN to SUPPORTED/
+    UNSUPPORTED only with cited evidence.
+
+If the first-party API doc URL cannot be located, STOP and report "missing first-party API doc
+source" — do not make strong capability claims from responses alone.
+
+## 2. Prohibited
+
+- Coding against an endpoint before reading its docs.
+- Inferring full API capability from a single smoke/fixture observation.
+- Writing `UNKNOWN` as `UNSUPPORTED` (or as `SUPPORTED`).
+- Generalizing one observed result into a global conclusion (one region → all regions; one
+  `orderby` field → all sort fields; one sample unit → confirmed unit).
+- Treating **field presence** as **sort capability** (a GMV field ≠ a GMV-sorted ranking).
+- Treating a **`page_size` cap** as a **total board-depth limit**.
+- Treating a `total` value as the true full count when only a fixed cap or a page count was
+  observed.
+- Guessing a field's unit from its name (basis points vs decimal vs percent; major vs minor
+  currency units; ISO week vs Monday-date).
+- Putting provider-specific details into the `keble-data-infra` universal layer.
+- Committing real credentials anywhere, including `.env.example` (use placeholders only).
+
+## 3. Three-state vocabulary (strict)
+
+- **SUPPORTED** — documented AND verified by at least one of smoke / fixture / test.
+- **UNSUPPORTED** — documented as absent, OR smoke-confirmed failing, AND the failing condition
+  is stated.
+- **UNKNOWN** — docs unclear, or not yet verified. UNKNOWN blocks coding against the capability.
+
+## 4. Every key conclusion must separate four layers
+
+For each key capability, the audit must state:
+
+- **Docs** — what the official documentation actually says.
+- **Observed** — what smoke / fixture / test actually returned.
+- **Inferred** — the reasoning built on docs + observation, with its uncertainty called out.
+- **Decision** — the engineering choice this phase (opened / withheld / approximated), and why.
+
+Do not write bare claims like "provider supports GMV" / "provider does not support GMV" /
+"provider only returns N rows" without doc + test evidence behind each layer.
+
+## 5. Capability matrix columns (minimum)
+
+`endpoint · business use · implemented? · request params · pagination params · page_size limit ·
+returns total? · next_cursor/has_more? · sort fields · sales field · GMV field · GMV-sort
+capability · price field · currency field · commission field · window/time format · region/market
+param · doc evidence · smoke evidence · test coverage · conclusion (SUPPORTED/UNSUPPORTED/UNKNOWN)
+· risk note`
+
+Keep `page_size` cap, `total` semantics, and board depth in **separate** columns — never merge
+them.
+
+## 6. Field retention
+
+Fields that are valuable downstream but not yet universalizable MUST be preserved on
+`channel_details` (or the domain's channel-specific detail object), not dropped just because the
+universal domain has no field for them yet. Never fabricate a value to fill a universal field;
+emit the metric as absent instead.
+
+## 7. Layering (unchanged, restated for providers)
+
+- Provider raw adapters, domain, and ports must NOT import `keble-data-infra` contracts.
+- Only bridge modules (`commerce_provider.py`, `creator_ranking_provider.py`,
+  `mapping/to_commerce.py`, `app.py`) adapt domain objects into the universal contract.
+- Provider selection (`if provider_id == "..."`) lives only in the composition root (`app.py`).

keble_tiktok-0.5.0/.cursor/rules/pytest-db-cleanup.mdc

@@ -0,0 +1,9 @@
+---
+description: Prevent database leaks during pytest runs
+globs: "tests/**"
+alwaysApply: false
+---
+
+# Prevent Pytest DB Leaks
+
+Prevent database leaks across MongoDB, Redis, Neo4j, and Qdrant during pytest. Clean up databases after each test run or test function.

keble_tiktok-0.5.0/.cursor/rules/python-standards.mdc

@@ -0,0 +1,48 @@
+---
+description: Python coding standards — pydantic, typing, backend schemas, and protocols
+globs: "**/*.py"
+alwaysApply: false
+---
+
+# Python
+
+0. Use MCP to check latest library docs when needed.
+1. Prefer pydantic models to restrict schemas rather than `hasattr` + `getattr`.
+2. When updating any library or Python package, run/update pytest and update `README.md` if necessary.
+3. Do not use in-function imports.
+4. Use `uv` to manage the environment (older docs may reference `conda`).
+5. After Python changes, run `npx --yes pyright .` at the repo root and fix all reported errors.
+
+## Pydantic AI Prompting — Use Strong Types
+
+Do not inject URLs (or any doc references) as plain strings into prompts. Pass typed prompt parts in a list:
+
+```python
+from pydantic_ai import Agent, ImageUrl
+
+agent = Agent(model='gateway/openai:gpt-5.2')
+result = await agent.run(
+    [
+        'What company is this logo from?',
+        ImageUrl(url='https://iili.io/3Hs4FMg.png'),
+    ]
+)
+```
+
+## Backend — Structural and Type Conversion
+
+Limit schema count: not over-reduced, not over-complicated.
+
+**CRUD** schemas (per entity): `*Base`, `*Update`, `*Create`, `*MongoObject` (or `*SqlObject`, etc.).
+
+**Logic** schemas: e.g. `MyLogic`, `MyLogics`, `MyLogicItem`, `MyLogicItemType(str, Enum)` — names reflect hierarchy. Every schema, especially `*Base`, needs a docstring stating its intention.
+
+**Client APIs**: `get_*`, `list_*`, etc. Each API needs a docstring stating intention and which types it converts (e.g. `client.get_* -> crud.list_* -> MyLogic.to_other_logic_type(crud_response) -> return`).
+
+Typing conversion + APIs is the core backend design pattern.
+
+## Libs and Submodules — Schemas and Protocol First
+
+Split complex backend logic across packages. To avoid mutual explicit dependencies while allowing implicit coordination, define `Protocol` types so dependent libs follow the contract without circular imports.
+
+Keep protocols in standalone files such as `schemas.py` and `protocols.py`. Wire implementations in the backend layer.

keble_tiktok-0.5.0/.cursor/rules/typescript-standards.mdc

@@ -0,0 +1,15 @@
+---
+description: TypeScript and React/Next.js coding standards
+globs: "**/*.{ts,tsx}"
+alwaysApply: false
+---
+
+# TypeScript
+
+0. Always run `nvm use 21` before TypeScript work to prevent wrong Node versioning.
+1. After updating any TypeScript files, run `tsc` to check for type errors.
+2. For React / Next.js projects, export components in this format — no `React.FC`, no `export default`:
+
+```ts
+export function MyComponent(props: MyComponentProps) {}
+```

keble_tiktok-0.5.0/.env.example

@@ -0,0 +1,10 @@
+FASTMOSS_CLIENT_SECRET=jdkzdjjtckcapoopnpotrewvcjknommg
+FASTMOSS_BASE_URL=https://openapi.fastmoss.com
+FASTMOSS_PROVIDER_ID=fastmoss
+RUN_FASTMOSS_SMOKE=1
+
+# EchoTik credentials
+ECHOTIK_USERNAME=260625095277577533
+ECHOTIK_PASSWORD=d7f0dbfc243348aabb4953efc26bbcbe
+ECHOTIK_BASE_URL=https://open.echotik.live
+RUN_LIVE_ECHOTIK=1

keble_tiktok-0.5.0/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

keble_tiktok-0.5.0/.gitignore

@@ -0,0 +1,41 @@
+# Generated by Cargo
+# will have compiled files and executables
+debug/
+target/
+cert/
+
+# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
+# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
+Cargo.lock
+
+# These are backup files generated by rustfmt
+**/*.rs.bk
+
+# MSVC Windows builds of rustc generate these, which store debugging information
+*.pdb
+*__ignored__*
+
+*.env
+*.DS_Store
+**/.DS_Store
+
+.vscode
+.idea
+
+*.crt
+
+uploads/
+!strapi-v5/public/uploads/
+!strapi-v5/public/uploads/.gitkeep
+test/
+resources/
+Brewfile
+qdrant/
+*.pyc
+**.pyc.*
+*/traefik/certs
+*/traefik/certs/*
+gcp.json
+.history
+
+prod.env.*

keble_tiktok-0.5.0/AGENTS.md

@@ -0,0 +1,98 @@
+
+1. Update `AiAgentChangesLogs.md` in project root directory on each completion. Include timestamp, project state, my prompt and your changes. Be simple when you are simply fixing a small bug. Be concise and conclusive when you are updating large portion of the codebase. Sample format:
+```markdown
+## 2026-01-01 14:00
+State: <the state of the project linked to this section>
+
+<!-- you may want to use git to check my git username, since there are multiple people working in the same branch -->
+<My github username>: <a summary of my prompt, shorten it if too long, it need to contained details bulletpoints of my requests>
+
+Ai: <a summary on what have you changed? Especially the mechanism, dependencies, schemas, etc...>
+```
+If `AiAgentChangesLogs.md` is NOT presented in the project root directory, create one, and copy paste my prompt
+```markdown
+Update `AiAgentChangesLogs.md` in project root directory on each completion. Include timestamp, project state, my prompt and your changes. Be simple when you are simply fixing a small bug. Be concise and conclusive when you are updating large portion of the codebase. Sample format: 
+```
+... as above
+
+## Project Context
+
+`keble-tiktok` is the **TikTok Channel Domain** layer of the Keble unified e-commerce data platform. It sits in the middle of the three-layer architecture:
+
+```text
+Provider Raw          (e.g. FastMoss, EchoTik, Crawler)
+    ↓
+Channel Domain        ← this repo (keble-tiktok: TikTok Domain + TikTokProductSource interface)
+    ↓
+Universal Commerce    (keble-data-infra-contract)
+    ↓
+Application Service / SDK / Agent
+```
+
+**Key architectural decisions**:
+- Source of truth: `keble-data-infra/docs/architecture/keble-data-platform-design.md`
+- Local implementation reference (extracted subset for this repo): `docs/architecture/tiktok-domain-impl.md`
+
+**Summary of decisions**:
+
+1. **Interface ownership**: provider-neutral schemas, protocols, operation keys, and manifests are defined in `keble-data-infra-contract`; this repo implements them.
+2. **Dependency direction**: TikTok domain, ports, and provider raw adapters do not import the API package. Bridge modules and `services.py` may import the contract to normalize provider results.
+3. **HTTP ownership**: this package exports `FastMossServices` and `EchoTikServices`; it must not import FastAPI or build routers/apps. `keble-data-infra-api` constructs every raw HTTP route.
+4. **Provider-native fields**: typed TikTok detail models remain internal and are not embedded into normalized public contracts.
+5. **No DI framework**: dependency injection via plain constructors; prefer `typing.Protocol` over abstract base classes.
+6. **Primary responsibility**: expose stable provider services that wrap FastMoss / EchoTik raw data into normalized contract models.
+7. **Minimal increment**: implement one capability at a time; test and commit before the next step.
+8. **No speculative implementations**: do not pre-build multi-source merge, MCP, or Agent layers until there is a concrete requirement.
+9. **Python >= 3.13**, pydantic v2 only.
+
+## Testing Rules
+
+- Follow the umbrella root `TESTING_GUIDELINE.md` for every test change.
+- Use the canonical layer-first structure: `tests/unit`, `tests/contract`, `tests/integration`, `tests/live`, `tests/evals`, and `tests/db_stack` only when those layers have real executable tests. Do not create empty placeholder test modules or folders just to mirror source files.
+- Default-safe tests must run without real FastMoss calls, Docker, shared dev/prod databases, or credentials:
+  `uv run pytest -m "not live and not slow and not eval and not local_stack and not db_stack and not container"`.
+- Local deterministic DB-heavy tests should be part of the local-full lane when the repo has them; opt-in gates are for real provider calls, eval datasets, cross-store `db_stack`, `local_stack`, and container/service orchestration.
+- Keep the canonical marker vocabulary aligned with the root guideline. `asyncio` is a pytest framework marker, not a semantic layer marker; use it only when pytest-asyncio needs it.
+- Real FastMoss canaries belong under `tests/live` and require `RUN_LIVE_FASTMOSS=1` plus credentials. Once the gate is enabled, provider request/schema failures should fail the test instead of being downgraded to skips.
+- Production clients that honor environment proxy settings require the
+  `httpx[socks]` runtime extra; do not remove it while `trust_env=True` remains
+  an API-owned production option.
+- Use `keble_db.testing` and `keble_keepa.testing` when DB or Keepa fixtures are needed in downstream repos. If a reusable fixture is missing, enrich the shared toolkit before adding ad hoc fakes here.
+- Provider response caching must use `ProviderOperationCache` with complete
+  request identity, the API-startup Mongo indexes, and shared
+  `keble_db.RedisLeaseManager`; never add provider-local locks or a second cache.
+- Service-only batches must deduplicate exact requests, preserve caller order,
+  and bound concurrency. Do not expose HTTP batch routes without a new contract.
+- Keep Sentry spans structural: cache outcome, lease ownership, stable
+  operation, and batch counts only. Never attach request bodies or credentials.
+- Run `uv lock --check`, the relevant pytest layer selectors, and `npx --yes pyright .` from this repo after Python test or typing changes.
+
+**Related repos**:
+- `keble-data-infra-contract` — provider-neutral caller-owned contracts
+- `keble-data-infra-api` — sole raw FastAPI composition root
+- `keble-products` — product data services (FastMoss integration live)
+- `keble-helpers` (installed as `keble_helpers==1.12.17`)
+- `keble-exceptions`, `keble-graphrag`, `keble-keepa`
+
+## Git Branching, Versioning, and Merge Policy
+
+1. Branch names normally must NOT include version numbers.
+2. Use topic-based branch names:
+   - `feature/<topic>`
+   - `fix/<topic>`
+   - `rewrite/<topic>`
+   - `refactor/<topic>`
+   - `hotfix/<topic>`
+3. Create a new branch when starting a meaningful line of work.
+4. If you are still in planning phase, ask whether this work needs:
+   - a new branch
+   - a new version bump
+   - a new release label
+5. Do not assume branch creation implies a version bump.
+6. Versions belong in annotated tags, normally pure semantic versioning such as `v0.1.0`.
+7. Only use extra tag labels if explicitly requested.
+8. When bumping a repo version, create and push the corresponding annotated tag after verification.
+9. After the work is verified, merge to `main`.
+10. For non-production repos, merging to `main` is allowed after verification.
+11. Do not delete branches, rewrite shared history, or force-push unless explicitly approved.
+12. Do not claim branch, tag, merge, or push success unless `git branch -vv`, `git tag`, and remote refs confirm it.