From 997128101b79c7f2c0cec85f11425462cf8b89c3 Mon Sep 17 00:00:00 2001
From: Abhishek Uniyal <56363630+uniyalabhishek@users.noreply.github.com>
Date: Thu, 19 Feb 2026 14:12:25 +0530
Subject: [PATCH] docs: add llms usage docs

---
 docs/build/tools/README.mdx |   1 +
 docs/build/tools/llms.md    | 129 ++++++++++++++++++++++++++++++++++++
 docusaurus.config.ts        |   7 ++
 sidebarBuild.ts             |   1 +
 src/css/custom.css          |  10 +++
 5 files changed, 148 insertions(+)
 create mode 100644 docs/build/tools/llms.md

diff --git a/docs/build/tools/README.mdx b/docs/build/tools/README.mdx
index 927333b3d9..4e9eb8c2e0 100644
--- a/docs/build/tools/README.mdx
+++ b/docs/build/tools/README.mdx
@@ -18,6 +18,7 @@ Oasis.
 ## See also
 
 <DocCardList items={[
+  findSidebarItem('/build/tools/llms'),
   findSidebarItem('/build/tools/abi-playground'),
   findSidebarItem('/build/tools/verification'),
   findSidebarItem('/build/tools/localnet'),
diff --git a/docs/build/tools/llms.md b/docs/build/tools/llms.md
new file mode 100644
index 0000000000..d9f1753227
--- /dev/null
+++ b/docs/build/tools/llms.md
@@ -0,0 +1,129 @@
+---
+description: Use Oasis documentation with AI coding assistants via llms.txt or Context7 MCP
+---
+
+# AI-Assisted Development
+
+Oasis documentation is available in LLM-optimized formats so AI coding
+assistants can reference accurate, up-to-date Oasis docs instead of relying on
+training data. There are two approaches: feed raw `llms.txt` files directly, or
+set up the [Context7] MCP server for persistent IDE integration.
+
+## llms.txt
+
+The [llms.txt] standard provides a structured, Markdown-based summary of the
+entire Oasis documentation site optimized for LLM consumption.
+
+Two files are available:
+
+| File                                   | Description                                                |
+|----------------------------------------|------------------------------------------------------------|
+| [`llms.txt`][llms.txt-file]            | Curated index with page titles, descriptions, and URLs     |
+| [`llms-full.txt`][llms-full.txt-file]  | Complete documentation content inlined into a single file  |
+
+### Usage
+
+Paste the URLs directly into any LLM chat or you can also add the URL as project
+context in tools that support it (e.g. Cursor's `@docs` feature, or Claude/Codex
+project knowledge, CLAUDE.md/AGENTS.md).
+
+:::tip
+
+Use `llms.txt` when you need a quick overview or are working within tight
+context limits. Use `llms-full.txt` when you need the agent to have access to
+the complete documentation.
+
+:::
+
+## Context7 MCP
+
+[Context7] is an MCP server that indexes documentation and serves it on demand
+to AI coding assistants. It supports [40+ clients][all-clients] including Claude
+Code, Cursor, VS Code, and JetBrains.
+
+The Oasis documentation is indexed and available at:
+
+```
+Library ID: llmstxt/oasis_io_llms_txt
+```
+
+:::info
+
+Use the library ID `llmstxt/oasis_io_llms_txt` in your prompts to ensure you
+get the complete Oasis documentation. Other Oasis-related libraries on Context7
+may be incomplete.
+
+:::
+
+### Claude Code
+
+Add the Context7 MCP server:
+
+```shell
+claude mcp add --transport http context7 https://mcp.context7.com/mcp
+```
+
+Verify the server is registered:
+
+```shell
+claude mcp list
+```
+
+### Cursor
+
+Add the following to your `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "url": "https://mcp.context7.com/mcp"
+    }
+  }
+}
+```
+
+### Other Clients
+
+Context7 supports 40+ clients including VS Code, JetBrains, Windsurf, Zed,
+and more. See the [full client list][all-clients] for setup instructions
+specific to your tool.
+
+### Example Prompts
+
+Once the MCP server is configured, use prompts like:
+
+```
+Use context7 MCP to fetch Oasis Sapphire quickstart docs.
+Use library ID: llmstxt/oasis_io_llms_txt
+```
+
+```
+Using context7, show me how to implement encrypted events on Sapphire.
+Use library ID: llmstxt/oasis_io_llms_txt
+```
+
+### Auto-Invocation
+
+To avoid specifying "use context7" in every prompt, add a rule to your agent's
+configuration:
+
+- **Claude Code:** Add to your project's `CLAUDE.md`:
+
+  ```
+  Always use Context7 MCP with library ID llmstxt/oasis_io_llms_txt when you
+  need Oasis documentation.
+  ```
+
+- **Cursor:** Add to Settings → Rules for AI:
+
+  ```
+  Always use Context7 MCP with library ID llmstxt/oasis_io_llms_txt when you
+  need Oasis documentation.
+  ```
+
+[Context7]: https://context7.com
+[all-clients]: https://context7.com/docs/resources/all-clients
+[llms.txt]: https://llmstxt.org
+[llms.txt-file]: https://docs.oasis.io/llms.txt
+[llms-full.txt-file]: https://docs.oasis.io/llms-full.txt
diff --git a/docusaurus.config.ts b/docusaurus.config.ts
index a6fb5b54fc..b66889ef40 100644
--- a/docusaurus.config.ts
+++ b/docusaurus.config.ts
@@ -112,6 +112,13 @@ const config: Config = {
   ],
   themeConfig:
     {
+      announcementBar: {
+        id: 'ai_assisted_dev',
+        content: 'Use Oasis docs with AI coding assistants — <a href="/build/tools/llms">llms.txt and Context7 MCP now available</a>!',
+        backgroundColor: '#18181B',
+        textColor: '#ffffff',
+        isCloseable: true,
+      },
       navbar: {
         logo: {
           alt: 'Oasis Docs',
diff --git a/sidebarBuild.ts b/sidebarBuild.ts
index 477b32495a..c4e7c10968 100644
--- a/sidebarBuild.ts
+++ b/sidebarBuild.ts
@@ -198,6 +198,7 @@ export const sidebarBuild: SidebarsConfig = {
             'build/tools/cli/rofl',
           ]
         },
+        'build/tools/llms',
         'build/tools/abi-playground',
         'build/tools/verification',
         'build/tools/band',
diff --git a/src/css/custom.css b/src/css/custom.css
index 438e1282ac..5b52027a16 100644
--- a/src/css/custom.css
+++ b/src/css/custom.css
@@ -161,6 +161,16 @@ html[data-theme='dark'] .docusaurus-highlight-code-line {
   font-size: 14px;
 }
 
+/* Announcement bar has a dark bg in both themes; use cyan for visible border */
+.theme-announcement-bar {
+  border-bottom: 2px solid #00ffff !important;
+}
+
+/* Buttons don't inherit color from parent; fix close button visibility on dark bg */
+.theme-announcement-bar .close {
+  color: #ffffff;
+}
+
 /* Make the search field more Oasis-like */
 .navbar__search-input {
   border-radius: 0;