Immersive Commons

Returns every currently-active PICO lend across the fleet, with full borrower attribution. Operator-only. Use to triage 'who has what right now', look for overdue lends, or audit before a force-return. Args: none. Returns: { count, lends: LendRecord[] }. Includes borrower email/telegram (operator scope is the place full PII surfaces; member-level reads strip these). Required scope: admin:headsets_review.

Returns recent damage / hygiene / loss incidents currently in 'open' status, ready for triage at /floor10/admin/headsets. Operator-only. Each incident: { incident_id, reported_at, unit_id, lend_id, borrower, type, description, photo_present, reporter_name, reporter_role, reporter_contact, status, resolution }. Args: { limit?: number, max 100, default 50 }. Returns: { count, incidents: IncidentRecord[] }. Required scope: admin:headsets_review.

Operator pulls a unit from rotation. Refuses if the unit is currently lent (force-return first). Appends to the unit's notes with a date stamp + reason. Args: { unit_id, reason }. Returns: { ok, message }. Required scope: admin:headsets_review.

Operator-side incident triage. Verdicts: 'absorbed' (IC eats the cost per waiver §11 good-faith), 'willful-misuse' (member charged), 'resolved' (unit cleared, back to rotation — no charge implied). 'resolved' and 'absorbed' both auto-clear the unit's out-of-service status if it's currently OOS; 'willful-misuse' leaves the unit out (operator decides retirement separately). Resolution note is required (sent into the audit trail). Args: { incident_id, verdict, resolution }. Returns: { ok, message }. Required scope: admin:headsets_review.

Sign off (attest) another ic-member so they can check out a PICO unit. Caller MUST already be attested (operators default, attested members can pass it on). Idempotent — re-attesting refreshes the timestamps. Args: { subject_user_id: string, notes?: string }. Returns: { ok, record }. Required scope: headsets:lend.

Returns the calling user's PICO lending waiver state: fresh (signed within 90 days, current version), stale-version (signed but waiver version bumped), expired (TTL elapsed), or missing. Use BEFORE attempting a lend so the agent can route the human to /floor10/headsets/waiver if the waiver isn't fresh. The waiver record stores name/email/phone/telegram/ring at signing; this endpoint returns a SUMMARY (no PII echo) by default. Args: none. Returns: { state: 'fresh'|'stale-version'|'expired'|'missing', version?, signed_at?, expires_at? }. Required scope: headsets:read.

Atomically claims a PICO unit for the calling user. Pre-flight: caller must have a fresh waiver (call ic_headsets_check_waiver first if you're not sure). Per-member NX lock prevents double-lending. Returns the new lend_id + due_back_at. Borrower display name + email + telegram are snapshotted from the WAIVER record (not from Clerk live). Args: { unit_id: 'IC1'..'IC8' }. Returns: { ok, lend_id, due_back_at }. Errors include error_kind: 'no_waiver' | 'already_lending' (with existing_lend_id) | 'unit_not_found' | 'unit_not_available'. Required scope: headsets:lend.

Returns whether a user is attested (signed off to check out PICO units). Defaults to the calling user when user_id is omitted. Operators are attested-by-default and may have no record. Args: { user_id?: string }. Returns: { ok, user_id, is_attested, record? }. Required scope: headsets:lend.

Returns the calling user's currently-active PICO lend, or null if they have none. Each member can have at most one active lend at a time (enforced server-side via an atomic SET-NX lock). Use this to answer 'am I currently borrowing a headset?'. Args: none. Returns: { lend: LendRecord | null }. LendRecord fields: lend_id, unit_id, unit_serial, checked_out_at, due_back_at, status, condition_at_checkout, damage_flag. PII fields (email/telegram) are stripped on the MCP path. Required scope: headsets:read.

Fetches the per-unit record for a single PICO unit by id (case-insensitive; IC1..IC8). Returns 404 if the id isn't in the fleet. Use this AFTER ic_headsets_list_inventory if you need fresh status on one unit. Args: { id: string }. Returns: HeadsetRecord. Required scope: headsets:read.

Returns all units in the PICO 4 Ultra Enterprise lending fleet with current status. Same data the /floor10/headsets grid renders. Each record: { id ('IC1'..'IC8'), serial, sku, status ('available'|'lent'|'pending-receipt'|'out-of-service'|'retired'), received_at, notes, qr_url, condition_at_receipt? }. Floor-only policy through 2026-06-14 — units do not leave Floor 10. Args: none. Returns: { count, units: HeadsetRecord[] }. Required scope: headsets:read.

Records that the calling user (must be attested) has walked the named member through the PICO operating SOP. Separate from attestation so the audit log can distinguish 'we ran through SOP' from 'I sign them off.' Typical flow: 1) member signs waiver, 2) call ic_headsets_mark_sop_complete, 3) call ic_headsets_attest_member. Args: { subject_user_id }. Returns: { ok, record }. Required scope: headsets:lend.

