Fix SDS blob uploads; add RichText utilities

.beads/.gitignore

@@ -0,0 +1,44 @@
+# SQLite databases
+*.db
+*.db?*
+*.db-journal
+*.db-wal
+*.db-shm
+
+# Daemon runtime files
+daemon.lock
+daemon.log
+daemon.pid
+bd.sock
+sync-state.json
+last-touched
+
+# Local version tracking (prevents upgrade notification spam after git ops)
+.local_version
+
+# Legacy database files
+db.sqlite
+bd.db
+
+# Worktree redirect file (contains relative path to main repo's .beads/)
+# Must not be committed as paths would be wrong in other clones
+redirect
+
+# Merge artifacts (temporary files from 3-way merge)
+beads.base.jsonl
+beads.base.meta.json
+beads.left.jsonl
+beads.left.meta.json
+beads.right.jsonl
+beads.right.meta.json
+
+# Sync state (local-only, per-machine)
+# These files are machine-specific and should not be shared across clones
+.sync.lock
+sync_base.jsonl
+
+# NOTE: Do NOT add negation patterns (e.g., !issues.jsonl) here.
+# They would override fork protection in .git/info/exclude, allowing
+# contributors to accidentally commit upstream issue databases.
+# The JSONL files (issues.jsonl, interactions.jsonl) and config files
+# are tracked by git by default since no pattern above ignores them.

.beads/README.md

