docs: complete DX1 resources, glossary, and shared FAQ

.changelog/unreleased/609-dx1-docs-resources.md

@@ -0,0 +1,8 @@
+---
+type: added
+area: docs
+pr: 615
+breaking: false
+---
+
+Added the first SO4 documentation resource set, a shared landing-page FAQ source, and an alphabetical perpetuals and Stellar glossary.

.github/workflows/ci.yml

@@ -34,7 +34,7 @@ jobs:
             ${{ runner.os }}-bun-
 
       - name: Install dependencies
-        run: bun install 
+        run: bun install
 
       - name: Lint
         run: bun lint
@@ -45,6 +45,12 @@ jobs:
       - name: Design token check
         run: bun run check:tokens
 
+      - name: Documentation content check
+        run: bun run check:content
+
+      - name: Documentation link and FAQ drift checks
+        run: bun run check:links && bun run --cwd apps/docs check:faq
+
       - name: Test
         run: bun run test
 

apps/docs/content/concepts/funding-and-fees.mdx

@@ -0,0 +1,12 @@
+---
+title: Funding and fees
+description: How funding, transaction charges, borrowing costs, and price impact affect a perpetual position.
+updated: 2026-08-24
+status: stable
+---
+
+Trading cost is more than a displayed fee because time, market balance, execution, and the Stellar transaction can each affect the result.
+
+<Term id="funding">Funding</Term> transfers value between long and short positions. <Term id="price-impact">Price impact</Term> changes the execution estimate as a trade changes market exposure. <Term id="open-interest">Open interest</Term> describes positions that remain active.
+
+Always review the transaction simulation and wallet prompt before signing. See [risk](/concepts/risk) for failure modes.

apps/docs/content/concepts/liquidation.mdx

@@ -0,0 +1,12 @@
+---
+title: Liquidation
+description: How maintenance margin and changing position value determine whether a leveraged position may be liquidated.
+updated: 2026-08-24
+status: stable
+---
+
+Liquidation is the protocol process that closes an under-collateralised position before its losses exceed the collateral available to support it.
+
+The displayed <Term id="liquidation-price">liquidation price</Term> is an estimate. A position becomes eligible when it breaches <Term id="maintenance-margin">maintenance margin</Term>; fees, funding, price impact, and fast markets can move the actual result.
+
+Read the broader [risk overview](/concepts/risk) before opening a leveraged position.

apps/docs/content/concepts/risk.mdx

@@ -0,0 +1,12 @@
+---
+title: Risk
+description: A concise overview of market, liquidation, oracle, contract, network, interface, and custody risks in SO4.
+updated: 2026-08-24
+status: stable
+---
+
+Using SO4 can result in partial or total loss of collateral, including through mechanisms outside the interface's control.
+
+A leveraged position can cross its <Term id="maintenance-margin">maintenance margin</Term> as prices move and be closed near its <Term id="liquidation-price">liquidation price</Term>. Other risks include volatile prices, adverse price impact, funding, unavailable liquidity, stale or incorrect oracle data, smart-contract defects, Stellar or RPC disruption, wallet compromise, and interface outages.
+
+The interface prepares transactions; your wallet authorises them and the protocol executes them. Review the [terms and plain-language disclosure](/resources/terms) before using the interface.

apps/docs/content/meta.json

@@ -0,0 +1,22 @@
+{
+  "sections": [
+    {
+      "label": "Concepts",
+      "pages": [
+        "concepts/risk",
+        "concepts/funding-and-fees",
+        "concepts/liquidation"
+      ]
+    },
+    { "label": "Reference", "pages": ["reference/glossary"] },
+    {
+      "label": "Resources",
+      "pages": [
+        "resources/terms",
+        "resources/faq",
+        "resources/roadmap",
+        "resources/changelog"
+      ]
+    }
+  ]
+}

apps/docs/content/reference/glossary.mdx

