ondaru 0.1.0__tar.gz

ondaru-0.1.0/.env.example

@@ -0,0 +1,39 @@
+# Copy to .env and fill in. Nothing here has a usable default — a missing
+# credential fails at startup rather than running against nothing.
+
+# --- Payment ------------------------------------------------------------
+# X Layer. The settlement token is fixed and registered in code; only the
+# recipient is yours. It MUST match the address the ASP is registered against,
+# because a mismatch sends a caller's funds somewhere else.
+ONDARU_PAY_TO=0x0000000000000000000000000000000000000000
+ONDARU_PAYMENT_NETWORK=eip155:196
+ONDARU_PAYMENT_TIMEOUT=120
+
+# --- Pricing ------------------------------------------------------------
+# Measured generation cost is $0.19-$0.30 per asset. The floor is enforced at
+# startup: an asset price at or below it refuses to boot rather than selling
+# at a loss. Observed marketplace maximum is 0.96.
+ONDARU_SPEC_PRICE=0.02
+ONDARU_ASSET_PRICE=0.90
+ONDARU_ASSET_PRICE_FLOOR=0.30
+ONDARU_CURRENCY=USDT
+
+# --- Generation backend -------------------------------------------------
+ONDARU_GENERATION_BASE_URL=https://api.your-vendor.example
+ONDARU_GENERATION_API_KEY=
+ONDARU_GENERATION_SUBMIT_TIMEOUT=30
+ONDARU_GENERATION_POLL_INTERVAL=5
+ONDARU_GENERATION_POLL_DEADLINE=900
+
+# --- Infrastructure -----------------------------------------------------
+ONDARU_DATABASE_URL=postgresql://ondaru:ondaru@127.0.0.1:55432/ondaru_test
+ONDARU_REDIS_URL=redis://127.0.0.1:56379/0
+ONDARU_DB_POOL_MIN=1
+ONDARU_DB_POOL_MAX=10
+
+# --- Service ------------------------------------------------------------
+# Asset URLs are built from this, so it must be the address callers can reach.
+ONDARU_PUBLIC_BASE_URL=https://ondaru.example
+ONDARU_RETENTION_HOURS=72
+ONDARU_STATUS_CACHE_TTL=5
+ONDARU_RATE_LIMIT_PER_MINUTE=60

ondaru-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

ondaru-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Reference repositories cloned for study — never committed.
+references/
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+.venv-*/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Local environment
+.env
+.env.local
+
+# Generated assets and every test artefact. `out/` is scratch: generated models,
+# renders, captured payloads, server logs. The evidence the README cites lives
+# in docs/, which is text and reviewable; the binaries it describes do not
+# belong in git.
+assets/
+.artifacts/
+out/
+dist/
+
+# Signed payment authorisations for the load test. Each one is a bearer
+# instrument that moves real funds when redeemed.
+tests/load/authorizations.json

ondaru-0.1.0/CLAUDE.md

