CLARA — MineSpace Inc. | MineSpace.us DEPLOYMENT AND OPERATIONS QUICK INSTALL 1. Back up any custom program.json, example.clara, jobs.json, and your private ~/.clara-web directory. Preserve browser drafts by exporting project packages. 2. Extract the upload ZIP into the domain document root, so index.html is at /Clara/index.html. Preserve the hidden .htaccess file and set runtime.cgi platform.cgi and host-probe.cgi to executable mode 755. Set Clara directory to 755 (not group/world writable). No npm or build command is needed. 3. Open https://minespace.us/Clara/ (or your HTTPS host at the same path). The public example compiles and executes automatically. Open Studio, then Settings, and check the browser and server results separately. A static host supports only browser operation; hosted features require Python 3 CGI, SQLite and Apache rewrite/authorization forwarding. Online HTTPS is required for browser cryptography and workspace credentials. HOST ADMINISTRATOR SETUP CGI initializes private storage and a random admin token on first successful server request. From SSH in the Clara folder, locate the private token file: python3 -c 'import hashlib,pathlib;print(pathlib.Path.home()/".clara-web"/hashlib.sha256(str(pathlib.Path.cwd().resolve()).encode()).hexdigest()[:24]/"admin-token")' Read it securely using SSH/private file manager. Alternatively configure a strong CLARA_ADMIN_TOKEN in the private CGI environment (16+ characters). Never copy that credential into a public file, URL, source or analytics. Storage must remain outside the web root and owned by the CGI account. Optional CLARA_ALLOWED_HOSTS (comma-separated host[:port]) and CLARA_ALLOWED_ORIGINS (exact origins) constrain platform requests. Configure HTTPS, host-level traffic throttling, backups and access-log retention. Direct health fallback: runtime.cgi?_route=/api/health. Platform probe: platform.cgi?service=status. If unavailable, inspect CGI permissions, Python location, Apache modules, .htaccess and hosting error logs. Browser storage is not a backup or a shared server database; there is no silent server fallback. DEVELOP AND DEPLOY See guide.html for the complete public workflow. Choose Projects > a starter, Build > compile, Test > browser requests; save project tests and run them in scratch storage. Local drafts are per-browser and path. Export project JSON for transfer; runtime data, signing keys and credentials are excluded. Create an organization in Teams using the hosting administrator credential. Copy the organization ID; redeem the owner invitation for member access. In Deploy, enter the organization ID and hosting administrator credential. Build, test & stage compiles locally, checks local tests and runs declared server VM tests. Candidate routes remain inaccessible until promotion. Choose a slug, preview or production, then explicitly promote after review. Stable URL: live/{org}/{slug}/{environment}/api/{route}. Revision 0 creates a channel, next promotions require the current channel revision. The channel's visibility cannot change, and rollback targets a previously active checked non-revoked release. Existing direct releases retain their prior behavior. Each release has its own SQLite database; two channels on one release share storage. Routing changes do not migrate data. Server checks execute uploaded bytecode, not an independent compiler, and do not prove authorization safety. The hosting administrator may issue application credentials in Deploy. These ca_ bearer keys are release-bound, hashed at rest, revocable, and expire after 1–720 hours. Read scope allows GET; write allows mutation methods; read-write allows both. Issue new keys after changing release. Public unprotected GET routes remain open. Never ship a write key in a public website. These are API client credentials, not a general-purpose end-user identity system. For the original server application only, an operator may manually deploy a reviewed program.json over SFTP; preserve earlier builds and data first. PRIVATE COLLABORATION AND LIBRARIES Teams: invitation-only organizations, owner/editor/viewer roles, hosted project vaults. The hosting admin is not excluded from ordinary server data. Connect: explicit push/pull with base revision comparison; conflicts require reconciliation. Scope team/API credentials to the minimum needed. Encrypted exchange uses client encryption and strong shared passphrases; no recovery. Ordinary sync is server-readable. Do not put keys or passphrases in projects. Public libraries: use NEXUS to sign a standalone functions-only package; export its project JSON, host over HTTPS with suitable CORS, and declare the exact package URL as a signed endpoint. CONNECT verifies publisher pins, package hashes and dependencies before linking. Offline signed bundles work without network. No general module namespace system or automated upgrades. Private peer search: configure CLARA_PRIVATE_DISCOVERY_ORIGINS to exact trusted HTTPS origins on each remote host. Use separate search-only keys; only the search action is enabled cross-origin. No central private index. COMPUTE AND OPTIONAL AUTOMATION Compute: supported integer/Boolean functions -> IR, WASM, WGSL and GLSL. Fabric: reviewed GPU workload or supported CPU functions; opt-in cross-tab helpers. Grid: persistent same-origin jobs, start workers explicitly and open additional tabs on the same project. No execution after all tabs close. Offline installation is optional in Grid; verified public assets only, no private API cache. GPU availability and storage quotas vary by browser. Cron is optional, runs on the host, not browser. Configure via your hosting panel to run the cron_runner.py CLI from the Clara directory using Python 3: /usr/bin/python3 /home/YOUR_USER/minespace.us/Clara/cron_runner.py Set a suitable interval. Edit reviewed jobs.json privately; it is not a public endpoint. At-most-once attempts, not guaranteed exactly-once effects. PUBLIC DISCOVERY, AGENTS, ANALYTICS AND DISTRIBUTION NEXUS: signed name records, dependencies and release verification. WORLD: explicit trusted peers, DNS-over-HTTPS _clara TXT discovery and DNSSEC authenticated-data requirement; no automatic DNS changes. See NEXUS.txt. Machine interfaces: clara.json, openapi.json, llms.txt, protocol JSON files. Public MCP: /Clara/mcp or platform.cgi?service=mcp. JSON Streamable HTTP, versions 2025-11-25, 2025-06-18, 2025-03-26. No arbitrary remote execution. Local MCP: use Node 22+ on agent machine with full package's agent/mcp.mjs as stdio command. Local execution is bounded and disposable. Private Insights: administrator-only adoption reporting. Optional browser analytics default off; GPC suppresses tracking. Public tool counts are separate. Browser analytics do not collect source or credentials. Hosting access logs are separate. Reports are approximate; 90-day retention prunes on service activity. Optional public IPFS CAR (full package): import and pin with Kubo. Use a trusted HTTPS CID subdomain gateway; static copy has no hosted CGI, cron or private server access. No live publication performed. Never distribute private files. INSTALLATION CHECKS AND RECOVERY After upload, open Settings > Verify your installation > Run installation checks. This credential-free report checks public file hashes, rewritten service endpoints and private-file protections. Download the report for troubleshooting. It does not replace a security audit or prove live GPU support. Server requests and scheduled jobs now commit storage changes and receipt entries together only on 2xx or 3xx responses; error responses, invalid or oversized output and runtime exceptions roll back all writes. Browser requests use optimistic snapshot commits, returning HTTP 409 when another tab changed storage. Browser and server project test suites roll back failed requests. Existing data formats are retained. Browser persistence is not a server backup. PRIVATE BACKUP AND RECOVERY (full source archive, operations/backup.py) Keep the CLI outside the web root; run as the hosting account owner. Pause writes and cron across applications for a consistent multi-database snapshot. Individual SQLite backups are consistent even if writes occur; the collection is not a global atomic snapshot. Example commands (adjust paths): python3 backup.py --document-root ~/minespace.us backup --site ~/minespace.us/Clara ~/clara-backups/before-update python3 backup.py --document-root ~/minespace.us verify ~/clara-backups/before-update python3 backup.py --document-root ~/minespace.us recover ~/clara-backups/before-update ~/clara-backups/recovered Recovery always writes to a NEW directory. It does not replace live databases. Inspect the recovered files, stop CGI and cron writes, retain the original data folder and have the hosting administrator perform the controlled cutover. The backup includes private databases and the generated token, if present; protect and encrypt backups separately. Environment-configured tokens, code, external credentials, browser drafts and browser-held signing keys need their own backup process. Do not publish recovery files or add them to the IPFS CAR. RELEASE GATE Before opening to public production: verify actual DreamHost/host installation, browser flows on desktop and mobile, GPU paths, external MCP interoperability, rate limits, backup/restore and security review. Approve corporate legal notices, privacy rights workflows, contact details, licensing and terms handling with qualified counsel. No compliance or production-security certification claimed. See legal.html, legal.json and guide.html. © 2026 MineSpace Inc. PUBLIC WEBSITE & SEARCH /Clara/ is the public product website. The local example executes automatically without sending the entered value to the host. Open Studio loads studio.html. Legacy /Clara/#workspace and project-query links are redirected in the browser. The workspace is noindex; this is an indexing preference, not an access control. Private data stays behind its original authorization boundaries. Public sitemap: https://minespace.us/Clara/sitemap.xml. Submit it in Search Console using a verified MineSpace.us property, and optionally append the following line to the EXISTING DOMAIN-ROOT robots.txt (do not overwrite it): Sitemap: https://minespace.us/Clara/sitemap.xml Do not disallow studio/API paths solely to hide content; crawlers need to see noindex directives. Do not put any private data in public assets. The sitemap includes only the public home, user guide and legal notices. Structured data, canonical URLs, descriptions, social card, SVG branding and site manifest are included. Search indexing, ranking and social cache refresh are external. The installable studio manifest and optional verified cache are included; actual PWA installation requires browser support and an HTTPS origin. Published application packages now receive an independent structural bytecode verification pass on the server (instructions, call arity, jumps, route and template shape, and reachable stack/scope balance). This is not independent source compilation or a formal proof of arbitrary application behavior. FEATURED APP: CLARA Projects Open /Clara/desk.html. Local app starts automatically. In Developer, Open source in Studio imports a verified editable copy. For hosted use, stage, run server quality gates, promote to a private channel, issue a scoped read-write application key and connect using the same-origin base URL (no /api/). Runtime data are separate from source and from other releases. Test production under HTTPS. Official apps: applications.html. Enterprise: enterprise.html (private operator console requires CGI, HTTPS and admin-issued enterprise key). Names: namespaces.html. Public catalog and naming policy are available immediately; hosted claims require accepted organization owner credentials. No critical-infrastructure control or safety certification. CLARA AI Public overview: /Clara/ai.html. Launch /Clara/ai-studio.html for local learning or connect as the installation administrator. The hosted model resides in private ai.sqlite, separate from application and enterprise data. Include it in backups; model exports can reveal text. Enable automatic training explicitly; optional host cron every five minutes: /usr/bin/python3 /absolute/path/Clara/ai_cron.py. No train jobs run when automatic is off. For approved corpus import, run ai_ingest.py --help from the hosting account CLI; HTTPS plaintext only, explicit hostname allowlist and rights affirmation. The importer is not a web CGI service. No unrestricted crawling, no automatic private data ingestion, no general-purpose LLM. Browser local writes require Web Locks and HTTPS. See guide.html#ai-training-guide. NETWORK: /Clara/network.html and /Clara/network-console.html work after upload on HTTPS. Download clara-node-kit.zip for independent local nodes; extract outside the webroot and follow node/README.txt. No radio hardware or consensus is included. Network Studio refinements: use the dry-run panel before signing a contract transition. The explorer includes block type and content search, exact full digest lookup, paging, and expandable full records. Hash a local document before attesting; only the hash and label are submitted. Updated standalone nodes report the effective token capability. To rotate both operator and replication credentials, stop your node and run node node/node.mjs rotate-tokens. Restart with the new credentials; signed ledger history is unchanged. Update both the hosted platform and separate node kit together. No new radio hardware support or network exposure is enabled. INSTALLATION AUDIT Open /Clara/diagnostics.html and choose Run live audit. Download the JSON report; no credentials, source drafts, or existing app data are inspected. The browser and server checks are independent, and the direct CGI probes distinguish rewrite issues from runtime failures. HTTP 500 RECOVERY Use host-probe.cgi to distinguish CGI launch failures from CLARA initialization. If it returns HTML/500, review hosting error.log and ownership, directory 755, CGI 755, the Python shebang and LF endings. Never disable private-file rules. If the probe passes, use runtime.cgi?_route=/api/health and inspect the JSON HOST_* code. STORAGE_INIT, CREDENTIAL_INIT, PROGRAM_LOAD, PROGRAM_FORMAT, RESOURCE_LIMIT and PLATFORM_IMPORT are distinct initialization failures. Do not delete or move ~/.clara-web to repair HTTP 500. Back up custom program files and private databases separately. The probe does not modify the database. FULL APPLICATIONS Open appmaker.html. Author HTML, CSS, JavaScript and CLARA backend separately. The restricted native report-template grammar is not a frontend language. Export the website as ZIP or the native backend as a CLARA project. The exported site runs over HTTPS or localhost HTTP; for hosted APIs set app-config.js after deployment. Never embed credentials in public source. If both health endpoints return 500, check host-probe.cgi and the CGI error log; ensure all CGI files and the Clara directory are 755 and Python 3 is available. A generic Apache 500 before CGI startup cannot be fixed from browser JavaScript. APPLICATION WORKSPACE The full application builder stores up to 12 local drafts, subject to browser storage quotas. The old single draft is migrated on first open without deleting its legacy source or preview data. Each new project has a separate data key. Imports never overwrite another project; duplicate copies source only. Delete removes the selected project and its preview data; export first. Restore last preview means last initialized source, not a passed test suite. Use the scratch API tester to exercise routes against independent temporary in-memory data. Web Locks serialize cooperating preview/export data commits where supported; other browsers use best-effort conflict checks. Do not edit the same draft in multiple tabs. HOST CGI STARTUP DIAGNOSTICS (2026-11-20) All five .cgi files must be owner-executable (755); Python backend .py files 644. Keep the directory pathname unchanged: private data is keyed by its absolute path. Test shell-probe.cgi, python-probe.cgi, host-probe.cgi in that order. If shell and Python probes both return HTML 500, CGI execution is failing before CLARA starts; check hosting ownership, permissions, suexec and process monitor. If shell passes but Python fails, check /usr/bin/python3 and host Python support. The runtime/platform CGI launchers now invoke a system Python through a private response buffer and return structured 503 diagnostics on Python startup failure. Never retry a failed mutating request automatically. Check the app state first. AUTOMATIC FIRST OPEN Extract the full Clara directory at the existing path; preserve hidden .htaccess, directory mode 755 and CGI mode 755. Opening index.html or studio.html initiates the fixed, credential-free startup sequence, initializes missing private tables and administrator token, then verifies direct runtime health. It does not overwrite data, publish user apps, change host settings, or expose the token. If hosting prevents CGI launch the browser runtime remains available; the host must enable CGI before hosted functions work. Retry via Studio > Check runtime. No PHP, npm, SSH commands or cron are needed for this compatible-host initialization. Cron and node operation remain separately configured. CLARA ASSISTANT / ORIGINAL CUBE One original faceless puzzle cube replaces all companion characters. Open Ask CLARA > Cube design studio or tap the cube > Cube skins; eight finishes persist locally. No limbs, clothes or parachute. The original 3D GLB includes 26 moveable cubies and 28 animations, and is loaded solely from this installation. Drag and release for a tumble and landing; hold for special animations or games. No external downloads required. Five FORGE models remain available only within Graphics. Local lessons and application data are preserved. Optional audio and voice retain existing controls. The renderer uses studio-style lighting, not full physically based environment reflections. CUBE TRICKS: Tap the companion, expand Cube tricks, and choose Cyclone, Block stack, Zero gravity, Chameleon, Letter magnet, Parkour or Ricochet. Autonomous play can be disabled in the same menu. Letter copies are limited to predefined UI words; no user content is changed, transmitted or trained on. Camouflage samples CSS background colors only. Parkour uses visible container rectangles and a bounded viewport arc, not physical collisions. Any page interaction, drag, build event, resize, scroll or reduced-motion preference stops active effects. HOST RECOVERY UPDATE (2026-11-20) The original Cube distribution passed local Apache CGI and rewrite tests. Do not replace existing databases, project drafts or customized program.json. An HTML 500 from both minimal probes is a host execution symptom, not proof of a specific cause. Use binary SFTP, preserve .htaccess and mode 755 on Clara and the five CGI launchers; keep .py files at 644. Never use mode 777. Run the separately supplied clara_host_recovery.py from outside the web root: python3 ~/clara_host_recovery.py ~/minespace.us/Clara python3 ~/clara_host_recovery.py ~/minespace.us/Clara --apply The tool only adjusts modes on the installation directory, .htaccess and known CGI files when owned by the running account. It does not change owners, CGI policy, source, databases or credentials. It runs three isolated CLI probes. Then re-run diagnostics.html; CLI success does not prove Apache CGI success. For an HTTP 500 that persists, inspect DreamHost website Error Logs immediately after requesting shell-probe.cgi. Ask support to check suEXEC ownership, CGI execution policy and the script's shebang if the logs do not explain the error. CUBIE / GRAPHICS DEVELOPER UPDATE 2.0.0 Upload the contents of Clara/ over the existing Clara install; maintain CGI permission settings. This release does not require a server backend for the game editor. Cubie defaults to CLARA Orange (one-time new skin preference key), voice on and sound on. Explicit skin choices and audio opt-outs are saved. The browser must allow audio after a gesture and a local speech voice must exist. Open game.html for the new rendering controls, camera orbit/zoom, lighting and quality profiles, undo/redo of tile and resize edits, route analysis, paused simulation tick stepping and debug export. Source code edits are not individually tracked in the scene history. Previous scene and replay formats are unchanged. Rendering is enhanced WebGL2 with procedural surface effects and bundled GLB assets; it is not a complete PBR engine or real-time shadow mapping. The software renderer supports camera and basic lighting controls without equivalent shader effects. Performance counters measure CPU draw submission, not GPU execution. Browser regression was blocked by the test environment's managed navigation policy; native compiler/replay and editor logic passed Node tests. CUBIE LIFE / SPATIAL BEHAVIOR Upload over the existing Clara directory. A third drag-release within 16 seconds triggers a random 26-piece real-mesh scatter, viewport bounce and spiral rebuild (3.8 seconds), followed by a short celebration and animated return to the dock. Quick menu > Cube tricks adds Explorer and Shatter & rebuild. The dock is a live layout anchor; page tricks finish at it, and explicit Return to dock travels rather than teleporting. Opening chat, hiding Cubie, rotating the device or enabling reduced motion interrupts ongoing effects safely. Preferences and game engine are unchanged. Audio still requires a browser gesture. CUBIE LIFE 2 / WORLD EATER All 18 top-level Clara pages now mount the same local companion; isolated app-preview.html remains unchanged. Flick Cubie to throw, slow release to drop. World eater is an explicit quick-menu trick, not an autonomous interruption. Escape or Skip cancels. Canvas effects simulate page infection without accessing or modifying page text, data, or inputs. CUBIE / THE BOOK OF CUBIE (2026-11-20) Open cubie-story.html from Cubie's quick menu or the documentation guide. The page compiles actual Clara source in a dedicated local browser worker. The forge reconstructs all 697 accessors and verifies their binary SHA-256; the canonical GLB is separately verified before it can be installed as the live companion. No CGI or original GLB download is needed for the forge itself. The original companion remains the default until the user selects "Use as my Cubie". IndexedDB holds the verified artifact and the preference is local. If storage or digest verification fails, the original verified GLB is used. The editable assembly spell is a separate educational VM program, not a modification of the installed canonical model. Browser rendering, gestures, audio, page behaviors and packaging remain JavaScript host capabilities.