• Ordinary owned automated browser runs use versioned Chrome for Testing or the browser provisioned for the pinned Playwright version. Reject the installed auto-updating Chrome application, including explicit executable overrides and symlinks; never fall back to it when provisioning is missing. Report the resolved executable and browser version, and close owned contexts and browsers gracefully in cleanup. Attaching to an explicitly authorized user-owned browser is a separate operation: preserve its profile and lifetime. Keep regression checks for browser selection in the existing required checks; see browser automation.
• Never start the system Chrome app directly from an agent shell; use the repository's browser tooling and respect its scheduler and browser custody controls. For owned launches, pass --mute-audio and merge PaintHolding,MacAppCodeSignClone into any existing --disable-features value instead of adding a second switch. Finish owned process, context, and profile cleanup before releasing the browser lane. Never signal another holder or manipulate its lease to obtain a slot.
• The sole native-runtime exception is Slopcamera’s documented signature-verified, version-bound, immutable task-owned Chrome snapshot, never a direct launch of the installed application. Its current integrity-bound launch contract must disable MacAppCodeSignClone; retain vendor identity verification, browser custody, graceful cleanup, and regression checks. Qualify the native fix with live clone-growth and cleanup evidence before activating this exception. It is not an executable override or fallback for ordinary automation; see the native-runtime exception.

Contents

• src/ – portable declarative and imperative workflow SDKs, host-resource admission, diagrams, direct Vercel AI Gateway generation, local vectorization, semantic operations, MCP, and canvas integration.
• apps/desktop/ – the canonical slopcamera CLI, complete local media host, durable scheduler, HTML and Three.js overlays, and the local Vision analysis helper.
• apps/web/ – the static slopcamera.com site, with a local browser bundle and a production-only anonymous pageview boundary but no API, account, or credential surface.
• apps/api/ – the hosted tool adapter for agent platforms: bounded REST and MCP endpoints over the canonical src/mcp runtime, per-request ephemeral workspaces, R2 artifact tickets, and Credits-billed image generation.
• apps/objects/ – the slopcamera-objects Cloudflare Worker: an HMAC-signed request proxy over the private slopcamera-api-artifacts R2 bucket, deployed with wrangler deploy.
• packages/scene/ – the shared local scene-analysis contract.
• src/code/ – portable declarative graph authoring, the closed public capability projection, compilation, planning, and execution contracts.
• src/spatial-scene/ – portable editable scene contracts, stable identity, semantic patches, calibrated evaluation, and bounded GLB parsing.
• src/studio/ – portable retained native production jobs, runtime evidence, output semantics, admission plans and receipts.
• schema/ – version-one diagram JSON Schema.
• skills/slopcamera/ – the canonical Slopcamera Agent Skill.
• .agents/skills/ – portable repository orchestration and knowledge-base workflows.
• kb/ – the Git-backed Markdown vault for rationale, evidence, maintained synthesis, plans, and scoped agent context.
• examples/ – checked diagram, configuration, and executable imperative and declarative Bun workflow examples.
• scripts/ – schema, skill, package, release, and official-vectorizer verification.
• bench/ – maintainer benchmarks run on demand, never in CI or the package; bench/token-savings/ measures agent token use with and without Slopcamera installed.
• dist/ and apps/desktop/dist/cli/ – committed Bun-targeted entrypoints consumed by package and Git installs.
• .github/workflows/ – routed SDK, local-host, static-site, macOS-native, official VTracer, and immutable release checks.
• docs/ – the documentation entry point, first-result tutorials, creative task guides, capability and SDK reference, architecture explanations, and provider/release runbooks.
• README.md, CONTRIBUTING.md, SECURITY.md, LICENSE, and NOTICE.md – public documentation, policy, and terms.
• WRITING.md and STYLE.md – internal and public prose contracts.
• package.json, tsconfig.json, and bun.lock – standalone package and verification configuration.

Guidelines

