# MoonRock agent instructions

MoonRock base URL: https://moonrock.co.il
MCP endpoint: https://moonrock.co.il/mcp
Health check: https://moonrock.co.il/health
Blog index: https://moonrock.co.il/blog
Blog markdown index: https://moonrock.co.il/blog.md

MoonRock is an agent-native infrastructure platform with private Git hosting, web analytics, a shared Markdown knowledge base, and credit-backed VPS rentals.

Important constraints:
- Repositories are private only.
- Do not request public repositories.
- Do not attempt visibility changes.
- Do not attempt ownership transfer.
- Do not attempt force push or history rewrite.

Login flow:
1. Start an auth session with POST /v1/auth/sessions using an agent name.
2. Send the returned approval_url to the user.
3. Wait for approval and poll GET /v1/auth/sessions/{session_id}?session_token=...
4. When approved, store access_token and refresh_token.
5. Use Authorization: Bearer <access_token> for API calls.

Core API routes:
- POST /v1/auth/sessions
- GET /v1/auth/sessions/{session_id}
- POST /v1/agent-tokens/refresh
- POST /v1/agent-tokens/revoke
- GET /v1/workspaces/me
- POST /v1/repositories
- GET /v1/repositories
- GET /v1/repositories/{repository_name}
- DELETE /v1/repositories/{repository_name}
- GET /v1/repositories/{repository_name}/branches
- POST /v1/repositories/{repository_name}/branches
- POST /v1/repositories/{repository_name}/commits
- POST /v1/repositories/{repository_name}/git-credentials
- GET /v1/repositories/{repository_name}/deploy-keys
- POST /v1/repositories/{repository_name}/deploy-keys
- DELETE /v1/repositories/{repository_name}/deploy-keys/{deploy_key_id}
- GET /v1/repositories/{repository_name}/webhooks
- POST /v1/repositories/{repository_name}/webhooks
- DELETE /v1/repositories/{repository_name}/webhooks/{webhook_id}
- GET /v1/quota
- GET /v1/audit-events
- POST /v1/analytics/sites
- GET /v1/analytics/sites
- GET /v1/analytics/sites/{site_id}
- POST /v1/analytics/sites/{site_id}/tokens/rotate
- GET /v1/analytics/sites/{site_id}/install-snippet
- POST /v1/analytics/ingest
- POST /v1/analytics/sql
- GET /v1/analytics/sites/{site_id}/summary
- GET /v1/analytics/sites/{site_id}/top-pages
- GET /v1/analytics/sites/{site_id}/referrers
- GET /v1/analytics/sites/{site_id}/timeseries
- GET /v1/analytics/sites/{site_id}/events
- POST /v1/knowledge/notes
- GET /v1/knowledge/notes
- GET /v1/knowledge/notes/{note_id}
- PUT /v1/knowledge/notes/{note_id}
- DELETE /v1/knowledge/notes/{note_id}
- POST /v1/knowledge/notes/{note_id}/move
- GET /v1/knowledge/notes/{note_id}/revisions
- POST /v1/knowledge/notes/{note_id}/restore
- POST /v1/knowledge/search
- GET /v1/knowledge/tree
- GET /v1/credits
- GET /v1/credits/ledger
- GET /v1/vps/plans
- POST /v1/vps/instances
- GET /v1/vps/instances
- GET /v1/vps/instances/{instance_id}
- GET /v1/vps/instances/{instance_id}/ssh-connection
- DELETE /v1/vps/instances/{instance_id}

Main MCP tools:
- start_login
- check_login_status
- create_repo
- list_repos
- create_branch
- commit_files
- get_git_credentials
- create_deploy_key
- create_webhook
- get_quota
- list_audit_events
- create_site
- list_sites
- get_install_snippet
- rotate_site_token
- query_analytics_sql
- get_site_summary
- get_top_pages
- get_referrers
- get_timeseries
- get_event_breakdown
- create_note
- read_note
- update_note
- delete_note
- move_note
- list_notes
- search_notes
- get_note_revisions
- restore_note_revision
- get_knowledge_tree
- get_credit_balance
- list_vps_plans
- create_vps
- list_vps_instances
- get_vps_instance
- get_vps_ssh_connection
- delete_vps_instance

Suggested usage pattern:
1. Authenticate the user first.
2. Create a private repository.
3. Use commit_files for direct content creation.
4. If raw git is needed, request git credentials and use the returned clone URL.
5. Check quota before large operations.
6. Use audit logs to inspect prior writes.
7. For analytics, create a site, install the browser snippet on the allowed hostname, and query rollups or SQL through the analytics API.
8. For shared agent memory, create Markdown knowledge notes and search them with regex, text, or path filters.
9. For VPS rentals, check available credits first, list plans, create the VPS, then fetch the managed SSH connection bundle when you need to operate the server directly.

Analytics trust boundaries:
- Browser tracking uses a public browser site key that is intended to appear in page markup.
- Browser events are accepted only for the site's allowed hostname policy.
- Server-side ingestion should use the rotatable site token, not the public browser site key.
- Do not expose server-side ingest tokens or MoonRock bearer tokens in browser-facing code.

Knowledge notes:
- Knowledge notes are workspace-scoped Markdown files.
- Multiple agents in the same workspace can create, read, update, move, delete, restore, and search them.
- Delete is reversible through note revisions.
- Use regex search when you want deterministic matching across prior operational notes.

VPS credits and lifecycle:
- VPS creation reserves one month of credits up front.
- Credits are prepaid and represented in USD-equivalent strings such as `5.00`.
- If a VPS is canceled before the current 30-day cycle ends, MoonRock charges only prorated usage for the elapsed time and releases the rest of the hold.
- If a cycle completes, MoonRock captures the held month and attempts to place a new hold for the next cycle.
- If there are not enough credits to renew, MoonRock terminates the VPS.
- MoonRock injects a managed SSH key into Hetzner during creation and can return the private key bundle later through the authenticated API.
- Use `user_data` for cloud-init when you need to install packages or bootstrap software during first boot.

Operator-only admin routes:
- `GET /v1/admin/workspaces/lookup`
- `POST /v1/admin/credits/grants`
- `POST /v1/admin/vps/reconcile`
- These routes require the MoonRock admin bearer token, not a normal workspace access token.

Current auth note:
The approval page uses Google OAuth when the deployment is configured with a Google client ID and client secret.

Plain-text version