Repository navigation
Tracer: publish a Memory Git repo and import through a Bot link #17
Description
Tracer: publish a Memory Git repository and import it through a Bot link
Native parent / specification: #18. This is one runnable end-to-end slice, not a horizontal export backend or disconnected marketplace mock. Reuse #298's fresh-Bot Git creation and current Host/Client seams rather than introducing a second Memory authority.
Observable behavior
A Human signs in with Email OTP, publishes a prepared committed Memory repository, opens its public Bot link, previews it and imports a fresh local PersonaBot. The imported Bot has the chosen branch, complete intended Git history/refs and portable presentation, while its local identity is new. A completed-import receipt is recorded only after durable local creation succeeds.
Scope of this first slice
- Reconcile ADR-0019/0020 with the confirmed contract below in a new ADR and integrate its result into the living architecture before implementation. Keep DSH platform seams and application-defined Memory/publication/account authority distinct; verify concrete APIs against current official source. Do not inherit the old PlanetScale/selected-file/accepted-only Snapshot rules.
- Owning Host module reads and validates ordinary committed branch/tag data plus committed sharing metadata; trusted Host/Client bridge supplies the publication/preview/import flow. Exclude internal recovery refs and source-machine runtime/configuration.
- Production-shaped Workers publication endpoint, D1 account/publication/version/receipt records and R2 immutable Git artifact/presentation data. Include author ownership, declared license and consistent fixed-version/latest-pointer behavior.
- Email OTP account sign-in through Better Auth and Cloudflare Email. Anonymous public page/preview; require platform sign-in for publish/import. Google/GitHub/Passkey are confirmed follow-on sign-in methods, not reasons to expand the first working tracer before Human feedback.
- Publish from a prepared local committed repository, supporting an author without GitHub. Expose the simple read-only Git remote required by the contract; imported origin/upstream must be usable, never the temporary archive path. This first slice proves the initial remote and ancestry; recurring updates follow after feedback.
- Minimal public Bot/version page and a real in-harness preview/import interaction. A successful import creates fresh Bot identity and uses the sharing descriptor's name/description/badges/avatar rules. Leave Profile Backup/Restore/Transfer (Design: Profile Backup / Restore / Transfer UX #76) separate.
- Complete import only after canonical local repository/Bot creation succeeds. Bind the idempotent completion receipt to authenticated importer and fixed version. Failure cleanup leaves no half-created Bot and no completed-import count.
- Author can withdraw the publication; future platform artifact/remote fetches and imports are refused, while a previously imported local repository remains usable. Withdrawal does not promise deletion of copied data or independent GitHub sources.
Focused automated regression
- A prepared fixture with two branches, a tag and historical file deletion retains the expected published refs/history and selected checkout. A dirty-only file and an internal recovery checkpoint never appear in the published Git objects/ref set merely because they are local.
- Committed descriptor/avatar produces the shared presentation with fresh identity; omitted avatar produces the new Bot's default. Profile-only credentials/bindings/session/recovery stores are not copied. The uploaded package never contains PersonaBot Model Plans, Model Preset bindings or provider credentials; an imported Bot selects its model locally (ADR-0027, moved here from Tracer: Preserve model plans in Profile Backup only #505).
- Test the real publication/preview/import seams and durable results: unauthenticated platform import refused; failed import has no success count; replayed completion does not double-count.
- Pinned version remains immutable; failed publication does not move latest. Withdrawn publication refuses new downloads/imports without breaking the already imported local Bot.
Runnable Human acceptance
Use isolated local DSH and a development Cloudflare service with a real deliverable OTP route. Prepare and commit a small Memory repo containing branch/tag history and sharing metadata; publish, open its public Bot link and import through the actual Client. Inspect the fresh Bot, chosen branch/refs/history/avatar, durable publication and completed-import receipt. Verify its remote is accessible through ordinary Git. Withdraw and show that a new platform import is refused while the existing Bot still works.
Record actual revision, running service and result evidence. A mocked email/provider or backend-only test does not establish the complete Human path. Seek Human feedback after this slice before creating sibling provider/discovery/update tickets. Cloud deployment remains separately scoped to the implementation task's authorization.
Next slices, after first-slice feedback
See #18 for ordering. Native Git updates, additional sign-in methods and discovery remain confirmed target behavior, not claimed delivered by this first slice.
Confirmed product contract — final, 2026-09-30
Project: https://github.com/orgs/BotHarness/projects/11 · Milestone: v1.1. The product decision frontier is settled; superseded proposals remain in historical details only.
Full committed Memory Git repository
- Share the complete committed Memory Git repository, including Git history and all ordinary branches/tags. Author selects the initial checkout branch. A published version fixes that branch HEAD and the published refs.
- No file selection, history cleaning or no-history toggle. Author/Human/Bot controls files, branches, commits and any history reinitialization through ordinary Git before publication.
- Publish only committed branch/tag content and its reachable history. Do not include staged/uncommitted/untracked files or internal refs such as refs/botharness/recovery/*, which can contain working-tree checkpoints. Do not replace this ref contract with git bundle --all.
- Git data is not source-machine .git/config, credential helpers, hooks, recovery/ledger databases or runtime state. Do not implicitly export Profile credentials, live IM bindings/grants, Sessions or Bot identity. Authors remain responsible for the contents they intentionally commit to the shared repository; this is not a historical-file redaction feature.
Presentation lives in Git; identity stays local
- Commit a portable sharing descriptor and avatar assets into the repository before publishing. Human/Bot can prepare them using normal file/Git operations; publication does not silently insert uncommitted metadata.
- Avatar sharing defaults on. If enabled, a fresh import uses the shared appearance, including preservation of generated appearance. If omitted/disabled, it uses the fresh Bot's normal default avatar.
- Descriptor includes display name, description and role badges. Missing optional presentation has defined normal local defaults; optional Soul (
SOUL.md, ADR-0134) remains optional; an installed repository that still usesPERSONA.mdgets the idempotent local rename commit. - Import creates a fresh local PersonaBot identity. Later git pull updates repository files; it does not automatically overwrite local Bot presentation preferences. Human/Bot decides whether to apply updated presentation.
Public publication and account contract
- Cloudflare Workers + D1 + R2; GitHub is optional. Public publication only, no private/unlisted publication mode in v1.1. Each publication is publicly listed with author, version, provenance and license; richer discovery UI follows the first tracer.
- Anonymous browsing. Platform sign-in is required to publish and import through Marketplace. Ordinary external Git operations are a separate path.
- Better Auth: passwordless Email OTP sent through Cloudflare Email, Google and GitHub sign-in, optional Passkey. Start with verified Email OTP or social sign-in, then enroll Passkey. Passkey sign-ins do not require an OTP email every time; OTP remains a fallback.
- License is author-confirmed: read an existing repository license or require an explicit declaration when absent.
- Withdrawal blocks future platform downloads/imports of the withdrawn publication. Already imported local repositories remain usable. Public GitHub sources remain under their author's GitHub control.
Native Git updates and simple publication
- No fork/PR/pull/push/merge/rebase/update-management UI. Human/Bot uses Git and ordinary GitHub collaboration directly.
- GitHub-backed author selects a tracked publication branch at initial publication. Subsequent pushes to that branch automatically produce new immutable Marketplace versions. Stable Bot link resolves the latest successfully published version; version-specific links stay fixed. Failed refresh does not advance the latest pointer.
- For authors without GitHub, Human asks Bot to publish the prepared committed repository through the platform publication API. The platform provides a read-only Git remote, updated on successful republication, so consumers can use ordinary git pull. Do not expand this into a platform Git push/receive-pack service or GitHub-like collaboration hosting.
- Imported repositories have a usable trusted origin/upstream and the selected branch's original commit ancestry; do not leave origin pointing at a temporary bundle file.
- Fast-forward is conditional on compatible ancestry and worktree state. Local commits or rewritten upstream may diverge. Human/Bot handles native merge/rebase; the platform does not force-reset or overwrite local work to manufacture fast-forward.
Honest popularity measurements
Completed local-import receipts are platform clone activity. Failed/replayed receipts do not inflate the count. Views, artifact downloads and distinct importers are separately named. External Git/GitHub clone/fork activity is not counted as a completed platform import. Authorization and version identity bind receipts to the actual completed import path.
Previous design round (superseded where inconsistent)
Confirmed direction — round 3, 2026-09-30
Feature Project: https://github.com/orgs/BotHarness/projects/11. Milestone: v1.1.
Repository and native Git workflow
- Default: full committed Memory Git repository with Git history, all ordinary branches and tags. Author chooses the initial checkout branch; publication freezes that branch HEAD and the published branch/tag refs at a version.
- No file-selection, history-cleaning, fork/PR-management, pull/push or Memory-update UI. Human or Bot prepares, edits, commits, collaborates and updates through ordinary Git; the previously proposed extra collaboration/update surfaces are superseded.
- A simple history opt-out remains an earlier requested possibility, but its compatibility with native future pulls still needs a decision. Do not silently claim a history-stripped snapshot retains the author's ancestry.
- Uncommitted/staged/untracked contents are not publication input. Include ordinary branches/tags and their reachable Git history; do not mechanically export every internal ref. Memory recovery stores working-tree checkpoints under refs/botharness/recovery/*, which must not enter public sharing merely because they are Git commits.
- Repository sharing transfers Git objects and selected ordinary refs, not source-machine .git/config, credentials, hooks, internal recovery refs or runtime state.
- Imported Git-backed Memory should retain a usable upstream for ordinary Git pull. Fast-forward is possible when local HEAD is an ancestor of upstream; local commits or rewritten author history may diverge. User/Bot resolves that using native Git. The platform must not overwrite local work to manufacture fast-forward.
- GitHub is optional. Existing raw Git URL import (Create PersonaBot from a Git Memory repository (HTTPS or SSH) #298) preserves origin and is separate from authenticated Marketplace import. A local clone does not create a GitHub fork.
Portable presentation and local identity
Avatar sharing defaults on. Included avatar means the shared appearance; omitted avatar means the new Bot's normal generated default. Carry name, description and role badges. Import creates a fresh PersonaBot identity; credentials, live grants/bindings, active Sessions and Profile identity never transfer. How portable presentation is versioned alongside later Git updates remains pending.
Publication, accounts and measurements
- Workers + D1 + R2; public publication only. GitHub is optional, including for authors.
- Anonymous browsing; platform sign-in required to publish and to import through Marketplace. Direct raw Git operations remain separate.
- Better Auth: Google, GitHub, passwordless Email + OTP via Cloudflare Email, and optional Passkey. Recommended onboarding is verified Email OTP or a social sign-in, then Passkey enrollment; subsequent Passkey sign-ins do not send OTP. Email OTP remains a fallback rather than a required step on each Passkey login.
- Completed local-import receipts are the platform clone metric. Failed attempts or replayed receipts do not inflate it; page views, artifact downloads and distinct importers are separately named. External Git/GitHub clones/forks are not silently counted as platform imports.
- Withdrawal blocks new platform downloads/imports, while existing local imports remain usable. Publication carries author-confirmed licensing, reading the repository license when available or requiring an explicit declaration.
First tracer and remaining decisions
Sign in → publish prepared committed repo → public Bot link → preview → import a fresh local Bot with intended history/branch and presentation → completed-import receipt. Validate this runnable path before expanding discovery and providers. Profile Backup/Restore/Transfer stays separate in #76.
Remaining product frontier: GitHub publication refresh trigger; whether non-GitHub publications get a platform Git remote in v1.1; Git-versioned portable presentation; history opt-out semantics. Do not invent manual update-management UI. Reconcile ADR-0019/0020 with this confirmed direction and current Memory contracts before implementation; the old selected-file/accepted-only Snapshot model is historical, not current authority.
This issue owns local repository packaging, preview/import and portable presentation. #18 owns publication, accounts and hosted distribution.
Previous design round (superseded where inconsistent)
Confirmed sharing direction — round 2, 2026-09-30
Feature Project: https://github.com/orgs/BotHarness/projects/11. Milestone: v1.1. This issue owns local committed-repository packaging, metadata/preview and clone import; #18 owns public publication and distribution.
Sharing unit
- Default sharing unit is the full committed Memory Git repository, including Git history. The previous in-product file selection design is superseded.
- No file-by-file sharing editor or history-cleaning UI. Human manages branches, commits, file removal and any history cleanup/reinitialization through ordinary Git workflows before publication.
- Allow opting out of history with one simple option; history is enabled by default. The exact no-history import contract is to be finalized without a complex tier UI.
- Publish committed content only. The chosen branch HEAD is fixed at publication; uncommitted/staged/untracked content is not silently added.
- Remaining decision: all branches/tags versus only the chosen branch and its reachable history. Do not equate a complete branch history with every repository ref.
- Deleted historical files can be recovered if their commits are in the shared history. A deletion commit, even in a clone, is not history removal. The platform does not pretend to hide files that remain in the shared Git data.
Portable Bot presentation
- Avatar sharing enabled by default. If included, import uses the shared appearance; if omitted, the new local Bot gets its normal default avatar.
- Display name, description and role badges travel with the repository and can be reviewed before import.
- Import creates a fresh local PersonaBot identity. Credentials, live grants/bindings, active Sessions and Profile identity do not travel.
- Full Git data means repository refs/commits/trees/blobs, not a copy of the source machine's .git/config, credential helpers, hooks or unrelated runtime state.
GitHub and cooperation
GitHub is optional. Existing raw Git URL creation (#298) remains a complete-repository path. GitHub-backed Memory repositories can be forked and improved through PRs in ordinary GitHub workflows. A local clone is not a GitHub fork. Whether the first product tracer includes creating a GitHub fork remains a decision; do not claim #298 already does that.
First tracer
Human prepares the repository → chooses committed publication version and avatar option → publishes publicly through #18 → opens a Bot link → previews → imports a fresh PersonaBot with the intended Git content/history and presentation. Catalog discovery follows this accepted path. Do not require full Profile Backup/Restore/Transfer (#76).
Pending decisions
Repository refs/history scope; email authentication mode and import login; GitHub fork/PR product depth; stable Bot link/version behavior; clone-metric boundaries. Existing accepted-commit-only Snapshot/file-filter assumptions are not current execution instructions; reconcile ADR-0019/0020 with current Memory and this confirmed sharing model before implementation.
Previous design round (superseded where inconsistent)
Confirmed sharing direction — 2026-09-30
Feature Project: https://github.com/orgs/BotHarness/projects/11. Milestone: v1.1. This issue owns local selection/package/preview/import; #18 owns hosted publication and Bot links.
- Human chooses a Memory Repository branch and selects files from it to share.
- Avatar can be shared, enabled by default; generated-avatar versus custom-avatar portability is being resolved.
- GitHub is optional. Existing raw Git URL creation (Create PersonaBot from a Git Memory repository (HTTPS or SSH) #298) remains a separate complete-repository path.
- Marketplace links resolve version-fixed distributable content and import into a fresh PersonaBot identity.
- First vertical path is select → publish → Bot link → preview → import; a catalog follows Human acceptance.
- Public sharing does not transfer credentials, live grants/bindings, active Sessions or Profile identity. Profile Backup/Restore/Transfer is separately scoped in Design: Profile Backup / Restore / Transfer UX #76.
Pending design frontier
Branch/ref freezing and working-tree behavior, selection/history semantics, portable avatar/name/settings, package validation/limits, and link/version lifecycle require confirmation. The historical accepted-Memory-Commit-only and required-PERSONA.md assumptions are not current execution instructions; reconcile ADR-0020 with current Memory semantics before implementation.
Do not duplicate the already-delivered Git clone feature or make complete Profile Backup a blocker. Split the smallest production-shaped implementation tracer only after its contract is confirmed.
Historical scope before 2026-09-30 reconciliation (superseded where inconsistent)
What to build
实现SoulSnapshot与外层PersonaBot Export的本地clone闭环；它们不是Profile Backup，也不保留live identity/authority。
- SoulSnapshot：immutable content-addressed package，固定引用一个Memory Service已接受的Memory Commit/tree，并包含Human选择的Memory文件与setup instructions；Persona只是其中的普通Memory内容，不硬编码PERSONA.md特殊文件。
- PersonaBot Export：始终包含一个SoulSnapshot；默认只导出Soul/selected Memory，可显式选择dependency-closed operational Export Facets。
- 可选facets可包括 Source Events/Attachments、Channel/Inbox/Attention facts、Triggers/Wake Policies、Messaging Archive、provider account refs 与 disabled Grant declarations。
- PersonaBot identity facets 可包含 avatar settings 与自定义头像 bytes；manifest 必须明确 included/omitted/redacted。确定性 Blobatar 只保存 identity-derived setting，不复制可再生图片 bytes；自定义头像必须 dependency-closed，不能产生 dangling asset reference。
- Workspace Grant与source absolute path不是portable authority。Export最多携带Desired Workspace Reference/provenance；Import后必须Target Resolution + Human重新授权。
- credentials、activeService/Workspace Grants、live bindings、pending/in-flight work、AgentHandles与可执行Session state永不进入普通export。
- Import永远创建新的PersonaBot identity、默认Memory Repository与fresh local ids，并保留Export Origin；operational authority保持disabled直到rebind/reauthorize。
Profile-wide identity-preserving Backup/Restore/Transfer由#76设计，不在本issue偷渡backup tier。
Acceptance criteria
- SoulSnapshot manifest/version/content hash、accepted Memory Commit identity、Memory selection、secret scan与size/archive safety有明确contract/tests。
- 未被Memory Service接受的dirty/raw Git state不能发布或导出为Snapshot。
- PersonaBot Export manifest 声明每个 facet 的 schema、dependency closure、included/omitted/redacted 状态；不允许 dangling refs，并覆盖 Blobatar setting 与可选 custom-avatar identity facet。
- 默认export = accepted Memory tree中的Persona + selected Memory；operational facets必须显式勾选。
- Import preview展示Memory、operational facets、dependency/rebind requirements；Human确认后才创建。
- 普通import始终clone；same Export重复提交以Import Receipt幂等，explicit additional clone才再次创建。
- Provider refs/Grant declarations导入后disabled；Workspace refs unavailable直到Human映射与重新授权；credentials不可导出/回显。
- round-trip与adversarial archive tests覆盖typed redaction、unknown newer schema、secret/zip-bomb/path traversal。
Blocked by
- Design: Profile Backup / Restore / Transfer UX #76：PersonaBot Export与Profile Backup/Restore/Transfer的用户边界和最小UI。
- Foundation: Git working tree as PersonaBot Memory #115：accepted Memory Commit与history/query contract。
References
- Wayfinder: Memory Repository / Workspace Grant / Assignment cwd #114、Foundation: Git working tree as PersonaBot Memory #115、Workspace Grants: folder access UI and enforced PersonaBot file boundary #116
- Architecture foundation：架构地基：显式 Session 归属与 deep modules（GrokBot-on-DSH 对齐） #71
- ADR-0020、ADR-0021、ADR-0040、ADR-0042～0044
Generated by Claude Code
Activity
docs(spec): SoulSnapshot & Soul registry decisions (ADR-0019/0020, sp…
DoodleBears commentedon Sep 18, 2026
M6 边界：模型不随包发布（ADR-0027）
docs/botharness.md§8 开放项，M6 不引入。bot.md清单不得出现模型/凭据字段。[-]M6: SoulSnapshot（导出/导入 + commit message 规则）[/-][+]M6: SoulSnapshot 与 PersonaBot Export（clone，不是 Profile Backup）[/+]7 remaining items
[-]Design/tracer: share a Memory branch, selected files and avatar[/-][+]Design/tracer: share and clone a full Memory Git repository[/+][-]Design/tracer: share and clone a full Memory Git repository[/-][+]Tracer: publish a Memory Git repo and import through a Bot link[/+]DoodleBears commentedon Oct 5, 2026
Reordered on 2026-10-05 by ADR-0131: this tracer is now Phase 2 of #18 and no longer the current executable slice, so
ready-for-agentis removed. Phase 1 is #913 (GitHub-indexed catalog). Re-slice this issue after Phase 1 Human feedback, adding Passkey/Google sign-in, terms acceptance, favorites and counts per #18.Generated by Claude Code
DoodleBears commentedon Oct 6, 2026
Not planned (Vain, 2026-10-06): BotHarness is open source and drops platform accounts entirely, so Better Auth, Email OTP/Passkey/Google sign-in, uploads to a hosted service, favorites and import receipts/counts will not be built. Marketplace sharing stays GitHub-only (#913, ADR-0131 Phase 1). Moving a Bot to another device or another person is covered by a local zip export/import instead (new issue linked from #18).
Generated by Claude Code