implement io.atcr.repo.page. try and fetch from github,gitlab,tangled README.md files if source exists.

cmd/appview/serve.go

···
 	slog.Info("Initializing hold health checker", "cache_ttl", cfg.Health.CacheTTL)
 	healthChecker := holdhealth.NewChecker(cfg.Health.CacheTTL)
 
-	// Initialize README cache
-	slog.Info("Initializing README cache", "cache_ttl", cfg.Health.ReadmeCacheTTL)
-	readmeCache := readme.NewCache(uiDatabase, cfg.Health.ReadmeCacheTTL)
+	// Initialize README fetcher for rendering repo page descriptions
+	readmeFetcher := readme.NewFetcher()
 
 	// Start background health check worker
 	startupDelay := 5 * time.Second // Wait for hold services to start (Docker compose)
···
 	middleware.SetGlobalAuthorizer(holdAuthorizer)
 	slog.Info("Hold authorizer initialized with database caching")
 
-	// Set global readme cache for middleware
-	middleware.SetGlobalReadmeCache(readmeCache)
-	slog.Info("README cache initialized for manifest push refresh")
-
 	// Initialize Jetstream workers (background services before HTTP routes)
 	initializeJetstream(uiDatabase, &cfg.Jetstream, defaultHoldDID, testMode)
 
···
 				BaseURL:        baseURL,
 				DeviceStore:    deviceStore,
 				HealthChecker:  healthChecker,
-				ReadmeCache:    readmeCache,
+				ReadmeFetcher:  readmeFetcher,
 				Templates:      uiTemplates,
 			})
 		}

docs/TEST_COVERAGE_GAPS.md

···
 
 **Remaining gaps:**
 - `notifyHoldAboutManifest()` - 0% (background notification, less critical)
-- `refreshReadmeCache()` - 11.8% (UI feature, lower priority)
 
 ## Critical Priority: Core Registry Functionality
 
···
 
 ---
 
-### 🟡 pkg/appview/readme (16.7% coverage)
+### 🟡 pkg/appview/readme (Partial coverage)
 
-README fetching and caching. Less critical but still needs work.
+README rendering for repo page descriptions. The cache.go was removed as README content is now stored in `io.atcr.repo.page` records and synced via Jetstream.
 
-#### cache.go (0% coverage)
 #### fetcher.go (📊 Partial coverage)
+- `RenderMarkdown()` - renders repo page description markdown
 
 ---
 

pkg/appview/config.go

···
 
 	// CheckInterval is the hold health check refresh interval (from env: ATCR_HEALTH_CHECK_INTERVAL, default: 15m)
 	CheckInterval time.Duration `yaml:"check_interval"`
-
-	// ReadmeCacheTTL is the README cache TTL (from env: ATCR_README_CACHE_TTL, default: 1h)
-	ReadmeCacheTTL time.Duration `yaml:"readme_cache_ttl"`
 }
 
 // JetstreamConfig defines ATProto Jetstream settings
···
 	// Health and cache configuration
 	cfg.Health.CacheTTL = getDurationOrDefault("ATCR_HEALTH_CACHE_TTL", 15*time.Minute)
 	cfg.Health.CheckInterval = getDurationOrDefault("ATCR_HEALTH_CHECK_INTERVAL", 15*time.Minute)
-	cfg.Health.ReadmeCacheTTL = getDurationOrDefault("ATCR_README_CACHE_TTL", 1*time.Hour)
 
 	// Jetstream configuration
 	cfg.Jetstream.URL = getEnvOrDefault("JETSTREAM_URL", "wss://jetstream2.us-west.bsky.network/subscribe")

pkg/appview/db/migrations/0006_add_repo_pages.yaml

···
+description: Add repo_pages table and remove readme_cache
+query: |
+  -- Create repo_pages table for storing repository page metadata
+  -- This replaces readme_cache with PDS-synced data
+  CREATE TABLE IF NOT EXISTS repo_pages (
+      did TEXT NOT NULL,
+      repository TEXT NOT NULL,
+      description TEXT,
+      avatar_cid TEXT,
+      created_at TIMESTAMP NOT NULL,
+      updated_at TIMESTAMP NOT NULL,
+      PRIMARY KEY(did, repository),
+      FOREIGN KEY(did) REFERENCES users(did) ON DELETE CASCADE
+  );
+  CREATE INDEX IF NOT EXISTS idx_repo_pages_did ON repo_pages(did);
+
+  -- Drop readme_cache table (no longer needed)
+  DROP TABLE IF EXISTS readme_cache;

pkg/appview/db/queries.go

···
 
 	return featured, nil
 }
+
+// RepoPage represents a repository page record cached from PDS
+type RepoPage struct {
+	DID         string
+	Repository  string
+	Description string
+	AvatarCID   string
+	CreatedAt   time.Time
+	UpdatedAt   time.Time
+}
+
+// UpsertRepoPage inserts or updates a repo page record
+func UpsertRepoPage(db *sql.DB, did, repository, description, avatarCID string, createdAt, updatedAt time.Time) error {
+	_, err := db.Exec(`
+		INSERT INTO repo_pages (did, repository, description, avatar_cid, created_at, updated_at)
+		VALUES (?, ?, ?, ?, ?, ?)
+		ON CONFLICT(did, repository) DO UPDATE SET
+			description = excluded.description,
+			avatar_cid = excluded.avatar_cid,
+			updated_at = excluded.updated_at
+	`, did, repository, description, avatarCID, createdAt, updatedAt)
+	return err
+}
+
+// GetRepoPage retrieves a repo page record
+func GetRepoPage(db *sql.DB, did, repository string) (*RepoPage, error) {
+	var rp RepoPage
+	err := db.QueryRow(`
+		SELECT did, repository, description, avatar_cid, created_at, updated_at
+		FROM repo_pages
+		WHERE did = ? AND repository = ?
+	`, did, repository).Scan(&rp.DID, &rp.Repository, &rp.Description, &rp.AvatarCID, &rp.CreatedAt, &rp.UpdatedAt)
+	if err != nil {
+		return nil, err
+	}
+	return &rp, nil
+}
+
+// DeleteRepoPage deletes a repo page record
+func DeleteRepoPage(db *sql.DB, did, repository string) error {
+	_, err := db.Exec(`
+		DELETE FROM repo_pages WHERE did = ? AND repository = ?
+	`, did, repository)
+	return err
+}
+
+// GetRepoPagesByDID returns all repo pages for a DID
+func GetRepoPagesByDID(db *sql.DB, did string) ([]RepoPage, error) {
+	rows, err := db.Query(`
+		SELECT did, repository, description, avatar_cid, created_at, updated_at
+		FROM repo_pages
+		WHERE did = ?
+	`, did)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var pages []RepoPage
+	for rows.Next() {
+		var rp RepoPage
+		if err := rows.Scan(&rp.DID, &rp.Repository, &rp.Description, &rp.AvatarCID, &rp.CreatedAt, &rp.UpdatedAt); err != nil {
+			return nil, err
+		}
+		pages = append(pages, rp)
+	}
+	return pages, rows.Err()
+}

pkg/appview/db/schema.sql

···
 );
 CREATE INDEX IF NOT EXISTS idx_crew_denials_retry ON hold_crew_denials(next_retry_at);
 
