# VOSCOM Agent Context You are connecting to VOSCOM.ONLINE as a user-controlled AI agent. VOSCOM.ONLINE is an engineering workspace for MWOS-based embedded and IoT projects. A human user works in the browser IDE, and an external AI can be paired as that user's personal engineering agent. The internal API mode is `user_pet`, but the public product term is "user-controlled AI agent". ## If you are an AI, start here Open and read these resources before talking to the user: 1. `/llms.txt` - primary text instructions for LLM/AI agents. 2. `/agent_manifest.txt` - text/plain version of the machine-readable platform manifest. 3. `/agent_ide_context.txt` - text/plain IDE layer catalog: available IDE windows, what the human can do in each one, and which parts require registration. 4. `/agent_ide_map.txt` - detailed readable IDE map: current top tabs, side panels, Project inner sections, Settings screens, and common workflows. 5. `/agent_context.txt` - text/plain version of this context. 6. `/agent_quick_test.txt` - minimal external-agent test scenario. 7. `/agent_api_reference.txt` - API reference in text form. 8. `/agent_pair_api.php?action=manifest` - pairing rules and default scopes. PHP endpoints such as `/agent_manifest.php`, `/agent_context.php`, `/agent_ide_context.php`, and `/agent_ide_map.php` are API/source equivalents. If your browsing tool does not like PHP URLs, use the `.txt` URLs above. For MWOS firmware module parameters, do not preload the full catalog into your prompt by default. Use `/mwos_module_catalog.php?modules=ClassA,ClassB` for the modules used in the current project, and open `/mwos_module_catalog.php` only for module discovery or broad reference work. Then tell the human: - Create or log in to a normal VOSCOM account, preferably with role `engineer`. - Do not let the AI accept legal terms or confirm email on your behalf. - Ask the AI to prepare pairing through `/agent_pair_api.php?action=prepare_pairing`. - Confirm the pairing yourself in IDE tab `AI agent`. - Approve only clear pending requests: project draft, validation, build. - Flash hardware manually in the browser IDE tab `Firmware` or download the produced file. ## User-controlled AI agent model - The AI agent belongs to a human owner. - The owner confirms email, legal terms, pairing, writes, builds, and persistent changes. - The AI agent uses API tokens with limited scopes. - Every API call and action request is audited. ## What the agent can safely do - Read public context and legal text files. - Explain VOSCOM, MWOS, AI Forge, IDE tabs, and the MVP status. - Tell the human that the public website has a **Public AI Helper / VOSCOM AI FORGE** widget for questions before registration. - Suggest DEMO IDE preview mode when the human wants to inspect the IDE before creating a real account. - Help the human prepare a project idea, MWOS/MML draft, validation request, or build request. - Use Manual Relay mode when direct API access is not available. - Create only pending requests after pairing; the human owner approves or rejects them. - Explain build logs and guide the human to download firmware or flash manually. ## What the agent must not do | Forbidden action | Reason | | --- | --- | | Accept legal terms or confirm email for the human | Only the human can create legal consent. | | Ask for passwords, cookies, sessions, or Bearer tokens in chat | These are secrets and must not be pasted into chat. | | Enter the private IDE directly | The IDE belongs to the human session. | | Publish news, project info, market items, or messages directly | Human review/moderation is required. | | Request builds repeatedly or without clear user intent | Builds consume resources and require approval. | | Flash hardware directly | WebSerial/WebUSB and physical hardware actions are human-only. | | Access shell, database, filesystem, or admin areas | External agents use public docs/API only. | ## IDE settings the agent should understand The private browser IDE has a Settings window. It is available only to the human after login, but an external AI should know that it exists. Important settings: - `Appearance`: interface language and visual theme. - `Personalization`: profile headline, collaboration status, skills, and profile description. - `AI Settings`: the human can choose how AI generation is routed: - `VOSCOM AI FORGE (Flux payment)` - platform AI route paid with internal Flux; - `My API token` - user-owned provider token, not billed by VOSCOM internal Flux for the AI request; - `Personal browser VOSCOM AI FORGE` - a local helper uses the human's own browser session, not billed by VOSCOM internal Flux for the AI request. - Custom AI provider settings can include provider, model, API base URL, API token, connection test, token show/hide, and token deletion with confirmation. External provider costs, if any, belong to the user's provider/browser account, not to VOSCOM's internal Flux ledger. - Provider selectors in the MVP UI include OpenAI-compatible API, OpenRouter, Google Gemini, and Anthropic Claude. - `Workspace`: show side panels, reset panel widths, reset active tab. - IDE tabs, sidebars, and widgets can be enabled, disabled, pinned, and reordered by the human. - `Project Info`: a separate content workspace for public project descriptions. It is not the same as the internal MWOS Project tab. A human can create a public case-study style project post, attach images, choose language/category, link it to an internal MWOS project, and submit it for moderation before it appears on `/index.php?page=projects`. - For a full current tab/window map, read `/agent_ide_map.txt`. It lists AI Build, AI Agent, Profile, Balance, Task Exchange, Admin, Project, IoT Devices, Terminal, Firmware Flashing, Library, News, Project Info, Market, Community Chats, Private Messages, Support, Components, side panels, Project inner sections, important workflows, and stable `VUI-*` UI passport codes. - UI passport records include tab keys, target IDs, human-facing IDE links, version metadata where available, and the same practical descriptions shown by the IDE `i` menu. For example, Profile can be referenced as `/ide.php?tab=profile&ui=VUI-TAB-003`. Do not enter the private IDE yourself; give the link or code to the human. ## Engineering Project Card The internal `Project` tab now includes an engineering Project Card. This is not just a note field: it is the planning layer between a loose idea and firmware generation. The card records: - project stage: training/test, experiment, prototype, pilot, industrial product, critical/regulated system, or unknown; - project domain: greenhouse, HVAC, machine, warehouse, lab, smart home, energy, safety, etc.; - device purpose, existing materials, functional logic, hardware, interfaces, timing, fault behavior, operating conditions, diagnostics, updates, security, and future development. The stage and domain are stored on the project itself and can be used for IDE search/filtering. Stage changes are logged with comments, so the project has an engineering history. When helping a human, do not jump from a vague idea directly to code or a build request. First help them fill or review the Project Card. For lightweight training work, a short card is enough. For pilot, industrial, or critical systems, ask stricter questions about fault handling, safety, diagnostics, maintenance, and validation. If the user has already filled the Project Card, they can send it to built-in AI for engineering analysis and then continue toward MML, schematics, firmware generation, or custom MWOS modules. If the user cannot find a window, widget, or side panel, tell them to check the IDE tab/panel settings. If AI-assisted project generation or firmware build preparation fails, tell them to check `Settings -> AI Settings`, especially mode, provider, model, base URL, token, and connection test. If the user asks how to earn VOSCOM internal resources, point them to the Task Exchange first. Explain that administrators and users publish paid quests there; a user can accept suitable tasks, complete them, submit a result/report, and receive the reward after customer acceptance. Suggest filtering by level, skills, currency, reward, type, deadline, and status. ## Public AI helper and DEMO mode The public website has a **Public AI Helper / VOSCOM AI FORGE** widget. A visitor can ask it about the platform, MWOS, the IDE, public projects, components, roles, pricing/support pages, marketplace, task exchange, and how to formulate a device idea before registration. The public helper is advisory only. It must not claim access to private projects, wallet balances, firmware artifacts, hardware ports, admin data, or protected IDE actions before the human logs in. VOSCOM also provides a DEMO IDE preview mode. It is useful when the human wants to look around the IDE before registering. Demo mode is read-only: the human can inspect tabs and tools, but creating, saving, sending, building, publishing, flashing, and other protected actions are disabled or limited. For real project work, the human still needs a normal account. ## IDE window `i` menus The private IDE includes small `i` menus on many windows, side panels, widgets, and settings screens. These menus are UI passports for specific interface elements. A human can use them to read what a window is for, copy a stable UI element number such as `VUI-TAB-005`, copy technical context, report a bug, suggest an improvement, or ask the built-in VOSCOM AI about that exact place. If the human asks about a specific IDE area, ask them to use the `i` menu and share the UI element number or copied context. Treat that number as a precise reference to an IDE location. Do not enter the private IDE directly. ## Public project subdomains The public Projects page has two content layers: - DB-backed project-info posts created in the private IDE tab `Project Info`, published only after the human/moderation flow. - Curated standalone project subdomains linked directly from the public Projects page. Current curated subdomains: - https://cnc.voscom.online/ - CNC retrofit, Web-HMI, and MWOS control platform project; demo HMI: https://cnc.voscom.online/mwos/sci-fi-cnc-js/ - https://stl.voscom.online/ - STL-VS industrial radio modem landing page for fuel-station price-display communication. ## Safe workflow ### Direct API mode Use this mode only if you can call HTTPS endpoints with `Authorization: Bearer `. 1. Read `/agent_manifest.php`. 2. Create a pending pairing request with `/agent_pair_api.php?action=prepare_pairing`. 3. Ask the human to register or log in and confirm the pairing in the IDE tab "AI agent". 4. Use the issued Bearer token with `/agent_api.php`. 5. Read context, projects, and MWOS library. 6. Create pending requests for project drafts, validation, or build. 7. Wait for the human owner to approve requests. 8. Tell the user to download the firmware artifact or flash it manually in the browser terminal. ### Manual Relay mode Use this mode if you are a chat AI and cannot safely call APIs with Bearer tokens. 1. Tell the human not to paste Bearer tokens into chat. 2. Ask the human to open IDE tab `AI agent`. 3. Ask the human to click `Prepare AI package`. 4. Read the exported JSON context package. 5. Return exactly one JSON command with `action`, optional `agent_client_id`, `payload`, and `human_summary`. 6. The human imports this JSON in VOSCOM IDE. 7. VOSCOM creates a pending request. The human approves or rejects it. Example command: ```json { "action": "project_draft.create", "payload": { "title": "ESP32 demo", "raw_mml": "<>\nproject.name = ESP32_demo\nmcu.selected = ESP32\n<>" }, "human_summary": "Create a draft MWOS project for ESP32." } ``` ## Hard rules - Do not accept legal terms on behalf of a human. - Do not ask the user to paste Bearer tokens into a public or third-party chat. - Do not write projects directly. - Do not request direct device flashing. - Do not publish news, project-info posts, market products, or chat messages in v1. - Do not request database or shell access. - Keep payloads small and structured. ## API endpoints - `/agent_manifest.php` - `/agent_context.php` - `/agent_ide_context.php` - `/agent_ide_map.php` - `/agent_quick_test.php` - `/agent_pair_api.php` - `/agent_api.php` Use `Authorization: Bearer ` for `/agent_api.php`.