• Use Bun 1.3.14 and complete the source gate in CONTRIBUTING.md: focused local checks and independent impact review, then fresh complete CI on the exact current integration candidate, or the local bun run check fallback. Preserve every explicit local, native, browser, installation, live, release and npm-mirror gate.
• Follow WRITING.md for internal prose and STYLE.md for public prose, preserving facts, exact terms, literals, quotations, links, and necessary uncertainty.
• Follow the shared README guidelines for the root README and any site copy that summarizes it.
• Apply the shared documentation guidelines to every maintained documentation surface. Use Diátaxis to distinguish guided learning, task completion, factual reference and explanation; make each page's reader need clear without imposing four folders. Keep marketing, README, docs, CLI/SDK help and agent skills consistent with actual release, interface, platform and trust boundaries. Preserve historical sources and all local validation gates.
• Public copy states only facts the source defines: tool, operation, workflow, style and HTML profile counts, tool and operation names, the current release and its commit, and commit links. bun run check:copy (scripts/check-copy.ts, rules in scripts/copy-facts.ts) checks the README, docs/, apps/web/src/docs/, skills/ and the generated agent pages against src/ and fails on drift; CI runs it on every pull request. When such a fact changes, update every surface in the same change, and change docs/ and apps/web/src/docs/ together because neither is generated from the other. Write historical mentions as "introduced in vX.Y.Z" so they are not read as the current release, link merged commits rather than branch commits, and add a rule when a new citable fact enters public copy.
• Apply unreasonably robust programming when agent work is cheap. Prefer coherent cross-file correctness and focused deterministic evidence while treating production risk, provider coordination, rollout, and observation as real costs.
• Deliver changes to main through a current-head pull request. Keep the stable Required CI job green, resolve every review thread, and serialize merges. Human approval stays optional while one regular maintainer would otherwise self-review. Never force-push or bypass the gate.
• Keep this repository independently buildable. Never depend on sibling paths, Git submodules, or coordinated main branches; consume external Hraness packages only through reviewed immutable release tags or commits. For a public npm package, an exact version (never a range) whose registry integrity was verified and recorded at admission counts as an immutable release.
• Extract a shared package only after a second concrete consumer proves a stable product-neutral contract. Shared packages never import product code.
• Keep Slopcamera's product and editor presentation local. Add @hraness/ui for portable accessible primitives or @hraness/design-kit for optional shared presentation only after concrete reuse warrants the dependency; domain layout and content remain Slopcamera-owned.
• Freeze shared interfaces before parallel lanes begin. Give one integration owner manifests, lockfiles, generated registries, and other convergence files, then let consumers upgrade immutable releases independently.
• Keep mandatory edit-time rules in the closest AGENTS.md, current procedures in docs/, executable contracts in types, schemas, and tests, and rationale, evidence, synthesis, and plans in kb/. KB lanes run bun run kb:check:lane; the integrator performs one refresh and bun run kb:check.
• Keep @hraness/slopcamera at the repository root. The root package owns both the portable SDK and canonical slopcamera binary built from apps/desktop/cli/main.ts.
• Keep canonical commands namespaced as slopcamera diagram init|check|render, slopcamera image generate|vectorize|icon, slopcamera image icon compose|render, slopcamera media soundtrack compose|grid, and the code, mcp, canvas, skill, and doctor surfaces.
• Keep local vectorization authentication-free and network-silent. Gateway generation reads AI_GATEWAY_API_KEY before VERCEL_OIDC_TOKEN, never persists credentials, pins the Gateway origin, bounds responses, and sets maxRetries: 0.
• The hosted adapter in apps/api/ serves only the checked tool registry over per-request ephemeral workspaces, never arbitrary operation or code execution. Billable operations hold and settle through Hraness Credits with caller idempotency; artifacts and uploads are TTL'd R2 objects. No accounts, OAuth, or credential persistence.
• Keep /artifacts/, .env, and .env.* ignored. Recordings, imported media, private project metadata, Gateway tokens, and provider options must never enter Git or a package artifact.
• Treat vercel env run -- <command> as the ergonomic local Vercel path. Never shell out to infer or scrape a token from the Vercel CLI.
• Treat Production as Slopcamera's only durable Vercel environment. Do not create a custom environment, persistent Preview domain, or provider-authoritative Preview branch. Pull requests may use Vercel's built-in disposable Preview target, without production-only variables or another durable backend. Follow the Vercel runbook and audit provider identity before changing this seam.
• Preserve .diagram.json version one and the five same-stem render outputs: .tldr, light and dark SVG, and light and dark PNG.
• Keep one self-contained Slopcamera identity. Public APIs, serialized identifiers, operation codes, source imports, configuration, and runtime surfaces use only Slopcamera names. The one exception is a named, exact-version external Hraness library admitted behind Slopcamera-named operations (currently @hraness/iconplace for slopcamera.icon.* and @hraness/soundfish for slopcamera.soundtrack.*): source may import it, and receipts may name it as the engine with its version, but its types, identifiers and names never become Slopcamera's public contract.
• Preserve every immutable version-1 tag and Release. Never rewrite a historical tag or recreate a repository at the former GitHub path, because doing so would replace GitHub's compatibility redirect.
• Treat diagram source as authoritative and generated media as replaceable. Defaults may resolve mechanics but must not invent claims, labels, legends, relationships, or decorative meaning.
• Model invalid states out, parse foreign values from unknown, and keep output deterministic. Preserve readable regression examples; add property tests for laws, parsers, reducers, ordering, and round trips, and promote shrunk failures into named deterministic examples.
• Keep semantic registries fixed and typed. Never accept source text, evaluation, dynamic imports, executable workspace configuration, shell commands, or caller-selected remote URLs.
• The fixed slopcamera.studio.run operation is an explicit native-authoring exception: it may execute a previously retained, hash-bound Python or native-scene bundle through a closed Blender/Manim/CadQuery host adapter. It requires a separate invocation-scoped trusted-current-user envelope; source import, pure planning and inspection stay inert. Runtime paths and argv remain host-owned, and the profile declares no OS sandbox or hermetic dependency closure.
• Preserve the root module and ./workflow v0.8 imperative APIs. Add declarative graphs through ./code and lower-level compiler contracts through ./code/advanced; do not add ./code/testing or ./code/workflows exports.
• Treat explicitly imported workflow modules as trusted current-user Bun code. Compile graphs only against the host's closed capability projection, reject an unsupported capability before executor or resource admission, and do not add an open operation-registration hook.
• Treat the portable SDK and core as the canonical graph contract. The complete local host consumes that contract through its own closed projection and owns durable media execution. The menu-bar companion is retired: slopcamera status, tui, commands --json and outputs cover what it showed, and legacy retire moves its login item aside without deleting it. Do not add a tray, menu bar or background owner.
• Model one project as immutable source plus explicit revisions, candidates, selections, and delivery variants. Keep ready work bounded by resource claims and serialize expensive encodes by default.
• Keep imperative workflows as explicitly imported trusted Bun modules over the fixed operation registry. Parse runtime input, bound and uniquely identify steps, drain dispatched work before returning, retain completed-step receipts on every failure path, and do not load caller-selected source paths.
• Keep semantic SDK, CLI, MCP, and workflow resource admission machine-global and crash-safe on macOS and Linux, with a truthful process-local fallback elsewhere. Preserve profile identity, FIFO admission for overlapping claims, callback-settlement ownership, and inherited lease descriptors through spawned vectorizer processes.
• Keep MCP paths root-relative and capability-small. Bound source bytes, arrays, shapes, edges, scale, pixels, findings, subprocess duration, and output bytes before execution.
• Keep vectorization fail-closed with checksum-pinned VTracer archives, inert rebuilt SVG, measured fidelity, and full provenance receipts. Do not add an embedded-raster fallback, upscaling model, or bundled commercial font.
• GitHub Releases are canonical. Follow docs/publishing.md; preserve every historical npm version, tag and Release. The new @hraness/slopcamera source package has no contentPolicy declaration. Keep factual data-handling guidance in PRIVACY.md and preserve actual capture, consent and credential controls. npm is an optional downstream mirror, and a publisher for the historical package does not authorize this new package.
• Use the two exact active refs/tags/v* rulesets: Immutable version tags restricts update/deletion with no bypass; Release tag creation restricts creation with owner User ID 894119 and the hraness-release-tagger App (Integration) as its only bypass actors. Releases accept a tag push from the owner or from hraness-release-tagger[bot] (Bot ID 337004703), which .github/workflows/auto-tag.yml uses once a version bump passes CI on main. From clean current main, use scripts/push-release-tag.ts; preserve exact owner/repository/protected-main/CI attempt/Required job, stable ordering and conditional annotated-tag identity. Never grant any other actor tag bypass, create probe tags, move a tag or recreate a historical release.
• Build one canonical archive from the protected tagged source after the full gate; retain isolated package installation and all five official VTracer targets. The retired menu-bar companion and capture shell have no build, packaging or release job. Bind the five documented assets to exact source, workflow, current-main helper closure and hosted run/attempt provenance. Attestation and publication jobs must check out no product source, run no package code, and independently reauthorize the complete handoff before credentials or mutation. Publish through a verified draft and require immutable Latest readback. Never overwrite assets or relabel a previous attempt's provenance; reconcile matching state and stop on mismatch or uncertain authority.
• Publish npm automatically inside the tag Release workflow: publish_npm runs only after the immutable Latest release, is checkout-free, declares the npm-release environment (sole deployment policy tag v*, disabled administrator bypass, no required reviewers or secrets) and the sole id-token: write besides attestation, downloads the attested artifact by numeric artifact ID so a rerun of only the failed job still publishes the same bytes, reauthorizes the current owner attempt and current-main helper closure, re-verifies the five-file signed handoff and the published immutable release before OIDC, treats an already published identical registry integrity as success and never overwrites a different one, and requires npm latest to stay monotonic with no explicit dist-tag, empty npm configurations, canonical packed configuration, bounded independent USTAR readers and no traditional token. admit_npm then verifies the public registry archive, signatures and provenance against the canonical asset. Do not add a dispatch, staged publish, or interactive two-factor step back; npm remains a mirror of the exact GitHub bytes and does not block GitHub delivery.

