Polis Skill

AI-powered workflows for decentralized social networking using the polis CLI.

Core Principles

1. Always use --json flag for structured output parsing
2. Handle errors gracefully using structured error codes
3. Confirm destructive actions before execution
4. Preserve user content - never overwrite without confirmation
5. Leave git control with user - offer commits, don't auto-commit

CLI Location

The polis CLI is located at: ./cli/bin/polis

All commands should use the --json flag for machine-readable output:

./cli/bin/polis --json <command> [options]

Environment Requirements

The following environment variables should be configured:

• POLIS_BASE_URL - Your polis site URL (e.g., https://yourdomain.com)
• POLIS_ENDPOINT_BASE - Discovery service URL
• DISCOVERY_SERVICE_KEY - API authentication key

Feature 1: Publish

Trigger phrases: "publish", "post", "sign and publish", "deploy post"

Workflow

1. Read the draft file to understand content and extract title

2. Suggest/refine title if needed:

   • Review the markdown heading
   • Suggest improvements if title could be clearer or more engaging
   • Let user approve or modify

3. Check for existing frontmatter:

   • If file has polis frontmatter (already published): note to user, use republish
   • If no frontmatter: use publish

4. Execute the command:

   # For new posts
   ./cli/bin/polis --json publish <file>
   
   # For updates to existing posts
   ./cli/bin/polis --json republish <file>
   
   # For inline content (stdin)
   echo "<content>" | ./cli/bin/polis --json publish - --filename <name.md> --title "<title>"
   

5. Parse and report results:

   • File path (canonical location)
   • Content hash
   • Canonical URL
   • Signature confirmation

6. Offer git commit (don't auto-commit):

   • Show what would be committed
   • Ask user if they want to commit
   • If yes, stage and commit with descriptive message

Notes

• Accept drafts from any path (no restriction to specific folders)
• Support stdin for inline content publishing

Feature 2: Discover

Trigger phrases: "discover", "find posts about", "search for", "what's being discussed"

Workflow

1. Load following list:

   cat metadata/following.json
   

2. Fetch local index (your own content):

   ./cli/bin/polis --json index
   

3. Fetch followed authors' indexes: For each author in following.json:

   curl -s <author-url>/metadata/public.jsonl
   

   • Parse and aggregate posts/comments
   • Handle unreachable sites gracefully (skip with note)

4. Semantic matching:

   • Match the topic/query against titles and excerpts
   • Consider both your content and followed authors' content
   • Rank by relevance

5. Present results:

   • Show matching posts with: author, title, URL, brief excerpt
   • Group by author or relevance as appropriate

6. Offer next actions:

   • "Preview this post?" -> use preview command
   • "Comment on this?" -> switch to comment workflow

Technical Notes

• Following list format: metadata/following.json contains author URLs
• Each author's public index at: <author-base-url>/metadata/public.jsonl
• This is following-based discovery (your network only)

Feature 3: Comment

Trigger phrases: "comment on", "reply to", "respond to"

Workflow

1. Preview the target post/comment:

   ./cli/bin/polis --json preview <url>
   

2. Present content to user:

   • Show title, author, content body
   • Show signature verification status
   • Summarize the key points

3. Gather context for drafting:

   • Read user's previous comments from local index to learn their tone/style
   • If enough prior comments exist: draft a reply matching their voice
   • If not enough context: ask user what they want to say

4. Present draft inline for user to edit:

   • Show the suggested draft
   • Let user modify directly before proceeding

5. Create the comment:

   echo "<approved-content>" | ./cli/bin/polis --json comment - <url> --filename <reply-name.md>
   

6. Report beseech status:

   • CLI automatically sends blessing request
   • Report the pending status to user

Tone Matching

• Read user's previous comments to learn their voice
• Match that tone (formal, casual, technical, etc.)
• Fall back to neutral professional if no prior comments exist

Feature 4: Manage Blessings

Trigger phrases: "manage blessings", "review blessings", "blessing requests", "pending comments"

Workflow

1. Sync and fetch requests:

   ./cli/bin/polis --json blessing sync
   ./cli/bin/polis --json blessing requests
   

2. Report auto-blessed comments (FYI):

   • Note any comments that were auto-blessed from followed authors
   • These don't need review, just confirmation they were handled

3. Walk through pending requests one-at-a-time:

   For each pending request:

   a. Preview the comment:

   ./cli/bin/polis --json preview <comment_url>
   

   b. Assess quality using these signals (weighted):

   1. Signature validity (required) - invalid = recommend deny
   2. Thread-specific trust (high weight) - has this author been blessed on other posts?
   3. On-topic relevance - is it about the post?
   4. Constructiveness - thoughtful vs spam/trolling
   5. Network reputation (lower weight) - followed by people you follow?

   c. Present with recommendation:

   Request <hash> from <author>
   On: <post-url>
   Comment: "<excerpt>..."
   Signature: VALID/INVALID
   
   AI Recommendation: GRANT/DENY (reasoning)
   
   [Grant] [Deny] [Skip]
   

   d. Execute user's decision:

   ./cli/bin/polis --json blessing grant <hash>
   # or
   ./cli/bin/polis --json blessing deny <hash>
   

   e. Move to next request

4. Deny silently (no rationale sent to commenter - future feature)

Feature 5: Status

Trigger phrases: "status", "polis status", "what's my status", "show activity"

Workflow

1. Gather data:

   # Your published content
   ./cli/bin/polis --json index
   
   # Pending blessing requests (others wanting your blessing)
   ./cli/bin/polis --json blessing requests
   
   # Git status for uncommitted changes
   git status --porcelain 2>/dev/null || true
   
   # Discovery service health
   curl -s -o /dev/null -w "%{http_code}" "${POLIS_ENDPOINT_BASE}/health" 2>/dev/null || echo "unreachable"
   
   # Following count
   cat metadata/following.json | jq 'length' 2>/dev/null || echo "0"
   

2. Parse and present dashboard:

   === Polis Status ===
   
   Published Content:
   - X posts (latest: "<title>" - <relative-time>)
   - Y comments (latest: reply to <domain> - <relative-time>)
   
   Pending Actions:
   - N blessing requests awaiting YOUR review
   - M of YOUR comments awaiting blessing from others
   - P uncommitted files
   
   Network:
   - Following: Q authors
   - Discovery service: connected/disconnected
   

Dashboard Includes

• Post/comment counts with latest activity
• Pending blessing requests (others -> you)
• Pending beseech status (your comments -> others)
• Uncommitted git changes
• Following count
• Discovery service health check

Feature 6: Notifications

Trigger phrases: "notifications", "pending actions", "what needs attention", "any updates"

Workflow

1. Fetch all notifications:

   ./cli/bin/polis --json notifications
   

2. Present categorized notifications:

   === Notifications ===
   
   Blessing Requests (N pending):
   - Request #42 from alice@example.com on "Your Post Title"
   - Request #43 from bob@example.com on "Another Post"
   
   Domain Migrations (M discovered):
   - old-domain.com -> new-domain.com (2025-01-15)
   

3. Offer actions:

   • For blessing requests: "Review these?" -> switch to blessing workflow
   • For migrations: "Apply these updates?" -> run migrations apply

Migration Application

When user wants to apply migrations:

1. Run interactive apply:

   ./cli/bin/polis migrations apply
   

2. For each migration, CLI shows:

   • Old domain -> New domain
   • Key verification status (ensures same owner)
   • Affected local files
   • Prompts for confirmation

3. Report results:

   • Files updated
   • Git changes staged

Security Note

The CLI verifies public key continuity before applying migrations. If the new domain's public key doesn't match the stored key from when migration was recorded, the migration is skipped with a warning about possible hijacking.

Error Handling

When commands fail, parse the JSON error response:

{
  "status": "error",
  "command": "...",
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message"
  }
}

Common error codes and responses:

• FILE_NOT_FOUND - Help user locate the correct file
• INVALID_INPUT - Explain required format
• API_ERROR - Check network/discovery service status
• SIGNATURE_ERROR - Report verification failure
• INVALID_STATE - Guide user (e.g., run polis init first)

References

For detailed command syntax and JSON response schemas, see:

• commands.md - CLI command reference
• json-responses.md - JSON response schemas