@@ -0,0 +1,364 @@
+# Ondaru
+
+Agent-ordered 3D product mockups, served as an A2MCP service on OKX.AI. Another
+agent describes a product; we return a textured `glb` and a turntable render,
+paid for inside that agent's own workflow.
+
+Plan: `docs/plans/2026-07-28-001-feat-agent-3d-product-mockups-plan.md`.
+Research and market measurement: `docs/notes/`.
+
+## Stack
+
+Python (`>=3.12`, developed on 3.14), managed with `uv`.
+
+| Concern | Choice |
+|---|---|
+| MCP surface | `fastmcp`, stateless with JSON responses |
+| Payments | `x402[evm]`, challenge emitted at the ASGI layer |
+| Persistence | Postgres (`asyncpg`) |
+| Cache, rate limit | Redis |
+| CLI | `typer` + `questionary` + `rich` |
+| Containers | Docker via OrbStack |
+| Load testing | k6 |
+
+## Commands
+
+```bash
+make up            # stack: Postgres, Redis, fake generation backend
+make check         # ruff + mypy (strict)
+make test          # integration suite, randomised order
+make test-seq      # sequential, for reproducing one failure
+make load          # k6 suites
+make down          # tear down, including volumes
+
+uv run python -m ondaru.mcp 8000      # the MCP surface + worker (production)
+uv run python -m ondaru.server 58000  # HTTP: asset delivery + load-test routes
+uv run ondaru                         # interactive: install, order, or check
+uv run ondaru setup-mcp               # install into a host agent
+uv run ondaru skills install          # install the skill
+uv run ondaru try --url ...           # order one mockup end to end, save it
+uv run ondaru credits                 # what each generation account has left
+uv run ondaru check --url ...         # exercise a live service
+```
+
+The integration suite runs against **real** Postgres and Redis. Only the
+generation vendor is faked, by a container speaking the same contract — not an
+in-process stub.
+
+## Invariants
+
+Each exists because breaking it produced a concrete failure.
+
+**No tool call may occupy the connection beyond 30 seconds.** Measured against
+OKX's own client: a call returning at 29s succeeds, one returning at 35s is
+severed at exactly 30. Progress notifications do **not** extend the window — a
+60s call emitting progress every 5s still died at 30 with no result, and
+returned an `ok` status with empty content rather than an error. Work that
+cannot finish inside roughly 25 seconds is submitted as a job and retrieved by
+a separate call. Two tests assert the timing directly.
+
+**No vendor vocabulary above the generation adapter.** The adapter speaks
+submit, poll, fetch. Vendor field names, status spellings, and staging stop
+there. The public tool contract is what agents install a skill against; a
+change to it after distribution is the expensive kind.
+
+**An unrecognised vendor status raises rather than defaulting.** Treating an
+unknown status as "still running" makes the worker poll a task that will never
+resolve.
+
+**Never fabricate a deliverable.** A failed job returns a named cause and no
+asset. Partial files are removed on the failure path, so a later fetch cannot
+find a truncated model that looks like success.
+
+**The LLM never sets a price.** Pricing is deterministic code reading config,
+and config refuses an asset price at or below the measured generation cost
+floor, or a non-positive spec price — the service will not boot at a
+loss-making price. Asset tier 0.90 against a measured 0.20 cost; spec tier
+0.02, the entry price behind the highest-volume ASP measured (PixelBrief,
+21,629 sales). Observed marketplace ceiling: 0.96.
+
+**Every tool that produces anything is paid.** `tools/list` is free because
+discovery must be; polling is free because charging per poll bills one job
+repeatedly. Both other tiers sit behind the paywall.
+
+**One authorisation buys one job.** Proven the hard way: a captured
+`PAYMENT-SIGNATURE` replayed three times produced four jobs from one 0.60
+payment, each burning ~$0.20 of vendor credit, and the replays carried
+*different* subjects. Signature recovery cannot see this — a replayed header is
+a valid signature. The EIP-3009 nonce is claimed in Postgres before work is
+released, and the primary key is the enforcement; a read-then-write check
+passes serially and loses the race against a replay arriving beside its
+original.
+
+**Vendor credit is only ever spent against money that has arrived.**
+`claim_next_queued` passes over any job whose payment has not settled on-chain.
+A verified signature is a promise; generation is a balance leaving the account.
+A failed settlement costs waiting, the other ordering costs money.
+
+**A duplicate order is not charged twice.** Its authorisation is written off
+rather than redeemed. Declining to submit *is* the refund — an authorisation
+nobody submits expires costing the payer nothing, and no transaction is needed.
+
+**An authorisation that cannot be collected fails its job, loudly.** Expired
+ones are abandoned rather than retried forever, and the job reports
+`payment_not_collected`. Silence is the one outcome a paid API must never
+produce.
+
+**Config refuses two mainnet pairings outright.** The fake generation backend
+on mainnet sells placeholder geometry for 0.90, and a localhost or `http://`
+`ONDARU_PUBLIC_BASE_URL` writes an unreachable URL into the job row as the
+delivered model — permanently, since the row is never rewritten. Both defaults
+are right on a laptop and catastrophic in production, and neither fails on its
+own: the service boots, takes payment, and only then produces something
+worthless. Testnet is unguarded, because running the fake backend against a
+fake host is the entire point of it.
+
+**A wrong EIP-712 domain is the quietest way to earn nothing.** Signatures
+recover to a different address, every honest payer looks like a forger, and the
+service refuses all revenue while reporting itself healthy. Boot verifies the
+domain against the token's own `DOMAIN_SEPARATOR()` and refuses to start on a
+mismatch. An unreachable RPC only warns — a node being down says nothing about
+the domain, and refusing to start over it trades a quiet failure for a loud
+outage.
+
+**Payment checks fail closed; the balance check fails open.** No verifier, no
+nonce claim, or an unverifiable header means refusal. But an unreachable RPC
+during the balance read does *not* refuse a paying caller — a node being down
+is not evidence of an empty wallet, and the settlement gate already protects
+the vendor spend. Know which checks are defences and which are diagnostics.
+
+**Invariants that concurrency can break live in the database.** Idempotency is
+a partial unique index; forward-only transitions are a conditional UPDATE.
+Eight concurrent identical orders produce exactly one job; six concurrent
+transitions settle on one winner.
+
+**The suite decides where it points; the environment does not.** Generation
+vendor, backend URL, `pay_to`, network, and settlement key are forced in
+`tests/integrations/conftest.py` at import — not defaulted. Deferring to the
+environment meant a sourced `.env` aimed the generation tests at the real Tripo
+API and `pay_to` at a live wallet, and fifty-two tests skipped while the run
+still reported green. Enforce at import: conftest is imported before the test
+modules, and they read these at module level, so a session fixture is too late.
+
+**Tests must pass under randomised ordering.** Fixture leakage passes
+sequentially and fails at random. `pytest-randomly` is on by default; use
+`-p no:randomly` only to reproduce a specific failure.
+
+## Test naming
+
+Nested classes, three levels: the method, then the case category, then the test.
+
+```python
+class DescribeCreateJob:
+    class DescribePositiveCases:
+        def test_new_request_creates_queued_job(self): ...
+    class DescribeNegativeCases:
+        def test_backward_transition_is_rejected(self): ...
+    class DescribeEdgeCases:
+        def test_concurrent_attempts_settle_on_one_winner(self): ...
+```
+
+When a test enforces an acceptance example from the plan, say so in a comment:
+`Covers AE3.`
+
+## Load testing
+
+Constant arrival rate, never ramping VUs — ramping conflates offered load with
+observed latency, and the percentiles end up describing a load nobody chose.
+Thresholds fail the run; verified by running one that cannot be met (k6 exits
+99). `summaryTrendStats` must include `p(99)` or every summary reports it as
+zero.
+
+Measured against the containerised stack:
+
+```
+plan    avg 0.9ms   med 0.6ms   p95 2.2ms   p99 3.4ms    @ 50 req/s
+order   avg 4.0ms   med 3.0ms   p95 7.8ms   p99 16.0ms
+poll    avg 1.7ms   med 1.5ms   p95 3.9ms   p99 7.0ms    @ 90 req/s
+```
+
+For context the marketplace population sits at p50 543ms, p95 1612ms.
+
+With real payments, real settlement, and all three tiers competing for one pool
+(`tests/load/paid_flow.js`, 60s, whole stack in Docker via OrbStack):
+
+```
+                avg       med       p95       p99      throughput
+challenge     2.77ms    0.49ms    5.16ms   75.69ms    60 req/s
+paid        239.43ms  229.47ms  339.93ms  524.27ms     2 req/s
+poll         11.34ms    3.17ms   23.14ms  221.97ms    40 req/s
+                                                     102 req/s total
+```
+
+120 payments presented, 120 accepted, 0 refused; all 120 redeemed on-chain,
+2.40 USD₮0 collected, 0 left pending. The paid tier's ~230ms is dominated by
+the X Layer RPC balance read, which is not ours — refusal and polling, which
+are entirely ours, stay under 12ms average.
+
+**Send `Accept: application/json, text/event-stream`.** The MCP surface
+negotiates content type and answers 406 before any tool runs. A load test
+missing it measures the rejection: one run reported every paid call refused,
+and the payments had already been claimed.
+
+**Layer the rates; do not run every tier flat out.** Free and refused paths run
+at full rate because they cost only CPU. The paid path is sampled at ~2/s
+because every iteration spends real testnet funds and burns a single-use
+authorisation — running it at 50/s drains the payer in seconds and then
+measures an empty wallet.
+
+**Load-test payments are real, never stubbed.** `tests/load/paid_flow.js`
+presents genuine EIP-3009 authorisations, pre-signed by
+`tests/load/sign_authorizations.py` against the live token domain, and the
+server verifies each exactly as it verifies a caller's. k6 cannot sign EIP-712,
+and signing per request would measure the signer. One authorisation per
+iteration, never reused — a repeat is the replay the service refuses, and the
+run would measure refusals instead of work.
+
+`tests/load/authorizations.json` is gitignored: each entry is a bearer
+instrument that moves real funds when redeemed.
+
+## The install must not cost 200 MB
+
+`uvx ondaru setup-mcp` edits a JSON file and copies a skill. Declaring the
+whole service as required dependencies made that a 230 MB, 124-package download
+— a database driver and an EVM stack, to write a config file.
+
+Base dependencies are the four the CLI actually needs: `httpx`, `typer`,
+`questionary`, `rich`. Everything else lives behind `ondaru[server]`, which is
+what the Dockerfile installs (`uv sync --extra server`).
+
+This only holds because every heavier import in `ondaru.cli` sits inside the
+function that needs it. Move one to module scope and the install quietly
+returns to 230 MB. Measured after the split: **14 MB, 19 packages**, all four
+commands working.
+
+## Two entry points, and they are not symmetric
+
+The **agent path is the product**: `uvx ondaru setup-mcp` plus
+`uvx ondaru skills install`, then the host agent orders and pays inside its own
+workflow. `uvx` is the Python equivalent of `npx` — runs without installing.
+
+The **CLI is the installer and the demo**, not a second way to buy. Treating it
+as a product would mean it needs a wallet, and a terminal tool holding the
+money is a terminal tool worth stealing. `ondaru try` therefore pays through
+the user's own Agentic Wallet by shelling out to `onchainos payment quote|pay`.
+No private key enters this process.
+
+## Generation vendor — measured, not estimated
+
+First real run, 2026-07-28, Tripo `v2.5-20250123`:
+
+```
+credits per textured PBR model   20
+wall clock                       ~90 seconds
+output                           valid glTF 2.0 binary, 14.65 MB
+```
+
+At $0.01/credit that is **$0.20 per asset**, inside the $0.19-$0.30 band the
+pricing floor was set from. The 0.60 asset tier keeps roughly $0.40.
+
+**90 seconds is the number that justifies the whole architecture.** It is three
+times the client ceiling. A synchronous asset tier would have been severed
+mid-generation on every single order.
+
+The model version is **pinned**. Left unset the vendor picks, and today's
+default costs 20 credits while the latest costs 40 for the same job — a default
+change would silently double unit cost.
+
+Tripo's free 600 credits are Studio credits that also serve the API; the earlier
+reading that API billing was entirely separate was wrong. 600 credits is 30
+assets.
+
+**Capacity comes from several accounts, spent as one.** 30 assets is an
+afternoon for a listed service, so `ONDARU_GENERATION_API_KEYS` takes a
+comma-separated list and the Tripo adapter rotates when a key is spent.
+
+Rotation is driven by the vendor's own refusal, never by a tally kept locally —
+a local count drifts the moment anything else spends the same account, and a
+drifted count either strands credit or keeps submitting to an empty key. Only
+submission rotates; a poll stays on the key that started the task, because
+another account has never heard of it.
+
+A content-policy refusal must **not** rotate, or one bad prompt burns the whole
+fleet. Both directions are asserted.
+
+Keys are masked to their last six characters in every log line. `ondaru
+credits` reads live balances before a demo — discovering an empty account
+mid-order means a paying caller waits on a job that cannot start.
+
+## X Layer payment facts
+
+All measured. Re-verify after any vendor or protocol update.
+
+- Chain **196**, confirmed via `eth_chainId` against `https://rpc.xlayer.tech`.
+- One settlement token across the entire marketplace — 3,306 service listings,
+  zero alternatives: `0x779ded0c9e1022225f8e0630b35a9b54be713736`, `USD₮0`,
+  6 decimals.
+- X Layer is **absent** from the `x402` package's shipped network table, so it
+  is registered in `src/ondaru/mcp/payments.py`.
+- The token reverts on `eip712Domain()` and has **no `version()`**, so the
+  domain version cannot be read. OKX's payer docs say it defaults to `"2"`; a
+  live listed ASP emits `"1"`.
+
+  Settled arithmetically rather than by preference. `DOMAIN_SEPARATOR()` does
+  answer, and the separator is a hash of name, version, chain id, and contract
+  — so the domain can be *proved*:
+
+  ```
+  contract   0xd591d9baf744328d9400b923cb02c9474d367d591ca1ab24d8c4068be527599d
+  version=1  0xd591d9baf744328d9400b923cb02c9474d367d591ca1ab24d8c4068be527599d  match
+  version=2  0x27ce12e6ff1ac3cdc0f7d47223876f4f1a4e36f2b29939c257f4ded1be47a27d
+  ```
+
+  `"1"` on mainnet **and** testnet. The service verifies this at boot and
+  refuses to start on a mismatch, naming the version that would have worked.
+- The challenge must be a transport-level **HTTP 402** carrying a base64
+  `payment-required` header and an **empty body**, and the MCP surface must be
+  **stateless with JSON responses**. A JSON-RPC result flagged as an error —
+  what the x402 package's MCP wrapper produces — is not recognised.
+- `accepts[].extra` carries exactly `name` and `version`. Extra hints are not
+  read by the payer and the working reference ASP does not send them.
+
+## Where things live
+
+```
+src/ondaru/contracts.py      shared types — the narrow waist; imports nothing sibling
+src/ondaru/config.py         environment-driven settings with guard rails
+src/ondaru/mcp/              MCP tools, payment wiring, ASGI paywall
+src/ondaru/spec/             the specification tier (a plan, never geometry)
+src/ondaru/generation/       the vendor seam and its HTTP implementation
+src/ondaru/worker/           queued -> generating -> rendering -> ready
+src/ondaru/storage/          atomic asset writes and retention
+src/ondaru/store/            Postgres job state, Redis cache and limits
+src/ondaru/server/           asset delivery and load-test routes
+src/ondaru/cli/              installers and the live-service check
+src/ondaru/skill_assets/     the skill shipped to other agents
+fakes/generation-backend/    contract-faithful, failure-injectable vendor
+tests/integrations/          real infrastructure, faked vendor
+tests/load/                  k6
+docs/plans/                  the implementation plan (U-IDs, R-IDs, AEs)
+references/                  cloned repos for study — gitignored, never committed
+```
+
+`references/` is deliberately excluded. Study material lives on disk, not in
+history.
+
+## Deployment
+
+`Dockerfile` runs the MCP surface with the worker alongside. Splitting them is
+the right call under real load; one process is one deployment target, and the
+rule that decides eligibility is a live endpoint.
+
+Mount a volume at `/app/assets` — a restart otherwise loses everything inside
+its retention window.
+
+`ONDARU_PUBLIC_BASE_URL` must be the address callers can actually reach: asset
+URLs are built from it **and written absolute into the job row**. Changing it
+later does not rewrite those rows, so every job inside its 72-hour retention
+window keeps pointing at the old host. The domain is chosen once, before the
+first paid order.
+
+The marketplace requires an **`https://`** endpoint, so a plain IP or an
+`http://` host cannot be listed. Registration QA runs at register and update
+time — the endpoint must already be live and correct, and registering first to
+fix afterwards is not a route. Full contract: `docs/going-live.md`.