@@ -0,0 +1,48 @@
+---
+title: Glossary
+description: Alphabetical definitions linking perpetual-markets and Stellar or Soroban terms to their detailed documentation.
+updated: 2026-08-24
+status: stable
+---
+
+Definitions here are short pointers. Follow each link for mechanics and context.
+
+## Authorisation entry {#authorisation-entry}
+
+A Soroban authorisation entry identifies an invocation a wallet or contract has permitted within a transaction. [Read about transaction risk](/concepts/risk).
+
+## Footprint {#footprint}
+
+A Soroban footprint declares the ledger entries a smart-contract transaction expects to read or write. [Read about transaction risk](/concepts/risk).
+
+## Funding {#funding}
+
+Funding is a recurring transfer between long and short positions intended to keep a perpetual market near its reference price. [Read about funding and fees](/concepts/funding-and-fees).
+
+## Ledger {#ledger}
+
+A ledger is a confirmed Stellar network state produced by consensus at a particular sequence number. [Read about protocol risk](/concepts/risk).
+
+## Liquidation price {#liquidation-price}
+
+Liquidation price is the estimated market price at which a position no longer satisfies its maintenance-margin requirement. [Read about liquidation](/concepts/liquidation).
+
+## Maintenance margin {#maintenance-margin}
+
+Maintenance margin is the minimum collateral value a leveraged position must retain to avoid liquidation. [Read about liquidation](/concepts/liquidation).
+
+## Open interest {#open-interest}
+
+Open interest is the total notional value of positions that remain open in a market. [Read about funding and fees](/concepts/funding-and-fees).
+
+## Price impact {#price-impact}
+
+Price impact is the execution-price change caused by a trade changing the market's balance of liquidity and exposure. [Read about funding and fees](/concepts/funding-and-fees).
+
+## SAC {#sac}
+
+A Stellar Asset Contract is the Soroban token interface through which a classic Stellar asset can be used by smart contracts. [Read about protocol risk](/concepts/risk).
+
+## Trustline {#trustline}
+
+A trustline is a Stellar ledger entry through which an account opts into holding a specific issued asset and records its balance and limits. [Read about protocol risk](/concepts/risk).

apps/docs/content/resources/changelog.mdx