-CREATE TABLE IF NOT EXISTS readme_cache (
-    url TEXT PRIMARY KEY,
-    html TEXT NOT NULL,
-    fetched_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+CREATE TABLE IF NOT EXISTS repo_pages (
+    did TEXT NOT NULL,
+    repository TEXT NOT NULL,
+    description TEXT,
+    avatar_cid TEXT,
+    created_at TIMESTAMP NOT NULL,
+    updated_at TIMESTAMP NOT NULL,
+    PRIMARY KEY(did, repository),
+    FOREIGN KEY(did) REFERENCES users(did) ON DELETE CASCADE
 );
-CREATE INDEX IF NOT EXISTS idx_readme_cache_fetched ON readme_cache(fetched_at);
+CREATE INDEX IF NOT EXISTS idx_repo_pages_did ON repo_pages(did);

pkg/appview/handlers/repository.go

···
 	Directory     identity.Directory
 	Refresher     *oauth.Refresher
 	HealthChecker *holdhealth.Checker
-	ReadmeCache   *readme.Cache
+	ReadmeFetcher *readme.Fetcher // For rendering repo page descriptions
 }
 
 func (h *RepositoryPageHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
···
 		isOwner = (user.DID == owner.DID)
 	}
 
-	// Fetch README content if available
+	// Fetch README content from repo page record or annotations
 	var readmeHTML template.HTML
-	if h.ReadmeCache != nil {
-		ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)
-		defer cancel()
 
-		if repo.ReadmeURL != "" {
-			// Explicit io.atcr.readme takes priority
-			html, err := h.ReadmeCache.Get(ctx, repo.ReadmeURL)
+	// Try repo page record from database (synced from PDS via Jetstream)
+	repoPage, err := db.GetRepoPage(h.DB, owner.DID, repository)
+	if err == nil && repoPage != nil && repoPage.Description != "" {
+		// Use repo page data
+		if h.ReadmeFetcher != nil {
+			html, err := h.ReadmeFetcher.RenderMarkdown([]byte(repoPage.Description))
 			if err != nil {
-				slog.Warn("Failed to fetch README", "url", repo.ReadmeURL, "error", err)
+				slog.Warn("Failed to render repo page description", "error", err)
 			} else {
 				readmeHTML = template.HTML(html)
 			}
-		} else if repo.SourceURL != "" {
-			// Derive README from org.opencontainers.image.source
-			html, err := h.ReadmeCache.GetFromSource(ctx, repo.SourceURL)
+		}
+		if repoPage.AvatarCID != "" {
+			repo.IconURL = atproto.BlobCDNURL(owner.DID, repoPage.AvatarCID)
+		}
+	} else if h.ReadmeFetcher != nil {
+		// Fall back to fetching from URL annotations
+		readmeURL := repo.ReadmeURL
+		if readmeURL == "" && repo.SourceURL != "" {
+			// Try to derive README URL from source URL
+			readmeURL = readme.DeriveReadmeURL(repo.SourceURL, "main")
+			if readmeURL == "" {
+				readmeURL = readme.DeriveReadmeURL(repo.SourceURL, "master")
+			}
+		}
+		if readmeURL != "" {
+			html, err := h.ReadmeFetcher.FetchAndRender(r.Context(), readmeURL)
 			if err != nil {
-				slog.Debug("Failed to derive README from source", "url", repo.SourceURL, "error", err)
-			} else if html != "" {
+				slog.Debug("Failed to fetch README from URL", "url", readmeURL, "error", err)
+			} else {
 				readmeHTML = template.HTML(html)
 			}
 		}

pkg/appview/jetstream/backfill.go

···
 		atproto.TagCollection,           // io.atcr.tag
 		atproto.StarCollection,          // io.atcr.sailor.star
 		atproto.SailorProfileCollection, // io.atcr.sailor.profile
+		atproto.RepoPageCollection,      // io.atcr.repo.page
 	}
 
 	for _, collection := range collections {
···
 		return b.processor.ProcessStar(context.Background(), did, record.Value)
 	case atproto.SailorProfileCollection:
 		return b.processor.ProcessSailorProfile(ctx, did, record.Value, b.queryCaptainRecordWrapper)
+	case atproto.RepoPageCollection:
+		// rkey is extracted from the record URI, but for repo pages we use Repository field
+		return b.processor.ProcessRepoPage(ctx, did, record.URI, record.Value, false)
 	default:
 		return fmt.Errorf("unsupported collection: %s", collection)
 	}

pkg/appview/jetstream/processor.go

···
 	return nil
 }
 
+// ProcessRepoPage processes a repository page record
+// This is called when Jetstream receives a repo page create/update event
+func (p *Processor) ProcessRepoPage(ctx context.Context, did string, rkey string, recordData []byte, isDelete bool) error {
+	if isDelete {
+		// Delete the repo page from our cache
+		return db.DeleteRepoPage(p.db, did, rkey)
+	}
+
+	// Unmarshal repo page record
+	var pageRecord atproto.RepoPageRecord
+	if err := json.Unmarshal(recordData, &pageRecord); err != nil {
+		return fmt.Errorf("failed to unmarshal repo page: %w", err)
+	}
+
+	// Extract avatar CID if present
+	avatarCID := ""
+	if pageRecord.Avatar != nil && pageRecord.Avatar.Ref.Link != "" {
+		avatarCID = pageRecord.Avatar.Ref.Link
+	}
+
+	// Upsert to database
+	return db.UpsertRepoPage(p.db, did, pageRecord.Repository, pageRecord.Description, avatarCID, pageRecord.CreatedAt, pageRecord.UpdatedAt)
+}
+
 // ProcessIdentity handles identity change events (handle updates)
 // This is called when Jetstream receives an identity event indicating a handle change.
 // The identity cache is invalidated to ensure the next lookup uses the new handle,

pkg/appview/jetstream/worker.go

···
 		case atproto.StarCollection:
 			slog.Info("Jetstream processing star event", "did", commit.DID, "operation", commit.Operation, "rkey", commit.RKey)
 			return w.processStar(commit)
+		case atproto.RepoPageCollection:
+			slog.Info("Jetstream processing repo page event", "did", commit.DID, "operation", commit.Operation, "rkey", commit.RKey)
+			return w.processRepoPage(commit)
 		default:
 			// Ignore other collections
 			return nil
···
 
 	// Use shared processor for DB operations
 	return w.processor.ProcessStar(context.Background(), commit.DID, recordBytes)
+}
+
+// processRepoPage processes a repo page commit event
+func (w *Worker) processRepoPage(commit *CommitEvent) error {
+	// Resolve and upsert user with handle/PDS endpoint
+	if err := w.processor.EnsureUser(context.Background(), commit.DID); err != nil {
+		return fmt.Errorf("failed to ensure user: %w", err)
+	}
+
+	isDelete := commit.Operation == "delete"
+
+	if isDelete {
+		// Delete - rkey is the repository name
+		slog.Info("Jetstream deleting repo page", "did", commit.DID, "repository", commit.RKey)
+		if err := w.processor.ProcessRepoPage(context.Background(), commit.DID, commit.RKey, nil, true); err != nil {
+			slog.Error("Jetstream ERROR deleting repo page", "error", err)
+			return err
+		}
+		slog.Info("Jetstream successfully deleted repo page", "did", commit.DID, "repository", commit.RKey)
+		return nil
+	}
+
+	// Parse repo page record
+	if commit.Record == nil {
+		return nil
+	}
+
+	// Marshal map to bytes for processing
+	recordBytes, err := json.Marshal(commit.Record)
+	if err != nil {
+		return fmt.Errorf("failed to marshal record: %w", err)
+	}
+
+	// Use shared processor for DB operations
+	return w.processor.ProcessRepoPage(context.Background(), commit.DID, commit.RKey, recordBytes, false)
 }
 
 // processIdentity processes an identity event (handle change)

