> ## Documentation Index
> Fetch the complete documentation index at: https://docs.legnext.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AGENTS

# CLAUDE.md — Legnext API Docs

Guidance for working in this repository.

## What this is

The **public API documentation** for Legnext (the Midjourney API platform).

* **Tooling**: [Mintlify](https://mintlify.com) — config in `docs.json` (theme `mint`), content in `.mdx`.
* **Published to**: `https://docs.legnext.ai`
* **Repo**: `github.com/legnext-ai/docs` (origin/main). Mintlify auto-deploys on push to `main`.
* ⚠️ This is the **only** live docs repo. `github.com/leggiemint/docs` (local `~/projects/API/docs`) is a stale abandoned clone — do not edit it.

## Structure

* `getting-started/` — overview, quickstart, models, image-parameters, video-parameters, output-storage, notice
* `api-reference/` — one `.mdx` per endpoint (image-generation, video-generation, enhancement, task-management, account-management)
* `sdk/` — per-language guides (csharp, go, java, javascript, php, python, ruby, rust)
* `integrations/` — make, n8n, postman
* `changelog.mdx`, `docs.json` (navigation — nav is explicit; a file not listed here is not linked)

## Preview & deploy

```bash theme={null}
mintlify dev        # local preview (or: npx mint dev) — do NOT auto-start; ask Kai or read an already-running port
```

Deploy = push to `main` (Mintlify picks it up). Per global rules: don't auto-push; prefer a new commit over amend.

## Sources of truth (do not guess — verify)

1. **Parameter / version / model behavior** → the backend: `~/projects/API/Legnext-backend/internal/task/mj_task/` (e.g. `version.go` for which flags each MJ version accepts) and the provider code under `internal/standalone_server/mj/provider/`.
2. **Midjourney's own semantics** → local scrape of MJ official docs in `docs/midjourney-prompt/` (prompt-related articles, markdown + `urls.txt` manifest for re-scraping; reference only, never publish as-is). The old mirror at `~/projects/saas/midjourney/midjourney-official-docs/` no longer exists.

When backend and our docs disagree, the **backend wins** (it's what actually runs). When our docs and MJ official docs disagree on MJ semantics, **MJ official wins**.

## Known gotchas / lessons

* **API Reference fields are generated from `openapi.yaml`.** Endpoint MDX files
  should contain only frontmatter plus intent, prerequisites, relationships, and
  common mistakes. Do not re-add hand-written headers, request/response tables,
  full JSON examples, or error-code lists: Mintlify already renders them from
  OpenAPI, and the duplicate layer previously drifted on Get Task auth, required
  fields, enums, and task IDs.

* **The Topaz-backed Enhancement API is suspended.** Keep
  `/v1/enhance-upscale` in OpenAPI with its `503` maintenance response for
  existing callers, but do not add it back to public navigation or describe it
  as available. Midjourney `/v1/upscale` and `/v1/enhance` are different
  follow-up actions.

* **The image-parameters table is GENERATED.** In `getting-started/image-parameters.mdx`, everything between the `{/* BEGIN GENERATED:image-parameters-table */}` and `{/* END ... */}` markers comes from `spec/mj-image-params.yaml` in `legnext-ai/Legnext-backend` — a backend CI job opens a sync PR here when the spec changes (KEH-286). Never hand-edit inside the markers (keep them intact); fix the YAML upstream instead. `schemas/mj-image-params.v1.json` is synced the same way and served at [https://docs.legnext.ai/schemas/mj-image-params.v1.json](https://docs.legnext.ai/schemas/mj-image-params.v1.json) — the public contract, additive-only within v1. Do not re-add hand-written parameter lists anywhere (incl. `openapi.yaml`); link to the schema URL.

* **`--cref` is NOT a v7+ parameter.** It only works on v6 / v6.1 / niji 6. v7 replaced it with Omni Reference (`--oref` / `--ow`); v8.1 drops omni too. Our docs historically mislabeled this (v7 marked ✓ for `--cref`), which caused a real support ticket — keep the version-support matrix accurate against the backend + MJ official docs.

* The **default model version is v7** (no `--v` → runs as v7). A param valid only on v6.x will fail upstream with an opaque `Invalid prompt format` unless the user pins `--v 6.1`.

* Keep `--oref` naming consistent (MJ calls it **Omni Reference**); avoid the old "Object Reference" / inconsistent "Universal Reference" labels.

* **`mint dev` can wedge on on-demand compiles (2026-08-10 incident).** First hit on a new/changed page triggers a compile; repeated or parallel requests against it queue up and snowball until the node process pins at \~100% CPU and the whole server stops responding (all pages, not just the new one). Discipline:
  1. One request at a time against the dev server, with a generous `--max-time` — never re-fire or parallelize curls when one is hanging; each extra request makes the wedge worse.
  2. A hang → check before retrying: `lsof -nP -iTCP:3000 -sTCP:LISTEN` + `ps` for CPU. \~100% CPU = wedged → `Ctrl+C` and restart `npx mint dev`; do not keep poking a wedged server.
  3. To rule out content errors without the dev server, run `npx mint validate` (static full-build validation). Only suspect MDX syntax if validate fails.
  4. After restart, re-verify with a single curl per page (`curl -s -o /dev/null -w "%{http_code}"`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.