@@ -0,0 +1,14 @@
+---
+title: Changelog
+description: How documentation updates relate to the product release history published on the SO4 interface.
+updated: 2026-08-24
+status: stable
+---
+
+The canonical SO4 product release history lives at [so4.market/changelog](https://so4.market/changelog).
+
+This documentation page explains releases and links readers to that history; it does not maintain a second copy. Product and protocol changes are announced on the interface changelog. Documentation-only corrections may be visible in repository history without becoming a product release.
+
+## Documentation site release
+
+**Shipped — 24 August 2026.** SO4 published its first documentation resource set, including the terms draft, shared FAQ, glossary, roadmap, and this changelog pointer.

apps/docs/content/resources/faq.mdx

@@ -0,0 +1,37 @@
+---
+title: Frequently asked questions
+description: Short answers to common SO4 trading, custody, fees, liquidation, wallet, and availability questions.
+updated: 2026-08-24
+status: stable
+landing: [what-is-so4, self-custody, liquidation, fees, availability]
+---
+
+These answers point to the detailed documentation that should guide a decision or troubleshooting step.
+
+## What is SO4? {#what-is-so4}
+
+SO4 is a perpetual-markets protocol on Stellar with a web interface for preparing and submitting transactions. [Read the protocol risk overview](/concepts/risk).
+
+## Do I keep custody of my assets? {#self-custody}
+
+The interface does not hold wallet keys; your wallet signs transactions and protocol contracts account for deposited collateral. [Read the interface and protocol distinction](/resources/terms#interface-and-protocol).
+
+## What can cause liquidation? {#liquidation}
+
+A position becomes liquidatable when its remaining collateral no longer meets the protocol's maintenance-margin requirement. [Read the liquidation mechanics](/concepts/liquidation).
+
+## What fees will I pay? {#fees}
+
+Costs can include opening, closing, funding, borrowing, network, and price-impact amounts, depending on the transaction. [Read about funding and fees](/concepts/funding-and-fees).
+
+## Is the interface always available? {#availability}
+
+No; deployments, incidents, RPC failures, congestion, and local connectivity can interrupt the website even while the protocol remains deployed. [Read the risk overview](/concepts/risk).
+
+## Is this financial advice? {#financial-advice}
+
+No; the interface and documentation provide operational information, not a recommendation to trade. [Read the terms](/resources/terms#no-financial-advice).
+
+## Why did my transaction fail? {#failed-transaction}
+
+A transaction can fail because of simulation errors, insufficient balance, stale state, authorization, slippage, or network conditions. [Review protocol risks](/concepts/risk).

apps/docs/content/resources/roadmap.mdx

@@ -0,0 +1,24 @@
+---
+title: Roadmap
+description: The current status of shipped and planned SO4 interface, protocol, and documentation work.
+updated: 2026-08-24
+status: stable
+---
+
+The roadmap separates work that has shipped from plans that remain subject to design, testing, and maintainer approval.
+
+## Shipped
+
+- **Shipped — 24 August 2026:** The first documentation site and its resource pages. Release details appear in the [changelog](/resources/changelog).
+- **Shipped — 24 August 2026:** A shared FAQ source for documentation and the landing interface. Release details appear in the [changelog](/resources/changelog).
+
+## In progress
+
+- **In progress — undated:** Complete and review the remaining concept, guide, developer, and generated-reference pages defined by the DX1 content map.
+- **In progress — undated:** Obtain legal review for the eligibility and jurisdiction language in the [terms draft](/resources/terms).
+
+## Planned
+
+- **Planned — undated:** Publish verified audit and responsible-disclosure information after maintainers confirm the reporting channel and current audit status.
+
+Dates are commitments only when an item explicitly says so. Undated work is intentionally not presented as a delivery promise.

apps/docs/content/resources/terms.mdx

@@ -0,0 +1,44 @@
+---
+title: Terms of use
+description: Draft terms governing access to the SO4 web interface and a plain-language disclosure of trading risks.
+updated: 2026-08-24
+status: draft
+---
+
+> **Pending legal review.** This draft is provided for maintainer and counsel review. It is not final legal language and must not be represented as legally approved.
+
+These terms explain access to the SO4 web interface. They do not change how the independent SO4 protocol operates on Stellar.
+
+## Interface and protocol
+
+The **interface** is the website maintained by SO4 Labs that helps a user prepare and submit transactions. The **protocol** is a set of independently deployed smart contracts on Stellar. The interface does not take custody of assets, execute protocol transactions itself, or control transactions after they are submitted. The protocol may remain accessible through other software even if this interface is unavailable.
+
+## Risk disclosure
+
+Perpetual trading can cause rapid and total loss of posted collateral. Leverage, liquidation, oracle failure, smart-contract defects, network congestion, volatile markets, and unavailable interfaces can increase that risk. Transactions are generally irreversible, and displayed estimates may differ from execution results. Read [How risk works](/concepts/risk) before using the interface.
+
+## No financial advice
+
+Information shown by the interface and documentation is educational and operational only. It is not financial, investment, legal, tax, or accounting advice, and no content is a recommendation to enter a transaction. Users are responsible for deciding whether a transaction is appropriate for them and for obtaining professional advice where needed.
+
+## Eligibility and jurisdiction
+
+> **Pending legal sign-off.** Maintainers must confirm restricted jurisdictions, minimum age, sanctions screening, and any professional- or qualified-user requirements before this section is approved.
+
+You may use the interface only where doing so is lawful, if you have legal capacity to accept these terms, and if you are not subject to applicable sanctions or other restrictions. You are responsible for complying with the laws that apply to you. Access from a particular location does not mean that SO4 Labs offers or solicits a regulated service there.
+
+## Acceptable use
+
+Do not use the interface to violate law, evade sanctions, interfere with other users, introduce malicious code, or misrepresent your identity or authority. Access may be limited when reasonably necessary to protect the interface, comply with law, or respond to security incidents. Such limits do not pause or alter the protocol.
+
+## Availability and warranties
+
+The interface is provided on an “as available” basis. To the extent permitted by law, no promise is made that it will be uninterrupted, accurate, secure, or fit for a particular purpose. Nothing here excludes a right or liability that applicable law does not permit parties to exclude.
+
+## Changes
+
+**Effective date: 24 August 2026.** Material changes will be announced in the [SO4 changelog](/resources/changelog) before or when they take effect. The effective date above will be updated. Continued use after a change takes effect constitutes acceptance only to the extent permitted by applicable law.
+
+## Contact
+
+Questions about this draft should be raised through the project’s [GitHub repository](https://github.com/SO4-Markets/interface). Security reports should follow the project security policy rather than a public issue.

apps/docs/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "docs",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "bun run scripts/build.ts",
+    "dev": "bun run scripts/build.ts",
+    "lint": "bun run check:content",
+    "format": "prettier --write \"content/**/*.mdx\" \"scripts/**/*.ts\"",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "check:content": "bun run scripts/check-content.ts",
+    "check:links": "bun run scripts/check-links.ts",
+    "generate:faq": "bun run scripts/generate-faq.ts",
+    "check:faq": "bun run scripts/generate-faq.ts --check"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.0",
+    "prettier": "^3.8.1",
+    "typescript": "^5.9.3"
+  }
+}

apps/docs/scripts/build.ts

@@ -0,0 +1,65 @@
+import { mkdir } from "node:fs/promises"
+import { join } from "node:path"
+
+import { $ } from "bun"
+import { appRoot, loadPages } from "./content"
+
+await $`bun run ${join(appRoot, "scripts/check-content.ts")}`
+await $`bun run ${join(appRoot, "scripts/check-links.ts")}`
+await $`bun run ${join(appRoot, "scripts/generate-faq.ts")} --check`
+
+const pages = await loadPages()
+const outputRoot = join(appRoot, ".output/public")
+
+function escape(value: string) {
+  return value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+}
+
+function renderInline(value: string) {
+  return value
+    .replace(
+      /<Term id="([a-z0-9-]+)">([^<]+)<\/Term>/g,
+      '<a href="/reference/glossary#$1">$2</a>',
+    )
+    .replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>')
+    .replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>")
+    .replace(/`([^`]+)`/g, "<code>$1</code>")
+}
+
+function render(body: string) {
+  const blocks = body.split(/\n\n+/)
+  return blocks
+    .map((block) => {
+      const heading = block.match(/^## (.+?)(?: \{#([a-z0-9-]+)\})?$/)
+      if (heading) {
+        const id =
+          heading[2] ??
+          heading[1]
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, "-")
+            .replace(/(^-|-$)/g, "")
+        return `<h2 id="${id}">${escape(heading[1])}</h2>`
+      }
+      if (block.startsWith("> "))
+        return `<aside>${renderInline(block.replace(/^> ?/gm, ""))}</aside>`
+      if (block.startsWith("- "))
+        return `<ul>${block
+          .split("\n")
+          .map((line) => `<li>${renderInline(line.slice(2))}</li>`)
+          .join("")}</ul>`
+      return `<p>${renderInline(block)}</p>`
+    })
+    .join("\n")
+}
+
+for (const page of pages) {
+  const directory = join(outputRoot, page.route.slice(1))
+  await mkdir(directory, { recursive: true })
+  const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>${escape(page.frontmatter.title)} · SO4 docs</title><meta name="description" content="${escape(page.frontmatter.description)}"><style>:root{font:16px/1.65 system-ui;color:#17191d;background:#fff}body{margin:0}header,main{max-width:760px;margin:auto;padding:24px}header{display:flex;justify-content:space-between;border-bottom:1px solid #ddd}a{color:#3156c8}h1{font-size:2.4rem;line-height:1.1}h2{margin-top:2.5rem}aside{border-left:4px solid #d99b16;background:#fff8df;padding:16px}code{background:#eee;padding:2px 5px}@media print{header{display:none}main{max-width:none;padding:0}a{color:inherit;text-decoration:none}aside{break-inside:avoid;background:none;border:1px solid #777}h2{break-after:avoid}}</style></head><body><header><a href="/">SO4 docs</a><a href="https://so4.market">Open interface</a></header><main><h1>${escape(page.frontmatter.title)}</h1>${render(page.body)}</main></body></html>`
+  await Bun.write(join(directory, "index.html"), html)
+}
+
+console.log(`Built ${pages.length} static documentation routes.`)