ondaru-0.1.0/Dockerfile

@@ -0,0 +1,32 @@
+# The deployed service: the MCP surface OKX.AI lists, with the worker running
+# alongside it.
+FROM python:3.12-slim
+
+# uv gives the same resolution here as on a developer machine, so a build that
+# passes locally cannot resolve differently in the image.
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+WORKDIR /app
+
+# Dependencies before source, so a code change does not re-resolve the world.
+# `--extra server` because the base install is the CLI only — see pyproject.
+COPY pyproject.toml uv.lock README.md ./
+RUN uv sync --frozen --no-dev --extra server --no-install-project
+
+COPY src ./src
+RUN uv sync --frozen --no-dev --extra server
+
+ENV PORT=8000
+EXPOSE 8000
+
+# Delivered assets live here, and production must mount a volume at this path:
+# a container restart otherwise loses every model inside its 72-hour retention
+# window, and a caller holding a `model_url` gets a 404 for something they paid
+# for.
+#
+# Declared in the platform rather than here. Railway rejects a `VOLUME`
+# instruction outright — "use Railway Volumes" — because it owns the mount, and
+# a Dockerfile that declares one fails the build before it starts.
+RUN mkdir -p /app/assets
+
+CMD ["sh", "-c", "uv run python -m ondaru.mcp ${PORT}"]