• Public copy (websites, READMEs, docs, package and GitHub descriptions, CLI help, llms.txt, generated pages) follows STYLE.md, synced from hraness/.github. Text a model writes for publication also follows GENERATION_STYLE.md.
• The delivery vocabulary in this file (admission, qualification, custody, receipt, bounded, lane, gate, surface, projection) is internal. Translate it into what the reader gets.
• Take one-line product and sibling descriptions from the portfolio registry and versions from the release record. Tests pin facts, not prose.
• Run bun run check:copy before handoff when the repository has it.

• GitHub Release pages follow RELEASES.md in hraness/.github: the title is the registry product name and the tag, and the body is a summary, ## Changes, ## Install, ## Verify, then the repository's identity record as a trailing HTML comment.
• The summary and changes come from the version's section of CHANGELOG.md in the tagged commit. Write that section in the version bump pull request. The release workflow copies it, generates Install and Verify from the release record, fails when the section is missing or empty, and never uses GitHub's generated notes.

• Treat the user's request to change this repository as standing authorization for routine task-owned commits, pushes, pull requests, merges, releases, deployments, and production verification after the gates applicable to that action pass. Do not ask for duplicate confirmation. Build confidence through relevant automated checks, bounded diagnostics, and independent review, not another human approval. Passing checks does not expand task scope or authority.
• Prefer agentic service provisioning for new infrastructure. Check Vercel Marketplace for a native product that can provision the required resource first; use Stripe Projects as a supported alternative when it better covers the service or the Marketplace route only connects an existing account. Verify the current catalog, account, region, plan, recurring cost and resource capabilities before selecting a route. Prefer supported provider CLIs or APIs over browser-only setup when neither catalog fits, and explain the concrete exception. Reuse existing owner-controlled resources where appropriate; this preference alone does not authorize migrations, duplicate accounts, paid upgrades or wider access. Continue setup already authorized by the task and budget without duplicate confirmation. Keep provider credentials and generated environment files private, complete required interactive authentication, and verify deployment, persistence and recovery separately from successful provisioning.
• Separate artifact admission from live qualification and operational activation. Use applicable automated source, security, package/install, and provenance evidence for artifact admission; live provider qualification is not a universal publication prerequisite. Preserve explicit live acceptance criteria and require relevant live evidence for claims that depend on it. If publication or an artifact's install, upgrade, or default-use path activates risky unqualified behavior, keep that behavior guarded or disabled, or obtain bounded relevant evidence before shipping or activation.
• Use the repository's documented delivery workflow and preserve the identity, target, capacity, migration, and recovery guards applicable to operational activation. Replace an obsolete gate through a reviewed source and policy change with corresponding tests, never an ad hoc skip. Preserve every runtime-enforced approval, access control, branch protection, environment rule, safety policy, and required final gate. Ask for user input only when delivery needs a material product decision, missing credentials or authority, unavoidable interactive authentication, an irreversibly destructive action outside task scope, or resolution of a failure that cannot be handled safely and autonomously.
• Preserve production and user data throughout delivery. Inspect the exact account, environment, deployment, and data target before writes. For data changes, inspect a dry run or equivalent migration plan and validate the recovery path before any effect that could lose or corrupt data. Prefer additive, backward-compatible migrations and bounded batches. Record mutation intent, use idempotency or conditional writes, and reconcile uncertain results before retrying. Verify deployed identity, health, and relevant data invariants after delivery. Routine delivery never authorizes resetting, truncating, dropping, or overwriting user data; stop the unsafe operation if preservation or recovery cannot be established.
• Prefer short-lived repository workload identities such as OIDC trusted publishing, GitHub Apps, and narrowly scoped machine identities. Use unattended stable publication and production promotion when supported by the provider and repository. Establish supported machine authority once and verify it with a non-publishing preflight where available; routine releases should not require recurring interactive authentication or conversational approval. Releases and deployments run without a human in the loop: do not add required reviewers, manual approval environments, or wait timers to release or deployment paths, and remove any you find through a reviewed change. Keep account two-factor authentication, and do not add long-lived personal tokens.
• Keep delivery gates proportional to the failure they prevent. Prefer required checks on the current integration candidate, independent agent review, and atomic or conditional integration. Add a merge queue or another approval stage only for a demonstrated coordination or safety need. Replace redundant queues, serial waits, and duplicate checks through reviewed policy changes while retaining evidence for the integrated result.
• Preserve useful reasoning fan-out, but avoid unnecessary checkout fan-out. Prefer subagents in the current task for bounded research, review, diagnosis, and focused checks when they can safely share one working tree; create a separate task or worktree only for independently deliverable divergent edits, an isolated verification tree, or a different execution environment.
• Give each expensive focused validation command and external wait one owner. The integration owner reviews that evidence and runs the repository-required aggregate or final gate once after convergence. Reuse evidence only for the exact Git tree, command, lockfiles, toolchain, relevant environment, and validity period, and never to skip a required final integration, merge, release, deployment, or production-verification gate.
• On Hraness development machines, use the installed host scheduler for heavyweight top-level commands when available. Keep ordinary work in the compute lane; give authenticated browser/dev-server/Chromium work one browser-auth owner and Mac-only validation one mac-native owner.
• When a CI or policy gate scans complete Git history, check out the exact governed SHA and fetch only the fully qualified governed refs before scanning. Preserve the complete-history gate and reject unexpected refs instead of importing unrelated concurrent heads.
• At closeout, record applicable branch, PR, check, merge, release, deployment, and production evidence. Archive only conclusively finished tasks, never from silence alone, and reclaim only freshly revalidated clean merged worktrees through the guarded exact-path flow.

