supercli-docs-dev

Files (1)

• SKILL.md

SKILL.md (first lines)

# Supercli Docs Development

Work on supercli documentation including docs/index.html, docs/plugins.html, and associated scripts.

## Docs Structure

```
docs/
├── index.html           # Main documentation page (single-page app)
├── plugins.html         # Plugin directory page
├── server.md            # Server documentation (loaded dynamically)
├── adapters.md          # Adapters documentation (loaded dynamically)
├── meta-plugins.json    # Generated plugin metadata (don't edit manually)
├── features/            # Feature-specific docs
└── ...other .md files
scripts/
└── generate-meta-plugins.js  # Generates meta-plugins.json
```

## Terminology Convention

**IMPORTANT: Use "capability" not "skill"**

The codebase uses "capability" as the primary term:
- Section titles → "Capability Layer Basics", "Capability Sources", "Capability Mesh Vision"
- Content references → "every capability becomes...", "capability discovery layer"
- Sidebar links → update both href AND display text
- Section IDs → change from `id="skill-*"` to `id="capability-*"`

Search keyword attributes can keep "skill" for backwards searchability.

## docs/index.html

Single-page documentation with:
- Sidebar navigation (links to #sections and other doc pages)
- Quick filter input (searches section content + data-keywords)
- Sections with `class="doc-section"` and `data-keywords="..."` attributes
- Consistent dark theme: `bg-slate-950`, `text-slate-300`, `brand-400` accents
- Tailwind + DaisyUI + Space Grotesk/Inter fonts (CDN)

### Common Edits

**Update sidebar:** Edit the `<nav>` inside `<aside id="sidebar">`
**Update mobile nav:** Clone happens automatically via JS from sidebar
**Add section:** Create `<article class="doc-section" id="..." data-keywords="...">`
**Link to another doc page:** `<a href="plugins.html">Plugin Directory</a>`
**Add dynamic .md section:** 
1. Create `docs/<section>.md` file
2. Add empty div in HTML: `<div id="<section>-content" class="prose prose-lg max-w-none text-[#2F3437]"></div>`
3. Add JS loader at bottom of page:
```javascript
async function loadSectionDocs() {
  const res = await fetch('<section>.md');
  const markdown = await res.text();
  const html = marked.parse(markdown);
  document.getElementById('<section>-content').innerHTML = html;
}
loadSectionDocs();
```

## docs/plugins.html

Plugin directory page that:
- Loads `meta-plugins.json` at runtime via fetch
- Displays plugin cards with search + tag filtering
- Shows install command with copy-to-clipboard buttons
- Uses same dark theme as index.html

Each card shows:
- Plugin name
- Description (line-clamped)
- Tags
- `supercli plugins install <name>` command
- Copy buttons (clipboard API with visual feedback)
- `has_learn` badge for plugins with SKILL.md

## scripts/generate-meta-plugins.js

Generates `docs/meta-plugins.json` deterministically:
- Reads `plugins/plugins.json` (legacy entries)
- Scans `plugins/*/meta.json` directories (new convention)
- Deduplicates (meta.json takes precedence over plugins.json)
- Sorts alphabetically by name
- Outputs: `{ generated, count, plugins: [...] }`

**Run:** `node scripts/generate-meta-plugins.js`

**Output format per plugin:**
```json
{
  "name": "beads",
  "description": "...",
  "tags": ["issues", "tracking"],
  "has_learn": true,
  "source": "plugins/beads/plugin.json"  // optional, for legacy
}
```

## Plugin Metadata Convention

New bundled plugins use isolated `meta.json` files:

```
plugins/<name>/
├── plugin.json           # Manifest (commands, checks, passthrough)
├── meta.json             # Registry metadata (description, tags, has_learn)
├── install-guidance.json # Optional install steps
├── skills/quickstart/SKILL.md  # Agent learning doc (if has_learn)
└── README.md            # Human docs
```

**meta.json format:**
```json
{
  "description": "Plugin description for registry discovery",
  "tags": ["tag1", "tag2"],
  "has_learn": true
}
```

From javimosch/supercli, MIT.

More from javimosch/supercli