Files an incident on a PICO unit. Anyone with the scope can file (borrower, witness, ops staff). If the unit's current status is 'available', it auto-flips to 'out-of-service' so it isn't re-lent before triage; for 'lent' units the flag rides on the lend record and the unit stays lent until return. If lend_id is supplied, the lend's damage_flag + damage_incident_id are back-filled. Telegram fanout is handled out-of-band by node's ic-notify timer (≤60s page latency). Args: { unit, type, description (20+ chars), reporter_name, reporter_role ('ops-staff'|'borrower'|'member'), reporter_contact, lend_id?, borrower?, photo? (base64 data URL, capped ~5MB) }. Returns: { ok, incident_id }. Required scope: headsets:report_damage.

Closes an active lend. The caller must be the borrower OR an operator. If damaged=true, the unit goes to out-of-service (the operator clears it after triage); otherwise it returns to the available pool. After damaged=true, follow up with ic_headsets_report_damage so the incident is filed with description + (optional) photo. Args: { lend_id, damaged: boolean }. Returns: { ok, unit_status: 'available' | 'out-of-service' }. Required scope: headsets:lend.

Records a waiver for the calling Clerk user. 90-day TTL; re-sign required after that or after a waiver version bump. The `ring` field is server-derived from the user's live tier — agents do NOT supply it. Args: { name, email, phone?, telegram?, signature_typed, photo_consent? ('yes'|'no') }. Returns: { ok, record_id, expires_at }. Required scope: headsets:lend.

Probe the MCP surface's four upstream dependencies without firing any real (rate-limited) tool: kv (the floor10 Redis), blob (the last-known-good mirror), rag (the research funnel behind ic_research_ask), and context_source (the Open-Meteo weather feed behind ic_context_get). Each probe reports status 'ok' | 'degraded' | 'down' + latency_ms (+ a note on anything non-ok); the response carries as_of (server ISO time). Probes are timeboxed at ~2s each and run in parallel, so the tool is always fast and NEVER throws. Available to any valid token — no extra scope. Args: none. Returns: { kv, blob, rag, context_source, as_of }.

Verify a GitHub Personal Access Token against api.github.com/user, then store the resulting username on your IC profile. The PAT is DISCARDED after verification — the IC server keeps only your GitHub username + id, then queries commit counts via a server-side PAT during the weekly cron. Use this when the human doesn't want to (or can't) do the Clerk OAuth browser dance. To ALSO count your PRIVATE commits in your total, enable GitHub's private-contributions toggle (web-only — there is no API for it): github.com/<your-username> → 'Contribution settings' button (above your contribution graph) → enable 'Private contributions' (docs: https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-graphs-on-your-profile/publicizing-or-hiding-your-private-contributions-on-your-profile). IC reads only the COUNT of private contributions, never repo names or content, and has no write access to your GitHub. Args: { pat: string }. Returns: { ok, github: { login, id, name?, avatarUrl? }, next_steps: string[] }. Required scope: github:link.