• Essays and blog posts follow the essay addendum in GENERATION_STYLE.md and ARTICLE_COPY.md in @hraness/design-kit. The byline is “Hraness”, every post shows the provenance note naming its recorded reviewer, and no AI-drafted post is credited to a person unless that person rewrites and adopts it.
• Take product names, one-line descriptions, addresses, status labels, and relations from the portfolio facts in @hraness/design-kit. Render versions from the release record (package.json, a published-release file), never typed by hand.
• Write a “How X uses Y” post only for a registered relation that has a description. Change the relation and its post in the same change. Link between products only along registered relations, and between a technique post and product posts about the same technique.
• Every post has a review record: reader job, non-obvious answer, sources with the date checked, owner, reviewer identity, reviewer type (ai or human), a score out of 12, and a reassessOn date 28 to 56 days after review. The reviewer is independent of the run or person that drafted the post. An AI reviewer is recorded and shown as AI; humanReview stays null unless a person reviewed the post.
• A new post starts out of search indexes, sitemaps, and feeds. It becomes indexable only when its review record is complete, scores at least 9 of 12 with no zero score, and the page shows the provenance note.
• When a product is renamed or a relation changes, update the post bodies that mention it in the same change.

• Launch posts, their social posts, product mockups, and launch films follow the launch beats and social posts addendum in GENERATION_STYLE.md and the beats shape under “Introducing a product” in ARTICLE_COPY.md in @hraness/design-kit. Channel limits are in the launch posts section of MESSAGING.md.
• Build them with the product-launch agent skill, the ./mockups and ./launch exports of @hraness/design-kit, and slopcamera html init --template launch-film.
• Take every number in a beat, social post, film caption, or store listing from the product's launch facts module, and the status from the release record. Keep mockup accessible descriptions accurate; visible captions are optional and must add useful context.
• The social kit emits posts for X, Bluesky, Threads, and LinkedIn, and a fact sheet for the Show HN post and the Product Hunt first comment. A person writes those two.

