WIP docs: reorganize Gina onboarding around product journeys

ai_docs/docs-host-verification.md

@@ -0,0 +1,41 @@
+# Gina documentation: host setup verification
+
+Checked 2026-09-06 against primary host documentation and repository source. These are documentation-supported configuration routes, not completed authenticated Gina end-to-end tests. Marketplace publication and custom MCP support are separate claims.
+
+## Canonical Gina inputs
+
+- Read-only URL: `https://askgina.ai/ai/gina/mcp`, scope `tools:read`. The current package provides four research/account skills. [Plugin manifest](../plugins/ask-gina/plugin.yaml), [skills](../plugins/ask-gina/skills).
+- Write access uses separate Spot, Predictions, and Perps connections. A read-only skill installation does not grant execution. [Access overview](../docs/mcp-access/index.mdx).
+- Human token fallback: sign in at `https://askgina.ai/agent-setup`, name the token, explicitly select **Read-only — view data**, generate, and copy once. Current chatbot UI defaults to full access. Tokens last 90 days and can be revoked. Source: private chatbot repository, commit `7b7b2bf16`, `components/agent-setup-catalogue.tsx` (config at line 52, default at 121, instructions at 298).
+
+## Verified host routes
+
+| Host               | Direct connection route supported by official docs                                                                                                                                                                                                        | Gina-specific confidence                                                                                                                                                    |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ChatGPT            | Settings → Security and login → Developer mode. Open Plugins, use plus, enter name/description and public MCP URL under Connection; create, review tools, then enable the connection in a conversation. Availability depends on account/workspace policy. | Gina OAuth/ChatGPT handling exists in backend; no public Gina marketplace listing verified. This is a custom developer-mode connection, not evidence of a published plugin. |
+| Claude web/Desktop | Customize → Connectors → plus → Add custom connector; enter URL, add, connect/authenticate, enable in chat. Team/Enterprise owners must provision first.                                                                                                  | Gina supports Claude OAuth. Do not conflate remote connectors with local Desktop config or Claude Code plugins.                                                             |
+| Claude Code        | `claude mcp add --transport http ask-gina https://askgina.ai/ai/gina/mcp`, then `/mcp` and browser authentication.                                                                                                                                        | URL and OAuth adapter match repository. Not live-tested in this pass.                                                                                                       |
+| Codex              | Add `[mcp_servers.ask-gina]` with `url = "https://askgina.ai/ai/gina/mcp"` in Codex config; run `codex mcp login ask-gina`. CLI alternative: `codex mcp add ask-gina --url https://askgina.ai/ai/gina/mcp`.                                               | Native Streamable HTTP and OAuth are documented; repository has Codex plugin metadata. No marketplace publication inferred.                                                 |
+| Cursor             | Add URL-only `ask-gina` under `mcpServers` in `.cursor/mcp.json` or `~/.cursor/mcp.json`; connect/authenticate when requested.                                                                                                                            | Repository `mcp.json` is URL-only and expressly targets Cursor/Grok Bot.                                                                                                    |
+| Perplexity         | Account settings → Connectors → + Custom connector → Remote; enter name/HTTPS URL, select OAuth, add, then open connector card to authenticate/enable.                                                                                                    | Gina has Perplexity CORS/origin handling. Host setup verified from newer documentation; no live Gina connection tested.                                                     |
+| Grok web           | `grok.com/connectors` → New Connector → Custom; enter MCP URL and authenticate.                                                                                                                                                                           | Official host route exists. Do not describe it as proof of Grok Bot plugin installation.                                                                                    |
+| OpenClaw           | Control UI Settings → MCP → Add server → Streamable HTTP → Gina URL. Configure OAuth in scoped editor, then `openclaw mcp login ask-gina`; verify with `openclaw mcp doctor ask-gina --probe`.                                                            | Viable current host route; Gina token fallback remains relevant. Installed older OpenClaw versions may differ.                                                              |
+
+Sources: [ChatGPT connect/test](https://developers.openai.com/plugins/deploy/connect-chatgpt), [Claude remote connectors](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp), [Claude Code MCP](https://code.claude.com/docs/en/mcp), [Codex MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli), [Cursor MCP](https://prod.cursor.com/docs/mcp), [Perplexity remote connectors](https://www.perplexity.ai/help-center/en/articles/13915507-adding-custom-remote-connectors), [Grok connectors](https://docs.x.ai/grok/connectors), [OpenClaw MCP](https://docs.openclaw.ai/tools/mcp).
+
+Perplexity's older [local/remote overview](https://www.perplexity.ai/help-center/en/articles/11502712-local-and-remote-mcps-for-perplexity) still says remote MCP is coming soon; use the specific newer remote-connector guide above. Avoid hardcoding plan availability from conflicting pages.
+
+Grok Build is another distinct surface: official docs support `grok mcp add --transport http ask-gina https://askgina.ai/ai/gina/mcp` with OAuth. [Grok Build MCP](https://docs.x.ai/build/features/mcp-servers). Repository references to **Grok Bot** say it loads plugins from the Cursor marketplace, and local Cursor installation does not verify Grok Bot. Keep that path separately labeled until a live marketplace entry is confirmed. [Package README](../plugins/ask-gina/README.md).
+
+## Skills and public distribution evidence
+
+- Canonical public source: [askgina/plugins skill directory](https://github.com/askgina/plugins/tree/main/plugins/ask-gina/skills). Names: `review-gina-account`, `research-spot-tokens`, `research-hyperliquid`, `research-prediction-markets`. Copy the complete selected directory, not a separately maintained duplicate instruction file.
+- OpenClaw supports `<workspace>/.agents/skills` and `~/.agents/skills`, plus `skills.load.extraDirs`. Therefore a checked-out Gina skill directory can be loaded through an extra root, or copied to a supported skill root. In this project use `.agents/skills` for project-local installation, per AGENTS.md. MCP authentication remains a separate step. [OpenClaw skills](https://docs.openclaw.ai/tools/skills).
+- This repository has a Claude marketplace manifest named `ask-gina-plugins`, with plugin `ask-gina`, source `./plugins/ask-gina`, skills `./skills`, and Claude MCP config `./targets/claude/.mcp.json`. That establishes a repository-hosted source, not an Anthropic directory approval. [Manifest](../.claude-plugin/marketplace.json).
+- A real public legacy ClawHub listing was found: [Polymarket via Gina](https://clawhub.ai/sidshekhar/askgina-polymarket), version 0.1.2, pointing to `/ai/predictions/mcp`. It is a trading-capable legacy skill, not the current four-skill read-only bundle. Listing existence is verified; content parity and release ownership process are not. Do not claim all OpenClaw skills are removed or that a current Gina Read ClawHub package is published.
+- Targeted public searches did not establish a current Ask Gina listing on ChatGPT, Claude, or Cursor. Claude directory crawling was blocked. Absence of search evidence does not establish absence of a listing. Use direct MCP setup as the concrete path; add marketplace buttons only with a verified URL and successful install check.
+- Package README explicitly distinguishes building archives from publishing/submitting. Do not infer npm availability or approved marketplace release from package names, generated archives, or target manifests. [README](../plugins/ask-gina/README.md).
+
+## Acceptance evidence still needed
+
+For each advertised host: record host/version or web date, setup method, successful OAuth/token authorization, discovered read tools, one successful read request, and reconnect behavior. For listings, record the real listing URL and installed package identity. For write guides, verify endpoint/access labels separately and never use a real trade as the connection smoke test. This research did not create credentials, install plugins, authorize accounts, or run financial tools.

ai_docs/docs/authoring.md

@@ -0,0 +1,78 @@
+# Maintaining Gina documentation
+
+The public Mintlify source is `docs/`. Track changes in [askgina/plugins issues](https://github.com/askgina/plugins/issues); this overhaul is [#42](https://github.com/askgina/plugins/issues/42). Internal research, verification evidence, templates, and inventories belong in `ai_docs/`.
+
+## Write for the task
+
+Lead with what the reader can accomplish. Explain Gina before its protocols. Use one primary purpose per page: a guided tutorial, task instructions, conceptual explanation, or factual reference. Keep this classification editorial; do not add another navigation layer.
+
+Use sentence-case headings and actual UI labels. Define MCP, plugin, skill, and authentication separately. Prefer a specific prompt and expected result over “try it out.” Preserve distinctions between research, preparation, submission, and settlement. Use “Write access (Degen mode)” in navigation and the literal “Full access — view and execute” label when describing Agent Setup.
+
+## Verify claims before publishing
+
+- Check tool names against `packages/contracts/src/index.ts` for Gina Read and the current server registry for each write venue. Do not infer write tools from the research plugin.
+- Check host setup against primary host documentation. Record evidence in `ai_docs/docs-host-verification.md`. Source adapters do not prove marketplace approval. Mark unverified availability and authenticated tests explicitly.
+- Store installation instructions once per client or venue; link quickstarts to them.
+- Preserve product-guide routes and existing frontmatter. The chatbot consumes eight explicit corpus entries with reciprocal `relatedSlugs`. New pages are public docs but are not automatically added to that corpus. Coordinate corpus additions in the chatbot repo.
+- Do not call a proposed flow “tested” until it was run. Keep UI-source verification separate from authenticated end-to-end verification.
+
+## Screenshots
+
+Capture actual app components with a demo account or Storybook fixture. Do not fabricate product UI. Use local images under `docs/images/product/`, crop around the relevant control, keep each image under 1 MB, and include descriptive alt text plus a caption. State when values are sample data. Never capture credentials or a real user's financial information. Record source component, fixture, capture date, and limitations in `screenshots.md`.
+
+Essential instructions must remain understandable in Markdown without images. Simulated and live run labels must be explained in text.
+
+## Checks and preview
+
+```sh
+node --test tools/docs/check.test.mjs
+node tools/docs/check.mjs
+node tools/docs/check.mjs --external
+cd docs
+mint dev --port 3005
+```
+
+Inspect desktop and mobile navigation, code blocks, tables, screenshots, and one path from homepage to first request. In the Mintlify preview, check affected pages and redirects; after deployment, verify `/llms.txt`, supported full-text/Markdown exports, and removal of retired content. The production index remains unchanged until deployment.
+
+CI covers navigation, component and Markdown links, local images, redirects, retired instructions, tool-catalog parity, scopes, skill names, corpus metadata, and the approved crawler policy. External URL checks can fail because of host access controls; investigate the result instead of declaring the target nonexistent.
+
+## Moving or retiring content
+
+Every public MDX page must be in navigation. Remove retired source so search and agent exports cannot retrieve stale instructions, add a redirect to the replacement, and update internal links to use the replacement directly. Preserve useful deep links. Use the inventory to record keep/rewrite/merge/retire decisions.
+
+## Page templates
+
+### Tutorial
+
+```md
+---
+title: "Complete a specific first task"
+description: "The result the reader will get."
+---
+
+By the end, you will [observable outcome]. You need [prerequisites].
+
+## 1. Connect
+
+[Exact setup link and permission choice.]
+
+## 2. Try the task
+
+[Copyable prompt or command.]
+
+Expected: [recognizable result and how to verify it].
+
+## If it fails
+
+[Smallest recovery action and troubleshooting link.]
+
+Next: [one useful follow-up task].
+```
+
+### Task guide or reference
+
+Begin with the task or capability. For a guide, list prerequisites, exact steps, expected result, and relevant limitations. For a reference, use a table of verified interfaces and examples, then link to a tutorial. Avoid duplicating setup configuration or generic safety text on every page.
+
+## Chatbot corpus compatibility
+
+The existing eight corpus pages require a source H1 matching frontmatter and an exact set of seven metadata keys. Included pages must be plain Markdown, and the assembled included corpus must stay under 12,000 characters. Use Markdown image syntax and text captions in those pages. `docs/style.css` hides the redundant source H1 in the web rendering because Mintlify already renders the page title. Recheck the selector when upgrading Mintlify.