diff --git a/.agents/docs/README.md b/.agents/docs/README.md index 80f88f2..1c843d4 100644 --- a/.agents/docs/README.md +++ b/.agents/docs/README.md @@ -3,6 +3,8 @@ These pages explain this repository's navigation and publication responsibilities. Host product guides and Protocol specifications remain at their source. +- [Agent discovery entry](../../llms.txt) and [task index](../../skills/index.md). +- [Install the documentation Skill](install-docs-skill.md). - [Contribute and choose the source owner](contributor-guide.md). - [Current portal implementation](../../site/README.md). - [Planned aggregation boundary](../../integrations/README.md). diff --git a/.agents/docs/install-docs-skill.md b/.agents/docs/install-docs-skill.md new file mode 100644 index 0000000..3b25d5c --- /dev/null +++ b/.agents/docs/install-docs-skill.md @@ -0,0 +1,44 @@ +# Install The CordisX Documentation Skill + +The `cordisx-docs` Skill teaches an assistant where to look when a CordisX task +arises. Its only installed file is [SKILL.md](../../skills/cordisx-docs/SKILL.md); +product documentation stays online with its owner. It is not an npm package, +runtime plugin, or replacement for `cordisx-plugin-development`. + +## Codex + +Use the user's configured Skill directory. The current documented Codex +user-level location is `$HOME/.agents/skills/cordisx-docs/SKILL.md`; see +[Codex Skill locations](https://developers.openai.com/codex/skills/). +If an older installation already discovers a copy under `$CODEX_HOME/skills` +or `$HOME/.codex/skills`, update that existing copy instead of creating a second +Skill with the same name. +Check whether that Skill already exists before downloading. Reuse an identical +copy; preserve local edits instead of overwriting them during initial setup. + +For a new installation: + +```bash +SKILL_DIR="$HOME/.agents/skills/cordisx-docs" +mkdir -p "$SKILL_DIR" +curl --fail --location https://raw.githubusercontent.com/cordisx/docs/main/skills/cordisx-docs/SKILL.md --output "$SKILL_DIR/SKILL.md" +``` + +Read the downloaded file and verify its `name: cordisx-docs` frontmatter. Use the +agent's Skill discovery/reload mechanism, or start a new session if necessary, +and verify it lists `cordisx-docs`. A successful download alone does not prove +the current session has loaded it. Do not restart the CordisX Host for this step. + +## Other Assistants Or Read-Only Use + +Use the assistant's documented Skill installer/directory for the same standalone +file. Do not guess another product's configuration path. Without Skill support, +read [the Docs entry](../../llms.txt) on demand; persistent installation is not +required to use the guides. + +## After Installation + +Ask a relevant question, such as "How do I configure a CordisX plugin source?" +The Skill should select the Marketplace route from [the index](../../skills/index.md), +not install anything or read all guides. Existing runtime plugins and their +permissions are unchanged. Remove only this Skill's directory to uninstall it. diff --git a/README.md b/README.md index 2ef9982..1c1fd67 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,18 @@ Navigation and presentation for `https://cordisx.github.io/docs/`. +## Getting started with an AI assistant + +```text +Read the CordisX documentation entry and install its documentation Skill so you can find the right guide for my CordisX requests: https://raw.githubusercontent.com/cordisx/docs/main/llms.txt +``` + +After installation, describe your CordisX task normally. The Skill loads relevant +owner documentation on demand. [Read the entry](llms.txt) or browse the +[Skill and documentation index](skills/index.md). + +## Portal ownership + The current implementation is a static portal linking to the Host and Protocol source documentation and the Marketplace. It does not fetch, render, or vendor the Markdown from those repositories. [`sources.yaml`](sources.yaml) declares diff --git a/llms.txt b/llms.txt new file mode 100644 index 0000000..099f977 --- /dev/null +++ b/llms.txt @@ -0,0 +1,24 @@ +# CordisX Documentation + +This entry routes agents to CordisX's owning documentation. It is a navigation +layer, not another implementation or copy of the Host and plugin manuals. + +## Reading Order + +1. For first-time product setup, read [CordisX adoption](https://raw.githubusercontent.com/cordisx/cordisx/main/llms.txt). + Skip setup already completed in this task. +2. To make documentation discoverable in future sessions, follow [Install the documentation Skill](.agents/docs/install-docs-skill.md). +3. For a specific question, choose the smallest relevant entry in [the Skill and documentation index](skills/index.md). + +Resolve relative links against this document's URL. Read only the selected topic +and its required references; do not crawl every linked page or loop back through +completed prerequisites. Read `SKILL.md` directly when persistent installation +is not wanted or the agent cannot install skills. + +## Boundary + +Documentation discovery does not install plugins, launch Apps, grant permissions, +or log into services. Follow the user's request and the target tool's permissions. +This public portal does not contain private source addresses or credentials. +Product commands and compatibility facts belong to their linked owners. Check +the installed release's help/docs if current `main` differs from that release. diff --git a/skills/cordisx-docs/SKILL.md b/skills/cordisx-docs/SKILL.md new file mode 100644 index 0000000..cd1bce3 --- /dev/null +++ b/skills/cordisx-docs/SKILL.md @@ -0,0 +1,30 @@ +--- +name: cordisx-docs +description: Find authoritative CordisX documentation for installation, startup, profiles, Marketplace sources, plugin installation, troubleshooting, and plugin-development references. Use for CordisX questions and setup; not general Codex account or coding questions. +--- + +# CordisX Documentation + +Read the [task index](https://raw.githubusercontent.com/cordisx/docs/main/skills/index.md) +and follow only the route relevant to the user's request. Fetch the linked owner +document rather than answering product commands from memory or downloading the +whole documentation set. + +- For adoption, follow the Host entry and preserve existing setup. Do not run + installation merely because the user asks a question. +- For an existing plugin, use the Marketplace and the user's selected source. + Read that plugin's own guide for service configuration and login. +- For plugin implementation, continue with the separate plugin-development + Skill; this Skill does not duplicate its contract or workflow. +- If the user provides a private entry, read it only in the authorized context. + Keep private URLs, source metadata, and credentials out of public files. + +Resolve relative links against the containing document's URL. A prerequisite +already completed need not be performed again. An inaccessible link is a missing +reference, not permission to guess endpoints or commands. Documentation on `main` +may be newer than the installed CLI; check help and the installed release tag +before applying version-sensitive instructions. + +Distinguish installation, running Host, plugin activation, permission state, and +provider-account login. Documentation discovery does not authorize additional +effects. Cite the source used and report what was actually verified. diff --git a/skills/index.md b/skills/index.md new file mode 100644 index 0000000..8afeac0 --- /dev/null +++ b/skills/index.md @@ -0,0 +1,17 @@ +# CordisX Skills And Documentation + +Choose one route for the current task. These are links to authoritative owners, +not an instruction to load every document. + +| Task | Read first | Continue only when relevant | +| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | +| Install or start CordisX | [Host entry](https://raw.githubusercontent.com/cordisx/cordisx/main/llms.txt) | Its Getting started and startup Q&A links | +| Configure a Marketplace or install an existing plugin | [Marketplace entry](https://raw.githubusercontent.com/cordisx/marketplace/main/llms.txt) | The selected source's own guide and plugin README | +| Keep documentation discoverable | [Install the navigation Skill](../.agents/docs/install-docs-skill.md) | [cordisx-docs](cordisx-docs/SKILL.md) | +| Add or change a plugin's behavior | [Plugin-development Skill](https://raw.githubusercontent.com/cordisx/cordisx/main/skills/cordisx-plugin-development/SKILL.md) | Its task-specific references | +| Understand Host configuration or troubleshoot behavior | [Host documentation index](https://raw.githubusercontent.com/cordisx/cordisx/main/.agents/docs/README.md) | The owning topic, at the installed release when needed | +| Check versioned plugin contracts | [Protocol index](https://raw.githubusercontent.com/cordisx/cordisx-protocol/main/.agents/docs/README.md) | The contract version named by the package | + +The navigation Skill routes reading; the development Skill guides implementation. +Neither is a CordisX runtime plugin. For a private source, use the entry supplied +by the user instead of guessing an internal URL or copying it into public docs.