# Kotobase: Free start

> One continuous Free loop: signup → biscuit → write → query → pin.
> Operator: Kotoba Labs Inc. No founder step.

A stranger finishes this on Free hosted secure storage in one session. Health
and MCP discovery grant no data access. Do not treat discovery as write, query,
or pin.

## 1. Signup

Open https://kotobase.net/signup and create a session with an approved wallet
signature (SIWE) or Passkey, as that page documents. The identity hop is
https://auth.kotoba.cloud (the live signup default).

Passkey rpIds stay separate and do not transfer: `auth.kotobase.net`
(rpId=auth.kotobase.net, rpName=Kotobase) and `auth.kotoba.cloud`
(rpId=auth.kotoba.cloud, rpName=Kotoba Cloud). A Passkey registered on one host
does not sign in on the other.

Optional CLI (needed for the `kotobase q` step). Requirements: Babashka (`bb`),
curl, a POSIX shell. Inspect the installer before running it.

```sh
curl -fsS https://kotobase.net/health
curl -fsS https://kotobase.net/install.sh -o /tmp/kotobase-install.sh
sh /tmp/kotobase-install.sh
export PATH="$HOME/.local/bin:$PATH"
kotobase help
kotobase health
```

`GET https://kotobase.net/health` must return HTTP 200 with `ok: true`.

## 2. Biscuit mint

After signup, mint a short-lived Biscuit for one tenant, one graph, and the
permissions you need. Public developers docs
(https://kotobase.net/developers) give this exact request:

```sh
curl -sS -X POST https://auth.kotobase.net/v1/biscuit/token \
  -H 'content-type: application/json' \
  -d '{"tenantId":"...","graph":"...","permissions":["data:write"]}'
```

Use the complete returned `Biscuit <token>` authorization value as
`KOTOBASE_TOKEN`. Do not put credentials into prompts, public config, logs, or
source control.

```sh
export KOTOBASE_TOKEN="Biscuit ..."
kotobase account-status
```

`auth.kotoba.cloud` is the signup session host. `POST
https://auth.kotobase.net/v1/biscuit/token` is the documented mint. Request only
your tenant, graph, and necessary permissions. HTTP 401 means authenticate;
HTTP 403 means check graph or permission scope. Do not retry with a broader
identity automatically.

## 3. One write

Smallest documented Free-tenant graph write on the public allowlist
(`https://kotobase.net/llms-full.txt`, also named in
https://github.com/kotoba-lang/kotobase-docs/blob/main/USING-AS-A-PIN-SERVICE.md):
`POST /xrpc/ai.gftd.apps.kotobase.kg.ingest`. Required field is `id`.

```sh
curl -s -X POST https://kotobase.net/xrpc/ai.gftd.apps.kotobase.kg.ingest \
  -H "authorization: $KOTOBASE_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"id":"hello","label_en":"hello"}'
```

Send the minted `Biscuit <token>` value. CACAO and opaque Bearer remain
migration-only compatibility paths. A rejected Biscuit is never retried as
CACAO or Bearer.

## 4. One query

CLI `q` uses a named-database compatibility path. Replace YOUR_DATABASE with
your own database.

```sh
kotobase q YOUR_DATABASE '{:find [?e] :where [[?e :bench/value "authenticated"]]}'
```

This read-only example returns entities with that attribute, or an empty result
if none exist. New Datomic Client API integrations use
https://datomic.kotobase.net/api/ and an explicit signed commit CID as
documented at https://kotobase.net/llms-full.txt.

## 5. One pinCreate

Exact public XRPC path from https://kotobase.net/llms-full.txt and
https://github.com/kotoba-lang/kotobase-docs/blob/main/USING-AS-A-PIN-SERVICE.md.
In this loop, send the same minted authorization value.

```sh
curl -s -X POST https://kotobase.net/xrpc/ai.gftd.apps.kotobase.pinCreate \
  -H "authorization: $KOTOBASE_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"name":"my-doc","cid":"bafyrei..."}'
```

Replace `bafyrei...` with a CID you hold (the ingest response may include
`subjectCid`). The published llms-full example still shows
`authorization: Bearer $JWT` as a compatibility header; new clients use the
Biscuit from step 2. Body shape is `{name, cid?|quads?, size_hint_bytes?}`.

## After auth: MCP discovery

Discovery alone is not write, query, or pin.

```sh
curl -fsS https://kotobase.net/.well-known/mcp
kotobase mcp
```

The descriptor names `https://kotobase.net/mcp` and `streamable-http`.
Advertised MCP schemes stay CACAO, Bearer, session-cookie — not Passkey, not
x402. Keep any generated Authorization header private.

## Evidence and the rest of the stack

- Measured production latency and limits: https://kotobase.net/benchmarks
- Raw receipt: https://kotobase.net/benchmarks/2026-09-08.json
- Pricing and included limits: https://kotobase.net/pricing
- Kotoba language / CLI / first executable program: https://kotoba-lang.org/agent-quickstart.md
- Kotoba Cloud discovery and signed packages: https://kotoba.cloud/agent-quickstart.md
- Full API reference: https://kotobase.net/llms-full.txt
- Developers (biscuit mint): https://kotobase.net/developers

A successful health check or MCP configuration is not evidence of a successful
write, query, or pin. Verify each response against the data in your graph.