ondaru-0.1.0/Makefile

@@ -0,0 +1,31 @@
+.PHONY: up down logs check test test-seq load fresh
+
+# Bring the stack up and wait for every health check to pass. Tests that start
+# before Postgres is ready fail in a way that looks like a code bug.
+up:
+	docker compose up -d --wait
+
+down:
+	docker compose down -v
+
+logs:
+	docker compose logs -f
+
+check:
+	uv run ruff check .
+	uv run mypy src
+
+# Randomised order is the default: fixture leakage passes sequentially and
+# fails at random, so the suite has to prove it is order-independent.
+test: up
+	uv run pytest tests/integrations
+
+# Sequential, for reproducing a specific failure.
+test-seq: up
+	uv run pytest tests/integrations -p no:randomly
+
+load: up
+	k6 run tests/load/spec_tier.js
+	k6 run tests/load/order_and_poll.js
+
+fresh: down up

ondaru-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: ondaru
+Version: 0.1.0
+Summary: Agent-ordered 3D product mockups, served as an A2MCP service on OKX.AI
+Project-URL: Homepage, https://github.com/Lexirieru/ondaru
+Project-URL: Repository, https://github.com/Lexirieru/ondaru
+License-Expression: MIT
+Keywords: 3d,agent,mcp,okx,x-layer,x402
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: questionary>=2.1.1
+Requires-Dist: rich>=15.0.0
+Requires-Dist: typer>=0.27.0
+Provides-Extra: server
+Requires-Dist: asyncpg>=0.30.0; extra == 'server'
+Requires-Dist: eth-abi>=5.2.0; extra == 'server'
+Requires-Dist: fastapi>=0.140.0; extra == 'server'
+Requires-Dist: fastmcp>=3.4.4; extra == 'server'
+Requires-Dist: mcp>=1.28.1; extra == 'server'
+Requires-Dist: redis>=5.2.0; extra == 'server'
+Requires-Dist: uvicorn>=0.51.0; extra == 'server'
+Requires-Dist: x402[evm]>=2.16.0; extra == 'server'
+Description-Content-Type: text/markdown
+
+# Ondaru
+
+**3D product mockups your agent can order.**
+
+Another agent describes a product, logo, or character. Ondaru returns a textured
+`glb` and a turntable render — ordered and paid for inside that agent's own
+workflow, with no human in the loop.
+
+Listed on [OKX.AI](https://okx.ai) as an A2MCP service.
+
+## Why an agent needs this
+
+A language model can describe a mesh. It cannot produce one. That is the whole
+proposition: Ondaru does the part the calling agent genuinely cannot do itself,
+which is what separates a service worth paying for from one that gets tried
+once and abandoned.
+
+## Install
+
+```bash
+pip install ondaru
+ondaru setup-mcp        # register the endpoint with your agent
+ondaru skills install   # teach your agent when to call it
+```
+
+Then ask your agent for a product mockup.
+
+## The three tools
+
+| Tool | What it does | Cost |
+|---|---|---|
+| `plan_product_mockup` | Dimensions, material, polygon budget, and a firm price — in about a second, because it produces a plan, not geometry | entry tier |
+| `order_product_mockup` | Places the order and returns a job id immediately | asset tier |
+| `check_product_mockup` | Polls the job and collects the asset when ready | free |
+
+**No tool waits for generation.** Ordering returns a job id, not a model — you
+poll for the result. That is not a design preference: the marketplace client
+severs any call at 30 seconds, and neither generation nor rendering reliably
+finishes inside that.
+
+Surfaces: mug, hoodie, tshirt, phone case, tote, sticker, figurine, packaging.
+
+## Reading the outcome
+
+A failed job names its cause and carries **no asset**. There is no placeholder
+and no degraded version — if the `asset` field is absent, nothing was produced.
+
+An identical order inside the retention window returns the same job and does
+not charge again, so retrying after a dropped connection is safe.
+
+## Development
+
+```bash
+make up      # Postgres, Redis, and a fake generation backend under OrbStack
+make check   # lint and types
+make test    # integration suite against real infrastructure
+make load    # k6, reporting avg / median / p95 / p99 and throughput
+```
+
+See `CLAUDE.md` for the invariants and the measured facts behind them, and
+`docs/plans/` for the implementation plan.
+
+## Licence
+
+MIT.

ondaru-0.1.0/README.md

@@ -0,0 +1,65 @@
+# Ondaru
+
+**3D product mockups your agent can order.**
+
+Another agent describes a product, logo, or character. Ondaru returns a textured
+`glb` and a turntable render — ordered and paid for inside that agent's own
+workflow, with no human in the loop.
+
+Listed on [OKX.AI](https://okx.ai) as an A2MCP service.
+
+## Why an agent needs this
+
+A language model can describe a mesh. It cannot produce one. That is the whole
+proposition: Ondaru does the part the calling agent genuinely cannot do itself,
+which is what separates a service worth paying for from one that gets tried
+once and abandoned.
+
+## Install
+
+```bash
+pip install ondaru
+ondaru setup-mcp        # register the endpoint with your agent
+ondaru skills install   # teach your agent when to call it
+```
+
+Then ask your agent for a product mockup.
+
+## The three tools
+
+| Tool | What it does | Cost |
+|---|---|---|
+| `plan_product_mockup` | Dimensions, material, polygon budget, and a firm price — in about a second, because it produces a plan, not geometry | entry tier |
+| `order_product_mockup` | Places the order and returns a job id immediately | asset tier |
+| `check_product_mockup` | Polls the job and collects the asset when ready | free |
+
+**No tool waits for generation.** Ordering returns a job id, not a model — you
+poll for the result. That is not a design preference: the marketplace client
+severs any call at 30 seconds, and neither generation nor rendering reliably
+finishes inside that.
+
+Surfaces: mug, hoodie, tshirt, phone case, tote, sticker, figurine, packaging.
+
+## Reading the outcome
+
+A failed job names its cause and carries **no asset**. There is no placeholder
+and no degraded version — if the `asset` field is absent, nothing was produced.
+
+An identical order inside the retention window returns the same job and does
+not charge again, so retrying after a dropped connection is safe.
+
+## Development
+
+```bash
+make up      # Postgres, Redis, and a fake generation backend under OrbStack
+make check   # lint and types
+make test    # integration suite against real infrastructure
+make load    # k6, reporting avg / median / p95 / p99 and throughput
+```
+
+See `CLAUDE.md` for the invariants and the measured facts behind them, and
+`docs/plans/` for the implementation plan.
+
+## Licence
+
+MIT.