seed-hypermedia-read_skill

Overview

This skill provides read-only gRPC access to Seed Hypermedia for querying documents, comments, entities, accounts, and server metadata. It is designed for inspection and retrieval only—any request that intends to write, update, or delete will be refused and routed to the write-seed-hypermedia skill. Use it to safely fetch Seed data, resolve IRIs, and download referenced media via the local HTTP gateway.

How this skill works

The skill connects to a Seed gRPC server (dev: localhost:58002, prod: localhost:56002) using grpcurl and server reflection to discover services and method signatures. It parses hypermedia IRIs into account, path, version, block, and latest flag, then composes one or more plaintext gRPC calls to fetch the requested resources. For media stored on IPFS it instructs use of the local HTTP gateway (grpcport - 1) to download bytes.

When to use it

• Fetch a document or specific document version without modifying anything
• List or read comments, entities, account metadata, or server info
• Resolve hm:// IRIs into their components and retrieve associated records
• Download media referenced by documents using the local HTTP gateway
• Inspect large responses and receive a concise summary of key metadata

Best practices

• Always try the dev endpoint first, then production if unavailable
• Use reflection once per session to discover service/method signatures, then reuse that structure
• Refuse and route any write/update/delete intent to the write-seed-hypermedia skill
• Omit absent IRI components instead of sending empty strings in RPC payloads
• Handle pagination with page_size defaults of 50–100 and check page_token fields
• Resolve human-friendly account display names when showing authors, but keep raw account in IRIs

Example use cases

• Read the latest version of a document given hm://<account>/<path>&l and show author display name
• Fetch a specific document version using ?v=<version> or a specific block via #<block>
• List comments for a document or author and summarize timestamps and authors
• Retrieve server metadata or list available services using grpcurl reflection
• Download an image referenced by ipfs://<cid> through http://localhost:<grpcport-1>/ipfs/<cid>