# Agent / vibe-coding rules (public)

Curl this file: https://gia.hub8.ai/vibe-coding/AGENTS.md

Index: https://gia.hub8.ai/llms.txt

## Product docs

### Entities (seed / vibe coding)

| Doc | URL |
|---|---|
| Vibe Coding | https://gia.hub8.ai/docs/apps/vibe-coding |
| Seed Packages | https://gia.hub8.ai/docs/apps/seed-packages |
| Entity Designer Doc (SPA) | https://gia.hub8.ai/docs/apps/entity-designer-doc |
| Agent markdown contract | https://gia.hub8.ai/vibe-coding/entity-designer-doc.md |
| Element / API catalog JSON | https://gia.hub8.ai/vibe-coding/entity-designer-catalog.json |
| Apply success/failure | https://gia.hub8.ai/vibe-coding/apply-contract.md |
| Golden mini seed | https://gia.hub8.ai/vibe-coding/golden-mini.seed.json |

### Workflows (vibe coding)

| Doc | URL |
|---|---|
| Workflow Vibe-Coding Guide | https://gia.hub8.ai/vibe-coding/workflows.md |
| Toolkit Catalog (all methods) | https://gia.hub8.ai/docs/workflows/toolkit-catalog |
| Workflow API Reference | https://gia.hub8.ai/docs/api/workflows |
| Tools API Reference | https://gia.hub8.ai/docs/api/tools |
| End-to-End Walkthrough | https://gia.hub8.ai/docs/workflows/walkthrough |
| Workflow Overview | https://gia.hub8.ai/docs/workflows/overview |
| Swagger | https://gia.hub8.ai/gia/swagger |

## Connect

```bash
export GIA_ENDPOINT=https://gia.hub8.ai/api   # cloud API; NOT https://gia.hub8.ai
# export GIA_ENDPOINT=http://127.0.0.1:4000  # local
export GIA_API_KEY=pk_...                     # Settings → API Support
```

## Flow

### Entities

1. `GET /v1/seeds/health`
2. Discover: `GET /v1/entities/metadata` **and** `GET /v1/entities/metadata/relation-graph` (required)
3. Start from **golden-mini.seed.json** (do not invent a first schema from scratch)
4. Edit display names carefully; keep `sourceLabel` exact
5. `--dry-run` = local package only (not server validation)
6. `POST /v1/seeds/apply` only after the human asked, on a **sandbox/dev** key
7. Verify: `GET /v1/entities/by-name/{displayName}` **and** relation-graph again

### Workflows

1. `GET /v1/seeds/health`
2. Discover: `GET /v1/tools/configs?view=minimal` (tool configs) + `GET /v1/entities/metadata` (entity names)
3. Build BPMN XML following hard rules (see workflow guide)
4. Upload: `POST /v1/workflows/configs` with BPMN file + scripts
5. Start: `POST /v1/workflows/{id}/start`
6. Monitor: `GET /v1/workflows/{id}/instances`
7. Full guide: https://gia.hub8.ai/vibe-coding/workflows.md

## Hard rules

### Entities
- Use **display names** (`Demo Items`), not slugs (`demo_items`), for by-name and `/metadata/{name}`
- Discover `GET /v1/entities/metadata/relation-graph` before inventing links or child grids
- Link fields: `apiDataSource.sourceId` **and** `sourceLabel` = exact entity display name
- Prefer canvas `entityDataSource` with entity **Label**; bind tables/charts/lists via `entityDataSourceName` (no inline `apiDataSource` on consumers)
- Layout: `box`/`card` = static; bound `stack`/`grid`/`imageList` = row repeaters; unbound `stack` = flex toolbar only
- Child Entity rows: child collection docs with `_parentId`, `_parentEntity`, `_parentField`, `_rowOrder` (not nested on parent)
- Table sort/filter/page: server only; never client-side DataTable query
- Records upsert via `matchFields`; no wipe API
- Do not invent platform runtime patches; seeds + HTTP only
- Full Entity Designer contract: https://gia.hub8.ai/vibe-coding/entity-designer-doc.md (61 palette types in catalog JSON)

### Workflows
- Service Task `moduleName` must match an existing Tool Config name — discover via `GET /v1/tools/configs?view=minimal`
- Use `${variable}` for parameter binding in BPMN — not string interpolation
- XML-escape all special characters in BPMN XML (`"` → `&quot;`, `<` → `&lt;`)
- Script Tasks access workflow variables directly — no HTTP to `/v1/`, no `requests` lib
- The worker remints auth — do not put API keys or `pk_` tokens in BPMN or scripts
- Entity names in Spaces toolkit calls are **display names** (`Leave Requests`, not `leave_requests`)
- Full toolkit method reference: https://gia.hub8.ai/docs/workflows/toolkit-catalog

### General
- Hub8 contributors with the private `onespace-dev-community` repo: also follow that repo's `AGENTS.md`