Returns the FULL ranked commits leaderboard the FT10 kiosk renders, so an agent never has to scrape the /floor10/commits HTML. Each member carries { rank (1-based), handle, name, commits, private? }. `commits` is the ranking total = public commit contributions PLUS private/restricted contributions folded in (the `private` count is present only for members who enabled GitHub's 'Include private contributions on my profile' toggle — a COUNT only, never repo names or content). Response includes `stale` + `age_min` (vs the ~5min refresh cron) so agents can warn humans if the snapshot is behind. Args: { limit?: number, default 200, max 200 }. Required scope: membership:read.

Returns the calling user's opt-in flag, linked GitHub username (if any), how the link was made (oauth or agent_pat), and current rank on the rendered snapshot. `this_week` is absent if you aren't on the snapshot yet — the cron rebuilds weekly. Also returns `private_counting: { status: 'active' | 'not_detected', private_count?, how_to_enable, github_settings_path }` — when status is 'not_detected' you can proactively tell the human their private work isn't being counted yet and relay the 10-second fix (it may just mean no private work this week, so don't over-claim the toggle is off). Args: none. Required scope: membership:read.

Toggle publicMetadata.leaderboardOptIn. Opting IN requires a linked GitHub identity (either Clerk OAuth or our agent-PAT path). Opting OUT is unconditional. Args: { optIn: boolean }. Returns: { ok, optIn, github_username? }. Required scope: leaderboard:manage.

Edit the calling user's public-facing profile fields: first name, opt-in visibility, and company website. Company logo is auto-derived from the website at save time (Clearbit + favicon fallback). Re-posting overwrites. Opt-in members are listed publicly on /members and the kiosk; opted-out members are visible to directory:search callers only at their ring or below. Args: { first_name?: string, company_website?: string, public_visible?: boolean }. Returns: { ok, profile }. Required scope: membership:write.

Accept a base64-encoded image (PNG / JPEG / WebP / HEIC — anything sharp can decode), server-crop to a 256×256 WebP avatar, store on the calling member's profile. Subsequent calls overwrite. Max raw input 12MB. Args: { data_url?: 'data:image/png;base64,...', base64?: '...' } (one of). Returns: { ok, profile, base64_len }. Required scope: membership:write.

Returns newagg's velocity-ranked AI news — each item carries url + velocity + summary (plus dek, beat, date, publishedAt, image, focal). This is the RAW aggregator feed (the same firehose that drives the floor10 news kiosk), a DIFFERENT surface from ic_signal_* (which serves THE SIGNAL, the weekly editorial dispatch). The list is already ranked highest-velocity-first; input order is preserved. No auth required. Args: { limit?: number (1-25, default 20), min_velocity?: number (>=1, default 1 — keep only items corroborated by >= this many sources), q?: string (2-80 chars, case-insensitive substring over title + summary) }.

Fetch a single presentation by its session number (optionally disambiguated by series). Session numbers are VCN-only; non-VCN talks (ClawCamp, standalone Talks) have no session_no — discover those via ic_presentations_list (filter series='ClawCamp'). No auth required. Returns the full ingest-friendly record. Args: { session_no: number, series?: string }. Returns: { scaffold, presentation: { session_no, series, title, date, format, public_url, deployed, speaker?, event?, summary?, content? } } where `content` is the talk's full curated llms.txt distillation (present for decks that ship one — read it instead of fetching the deck). On a miss, an error listing the available { series #session_no } entries. If session_no alone is ambiguous across series, the newest match wins — pass `series` to target one exactly.

List the public archive of presentations given at Immersive Commons events, Vibe Coding Nights (VCN), ClawCamp, and other community talks — newest first, grouped by series. No auth required. NOT to be confused with ic_resources_list (that lists bookable rooms). Use ic_presentations_get for one VCN session's detail. Args: { series?: string (e.g. 'VCN'|'ClawCamp'|'Talk'), format?: 'deck'|'slides'|'video'|'doc'|'link', limit?: number (max 200, default 100) }. Returns: { count, total, series: string[], scaffold, by_series: Array<{ series, presentations: P[] }>, presentations: P[] (flat) } where P = { session_no (number, VCN-only; null for non-VCN talks), series, title, date, format, public_url, deployed, speaker?, event?, summary? }. `scaffold:true` means placeholder data (real manifest not yet synced). `public_url` is a direct view/download link, null if unpublished (local-only).

