basecradle 0.2.0__tar.gz → 0.3.0__tar.gz

{basecradle-0.2.0 → basecradle-0.3.0}/CHANGELOG.md

@@ -6,6 +6,26 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). The API the
 SDK wraps is unversioned and additive-only, so SDK minor versions track API additions.
 
+## [0.3.0] - 2026-06-03
+
+Tracks the platform's Dashboard documentation reshape
+([basecradle/basecradle#256](https://github.com/basecradle/basecradle/pull/256)): the
+never-populated `sdk` slot is gone, replaced by per-language `sdks` objects and a
+`changelog` pointer.
+
+### Added
+
+- **`me.documentation.changelog`** — the platform changelog URL.
+- **`me.documentation.sdks`** — the official SDKs, typed and keyed by language:
+  `sdks.python.repository` and `sdks.python.package`. New languages and new per-SDK
+  pointers are additive.
+
+### Removed
+
+- **`me.documentation.sdk`** — the placeholder that only ever returned `None`. The
+  platform removed it from the wire; reading it now raises the standard
+  "API did not return" `AttributeError`.
+
 ## [0.2.0] - 2026-06-03
 
 The async release: the same SDK for async code, on one shared core.
@@ -51,5 +71,6 @@ The first release: complete coverage of the BaseCradle API, for humans and AI pe
 - **The spec drift-guard** — CI fails if the live API ever has endpoints this SDK doesn't
   cover.
 
+[0.3.0]: https://github.com/basecradle/basecradle-python/releases/tag/v0.3.0
 [0.2.0]: https://github.com/basecradle/basecradle-python/releases/tag/v0.2.0
 [0.1.0]: https://github.com/basecradle/basecradle-python/releases/tag/v0.1.0

{basecradle-0.2.0 → basecradle-0.3.0}/CLAUDE.md

@@ -91,6 +91,24 @@ Runtime dependencies: `httpx`. That's the list. Every addition is argued in a PR
 - **Versioning**: semver, `0.x` until the platform owner declares 1.0. The API is additive-only, so SDK minor versions track API additions.
 - **Public package name**: `basecradle` on PyPI. Publishing is via PyPI **Trusted Publishing** (GitHub Actions OIDC — no stored credentials), on git tag.
 
+## Releasing
+
+The pipeline is `.github/workflows/release.yml`: pushing a `v*` tag → build → TestPyPI rehearsal → human approval → PyPI, all via OIDC Trusted Publishing (zero stored credentials). The workflow filename and the environment names (`testpypi`, `pypi`) are **contractual** — they match the Trusted Publisher registrations on PyPI/TestPyPI; renaming any of them breaks the trust relationship. The `pypi` environment requires the project owner's approval.
+
+The procedure, in order:
+
+1. **Release PR**: bump `src/basecradle/_version.py` from `X.Y.Z.dev0` to `X.Y.Z` and add the `CHANGELOG.md` entry (Keep a Changelog format). Merge on green CI. Do **not** put `Closes #N` on release PRs — see step 6.
+2. **Tag**: on main after the merge — `git tag vX.Y.Z && git push origin vX.Y.Z`. This triggers the release workflow.
+3. **Verify the rehearsal**: the TestPyPI publish is automatic. In a clean venv:
+   `pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ basecradle==X.Y.Z`
+   The extra index is required (httpx lives on real PyPI, not TestPyPI). Expect a minute or two of index-propagation lag — retry, don't panic.
+4. **The human gate**: the workflow waits on the `pypi` environment. Announce this unmissably (see the human-action-gate convention above); only the project owner can approve.
+5. **Verify the release**: clean venv, `pip install basecradle==X.Y.Z`, check import + `__version__` + both clients construct, and that https://pypi.org/project/basecradle/ renders. (The PyPI JSON API caches — pip resolving the new version is the real test.)
+6. **Close the release issue manually** with the verification record. Release issues never auto-close via a merged PR: an issue that closed before the publish was verified would lie.
+7. **Post-release version bump**: the first PR of the next cycle bumps `_version.py` to the next minor `.dev0` (after `0.2.0` ships, main becomes `0.3.0.dev0`) so dev builds are always distinguishable from releases.
+
+Versioning facts: `_version.py` is the single source of truth (hatchling reads it; `pyproject.toml` declares `dynamic = ["version"]`). Local editable installs cache metadata — after editing the version, run `uv sync --reinstall-package basecradle` or the version-wiring test fails (that failure is the test doing its job).
+
 ## Where to Start
 
 The build is fully mapped in this repo's **GitHub Issues** — each issue is one PR-sized unit with its design details and steps, in dependency order. Start at the lowest open issue number, plan-first for anything non-trivial, and work through them in order unless an issue says otherwise.
@@ -99,6 +117,35 @@ The build is fully mapped in this repo's **GitHub Issues** — each issue is one
 gh issue list --repo basecradle/basecradle-python --state open
 ```
 
+## Cross-Repo Handoffs
+
+BaseCradle is built across multiple repositories — the private Rails core, the public SDKs, and future ecosystem repos — each worked on by its own Claude Code sessions. Sessions cannot reach across repos; the human (Drawk) is the relay between them. This procedure makes that relay lossless and identical in every direction. It is ecosystem-wide: every BaseCradle repo carries this same section in its CLAUDE.md (see "Propagating this procedure"), so both ends of any handoff follow the same rules.
+
+### Sending work to another repo
+
+When work in this repo creates work in another BaseCradle repo (a wire-shape change an SDK must mirror, a bug discovered in another repo's code, a feature needing a counterpart):
+
+1. **File the issue(s) on the target repo.** The issue is the complete, self-sufficient spec: the trigger (what changed here, with PR links), what the target repo must do, ordering/timing constraints ("release only after the platform deploys"), and the definition of done. Write it for a reader with zero context from the conversation that produced it.
+2. **Compose the handoff prompt and present it to Drawk in one copy-pasteable code block, immediately after filing.** Drawk pastes it verbatim into a Claude Code session running in the target repo. Structure, in order:
+   - Opening line: `Cross-repo handoff: work <issue URL>` — the receiving session recognizes a handoff by this line.
+   - The trigger in one or two lines, with links.
+   - Cross-repo state the receiving session cannot discover on its own: what is deployed, what is verified on production, what is blocked on what.
+   - What "done" looks like, including whether a return handoff is required.
+3. **The issue is the spec; the prompt is the pointer.** Never put a requirement only in the prompt — prompts are ephemeral, issues persist. If prompt and issue disagree, the issue wins, and the issue gets corrected.
+
+### Receiving work from another repo
+
+When Drawk pastes a prompt beginning `Cross-repo handoff:`:
+
+1. Read the referenced issue(s) in full before acting — the issue is the spec.
+2. Execute under **this** repo's conventions (its own CLAUDE.md, workflow, tests). The sending repo's conventions do not transfer.
+3. Respect the issue's ordering constraints (e.g., verify a dependency has deployed before releasing).
+4. When done, report completion to Drawk: what shipped, version numbers, links. If the issue requires a return handoff (the sending repo is blocked on this work), compose one per "Sending work to another repo."
+
+### Propagating this procedure
+
+Every BaseCradle ecosystem repo carries this same "Cross-Repo Handoffs" section in its CLAUDE.md, copied verbatim (it is written repo-agnostically so no adaptation is needed). When handing off to a repo whose CLAUDE.md lacks the section — always true for a brand-new repo — the handoff prompt's definition of done includes adding it, copied from this repo's CLAUDE.md by file-system path (the same mechanism public repos use to reference `constitution.md`).
+
 ## Development Commands
 
 ```bash

{basecradle-0.2.0 → basecradle-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: basecradle
-Version: 0.2.0
+Version: 0.3.0
 Summary: The official Python SDK for BaseCradle — a communications platform where humans and AI are equal peers.
 Project-URL: Homepage, https://basecradle.com
 Project-URL: Documentation, https://basecradle.com/docs/api

{basecradle-0.2.0 → basecradle-0.3.0}/src/basecradle/__init__.py

@@ -10,6 +10,8 @@ from basecradle._dashboard import (
     DashboardDocumentation,
     DashboardEnvironment,
     DashboardInteraction,
+    DashboardSdk,
+    DashboardSdks,
     DashboardTimelines,
 )
 from basecradle._exceptions import (
@@ -90,6 +92,8 @@ __all__ = [
     "DashboardDocumentation",
     "DashboardEnvironment",
     "DashboardInteraction",
+    "DashboardSdk",
+    "DashboardSdks",
     "DashboardTimelines",
     "Item",
     "Message",

{basecradle-0.2.0 → basecradle-0.3.0}/src/basecradle/_dashboard.py

@@ -1,6 +1,6 @@
 """The Dashboard — the one place any peer lands to orient and navigate.
 
-Five sections, mirroring ``GET /users/dashboard`` exactly: identity (``you``),
+Five sections, mirroring ``GET /users/dashboard`` exactly: identity,
 environment, interaction, account, and documentation.
 """
 
@@ -15,6 +15,8 @@ __all__ = [
     "DashboardDocumentation",
     "DashboardEnvironment",
     "DashboardInteraction",
+    "DashboardSdk",
+    "DashboardSdks",
     "DashboardTimelines",
 ]
 
@@ -53,14 +55,36 @@ class DashboardAccount(ApiObject):
     change_password_url: str
 
 
+class DashboardSdk(ApiObject):
+    """One official SDK: where its code lives and where to install it from.
+
+    Per-SDK pointers are additive — fields the platform adds after this release are
+    readable immediately (``ApiObject`` reads the wire).
+    """
+
+    repository: str
+    package: str
+
+
+class DashboardSdks(ApiObject):
+    """The official SDKs, keyed by language.
+
+    Languages the platform adds after this release are readable immediately as untyped
+    objects; typed attributes are added here as each SDK ships.
+    """
+
+    python: DashboardSdk
+
+
 class DashboardDocumentation(ApiObject):
-    """The guides — prose, machine contract, interactive reference, and (in time) the SDK."""
+    """The guides — prose, machine contract, interactive reference, changelog, and the SDKs."""
 
     user_guide: str
     api: str
+    changelog: str
     openapi: str
     reference: str
-    sdk: str | None
+    sdks: DashboardSdks
 
 
 class Dashboard(ApiObject):

basecradle-0.3.0/src/basecradle/_version.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"

{basecradle-0.2.0 → basecradle-0.3.0}/tests/conftest.py

@@ -287,9 +287,15 @@ DASHBOARD_RESPONSE = {
     "documentation": {
         "user_guide": "https://basecradle.com/docs/user_guide.md",
         "api": "https://basecradle.com/docs/api.md",
+        "changelog": "https://basecradle.com/docs/changelog.md",
         "openapi": "https://basecradle.com/docs/api.yaml",
         "reference": "https://basecradle.com/docs/api/reference",
-        "sdk": None,
+        "sdks": {
+            "python": {
+                "repository": "https://github.com/basecradle/basecradle-python",
+                "package": "https://pypi.org/project/basecradle/",
+            },
+        },
     },
 }
 

{basecradle-0.2.0 → basecradle-0.3.0}/tests/test_dashboard.py

@@ -8,6 +8,8 @@ from basecradle import (
     DashboardDocumentation,
     DashboardEnvironment,
     DashboardInteraction,
+    DashboardSdk,
+    DashboardSdks,
     DashboardTimelines,
     UnauthorizedError,
     User,
@@ -66,7 +68,32 @@ class TestMe:
         assert me.interaction.timelines.url == "https://basecradle.com/timelines.json"
         assert me.account.sessions_url == "https://basecradle.com/users/sessions.json"
         assert me.documentation.openapi == "https://basecradle.com/docs/api.yaml"
-        assert me.documentation.sdk is None
+        assert me.documentation.changelog == "https://basecradle.com/docs/changelog.md"
+
+    def test_documentation_sdks_are_typed_by_language(self, bc, api):
+        """The official SDKs, keyed by language, each entry an object of per-SDK pointers.
+
+        Pins the platform shape from core PR #256 — a regression there fails here.
+        """
+        api.get("/users/dashboard").respond(200, json=DASHBOARD_RESPONSE)
+
+        sdks = bc.me.documentation.sdks
+
+        assert isinstance(sdks, DashboardSdks)
+        assert isinstance(sdks.python, DashboardSdk)
+        assert sdks.python.repository == "https://github.com/basecradle/basecradle-python"
+        assert sdks.python.package == "https://pypi.org/project/basecradle/"
+
+    def test_the_removed_sdk_slot_raises_the_standard_attribute_error(self, bc, api):
+        """Core PR #256 removed `sdk` (the never-populated placeholder) from the wire.
+
+        Reading it gets the standard "API did not return" AttributeError listing the
+        real fields — never a silent None.
+        """
+        api.get("/users/dashboard").respond(200, json=DASHBOARD_RESPONSE)
+
+        with pytest.raises(AttributeError, match="did not return 'sdk'"):
+            bc.me.documentation.sdk
 
     def test_me_is_fetched_fresh_on_every_access(self, bc, api):
         """Decided in issue #4: no caching — bc.me is the live answer to "who am I?"."""

basecradle-0.2.0/src/basecradle/_version.py

@@ -1 +0,0 @@
-__version__ = "0.2.0"