pkg/appview/middleware/registry.go

···
 // These are set by main.go during startup and copied into NamespaceResolver instances.
 // After initialization, request handling uses the NamespaceResolver's instance fields.
 var (
-	globalRefresher   *oauth.Refresher
-	globalDatabase    storage.DatabaseMetrics
-	globalAuthorizer  auth.HoldAuthorizer
-	globalReadmeCache storage.ReadmeCache
+	globalRefresher  *oauth.Refresher
+	globalDatabase   storage.DatabaseMetrics
+	globalAuthorizer auth.HoldAuthorizer
 )
 
 // SetGlobalRefresher sets the OAuth refresher instance during initialization
···
 	globalAuthorizer = authorizer
 }
 
-// SetGlobalReadmeCache sets the readme cache instance during initialization
-// Must be called before the registry starts serving requests
-func SetGlobalReadmeCache(readmeCache storage.ReadmeCache) {
-	globalReadmeCache = readmeCache
-}
-
 func init() {
 	// Register the name resolution middleware
 	registrymw.Register("atproto-resolver", initATProtoResolver)
···
 	refresher       *oauth.Refresher        // OAuth session manager (copied from global on init)
 	database        storage.DatabaseMetrics // Metrics database (copied from global on init)
 	authorizer      auth.HoldAuthorizer     // Hold authorization (copied from global on init)
-	readmeCache     storage.ReadmeCache     // README cache (copied from global on init)
 	validationCache *validationCache        // Request-level service token cache
 }
 
···
 		refresher:       globalRefresher,
 		database:        globalDatabase,
 		authorizer:      globalAuthorizer,
-		readmeCache:     globalReadmeCache,
 		validationCache: newValidationCache(),
 	}, nil
 }
···
 		Database:      nr.database,
 		Authorizer:    nr.authorizer,
 		Refresher:     nr.refresher,
-		ReadmeCache:   nr.readmeCache,
 	}
 
 	return storage.NewRoutingRepository(repo, registryCtx), nil

pkg/appview/middleware/registry_test.go

···
 	// If we get here without panic, test passes
 }
 