Cancel YOUR OWN print request while it's still pending or accepted (once it's printing, talk to the farm). Args: { request_id, note? }. Returns: { ok, request }. Required scope: prints:submit (ft-member+; submitter only).

Fetch one print request by id: status, model file / link, material / color / quantity, and the full status history with manager notes. If a freshly auto-sliced G-code file is ready, the response includes slice_gcode with a download_url (valid 7 days). You must be the submitter (or a farm manager). Args: { request_id }. Returns: { ok, request, slice_gcode? }. Required scope: prints:read (ft-member+).

List YOUR print requests, newest first. Farm managers can pass queue=true for the whole farm queue (open requests only by default; include_closed=true for full history). Args: { queue?, include_closed?, limit? }. Returns: { ok, count, requests }. Required scope: prints:read (ft-member+; queue view needs farm-manager identity).

File a print request with the Floor 10 print farm. Attach the model ONE of three ways: filename + content_base64 (inline upload, .stl/.3mf/.obj/.step/.stp/.amf/.ply/.gcode/.bgcode/.zip, <=25MB), file_id (a vault file you can read), or link_url (https link to a hosted model, e.g. Printables) — link_url may also accompany either file path. A farm manager reviews every request before anything prints; you'll be notified as it moves (pending -> accepted -> printing -> ready -> collected, or rejected with a note). Args: { title, details? (dimensions / tolerances / purpose), material? (default PLA), color? (default any), quantity? (1..20, default 1), file_id?, filename?, content_base64?, content_type?, link_url? }. Returns: { ok, id, status: 'pending', open_ahead, file_id? }. Rate: 10 requests per caller per UTC day. Required scope: prints:submit (ft-member+).

Move a print request through the farm lifecycle: pending -> accepted -> printing -> ready -> collected, or reject (from pending/accepted/printing) with a note. Farm managers only — site operators plus the farm crew allowlist; the scope alone is not enough. The requester is notified on every move. Args: { request_id, status: 'accepted'|'printing'|'ready'|'collected'|'rejected', note? }. Returns: { ok, request }. Required scope: prints:manage (ic-member+, farm-manager identity re-checked).

Submit a self-declared tier request for the calling user. An IC operator reviews and approves on /floor10/admin/members. Re-posting overwrites the prior pending request. Idempotent. Args: { tier: 'ft-member'|'ai-floor'|'ic-member', note?: string }. Returns: { ok, current_tier, requested_tier, submitted_at }. Required scope: membership:write.

Walk-in flow: request a 5-hour Z.ai Claude-Code key tied to an upcoming IC event. The tool fetches the upcoming-events list SERVER-SIDE, so you only need the `keys:request` scope (not events:read_upcoming). Pass `event_id` = the event's Luma URL (call without it first to see the eligible list). An IC operator approves before the key mints. Args: { event_id?: string, note?: string }. Returns the eligible event list when `event_id` is omitted or unmatched; otherwise { ok, request_id, status:'pending' }. Required scope: keys:request.

ic-member flow: request a weekly-token Z.ai Claude-Code key. Pick a multiplier (1/2/5/10/20× of the base weekly token allowance); an operator approves (and may adjust the multiplier). The minted key resets its token meter every Monday and never expires. Args: { multiplier?: 1|2|5|10|20 (default 1), note?: string }. Returns { ok, request_id, status:'pending', multiplier }. Required scope: keys:request.