@@ -0,0 +1,87 @@
+# Beads - AI-Native Issue Tracking
+
+Welcome to Beads! This repository uses **Beads** for issue tracking - a modern, AI-native tool designed to live directly
+in your codebase alongside your code.
+
+## What is Beads?
+
+Beads is issue tracking that lives in your repo, making it perfect for AI coding agents and developers who want their
+issues close to their code. No web UI required - everything works through the CLI and integrates seamlessly with git.
+
+**Learn more:** [github.com/steveyegge/beads](https://github.com/steveyegge/beads)
+
+## Quick Start
+
+### Essential Commands
+
+```bash
+# Create new issues
+bd create "Add user authentication"
+
+# View all issues
+bd list
+
+# View issue details
+bd show <issue-id>
+
+# Update issue status
+bd update <issue-id> --status in_progress
+bd update <issue-id> --status done
+
+# Sync with git remote
+bd sync
+```
+
+### Working with Issues
+
+Issues in Beads are:
+
+- **Git-native**: Stored in `.beads/issues.jsonl` and synced like code
+- **AI-friendly**: CLI-first design works perfectly with AI coding agents
+- **Branch-aware**: Issues can follow your branch workflow
+- **Always in sync**: Auto-syncs with your commits
+
+## Why Beads?
+
+✨ **AI-Native Design**
+
+- Built specifically for AI-assisted development workflows
+- CLI-first interface works seamlessly with AI coding agents
+- No context switching to web UIs
+
+🚀 **Developer Focused**
+
+- Issues live in your repo, right next to your code
+- Works offline, syncs when you push
+- Fast, lightweight, and stays out of your way
+
+🔧 **Git Integration**
+
+- Automatic sync with git commits
+- Branch-aware issue tracking
+- Intelligent JSONL merge resolution
+
+## Get Started with Beads
+
+Try Beads in your own projects:
+
+```bash
+# Install Beads
+curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
+
+# Initialize in your repo
+bd init
+
+# Create your first issue
+bd create "Try out Beads"
+```
+
+## Learn More
+
+- **Documentation**: [github.com/steveyegge/beads/docs](https://github.com/steveyegge/beads/tree/main/docs)
+- **Quick Start Guide**: Run `bd quickstart`
+- **Examples**: [github.com/steveyegge/beads/examples](https://github.com/steveyegge/beads/tree/main/examples)
+
+---
+
+_Beads: Issue tracking that moves at the speed of thought_ ⚡

.beads/config.yaml

@@ -0,0 +1,62 @@
+# Beads Configuration File
+# This file configures default behavior for all bd commands in this repository
+# All settings can also be set via environment variables (BD_* prefix)
+# or overridden with command-line flags
+
+# Issue prefix for this repository (used by bd init)
+# If not set, bd init will auto-detect from directory name
+# Example: issue-prefix: "myproject" creates issues like "myproject-1", "myproject-2", etc.
+# issue-prefix: ""
+
+# Use no-db mode: load from JSONL, no SQLite, write back after each command
+# When true, bd will use .beads/issues.jsonl as the source of truth
+# instead of SQLite database
+# no-db: false
+
+# Disable daemon for RPC communication (forces direct database access)
+# no-daemon: false
+
+# Disable auto-flush of database to JSONL after mutations
+# no-auto-flush: false
+
+# Disable auto-import from JSONL when it's newer than database
+# no-auto-import: false
+
+# Enable JSON output by default
+# json: false
+
+# Default actor for audit trails (overridden by BD_ACTOR or --actor)
+# actor: ""
+
+# Path to database (overridden by BEADS_DB or --db)
+# db: ""
+
+# Auto-start daemon if not running (can also use BEADS_AUTO_START_DAEMON)
+# auto-start-daemon: true
+
+# Debounce interval for auto-flush (can also use BEADS_FLUSH_DEBOUNCE)
+# flush-debounce: "5s"
+
+# Git branch for beads commits (bd sync will commit to this branch)
+# IMPORTANT: Set this for team projects so all clones use the same sync branch.
+# This setting persists across clones (unlike database config which is gitignored).
+# Can also use BEADS_SYNC_BRANCH env var for local override.
+# If not set, bd sync will require you to run 'bd config set sync.branch <branch>'.
+# sync-branch: "beads-sync"
+
+# Multi-repo configuration (experimental - bd-307)
+# Allows hydrating from multiple repositories and routing writes to the correct JSONL
+# repos:
+#   primary: "."  # Primary repo (where this database lives)
+#   additional:   # Additional repos to hydrate from (read-only)
+#     - ~/beads-planning  # Personal planning repo
+#     - ~/work-planning   # Work planning repo
+
+# Integration settings (access with 'bd config get/set')
+# These are stored in the database, not in this file:
+# - jira.url
+# - jira.project
+# - linear.url
+# - linear.api-key
+# - github.org
+# - github.repo

.beads/metadata.json

@@ -0,0 +1,4 @@
+{
+  "database": "beads.db",
+  "jsonl_export": "issues.jsonl"
+}

.changeset/add-richtext-utility.md

@@ -0,0 +1,12 @@
+---
+"@hypercerts-org/sdk-core": minor
+---
+
+Add RichText utility functions for auto-detecting facets from text
+
+New utility functions to simplify creating rich text facets:
+
+- `createFacetsFromText(text, agent?)` - async function that auto-detects URLs, hashtags, and @mentions. If an agent is
+  provided, resolves mentions to DIDs.
+- `createFacetsFromTextSync(text)` - sync function for fast detection without mention resolution
+- Re-exports `RichText` class from `@atproto/api` for advanced use cases

.changeset/enhance-collection-method-docs.md

@@ -0,0 +1,12 @@
+---
+"@hypercerts-org/sdk-core": patch
+---
+
+Enhance JSDoc documentation for collection and project methods
+
+Added comprehensive JSDoc with examples for:
+
+- `createCollection()` - examples for basic collections, avatar/banner images, and locations
+- `updateCollection()` - examples for updating title, images, and adding locations
+- `createProject()` - examples for basic projects, avatar/banner, and locations
+- `updateProject()` - examples for updating project images

.changeset/fix-sds-endpoint-routing.md

@@ -0,0 +1,18 @@
+---
+"@hypercerts-org/sdk-core": minor
+---
+
+Fix SDS blob uploads, add profile creation, and refactor blob operations
+
+**BREAKING:** `HypercertOperationsImpl` and `ProfileOperationsImpl` constructors now require a `BlobOperations` instance
+instead of a server URL.
+
+- Route SDS blob uploads to `com.sds.repo.uploadBlob` with repo query parameter, and PDS blob uploads to standard
+  `com.atproto.repo.uploadBlob`
+- Remove incorrect SDS routing logic from profile operations (profiles use standard ATProto endpoints on both PDS and
+  SDS)
+- DRY blob uploads: extract shared `BlobOperations` interface and use dependency injection in both
+  `ProfileOperationsImpl` and `HypercertOperationsImpl`
+- Refactor `applyParamsToProfile` to eliminate code duplication with helper methods
+- Add `create()` method to `ProfileOperationsImpl` for creating new profiles
+- Fix collection blob upload tests to mock `BlobOperations.upload` instead of `agent.uploadBlob`

.gitattributes

@@ -0,0 +1,3 @@
+
+# Use bd merge for beads JSONL files
+.beads/issues.jsonl merge=beads

AGENTS.md

@@ -92,16 +92,29 @@ pnpm clean                # Remove build artifacts
 
 ### Package-specific commands
 
+**Prefer running commands from within the package directory** (cleaner output, easier to pass args):
+
 ```bash
 # sdk-core
-pnpm --filter @hypercerts-org/sdk-core build
-pnpm --filter @hypercerts-org/sdk-core test
-pnpm --filter @hypercerts-org/sdk-core lint
+cd packages/sdk-core
+pnpm test                    # Run all tests
+pnpm test SomeFile           # Run specific test file
+pnpm build
+pnpm lint
 
 # sdk-react
+cd packages/sdk-react
+pnpm test
+pnpm build
+pnpm typecheck
+pnpm lint
+```
+
+Alternative using `--filter` from repository root (useful for CI/scripts):
+
+```bash
+pnpm --filter @hypercerts-org/sdk-core test
 pnpm --filter @hypercerts-org/sdk-react build
-pnpm --filter @hypercerts-org/sdk-react typecheck
-pnpm --filter @hypercerts-org/sdk-react lint
 ```
 
 ## Architecture
@@ -382,9 +395,11 @@ The repository has Git hooks that ensure code quality:
 # ... edit files ...
 
 # 2. Run tests for affected packages
-pnpm --filter @hypercerts-org/sdk-core test
+cd packages/sdk-core
+pnpm test
 
-# 3. Verify the build works
+# 3. Verify the build works (from repo root)
+cd ../..
 pnpm build
 
 # 4. Stage changes
@@ -461,3 +476,30 @@ git commit -m "chore: add changeset for project operations"
 
 - Source maps are generated for all builds
 - Coverage reports in `packages/sdk-core/coverage/`
+
+## Landing the Plane (Session Completion)
+
+**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
+
+**MANDATORY WORKFLOW:**
+
+1. **File issues for remaining work** - Create issues for anything that needs follow-up
+2. **Run quality gates** (if code changed) - Tests, linters, builds
+3. **Update issue status** - Close finished work, update in-progress items
+4. **PUSH TO REMOTE** - This is MANDATORY:
+   ```bash
+   git pull --rebase
+   bd sync
+   git push
+   git status  # MUST show "up to date with origin"
+   ```
+5. **Clean up** - Clear stashes, prune remote branches
+6. **Verify** - All changes committed AND pushed
+7. **Hand off** - Provide context for next session
+
+**CRITICAL RULES:**
+
+- Work is NOT complete until `git push` succeeds
+- NEVER stop before pushing - that leaves work stranded locally
+- NEVER say "ready to push when you are" - YOU must push
+- If push fails, resolve and retry until it succeeds

packages/sdk-core/package.json

@@ -23,7 +23,7 @@
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "typecheck": "tsc --noEmit",
-    "check": "pnpm run lint && pnpm run typecheck && pnpm run build && pnpm run test",
+    "check": "pnpm run format:check && pnpm run lint && pnpm run typecheck && pnpm run build && pnpm run test",
     "clean": "rm -rf dist",
     "test:ui": "vitest --ui",
     "test:coverage": "vitest --coverage"

packages/sdk-core/src/index.ts

@@ -249,3 +249,7 @@ export type {
   PermissionInput,
   Permission,
 } from "./auth/permissions.js";
+
+// Rich Text Utilities
+export { createFacetsFromText, createFacetsFromTextSync, RichText } from "./lib/rich-text.js";
+export type { RichTextResult, AppBskyRichtextFacet } from "./lib/rich-text.js";