-func TestSetGlobalReadmeCache(t *testing.T) {
-	SetGlobalReadmeCache(nil)
-	// If we get here without panic, test passes
-}
-
 // TestInitATProtoResolver tests the initialization function
 func TestInitATProtoResolver(t *testing.T) {
 	ctx := context.Background()

pkg/appview/readme/cache.go

···
-// Package readme provides README fetching, rendering, and caching functionality
-// for container repositories. It fetches markdown content from URLs, renders it
-// to sanitized HTML using GitHub-flavored markdown, and caches the results in
-// a database with configurable TTL.
-package readme
-
-import (
-	"context"
-	"database/sql"
-	"log/slog"
-	"time"
-)
-
-const (
-	// negativeCacheTTL is the TTL for negative cache entries (no README found)
-	negativeCacheTTL = 15 * time.Minute
-	// sourceCachePrefix is the prefix for source-derived cache keys
-	sourceCachePrefix = "source:"
-)
-
-// Cache stores rendered README HTML in the database
-type Cache struct {
-	db      *sql.DB
-	fetcher *Fetcher
-	ttl     time.Duration
-}
-
-// NewCache creates a new README cache
-func NewCache(db *sql.DB, ttl time.Duration) *Cache {
-	if ttl == 0 {
-		ttl = 1 * time.Hour // Default TTL
-	}
-	return &Cache{
-		db:      db,
-		fetcher: NewFetcher(),
-		ttl:     ttl,
-	}
-}
-
-// Get retrieves a README from cache or fetches it
-func (c *Cache) Get(ctx context.Context, readmeURL string) (string, error) {
-	// Try to get from cache
-	html, fetchedAt, err := c.getFromDB(readmeURL)
-	if err == nil {
-		// Check if cache is still valid
-		if time.Since(fetchedAt) < c.ttl {
-			return html, nil
-		}
-	}
-
-	// Cache miss or expired, fetch fresh content
-	html, err = c.fetcher.FetchAndRender(ctx, readmeURL)
-	if err != nil {
-		// If fetch fails but we have stale cache, return it
-		if html != "" {
-			return html, nil
-		}
-		return "", err
-	}
-
-	// Store in cache
-	if err := c.storeInDB(readmeURL, html); err != nil {
-		// Log error but don't fail - we have the content
-		slog.Warn("Failed to cache README", "error", err)
-	}
-
-	return html, nil
-}
-
-// GetFromSource fetches a README by deriving the URL from a source repository URL.
-// It tries main branch first, then falls back to master if 404.
-// Returns empty string if no README found (cached as negative result with shorter TTL).
-func (c *Cache) GetFromSource(ctx context.Context, sourceURL string) (string, error) {
-	cacheKey := sourceCachePrefix + sourceURL
-
-	// Try to get from cache
-	html, fetchedAt, err := c.getFromDB(cacheKey)
-	if err == nil {
-		// Determine TTL based on whether this is a negative cache entry
-		ttl := c.ttl
-		if html == "" {
-			ttl = negativeCacheTTL
-		}
-		if time.Since(fetchedAt) < ttl {
-			return html, nil
-		}
-	}
-
-	// Derive README URL and fetch
-	// Try main branch first
-	readmeURL := DeriveReadmeURL(sourceURL, "main")
-	if readmeURL == "" {
-		return "", nil // Unsupported platform, don't cache
-	}
-
-	html, err = c.fetcher.FetchAndRender(ctx, readmeURL)
-	if err != nil {
-		if Is404(err) {
-			// Try master branch
-			readmeURL = DeriveReadmeURL(sourceURL, "master")
-			html, err = c.fetcher.FetchAndRender(ctx, readmeURL)
-			if err != nil {
-				if Is404(err) {
-					// No README on either branch - cache negative result
-					if cacheErr := c.storeInDB(cacheKey, ""); cacheErr != nil {
-						slog.Warn("Failed to cache negative README result", "error", cacheErr)
-					}
-					return "", nil
-				}
-				// Other error (network, etc.) - don't cache, allow retry
-				return "", err
-			}
-		} else {
-			// Other error (network, etc.) - don't cache, allow retry
-			return "", err
-		}
-	}
-
-	// Store successful result in cache
-	if err := c.storeInDB(cacheKey, html); err != nil {
-		slog.Warn("Failed to cache README from source", "error", err)
-	}
-
-	return html, nil
-}
-
-// getFromDB retrieves cached README from database
-func (c *Cache) getFromDB(readmeURL string) (string, time.Time, error) {
-	var html string
-	var fetchedAt time.Time
-
-	err := c.db.QueryRow(`
-		SELECT html, fetched_at
-		FROM readme_cache
-		WHERE url = ?
-	`, readmeURL).Scan(&html, &fetchedAt)
-
-	if err != nil {
-		return "", time.Time{}, err
-	}
-
-	return html, fetchedAt, nil
-}
-
-// storeInDB stores rendered README in database
-func (c *Cache) storeInDB(readmeURL, html string) error {
-	_, err := c.db.Exec(`
-		INSERT INTO readme_cache (url, html, fetched_at)
-		VALUES (?, ?, ?)
-		ON CONFLICT(url) DO UPDATE SET
-			html = excluded.html,
-			fetched_at = excluded.fetched_at
-	`, readmeURL, html, time.Now())
-
-	return err
-}
-
-// Invalidate removes a README from the cache
-func (c *Cache) Invalidate(readmeURL string) error {
-	_, err := c.db.Exec(`
-		DELETE FROM readme_cache
-		WHERE url = ?
-	`, readmeURL)
-	return err
-}
-
-// Cleanup removes expired entries from the cache
-func (c *Cache) Cleanup() error {
-	cutoff := time.Now().Add(-c.ttl * 2) // Keep for 2x TTL
-	_, err := c.db.Exec(`
-		DELETE FROM readme_cache
-		WHERE fetched_at < ?
-	`, cutoff)
-	return err
-}

pkg/appview/readme/cache_test.go

···
-package readme
-
-import (
-	"context"
-	"database/sql"
-	"fmt"
-	"testing"
-	"time"
-
-	_ "github.com/mattn/go-sqlite3"
-)
-
-func TestCache_Struct(t *testing.T) {
-	// Simple struct test
-	cache := &Cache{}
-	if cache == nil {
-		t.Error("Expected non-nil cache")
-	}
-}
-
-func setupTestDB(t *testing.T) *sql.DB {
-	t.Helper()
-	db, err := sql.Open("sqlite3", ":memory:")
-	if err != nil {
-		t.Fatalf("Failed to open database: %v", err)
-	}
-
-	// Create the readme_cache table
-	_, err = db.Exec(`
-		CREATE TABLE readme_cache (
-			url TEXT PRIMARY KEY,
-			html TEXT NOT NULL,
-			fetched_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
-		)
-	`)
-	if err != nil {
-		t.Fatalf("Failed to create table: %v", err)
-	}
-
-	return db
-}
-
-func TestGetFromSource_UnsupportedPlatform(t *testing.T) {
-	db := setupTestDB(t)
-	defer db.Close()
-
-	cache := NewCache(db, time.Hour)
-	ctx := context.Background()
-
-	// Unsupported platform should return empty, no error
-	html, err := cache.GetFromSource(ctx, "https://bitbucket.org/user/repo")
-	if err != nil {
-		t.Errorf("Expected no error for unsupported platform, got: %v", err)
-	}
-	if html != "" {
-		t.Errorf("Expected empty string for unsupported platform, got: %q", html)
-	}
-}
-
-func TestGetFromSource_CacheHit(t *testing.T) {
-	db := setupTestDB(t)
-	defer db.Close()
-
-	cache := NewCache(db, time.Hour)
-	sourceURL := "https://github.com/test/repo"
-	cacheKey := sourceCachePrefix + sourceURL
-	expectedHTML := "<h1>Cached Content</h1>"
-
-	// Pre-populate cache
-	_, err := db.Exec(`
-		INSERT INTO readme_cache (url, html, fetched_at)
-		VALUES (?, ?, ?)
-	`, cacheKey, expectedHTML, time.Now())
-	if err != nil {
-		t.Fatalf("Failed to insert cache: %v", err)
-	}
-
-	ctx := context.Background()
-	html, err := cache.GetFromSource(ctx, sourceURL)
-	if err != nil {
-		t.Errorf("Expected no error, got: %v", err)
-	}
-	if html != expectedHTML {
-		t.Errorf("Expected %q, got %q", expectedHTML, html)
-	}
-}
-
-func TestGetFromSource_CacheExpired(t *testing.T) {
-	db := setupTestDB(t)
-	defer db.Close()
-
-	cache := NewCache(db, time.Millisecond) // Very short TTL
-	sourceURL := "https://github.com/test/repo"
-	cacheKey := sourceCachePrefix + sourceURL
-	oldHTML := "<h1>Old Content</h1>"
-
-	// Pre-populate cache with old timestamp
-	_, err := db.Exec(`
-		INSERT INTO readme_cache (url, html, fetched_at)
-		VALUES (?, ?, ?)
-	`, cacheKey, oldHTML, time.Now().Add(-time.Hour))
-	if err != nil {
-		t.Fatalf("Failed to insert cache: %v", err)
-	}
-
-	ctx := context.Background()
-
-	// With expired cache and no network (GitHub won't respond), we expect an error
-	// but the function should try to fetch
-	_, err = cache.GetFromSource(ctx, sourceURL)
-	// We expect an error because we can't actually fetch from GitHub in tests
-	// The important thing is that it tried to fetch (didn't return cached content)
-	if err == nil {
-		t.Log("Note: GetFromSource returned no error - cache was expired and fetch was attempted")
-	}
-}
-
-func TestGetFromSource_NegativeCache(t *testing.T) {
-	db := setupTestDB(t)
-	defer db.Close()
-
-	cache := NewCache(db, time.Hour)
-	sourceURL := "https://github.com/test/repo"
-	cacheKey := sourceCachePrefix + sourceURL
-
-	// Pre-populate cache with empty string (negative cache)
-	_, err := db.Exec(`
-		INSERT INTO readme_cache (url, html, fetched_at)
-		VALUES (?, ?, ?)
-	`, cacheKey, "", time.Now())
-	if err != nil {
-		t.Fatalf("Failed to insert cache: %v", err)
-	}
-
-	ctx := context.Background()
-	html, err := cache.GetFromSource(ctx, sourceURL)
-	if err != nil {
-		t.Errorf("Expected no error for negative cache hit, got: %v", err)
-	}
-	if html != "" {
-		t.Errorf("Expected empty string for negative cache hit, got: %q", html)
-	}
-}
-
-func TestGetFromSource_NegativeCacheExpired(t *testing.T) {
-	db := setupTestDB(t)
-	defer db.Close()
-
-	cache := NewCache(db, time.Hour)
-	sourceURL := "https://github.com/test/repo"
-	cacheKey := sourceCachePrefix + sourceURL
-
-	// Pre-populate cache with expired negative cache (older than negativeCacheTTL)
-	_, err := db.Exec(`
-		INSERT INTO readme_cache (url, html, fetched_at)
-		VALUES (?, ?, ?)
-	`, cacheKey, "", time.Now().Add(-30*time.Minute)) // 30 min ago, negative TTL is 15 min
-	if err != nil {
-		t.Fatalf("Failed to insert cache: %v", err)
-	}
-
-	ctx := context.Background()
-
-	// With expired negative cache, it should try to fetch again
-	_, err = cache.GetFromSource(ctx, sourceURL)
-	// We expect an error because we can't actually fetch from GitHub
-	// The important thing is that it tried (didn't return empty from expired negative cache)
-	if err == nil {
-		t.Log("Note: GetFromSource attempted refetch after negative cache expired")
-	}
-}
-
-func TestGetFromSource_EmptyURL(t *testing.T) {
-	db := setupTestDB(t)
-	defer db.Close()
-
-	cache := NewCache(db, time.Hour)
-	ctx := context.Background()
-
-	html, err := cache.GetFromSource(ctx, "")
-	if err != nil {
-		t.Errorf("Expected no error for empty URL, got: %v", err)
-	}
-	if html != "" {
-		t.Errorf("Expected empty string for empty URL, got: %q", html)
-	}
-}
-
-func TestGetFromSource_UnsupportedPlatforms(t *testing.T) {
-	db := setupTestDB(t)
-	defer db.Close()
-
-	cache := NewCache(db, time.Hour)
-	ctx := context.Background()
-
-	unsupportedURLs := []string{
-		"https://bitbucket.org/user/repo",
-		"https://sourcehut.org/user/repo",
-		"https://codeberg.org/user/repo",
-		"ftp://github.com/user/repo",
-		"not-a-url",
-	}
-
-	for _, url := range unsupportedURLs {
-		html, err := cache.GetFromSource(ctx, url)
-		if err != nil {
-			t.Errorf("Expected no error for unsupported URL %q, got: %v", url, err)
-		}
-		if html != "" {
-			t.Errorf("Expected empty string for unsupported URL %q, got: %q", url, html)
-		}
-	}
-}
-
-func TestIs404(t *testing.T) {
-	tests := []struct {
-		name string
-		err  error
-		want bool
-	}{
-		{
-			name: "nil error",
-			err:  nil,
-			want: false,
-		},
-		{
-			name: "404 error",
-			err:  fmt.Errorf("unexpected status code: 404"),
-			want: true,
-		},
-		{
-			name: "404 error with context",
-			err:  fmt.Errorf("failed to fetch: unexpected status code: 404"),
-			want: true,
-		},
-		{
-			name: "500 error",
-			err:  fmt.Errorf("unexpected status code: 500"),
-			want: false,
-		},
-		{
-			name: "network error",
-			err:  fmt.Errorf("connection refused"),
-			want: false,
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got := Is404(tt.err)
-			if got != tt.want {
-				t.Errorf("Is404(%v) = %v, want %v", tt.err, got, tt.want)
-			}
-		})
-	}
-}

