Documenting your app

Every marketplace app needs documentation that end users (tenants, not developers) can read to understand what it does and how to use it. The platform gives you a single convention that publishes to two surfaces:

1. docs.linkworld.ai/apps/<slug>/ — public Starlight site, same look-and-feel as this developer doc. Searchable, deep-linkable, SEO.
2. In-app “Help” tab — the right-side chrome panel inside your app’s UI. Same Markdown, rendered alongside the app so users don’t leave context to find help.

You only write the narrative. The platform auto-appends a Reference section (tools, agents, scopes, install settings, emitted events) from your manifest — those stay in sync without effort.

The app_docs/ directory

Drop Markdown files into app_docs/ at the root of your app, next to linkworld.app.yaml:

my-app/
├── linkworld.app.yaml
├── main.py
├── app_docs/
│   ├── user.md              ← required entry point
│   ├── getting-started.md
│   ├── workflows/
│   │   ├── lead-import.md
│   │   └── reply-triage.md
│   └── troubleshooting.md
└── web/
    └── ...

linkworld init ships a starter app_docs/user.md with section headings and prompts. Edit it in place.

Conventions:

• user.md is the entry point. It renders as the app’s /apps/<slug>/ page on the docs site and is the “Help” tab’s landing.
• Other .md files at any depth become subroutes (workflows/lead-import.md → /apps/<slug>/workflows/lead-import/).
• Files are read as UTF-8. Non-text files (PNG, PDF) belong in web/, not app_docs/.
• Markdown frontmatter is honored. Without one, the platform infers title from the first H1 and description from the first paragraph.

Caps

Limit	Value
Total payload	5 MB
Per file	500 KB
File count	200

Above these caps linkworld deploy fails fast with a clear error; the server re-validates on register so you can’t sneak a 50 MB blob through by hand-editing the manifest. If you hit a cap, consolidate topics into longer pages — most apps need <10 pages total.

The auto-generated Reference section

At render time the docs builder appends a Reference section to your user.md page, pulled from the published manifest:

• Required scopes — flat list with the scope ids
• Install settings — table of (key, label, type, required)
• Agents — name + is_default marker
• Tools — name, one-line description, scopes_required
• Emitted events — flat list of event names

You don’t need to mirror any of this in your narrative — it stays truthful to the manifest forever. Mention agents/tools by name in your prose where it helps users (e.g. “the SDR agent will ask…”), but skip duplicating the catalog.

External docs (docs_url)

If you already host your docs elsewhere (Notion, GitBook, your own site), set docs_url: in the manifest:

linkworld.app.yaml

docs_url: https://docs.example.com/my-app/

The Help tab renders a link instead of inline content; the /apps/<slug>/ Starlight page shows a one-line “external docs” notice with the URL. Auto-generated Reference still appears. This is the escape hatch — most apps should ship app_docs/ instead, for the better integration.

Publishing

# Edit app_docs/user.md
$ vim app_docs/user.md

# Deploy as usual — the CLI auto-discovers app_docs/**/*.md
$ linkworld deploy

# Wait ~2 min for the docs site to rebuild (or trigger a Vercel rebuild
# manually if you can't wait — the docs site polls daily otherwise)

docs.linkworld.ai rebuilds the marketplace section on every backend deploy and once a day in the background. The in-app Help tab fetches your docs on every page-load, so it’s always current with the version the tenant has installed.

Worked example

The Pipeline marketplace app’s docs live at examples/pipeline/app_docs/ in the repo and render at docs.linkworld.ai/apps/pipeline/ on this site. Use it as a reference for structure + tone.

Anti-patterns

• Don’t recreate the SDK docs inside your app. Users opening Help want to know what your app does, not how the platform works.
• Don’t paste your README. READMEs target contributors; app_docs/user.md targets end-users (often non-technical tenant admins).
• Don’t hardcode the auto-Reference content into your narrative. You’ll diverge. Let the platform render it from the manifest.
• Don’t ship secrets or test data. The docs are public. A token that lands in app_docs/getting-started.md is leaked the moment you linkworld deploy.