Maintain this documentation

This site has its own repository and serves pages from /. It can be developed and deployed independently of the trading application. The public application is masayume.app; the docs domain is configured separately.

Start the site

Use Node.js 22 or newer, install with the repository's pinned pnpm version, then run:

pnpm install --frozen-lockfile
cp .env.example .env.local
pnpm dev

Open http://localhost:3333. Set NEXT_PUBLIC_DOCS_URL to that origin locally and NEXT_PUBLIC_APP_URL to https://masayume.app. These are public origins, not credentials. The documentation server needs no wallet key, database or model provider.

Add a useful guide

Start with what the reader wants to achieve. Explain what they need, the exact controls they use, what success looks like and what to do if the result is unfinished. Keep the first explanation simple; put contract details below it or link to the architecture page.

Create the page under content/docs/<section>/<slug>.mdx:

---
title: Make your first call
description: Choose a Window, review the price and follow the result.
sources:
  - web/src/app/markets/page.tsx
---

Open <AppLink href="/markets">Markets</AppLink> and choose a Window.

Read [how the ticket works](/architecture/event-contracts).

Add the slug to that section's meta.json. The file's location determines the documentation URL. index.mdx is the section's root page.

Use ordinary Markdown links between docs pages. Use AppLink for application destinations, so a deployment can set the app origin once. Source paths are relative to the Masayume application repository; they are not paths in this documentation repository.

Read each cited source and the surrounding call path. A file existing is useful evidence for a link check, but does not prove a description is accurate. Screens that are empty, unavailable, behind a wallet connection or developer fixtures need to be described in their actual state.

Add an annotated capture

1. Open the real screen on https://masayume.app and reach the state the guide explains.
2. Capture the viewport without account-identifying details or private recovery material. A connected session does not authorize a trade or public post.
3. Keep the original file bytes: use public/guides/<name>.png for a PNG or public/guides/<name>.jpg for a JPEG.
4. Add its entry to lib/guides.ts: title, alt text, app path, honest state, dimensions and arrow coordinates. Add extension: 'jpg' for JPEG captures; PNG is the default.
5. Place the component where the screenshot helps the next step:

<GuideShot name="markets" caption="Read the selected Window before reviewing your call." />

The component adds numbered arrows and Masayume branding in a separate layer. Keep the underlying capture intact. The shared guideImagePath(name) helper uses the recorded extension for screenshots, original-image links and video posters. Correct a mislabeled extension by renaming the file and updating its registry entry; do not convert or regenerate its pixels. The content checker verifies PNG/JPEG signatures as well as file existence.

Check that each arrow lands on the intended control at the actual capture dimensions. Open and close the expanded view with both pointer and keyboard. Review the caption's capture date and state when replacing an image; old commentary should not silently describe a new capture.

Add a walkthrough

Record the real interaction. A preview of a ticket should be labelled as a preview. An explanation of a trade should only call it completed when the recording actually shows the receipt or confirmed fill.

Store the video at public/videos/<name>.mp4 and synchronized captions at public/videos/<name>.vtt. Add the title, description, poster and chapters to the movies manifest in components/walkthrough.tsx, then reference it:

<Walkthrough name="practice" />

Write the chapter text as a useful transcript for someone who cannot play the video. Check that each chapter time matches the recording, its button seeks to the correct moment, captions appear and the poster exists. Keep temporary captures and browser logs outside public assets.

The three included public-app videos can be rebuilt with node scripts/render-walkthroughs.mjs practice candle-hop ticket when their original timestamped JPEG recordings are available under evidence/raw-video. That directory is ignored by Git. The script needs local ffmpeg and ffprobe, uses Next's installed Sharp image runtime for separate annotation layers, and retains the original frame files unchanged. Exported MP4s, captions and capture provenance stay in public/videos.

Update an architecture map

Edit the named map in lib/diagrams.json. Give each box a plain-English role, a clear authority statement and the source paths that support it. Connect only relationships that exist in the code. An API storing a game record and a contract paying a winner are different responsibilities and should remain distinguishable.

Generate the branded downloads after editing:

node scripts/export-diagrams.mjs

Architecture renders the interactive map and links to public/diagrams/<name>.svg. Set exportPng: true on a map when a raster image is also needed, as in the DreamDEX integration map. The same export command generates both formats. Set a map's reviewed date only after checking its sources; existing maps retain their own dates.

Check box selection, small-screen scrolling, the text equivalent and the exported image. The checker can detect a missing box or file; it cannot decide whether an arrow tells the truth.

Keep coverage current

evidence/source-coverage.json records the reviewed application commit, the design-reference commit, every app page and every API method. Each app route points to a guide or has an explicit developer-only, redirect, unavailable or removed status. Developer-only describes a fixture's intended use; it is not an authentication claim.

When application behavior changes:

1. Read the change against the recorded commit.
2. Update the affected user steps, architecture and builder reference.
3. Add or revise the route/API coverage entries.
4. Refresh media when a control or state no longer matches.
5. Advance the source revision in the evidence record and lib/site.ts after reviewing the content.

The STRK20 site is a design reference. Its behavior is never a substitute for reading Masayume's own source. A source commit also does not prove which build is live at the public app domain.

Run the checks

The source checker expects the app in sibling directory ../sommina-events. Supply a different location if needed:

node scripts/check-content.mjs --source /path/to/masayume
pnpm typecheck
pnpm build

It checks documentation links, ordinary heading fragments, navigation, application links, source paths at the pinned commit, route coverage, API methods and media files. Dynamic links and generated headings still need a browser check.

During capture work, --allow-missing-media keeps missing media visible as warnings. Run the strict checker before release. Neither mode changes content or removes an unfinished reference.

Finish by opening the affected pages at desktop and phone sizes in light and dark mode. Test search, screenshot expansion, diagrams and any video controls. Builds and source checks complement that browser review; they do not replace it.

Publish independently

Connect this repository to a Next.js-capable host. Build from the repository root with pnpm build. Set NEXT_PUBLIC_DOCS_URL to the chosen docs origin and NEXT_PUBLIC_APP_URL to the public app origin before building.

After the docs domain is ready, set the application's own docs-origin variable to that domain and rebuild the app's outgoing links and old-bookmark redirects. Verify both directions on the deployed sites. The independent docs repository is Blockchain-Oracle/masayume-docs; access is private. The public deployment at docs.masayume.app was verified on 7 September 2026.

Keep AI-readable exports useful

The site serves llms.txt as a short index and llms-full.txt as the complete guide export. Each page also has a /raw/<guide-path> Markdown endpoint, used by Copy Markdown. For example, the DreamDEX SDK guide contains the feature-to-code map without requiring a browser to render the page.

These exports are generated from the same guide collection as the site. The index starts with the SDK integration and architecture guides; individual and full exports include the canonical page URL, review date and the same pinned source notes shown in the browser. An application link inside an AppLink component uses the application origin; ordinary relative documentation links use the docs origin. GitHub source links still need repository access.

After a content change, verify that the new guide appears in the index and full export, that its source URLs name the reviewed commit, and that its Markdown endpoint responds as text/plain. The filenames are lowercase llms.txt and llms-full.txt.