homelab/.claude/skills/wiki-docs.md

# Wiki Documentation Skill

Create and manage markdown documentation files that sync to Wiki.js.

## Context

**Repository Location:** `/mnt/media/wikijs-content/`
**Git Remote:** `git.fig.systems/eddie/wiki.git`
**Wiki.js URL:** https://wiki.fig.systems

This repository is synchronized with Wiki.js. Any markdown files created here will automatically appear in the wiki after a sync (typically within 5 minutes, or immediately if triggered manually).

## Capabilities

1. **Create Documentation Pages**
   - Write markdown files with proper Wiki.js frontmatter
   - Organize content in directories (maps to wiki hierarchy)
   - Add tags and metadata

2. **Git Operations**
   - Commit changes with descriptive messages
   - Push to remote repository
   - Pull latest changes before writing

3. **Frontmatter Format**
   All wiki pages require this YAML frontmatter:
   ```yaml
   ---
   title: Page Title
   description: Brief description of the page
   published: true
   date: 2026-03-15T00:00:00.000Z
   tags: tag1, tag2, tag3
   editor: markdown
   dateCreated: 2026-03-15T00:00:00.000Z
   ---
   ```

   **Important:** Tags must be comma-separated, not YAML array format!

## Workflow

When creating wiki documentation:

1. **Navigate to repo:**
   ```bash
   cd /mnt/media/wikijs-content
   ```

2. **Pull latest changes:**
   ```bash
   git pull
   ```

3. **Write markdown file:**
   - Use clear, descriptive filenames (lowercase-with-dashes.md)
   - Include proper frontmatter
   - Use standard markdown formatting
   - Organize in subdirectories as needed (e.g., `home/containers/services/service-name.md`)

4. **Scan for secrets with Gitleaks:**
   ```bash
   # Install gitleaks if not already installed
   # On Ubuntu/Debian: apt install gitleaks
   # Or download from: https://github.com/gitleaks/gitleaks/releases

   # Scan staged files before commit
   gitleaks detect --source . --verbose --no-git

   # Or scan specific files
   gitleaks detect --source . --verbose --no-git --log-opts="<filename>"
   ```

   **If secrets are found:**
   - **Remove them immediately** - replace with environment variables or placeholders
   - Use patterns like `${SECRET_KEY}`, `YOUR_KEY_HERE`, or `TBD`
   - Never commit actual passwords, API keys, tokens, or credentials
   - Check `.gitleaks.toml` for allowlist patterns

5. **Commit and push:**
   ```bash
   git add <filename>
   git commit -m "Add/Update: brief description"
   git push
   ```

   **Note:** Gitleaks CI/CD will automatically scan on push and fail if secrets detected

6. **Verify:** Changes will appear at https://wiki.fig.systems after sync

## File Organization

Suggested directory structure:
```
/mnt/media/wikijs-content/
├── homelab/
│   ├── services/
│   │   └── service-name.md
│   ├── networking/
│   │   └── traefik-setup.md
│   └── guides/
│       └── how-to-guide.md
├── development/
│   └── project-docs.md
└── reference/
    └── commands.md
```

Directories in the repo map to page hierarchy in Wiki.js.

## Examples

### Create a Service Documentation Page

```markdown
---
title: Jellyfin Media Server
description: Jellyfin configuration and usage guide
published: true
date: 2026-03-15T00:00:00.000Z
tags: homelab, media, jellyfin
editor: markdown
dateCreated: 2026-03-15T00:00:00.000Z
---

# Jellyfin Media Server

Jellyfin is a free software media system...

## Access
- **URL:** https://jellyfin.fig.systems
- **Authentication:** Authelia SSO

## Configuration
...
```

### Create a How-To Guide

```markdown
---
title: How to Add a New Service
description: Step-by-step guide for adding services to the homelab
published: true
date: 2026-03-15T00:00:00.000Z
tags: homelab, guide, docker
editor: markdown
dateCreated: 2026-03-15T00:00:00.000Z
---

# How to Add a New Service

This guide walks through the process...
```

## Git Configuration

The repository is already configured:
- **User:** Claude
- **Email:** claude@fig.systems
- **Authentication:** Token-based (embedded in remote URL)

## Best Practices