pkg/appview/readme/fetcher.go

···
 	return err != nil && strings.Contains(err.Error(), "unexpected status code: 404")
 }
 
+// RenderMarkdown renders a markdown string to sanitized HTML
+// This is used for rendering repo page descriptions stored in the database
+func (f *Fetcher) RenderMarkdown(content []byte) (string, error) {
+	// Render markdown to HTML (no base URL for repo page descriptions)
+	return f.renderMarkdown(content, "")
+}
+
 // rewriteRelativeURLs converts relative URLs to absolute URLs
 func rewriteRelativeURLs(html, baseURL string) string {
 	if baseURL == "" {

pkg/appview/readme/fetcher_test.go

···
 	}
 }
 
+func TestFetcher_RenderMarkdown(t *testing.T) {
+	fetcher := NewFetcher()
+
+	tests := []struct {
+		name        string
+		content     string
+		wantContain string
+		wantErr     bool
+	}{
+		{
+			name:        "simple paragraph",
+			content:     "Hello, world!",
+			wantContain: "<p>Hello, world!</p>",
+			wantErr:     false,
+		},
+		{
+			name:        "heading",
+			content:     "# My App",
+			wantContain: "<h1",
+			wantErr:     false,
+		},
+		{
+			name:        "bold text",
+			content:     "This is **bold** text.",
+			wantContain: "<strong>bold</strong>",
+			wantErr:     false,
+		},
+		{
+			name:        "italic text",
+			content:     "This is *italic* text.",
+			wantContain: "<em>italic</em>",
+			wantErr:     false,
+		},
+		{
+			name:        "code block",
+			content:     "```\ncode here\n```",
+			wantContain: "<pre>",
+			wantErr:     false,
+		},
+		{
+			name:        "link",
+			content:     "[Link text](https://example.com)",
+			wantContain: `href="https://example.com"`,
+			wantErr:     false,
+		},
+		{
+			name:        "image",
+			content:     "![Alt text](https://example.com/image.png)",
+			wantContain: `src="https://example.com/image.png"`,
+			wantErr:     false,
+		},
+		{
+			name:        "unordered list",
+			content:     "- Item 1\n- Item 2",
+			wantContain: "<ul>",
+			wantErr:     false,
+		},
+		{
+			name:        "ordered list",
+			content:     "1. Item 1\n2. Item 2",
+			wantContain: "<ol>",
+			wantErr:     false,
+		},
+		{
+			name:        "empty content",
+			content:     "",
+			wantContain: "",
+			wantErr:     false,
+		},
+		{
+			name:        "complex markdown",
+			content:     "# Title\n\nA paragraph with **bold** and *italic* text.\n\n- List item 1\n- List item 2\n\n```go\nfunc main() {}\n```",
+			wantContain: "<h1",
+			wantErr:     false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			html, err := fetcher.RenderMarkdown([]byte(tt.content))
+			if (err != nil) != tt.wantErr {
+				t.Errorf("RenderMarkdown() error = %v, wantErr %v", err, tt.wantErr)
+				return
+			}
+			if !tt.wantErr && tt.wantContain != "" {
+				if !containsSubstring(html, tt.wantContain) {
+					t.Errorf("RenderMarkdown() = %q, want to contain %q", html, tt.wantContain)
+				}
+			}
+		})
+	}
+}
+
+func containsSubstring(s, substr string) bool {
+	return len(substr) == 0 || (len(s) >= len(substr) && (s == substr || len(s) > 0 && containsSubstringHelper(s, substr)))
+}
+
+func containsSubstringHelper(s, substr string) bool {
+	for i := 0; i <= len(s)-len(substr); i++ {
+		if s[i:i+len(substr)] == substr {
+			return true
+		}
+	}
+	return false
+}
+
 // TODO: Add README fetching and caching tests

pkg/appview/routes/routes.go

···
 	BaseURL        string
 	DeviceStore    *db.DeviceStore
 	HealthChecker  *holdhealth.Checker
-	ReadmeCache    *readme.Cache
+	ReadmeFetcher  *readme.Fetcher
 	Templates      *template.Template
 }
 
···
 			Directory:     deps.OAuthClientApp.Dir,
 			Refresher:     deps.Refresher,
 			HealthChecker: deps.HealthChecker,
-			ReadmeCache:   deps.ReadmeCache,
+			ReadmeFetcher: deps.ReadmeFetcher,
 		},
 	).ServeHTTP)
 

pkg/appview/static/css/style.css

···
     --version-badge-text: #7b1fa2;
     --version-badge-border: #ba68c8;
 
+    /* Attestation badge */
+    --attestation-badge-bg: #d1fae5;
+    --attestation-badge-text: #065f46;
+
     /* Hero section colors */
     --hero-bg-start: #f8f9fa;
     --hero-bg-end: #e9ecef;
···
     --version-badge-bg: #9b59b6;
     --version-badge-text: #ffffff;
     --version-badge-border: #ba68c8;
+
+    /* Attestation badge */
+    --attestation-badge-bg: #065f46;
+    --attestation-badge-text: #6ee7b7;
 
     /* Hero section colors */
     --hero-bg-start: #2d2d2d;
···
 }
 
 body {
-    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+    font-family:
+        -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue",
+        Arial, sans-serif;
     background: var(--bg);
     color: var(--fg);
     line-height: 1.6;
···
 }
 
 .nav-links a:hover {
-    background:var(--secondary);
+    background: var(--secondary);
     border-radius: 4px;
 }
 
