# Publishing Runbook

Organization: `numex-greenfield` Source folder in repo: `docs/gitbook` Frontend docs fallback route: `/docs` Frontend GitBook env var: `NEXT_PUBLIC_DOCS_URL`

## Current State

The GitBook-ready Markdown docs are prepared locally under `docs/gitbook` with:

* `README.md` as the landing page.
* `SUMMARY.md` as the table of contents.
* User-flow pages.
* Technology pages.
* Important links.
* Design asset prompts for polished infographics.

The Numex frontend includes a `Docs` nav item. If `NEXT_PUBLIC_DOCS_URL` is set, the nav opens GitBook. If it is unset, the nav opens the local `/docs` landing page.

## Important CLI Caveat

`@gitbook/cli` is installed locally under the user npm prefix:

```bash
~/.npm-global/bin/gitbook --help
```

The CLI currently describes itself as:

```txt
CLI to build and publish integrations on GitBook.com
```

That means it is useful for GitBook integrations, but it is not the primary way to publish this Markdown documentation space. Use GitBook's UI/Git Sync/import flow for the docs content.

## Recommended GitBook Setup

1. In GitBook, open organization `numex-greenfield`.
2. Create a new space named `Numex Docs` or `Numex Greenfield Docs`.
3. Choose GitHub/Git Sync or import existing Markdown.
4. Select repository `jacksonhblau/numex-greenfield`.
5. Set the content root to:

```txt
docs/gitbook
```

6. Confirm `SUMMARY.md` is used as the table of contents.
7. Publish the space.
8. Copy the published GitBook URL.
9. Add it to local and Vercel env:

```bash
NEXT_PUBLIC_DOCS_URL=https://YOUR_GITBOOK_URL
```

10. Rebuild/deploy the frontend so the `Docs` nav opens GitBook.

## Local Frontend Verification

```bash
npm --workspace apps/web run lint
npm --workspace apps/web run build
```

Expected route:

```txt
/docs
```

## Suggested First GitBook Pages To Polish

* `README.md`
* `user-flows/collector-experience.md`
* `technology/proof-of-integrity.md`
* `technology/smart-contracts.md`
* `technology/base-sepolia-smoke-deployment.md`
* `resources/important-links.md`

## Infographic Workflow

Use `resources/design-asset-brief.md` as the prompt source for Claude Design, Figma, or Higgsfield. Mermaid diagrams should remain the source of truth until polished visuals are produced.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://numex-greenfield.gitbook.io/numex-docs/resources/publishing-runbook.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.