• costs.json at the repository root is the checked registry of every product data surface: store, kind (authoritative | derived | telemetry | served), retention class (ephemeral | ttl:<ISO-8601> | account | tombstone | persistent), owner module, and budget. A new table, bucket, stream, dynamic route, blob, or provider meter fails check:cost-surfaces until it registers.
• Bound every input before storage or provider I/O: request bytes, row counts, page sizes, batch sizes, retry counts, and event payloads. Unbounded input is a contract violation.
• No writes on read paths. Reads may cache; they never mutate.
• Derived state is rebuildable and lives in the cheapest tier that can serve it. Only authoritative state pays for transactional storage.
• Every mutation carries an idempotency key; a retried write never double-charges storage, quota, or provider spend.
• Analytics and metering events come from a checked allowlist with a byte ceiling per event.
• Content bytes live in the content store; the control plane keeps references and metadata only.
• Run bun run check:cost-surfaces before handoff whenever a data surface changes.

• Prefer the globally installed algal-* skills for bounded git state, diffs, repository survey/search, test and release gates, CI polling, and web fetches instead of repeated raw tool output.
• At session start, if the algal skill is unavailable, install the current skill pack for Claude Code, Codex, and Devin for Terminal with bunx skills add 0thernet/algal-skills --global --agent claude-code codex devin --skill '*' --copy --yes.
• Confirm installation with bunx skills list --global. If Bun or network access is unavailable, continue with repository-native tools instead of blocking delivery.
• Treat ALGAL receipts as execution evidence, not provider attestation, and preserve the repository's normal verification and release gates.