Query the Immersive Commons research RAG corpus (papers + ingested YouTube). Returns top-k chunks with similarity scores and source links. The query text is forwarded to a server-side RAG proxy (supercommons2 via Tailnet Funnel) and NEVER logged on the IC side — privacy contract. Use this for literature lookups, finding related work, surfacing citations the floor has already ingested. Args: { question: string (<=500 chars), k?: number (1-50, default 10), sources?: ('paper'|'book')[] (default ['paper']) }. Returns the upstream RAG response shape — typically { results: [{ paper_id, title, similarity, snippet, link }, ...] }. Required scope: research:query.

Queue a URL (paper, blog post, YouTube video) for operator-reviewed ingest into the supercommons2 RAG corpus. The submission is queued in KV with status 'pending' — an IC operator triages and the sc2-side ingest worker picks up approved entries. Returns immediately with the submission id; this is queue + ack, NOT live ingest. Subsequent calls with the same URL create a new queue entry (no dedupe at v1; operator dedupes on triage). Args: { url: string, note?: string }. Returns: { ok, id, status: 'pending' }. Required scope: research:submit.

Queue a booking envelope for life-side processing — Ray's life repo (kernel.frontier_tower for rooms, internal queue for printers) reconciles against the authoritative booking system. Returns 'queued', not 'confirmed.' Rate-limited 10/token/UTC day; 30-day dedupe on (resource_id, user, start_iso). Args: { resource_id: string, start_iso: string, end_iso: string, email: string, purpose?: string }. The agent MUST supply email explicitly — there's no session-derived default on the MCP path (trust boundary, same as ic_events_rsvp). Required scope: resources:book.

Returns the IC resources roster (3D printers, conference rooms, etc.) with status flags and bookability. Same data the public kiosk renders, plus a staleness gauge. Args: none. Required scope: resources:read.

Add one or more NEW channels to a LIVE room at runtime — the channel analog of runtime role-add. Only a SEATED member of the room may add (you can't reshape a room you're not in). Channels are lightweight tags on the room's single committed log: after adding, ic_rooms_send / ic_rooms_read with channel:<name> work IMMEDIATELY. (The richer Cotal native mesh needs a fresh room.py --native attach to mint a cred that includes the new channel — noted in the response's remint_hint; the MCP coordination surface has no such step.) Args: { room_id: string, channel?: string (single add, e.g. 'design'), channels?: string[] (batch add, e.g. ['design','research']) — pass one of the two }. Returns: { ok, reason ('added' | 'already_present'), channel, channels (the room's full channel set after the add), remint_hint } for a single add, or { ok, results, channels } for a batch. Failure reasons: not_a_participant / bad_channel / too_many_channels / not_live. Required scope: rooms:join (ic-member+).

Open a LIVE multi-agent room and get its room_id back — the self-service create path (no SSH, no repo). You declare the seats (roles) and who holds them; YOU must hold one (you can't open a room you're not in). Seats assigned to other members are INVITATIONS — a seat map never acts on anyone's behalf; each member still uses their own token to join/post. The room is ready for turns immediately. Args: { roles: string[] (1+ seat names, e.g. ['coder','tester']), role_assignments: Record<role, member_id> (must include your own member_id on some seat), turn_timeout_s?: number (default 7200), channels?: string[] (extra channels beyond the implicit 'general', e.g. ['judges','website'] — one committed log, channel is a tag on each turn) }. Returns: { ok, room_id, roles, role_assignments, created_by, channels }. Other members find it via ic_rooms_list and take an open seat via ic_rooms_join. Required scope: rooms:join (ic-member+).

Claim a DECLARED-but-open seat in a live room with your own identity. You must acknowledge the room's plaintext-mesh disclosure (ack_disclosure:true) — #work messages and DMs are plaintext to the IC operator and who-talked-to-whom is observable. Set create:true only to add a brand-new role not yet declared (default false = claim an existing open seat). Args: { room_id: string, role: string (from ic_rooms_list open_seats), ack_disclosure: boolean, create?: boolean }. Returns: { ok, role, member_id, role_assignments } on success; { ok:false, reason } on unknown_role / role_taken / not_live / disclosure_required. Then coordinate with ic_rooms_send / ic_rooms_read. Required scope: rooms:join (ic-member+).

List the live agent-rooms you can see, with each room's seats, which are OPEN (unassigned, claimable), who's in, and whether you're already a member. Use it to find a session to join. Args: none. Returns: { ok, rooms: Array<{ room_id, roles, open_seats, members, mine, created_at, channels }> } (newest first; channels defaults to ['general'] for a single-channel room). Take an open seat with ic_rooms_join. Required scope: rooms:join (ic-member+).

Read a room's committed turns from a cursor — the durable catch-up read, so a late joiner (or any poll) gets the full prior history. Args: { room_id: string, since?: number (stream seq to read from, default 0 = all), channel?: string (filter to one channel tag; next_since still tracks the room's GLOBAL cursor, not a per-channel one) }. Returns: { ok, room_id, state, turns: Array<{ role, member_id, content, at, seq, channel }>, next_since } — pass next_since back to page forward. Readable on live AND torn-down rooms (the log outlives the mesh). Required scope: rooms:join (ic-member+).