···
 }
 
 .user-menu-btn:hover {
-    background:var(--secondary);
+    background: var(--secondary);
 }
 
 .user-avatar {
···
     position: absolute;
     top: calc(100% + 0.5rem);
     right: 0;
-    background:var(--bg);
+    background: var(--bg);
     border: 1px solid var(--border);
     border-radius: 8px;
     box-shadow: var(--shadow-lg);
···
     color: var(--fg);
     text-decoration: none;
     border: none;
-    background:var(--bg);
+    background: var(--bg);
     cursor: pointer;
     transition: background 0.2s;
     font-size: 0.95rem;
···
 }
 
 /* Buttons */
-button, .btn, .btn-primary, .btn-secondary {
+button,
+.btn,
+.btn-primary,
+.btn-secondary {
     padding: 0.5rem 1rem;
     background: var(--button-primary);
     color: var(--btn-text);
···
     transition: opacity 0.2s;
 }
 
-button:hover, .btn:hover, .btn-primary:hover, .btn-secondary:hover {
+button:hover,
+.btn:hover,
+.btn-primary:hover,
+.btn-secondary:hover {
     opacity: 0.9;
 }
 
···
 }
 
 /* Cards */
-.push-card, .repository-card {
+.push-card,
+.repository-card {
     border: 1px solid var(--border);
     border-radius: 8px;
     padding: 1rem;
     margin-bottom: 1rem;
-    background:var(--bg);
+    background: var(--bg);
     box-shadow: var(--shadow-sm);
 }
 
···
 }
 
 .digest {
-    font-family: 'Monaco', 'Courier New', monospace;
+    font-family: "Monaco", "Courier New", monospace;
     font-size: 0.85rem;
     background: var(--code-bg);
     padding: 0.1rem 0.3rem;
···
 }
 
 .docker-command-text {
-    font-family: 'Monaco', 'Courier New', monospace;
+    font-family: "Monaco", "Courier New", monospace;
     font-size: 0.85rem;
     color: var(--fg);
     flex: 0 1 auto;
···
     border-radius: 4px;
     opacity: 0;
     visibility: hidden;
-    transition: opacity 0.2s, visibility 0.2s;
+    transition:
+        opacity 0.2s,
+        visibility 0.2s;
 }
 
 .docker-command:hover .copy-btn {
···
 }
 
 .repo-stats {
-    color:var(--border-dark);
+    color: var(--border-dark);
     font-size: 0.9rem;
     display: flex;
     gap: 0.5rem;
···
     padding-top: 1rem;
 }
 
-.tags-section, .manifests-section {
+.tags-section,
+.manifests-section {
     margin-bottom: 1.5rem;
 }
 
-.tags-section h3, .manifests-section h3 {
+.tags-section h3,
+.manifests-section h3 {
     font-size: 1.1rem;
     margin-bottom: 0.5rem;
     color: var(--secondary);
 }
 
-.tag-row, .manifest-row {
+.tag-row,
+.manifest-row {
     display: flex;
     gap: 1rem;
     align-items: center;
···
     border-bottom: 1px solid var(--border);
 }
 
-.tag-row:last-child, .manifest-row:last-child {
+.tag-row:last-child,
+.manifest-row:last-child {
     border-bottom: none;
 }
 
···
 }
 
 .settings-section {
-    background:var(--bg);
+    background: var(--bg);
     border: 1px solid var(--border);
     border-radius: 8px;
     padding: 1.5rem;
···
     padding: 1rem;
     border-radius: 4px;
     overflow-x: auto;
-    font-family: 'Monaco', 'Courier New', monospace;
+    font-family: "Monaco", "Courier New", monospace;
     font-size: 0.85rem;
     border: 1px solid var(--border);
 }
···
 }
 
 .login-form {
-    background:var(--bg);
+    background: var(--bg);
     padding: 2rem;
     border-radius: 8px;
     border: 1px solid var(--border);
···
 }
 
 .repository-header {
-    background:var(--bg);
+    background: var(--bg);
     border: 1px solid var(--border);
     border-radius: 8px;
     padding: 2rem;
···
 }
 
 .star-btn.starred {
-    border-color:var(--star);
+    border-color: var(--star);
     background: var(--code-bg);
 }
 
···
 }
 
 .repo-section {
-    background:var(--bg);
+    background: var(--bg);
     border: 1px solid var(--border);
     border-radius: 8px;
     padding: 1.5rem;
···
     border-bottom: 2px solid var(--border);
 }
 
-.tags-list, .manifests-list {
+.tags-list,
+.manifests-list {
     display: flex;
     flex-direction: column;
     gap: 1rem;
 }
 
-.tag-item, .manifest-item {
+.tag-item,
+.manifest-item {
     border: 1px solid var(--border);
     border-radius: 6px;
     padding: 1rem;
     background: var(--hover-bg);
 }
 
-.tag-item-header, .manifest-item-header {
+.tag-item-header,
+.manifest-item-header {
     display: flex;
     justify-content: space-between;
     align-items: center;
···
     color: var(--fg);
     border: 1px solid var(--border);
     white-space: nowrap;
-    font-family: 'Monaco', 'Courier New', monospace;
+    font-family: "Monaco", "Courier New", monospace;
 }
 
 .platforms-inline {
···
 .badge-attestation {
     display: inline-flex;
     align-items: center;
-    gap: 0.35rem;
-    padding: 0.25rem 0.5rem;
-    background: #f3e8ff;
-    color: #7c3aed;
-    border: 1px solid #c4b5fd;
-    border-radius: 4px;
-    font-size: 0.85rem;
+    gap: 0.3rem;
+    padding: 0.25rem 0.6rem;
+    background: var(--attestation-badge-bg);
+    color: var(--attestation-badge-text);
+    border-radius: 12px;
+    font-size: 0.75rem;
     font-weight: 600;
     margin-left: 0.5rem;
+    vertical-align: middle;
+    white-space: nowrap;
 }
 
 .badge-attestation .lucide {
-    width: 0.9rem;
-    height: 0.9rem;
+    width: 0.75rem;
+    height: 0.75rem;
 }
 
 /* Featured Repositories Section */
···
 
 /* Hero Section */
 .hero-section {
-    background: linear-gradient(135deg, var(--hero-bg-start) 0%, var(--hero-bg-end) 100%);
+    background: linear-gradient(
+        135deg,
+        var(--hero-bg-start) 0%,
+        var(--hero-bg-end) 100%
+    );
     padding: 4rem 2rem;
     border-bottom: 1px solid var(--border);
 }
···
 .terminal-content {
     padding: 1.5rem;
     margin: 0;
-    font-family: 'Monaco', 'Courier New', monospace;
+    font-family: "Monaco", "Courier New", monospace;
     font-size: 0.95rem;
     line-height: 1.8;
     color: var(--terminal-text);
···
 }
 
 .code-block code {
-    font-family: 'Monaco', 'Menlo', monospace;
+    font-family: "Monaco", "Menlo", monospace;
     font-size: 0.9rem;
     line-height: 1.5;
     white-space: pre-wrap;
···
         flex-wrap: wrap;
     }
 
-    .tag-row, .manifest-row {
+    .tag-row,
+    .manifest-row {
         flex-wrap: wrap;
     }
 
···
 /* README and Repository Layout */
 .repo-content-layout {
     display: grid;
-    grid-template-columns: 7fr 3fr;
+    grid-template-columns: 6fr 4fr;
     gap: 2rem;
     margin-top: 2rem;
 }
···
     background: var(--code-bg);
     padding: 0.2rem 0.4rem;
     border-radius: 3px;
-    font-family: 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace;
+    font-family:
+        "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
     font-size: 0.9em;
 }
 

pkg/appview/storage/context.go

···
 package storage
 
 import (
-	"context"
-
 	"atcr.io/pkg/atproto"
 	"atcr.io/pkg/auth"
 	"atcr.io/pkg/auth/oauth"
···
 	IncrementPullCount(did, repository string) error
 	IncrementPushCount(did, repository string) error
 	GetLatestHoldDIDForRepo(did, repository string) (string, error)
-}
-
-// ReadmeCache interface for README content caching
-type ReadmeCache interface {
-	Get(ctx context.Context, url string) (string, error)
-	Invalidate(url string) error
 }
 
 // RegistryContext bundles all the context needed for registry operations
···
 	AuthMethod    string          // Auth method used ("oauth" or "app_password")
 
 	// Shared services (same for all requests)
-	Database    DatabaseMetrics     // Metrics tracking database
-	Authorizer  auth.HoldAuthorizer // Hold access authorization
-	Refresher   *oauth.Refresher    // OAuth session manager
-	ReadmeCache ReadmeCache         // README content cache
+	Database   DatabaseMetrics     // Metrics tracking database
+	Authorizer auth.HoldAuthorizer // Hold access authorization
+	Refresher  *oauth.Refresher    // OAuth session manager
 }

pkg/appview/storage/context_test.go

···
 package storage
 
 import (
-	"context"
 	"sync"
 	"testing"
 
···
 	return m.pushCount
 }
 
-type mockReadmeCache struct{}
-
-func (m *mockReadmeCache) Get(ctx context.Context, url string) (string, error) {
-	return "# Test README", nil
-}
-
-func (m *mockReadmeCache) Invalidate(url string) error {
-	return nil
-}
-
 type mockHoldAuthorizer struct{}
 
 func (m *mockHoldAuthorizer) Authorize(holdDID, userDID, permission string) (bool, error) {
···
 		ATProtoClient: &atproto.Client{
 			// Mock client - would need proper initialization in real tests
 		},
-		Database:    &mockDatabaseMetrics{},
-		ReadmeCache: &mockReadmeCache{},
+		Database: &mockDatabaseMetrics{},
 	}
 
 	// Verify fields are accessible
···
 	}
 
 	err = ctx.Database.IncrementPushCount("did:plc:test", "repo")
-	if err != nil {
-		t.Errorf("Unexpected error: %v", err)
-	}
-}
-
-func TestRegistryContext_ReadmeCacheInterface(t *testing.T) {
-	cache := &mockReadmeCache{}
-	ctx := &RegistryContext{
-		ReadmeCache: cache,
-	}
-
-	// Test that interface methods are callable
-	content, err := ctx.ReadmeCache.Get(context.Background(), "https://example.com/README.md")
-	if err != nil {
-		t.Errorf("Unexpected error: %v", err)
-	}
-	if content != "# Test README" {
-		t.Errorf("Expected content %q, got %q", "# Test README", content)
-	}
-
-	err = ctx.ReadmeCache.Invalidate("https://example.com/README.md")
 	if err != nil {
 		t.Errorf("Unexpected error: %v", err)
 	}

pkg/appview/storage/manifest_store.go

···
 	"net/http"
 	"strings"
 	"sync"
-	"time"
 
 	"atcr.io/pkg/atproto"
 	"github.com/distribution/distribution/v3"
···
 		}()
 	}
 
-	// Refresh README cache asynchronously if manifest has io.atcr.readme annotation
-	// This ensures fresh README content is available on repository pages
+	// Create or update repo page asynchronously if manifest has relevant annotations
+	// This ensures repository metadata is synced to user's PDS
 	go func() {
 		defer func() {
 			if r := recover(); r != nil {
-				slog.Error("Panic in refreshReadmeCache", "panic", r)
+				slog.Error("Panic in ensureRepoPage", "panic", r)
 			}
 		}()
-		s.refreshReadmeCache(context.Background(), manifestRecord)
+		s.ensureRepoPage(context.Background(), manifestRecord)
 	}()
 
 	return dgst, nil
···
 	return nil
 }
 
-// refreshReadmeCache refreshes the README cache for this manifest if it has io.atcr.readme annotation
-// This should be called asynchronously after manifest push to keep README content fresh
-func (s *ManifestStore) refreshReadmeCache(ctx context.Context, manifestRecord *atproto.ManifestRecord) {
-	// Skip if no README cache configured
-	if s.ctx.ReadmeCache == nil {
+// ensureRepoPage creates or updates a repo page record in the user's PDS if needed
+// This syncs repository metadata from manifest annotations to the io.atcr.repo.page collection
+// Only creates a new record if one doesn't exist (doesn't overwrite user's custom content)
+func (s *ManifestStore) ensureRepoPage(ctx context.Context, manifestRecord *atproto.ManifestRecord) {
+	// Skip if no annotations
+	if manifestRecord.Annotations == nil {
 		return
 	}
 
-	// Skip if no annotations or no README URL
-	if manifestRecord.Annotations == nil {
+	// Check for relevant annotations that we can use for repo page
+	description := manifestRecord.Annotations["org.opencontainers.image.description"]
+	if description == "" {
+		// No description annotation - nothing to create
 		return
 	}
 
-	readmeURL, ok := manifestRecord.Annotations["io.atcr.readme"]
-	if !ok || readmeURL == "" {
+	// Check if repo page already exists (don't overwrite user's custom content)
+	rkey := s.ctx.Repository
+	_, err := s.ctx.ATProtoClient.GetRecord(ctx, atproto.RepoPageCollection, rkey)
+	if err == nil {
+		// Record already exists - don't overwrite
+		slog.Debug("Repo page already exists, skipping creation", "did", s.ctx.DID, "repository", s.ctx.Repository)
 		return
 	}
 
-	slog.Info("Refreshing README cache", "did", s.ctx.DID, "repository", s.ctx.Repository, "url", readmeURL)
-
-	// Invalidate the cached entry first
-	if err := s.ctx.ReadmeCache.Invalidate(readmeURL); err != nil {
-		slog.Warn("Failed to invalidate README cache", "url", readmeURL, "error", err)
-		// Continue anyway - Get() will still fetch fresh content
+	// Only continue if it's a "not found" error - other errors mean we should skip
+	if !errors.Is(err, atproto.ErrRecordNotFound) {
+		slog.Warn("Failed to check for existing repo page", "did", s.ctx.DID, "repository", s.ctx.Repository, "error", err)
+		return
 	}
 
-	// Fetch fresh content to populate cache
-	// Use context with timeout to avoid hanging on slow/dead URLs
-	ctxWithTimeout, cancel := context.WithTimeout(ctx, 10*time.Second)
-	defer cancel()
+	// Create new repo page record from manifest annotations
+	// Note: Avatar is not extracted from annotations here - that's handled separately
+	// (would require uploading a blob if annotation contains a URL)
+	repoPage := atproto.NewRepoPageRecord(s.ctx.Repository, description, nil)
+
+	slog.Info("Creating repo page from manifest annotations", "did", s.ctx.DID, "repository", s.ctx.Repository)
 
-	_, err := s.ctx.ReadmeCache.Get(ctxWithTimeout, readmeURL)
+	_, err = s.ctx.ATProtoClient.PutRecord(ctx, atproto.RepoPageCollection, rkey, repoPage)
 	if err != nil {
-		slog.Warn("Failed to refresh README cache", "url", readmeURL, "error", err)
-		// Not a critical error - cache will be refreshed on next page view
+		slog.Warn("Failed to create repo page", "did", s.ctx.DID, "repository", s.ctx.Repository, "error", err)
 		return
 	}
 
-	slog.Info("README cache refreshed successfully", "url", readmeURL)
+	slog.Info("Repo page created successfully", "did", s.ctx.DID, "repository", s.ctx.Repository)
 }

pkg/atproto/lexicon.go

···
 
 	// StarCollection is the collection name for repository stars
 	StarCollection = "io.atcr.sailor.star"
+
+	// RepoPageCollection is the collection name for repository page metadata
+	// Stored in user's PDS with rkey = repository name
+	RepoPageCollection = "io.atcr.repo.page"
 )
 
 // ManifestRecord represents a container image manifest stored in ATProto
···
 	return &SailorProfileRecord{
 		Type:        SailorProfileCollection,
 		DefaultHold: defaultHold,
+		CreatedAt:   now,
+		UpdatedAt:   now,
+	}
+}
+
+// RepoPageRecord represents repository page metadata (description + avatar)
+// Stored in the user's PDS with rkey = repository name
+// Users can edit this directly in their PDS to customize their repository page
+type RepoPageRecord struct {
+	// Type should be "io.atcr.repo.page"
+	Type string `json:"$type"`
+
+	// Repository is the name of the repository (e.g., "myapp")
+	Repository string `json:"repository"`
+
+	// Description is the markdown README/description content
+	Description string `json:"description,omitempty"`
+
+	// Avatar is the repository avatar/icon blob reference
+	Avatar *ATProtoBlobRef `json:"avatar,omitempty"`
+
+	// CreatedAt timestamp
+	CreatedAt time.Time `json:"createdAt"`
+
+	// UpdatedAt timestamp
+	UpdatedAt time.Time `json:"updatedAt"`
+}
+
+// NewRepoPageRecord creates a new repo page record
+func NewRepoPageRecord(repository, description string, avatar *ATProtoBlobRef) *RepoPageRecord {
+	now := time.Now()
+	return &RepoPageRecord{
+		Type:        RepoPageCollection,
+		Repository:  repository,
+		Description: description,
+		Avatar:      avatar,
 		CreatedAt:   now,
 		UpdatedAt:   now,
 	}

pkg/atproto/lexicon_test.go

···
 		t.Errorf("CreatedAt = %q, want %q", decoded.CreatedAt, record.CreatedAt)
 	}
 }
+
+func TestNewRepoPageRecord(t *testing.T) {
+	tests := []struct {
+		name        string
+		repository  string
+		description string
+		avatar      *ATProtoBlobRef
+	}{
+		{
+			name:        "with description only",
+			repository:  "myapp",
+			description: "# My App\n\nA cool container image.",
+			avatar:      nil,
+		},
+		{
+			name:        "with avatar only",
+			repository:  "another-app",
+			description: "",
+			avatar: &ATProtoBlobRef{
+				Type:     "blob",
+				Ref:      Link{Link: "bafyreiabc123"},
+				MimeType: "image/png",
+				Size:     1024,
+			},
+		},
+		{
+			name:        "with both description and avatar",
+			repository:  "full-app",
+			description: "This is a full description.",
+			avatar: &ATProtoBlobRef{
+				Type:     "blob",
+				Ref:      Link{Link: "bafyreiabc456"},
+				MimeType: "image/jpeg",
+				Size:     2048,
+			},
+		},
+		{
+			name:        "empty values",
+			repository:  "",
+			description: "",
+			avatar:      nil,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			before := time.Now()
+			record := NewRepoPageRecord(tt.repository, tt.description, tt.avatar)
+			after := time.Now()
+
+			if record.Type != RepoPageCollection {
+				t.Errorf("Type = %v, want %v", record.Type, RepoPageCollection)
+			}
+
+			if record.Repository != tt.repository {
+				t.Errorf("Repository = %v, want %v", record.Repository, tt.repository)
+			}
+
+			if record.Description != tt.description {
+				t.Errorf("Description = %v, want %v", record.Description, tt.description)
+			}
+
+			if tt.avatar == nil && record.Avatar != nil {
+				t.Error("Avatar should be nil")
+			}
+
+			if tt.avatar != nil {
+				if record.Avatar == nil {
+					t.Fatal("Avatar should not be nil")
+				}
+				if record.Avatar.Ref.Link != tt.avatar.Ref.Link {
+					t.Errorf("Avatar.Ref.Link = %v, want %v", record.Avatar.Ref.Link, tt.avatar.Ref.Link)
+				}
+			}
+
+			if record.CreatedAt.Before(before) || record.CreatedAt.After(after) {
+				t.Errorf("CreatedAt = %v, want between %v and %v", record.CreatedAt, before, after)
+			}
+
+			if record.UpdatedAt.Before(before) || record.UpdatedAt.After(after) {
+				t.Errorf("UpdatedAt = %v, want between %v and %v", record.UpdatedAt, before, after)
+			}
+
+			// CreatedAt and UpdatedAt should be equal for new records
+			if !record.CreatedAt.Equal(record.UpdatedAt) {
+				t.Errorf("CreatedAt (%v) != UpdatedAt (%v)", record.CreatedAt, record.UpdatedAt)
+			}
+		})
+	}
+}
+
+func TestRepoPageRecord_JSONSerialization(t *testing.T) {
+	record := NewRepoPageRecord(
+		"myapp",
+		"# My App\n\nA description with **markdown**.",
+		&ATProtoBlobRef{
+			Type:     "blob",
+			Ref:      Link{Link: "bafyreiabc123"},
+			MimeType: "image/png",
+			Size:     1024,
+		},
+	)
+
+	// Serialize to JSON
+	jsonData, err := json.Marshal(record)
+	if err != nil {
+		t.Fatalf("json.Marshal() error = %v", err)
+	}
+
+	// Deserialize from JSON
+	var decoded RepoPageRecord
+	if err := json.Unmarshal(jsonData, &decoded); err != nil {
+		t.Fatalf("json.Unmarshal() error = %v", err)
+	}
+
+	// Verify fields
+	if decoded.Type != record.Type {
+		t.Errorf("Type = %v, want %v", decoded.Type, record.Type)
+	}
+	if decoded.Repository != record.Repository {
+		t.Errorf("Repository = %v, want %v", decoded.Repository, record.Repository)
+	}
+	if decoded.Description != record.Description {
+		t.Errorf("Description = %v, want %v", decoded.Description, record.Description)
+	}
+	if decoded.Avatar == nil {
+		t.Fatal("Avatar should not be nil")
+	}
+	if decoded.Avatar.Ref.Link != record.Avatar.Ref.Link {
+		t.Errorf("Avatar.Ref.Link = %v, want %v", decoded.Avatar.Ref.Link, record.Avatar.Ref.Link)
+	}
+}