1. **Always pull before writing** to avoid conflicts
2. **Scan for secrets with Gitleaks** before committing
3. **Use descriptive commit messages** following the pattern: "Add: X" or "Update: Y"
4. **Include proper frontmatter** - pages without it won't render correctly
5. **Use semantic filenames** - lowercase with dashes instead of spaces
6. **Organize logically** - use subdirectories for categories
7. **Add relevant tags** - helps with wiki navigation and search
8. **Set published: true** - pages with `published: false` won't be visible
9. **Never commit secrets** - use placeholders like `TBD`, `${VAR}`, or `YOUR_KEY_HERE`

## Secret Management with Gitleaks

### What is Gitleaks?

Gitleaks is a secret scanner that detects hardcoded secrets, passwords, API keys, and tokens in Git repositories.

### CI/CD Integration

The wiki repository has automated Gitleaks scanning:
- **Workflow**: `.forgejo/workflows/gitleaks.yaml`
- **Config**: `.gitleaks.toml`
- **Triggers**: Every push to main, all pull requests
- **Action**: Fails build if secrets detected

### Local Scanning

**Before committing:**
```bash
cd /mnt/media/wikijs-content

# Scan all files
gitleaks detect --source . --verbose --no-git

# Scan specific files
gitleaks detect --source . --verbose --no-git --log-opts="path/to/file.md"

# Scan uncommitted changes only
gitleaks protect --staged --verbose
```

### Handling Detected Secrets

**If Gitleaks finds secrets:**

1. **Immediate action:**
   - DO NOT commit
   - Replace secret with placeholder
   - Use `TBD`, `${SECRET_KEY}`, or `YOUR_KEY_HERE`

2. **Examples of safe placeholders:**
   ```markdown
   API_KEY=YOUR_API_KEY_HERE
   PASSWORD=${DB_PASSWORD}
   TOKEN=TBD
   ```

3. **Allowlisted patterns** (in `.gitleaks.toml`):
   - `example.com` domains
   - `localhost` and `127.0.0.1`
   - `TBD` placeholders
   - Environment variable syntax `${VAR}`

### What Gitleaks Detects

- AWS keys (AKIA...)
- GitHub tokens (ghp_...)
- GitLab tokens (glpat-...)
- Private keys (-----BEGIN PRIVATE KEY-----)
- Generic API keys and secrets
- Passwords in configuration files

### False Positives

If Gitleaks flags safe content:

1. **Update `.gitleaks.toml` allowlist:**
   ```toml
   [allowlist]
     regexes = [
       '''safe-pattern-here''',
     ]
   ```

2. **Commit the config update:**
   ```bash
   git add .gitleaks.toml
   git commit -m "chore: Update Gitleaks allowlist"
   ```

### Git History Scanning

To scan entire git history:
```bash
gitleaks detect --source . --verbose
```

This checks all commits, not just current files.

## Troubleshooting

**If page doesn't appear in Wiki.js:**
- Check Wiki.js logs: `docker compose logs wikijs`
- Manually trigger sync in Wiki.js admin panel (Storage section)
- Verify frontmatter is valid YAML
- Ensure file has `.md` extension

**If git push fails:**
- Check authentication token is still valid
- Verify network connectivity to git.fig.systems
- Try pulling first to resolve conflicts

**If Gitleaks CI/CD fails:**
- View Forgejo Actions logs at https://git.fig.systems/eddie/wiki/actions
- Identify detected secrets in the workflow output
- Remove or replace secrets with placeholders
- Update `.gitleaks.toml` if false positive
- Commit and push again

**If Gitleaks not installed locally:**
```bash
# Ubuntu/Debian
sudo apt install gitleaks

# Or download latest release
wget https://github.com/gitleaks/gitleaks/releases/latest/download/gitleaks_linux_amd64.tar.gz
tar -xzf gitleaks_linux_amd64.tar.gz
sudo mv gitleaks /usr/local/bin/
```

## Integration with Other Services

This wiki can document:
- **Homelab services** (compose/services/*)
- **Infrastructure setup** (Traefik, Authelia, LLDAP)
- **Media management** (*arr stack, Jellyfin)
- **Development projects**
- **Personal notes and references**

All documentation is version-controlled and backed up via Git!