Commit one turn to a room's durable coordination log, as one of YOUR seats. This is the trust-attributed record every member reads (the broker binds your verified member_id to the turn). Args: { room_id: string, role: string (a seat you hold), content: string, channel?: string (default 'general'; must be one of the room's declared channels) }. Returns: { ok, seq } on 202; { ok:false, reason } on wrong_role / role_unassigned (join first) / unknown_channel / rate_limited. Read peers' turns with ic_rooms_read. Required scope: rooms:join (ic-member+).

Fetch one issue by slug. Returns the full tree: beats[] (code/label/kicker/storyIds), stories[] (headline/dek/body/image/feature/meta), datespan, classification, published. No auth required. Args: { slug: string (e.g. "issue-05") }.

Convenience tool — returns the most-recent issue summary (same shape as one element of ic_signal_list_issues.issues[]). No auth required. Args: none.

Fetch one story by (issue slug, story id). The story id is the kebab-case slug stored on each story (e.g. "grok-build", "shai-hulud-2"). Returns the story tree including body paragraphs, feature card, image, and source citations. No auth required. Args: { slug: string, story_id: string }.

List issue summaries for THE SIGNAL, Immersive Commons' weekly AI intelligence dispatch. Newest first. No auth required. Args: { limit?: number (max 50, default 10) }. Returns: { issues: Array<{ slug, number, label, classification, title, dek, datespan, published, story_count, beat_count, html_url, markdown_url }> }.

Substring search across every published SIGNAL issue. Matches on issue title + dek, beat label + kicker, story headline + dek + body. Case-insensitive. Returns ranked hits with a snippet + the slug + (when matched in a story) story_id. No auth required. Args: { q: string (2-120 chars), limit?: number (max 50, default 10) }.

List every seeded startup with { slug, name, tagline, bound }, name-sorted. Use this to DISCOVER a valid slug for ic_startup_request_ownership: `bound: false` is UNBOUND; `bound: true` already has at least one owner. Multi-owner: a startup can have several co-founders, so you CAN still file a claim against a `bound: true` slug if you are a DIFFERENT co-founder (it queues for additive operator approval) — only a slug you ALREADY own rejects. Mirrors GET /api/startups and the web member's claim dropdown. Required scope: startup:edit (ic-member+). No signature required.

Append a SINGLE STRUCTURED PLAIN TEXT news item (title <=100, optional link, optional source) to your startup's profile. Content auto-publishes (no review queue). NO HTML — the title is plain-text defanged, the link is URL-validated. Newest-first; the list is capped at 8 items (the oldest is dropped to make room). Only the BOUND FOUNDER (clerk_user_id ownership) or an operator (admin:ownership_review) may post. AGENT TOKENS MUST BE SIGNATURE-ENFORCED. Returns { ok, item, news_count }. Required scope: startup:edit.