Fiona-Assistant

LLM Wiki Tool Helper for LLM Agents/Hives

Fiona-Assistant is a command-line toolkit designed to manage, organize, and maintain LLM wiki content with minimal AI token dependence. It combines script-based automation with structured workflows to help LLM Agents and Hives efficiently manage documentation, markdown files, and code quality.

---

Overview

Purpose

Fiona-Assistant serves as a standalone MD/scripts/docs organizer and LLM wiki management helper that:

• Reduces AI Token Usage: Uses deterministic scripts and tools to handle wiki management tasks that don't require LLM intelligence
• Maintains Wiki Structure: Enforces consistent organization of markdown files, concepts, and raw source materials
• Validates Content Quality: Provides linting and diagnosis tools for markdown and Python code
• Enables Script-Based Workflows: Automates repetitive wiki maintenance tasks through CLI commands

Core Philosophy

Use scripts for deterministic tasks, reserve AI tokens for creative and analytical work

The toolkit is designed to be AI-friendly - outputs are formatted in consistent, parseable structures that LLMs can easily read and process.

---

Features

Tool Suite

Tool	Purpose	Key Capabilities
Librarian	Wiki content management	List files, scan directories, organize MD content
MDoctor	Markdown diagnosis	Lint markdown files using PyMarkdown, detect formatting issues
Python-Ruff	Code quality	Lint Python files using Ruff, enforce code standards
Generate-TOC	Table of contents	Auto-generate nested TOC from markdown headers

Wiki Structure Support

Fiona-Assistant understands and maintains the LLM Wiki directory structure:

llm-wiki/
├── ingest/          # Input zone: files to be processed
├── raw/             # Archived source materials (read-only)
│   ├── articles/
│   ├── papers/
│   ├── transcripts/
│   └── assets/
├── wiki/            # Processed content
│   └── concepts/    # Synthesized concept notes
├── personal/        # User notes (read-only for agents)
└── utils/           # Utility scripts

---

Installation

Quick Install (Production)

python -m pip install fiona-assistant

Development Setup

• Clone the repository:

  git clone <repository-url>
  cd fiona-assistant
  

• Create and activate the virtual environment:

  Linux / macOS:

  source bootstrap --env fiona_env -c
  

  Windows (PowerShell):

  Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
  . .\bootstrap.ps1 --env fiona_env -c
  

  Make sure fiona_env is activated before proceeding. On Windows the environment lives in .venvs\fiona_env.

---

Usage

Main CLI

Fiona-Assistant provides a unified CLI with multiple subcommands:

# Show all available commands
fiona-assistant --help

# Run via Python module
python -m fiona --help

Available Commands

# Run tests
fiona-assistant test

# Manage wiki content with Librarian
fiona-assistant librarian [directory]

# Generate an in-file table of contents below the H1
fiona-assistant librarian toc file <path_to_file>

# Force section numbering on for the run
fiona-assistant librarian toc file <path_to_file> --sectionized

# Generate in-file TOCs for every md file in the current directory / wiki root
fiona-assistant librarian toc file '*'

# Diagnose markdown files with MDoctor
fiona-assistant mdoctor [chklint] [directory]

# Lint Python code with Ruff
fiona-assistant python-ruff [chklint] [directory]

Direct Tool Access

Each tool can also be called directly:

# Librarian - List all files in a directory
librarian [directory]

# MDoctor - Check markdown lint violations
mdoctor chklint [directory]

# MDoctor - List all files

# Python-Ruff - Check Python code quality
python-ruff chklint [directory]

# Generate table of contents for markdown files
generate-toc [directory] [options]

---

Workflow Examples

Wiki Ingestion Workflow

# 1. Drop raw files into ingest directory
# (Manual or automated process)

# 2. List files ready for processing
librarian llm-wiki/ingest

# 3. Validate markdown quality before processing
mdoctor chklint llm-wiki/ingest

# 4. Move processed files to raw archive
# (Agent/orchestration task)

Content Maintenance Workflow

# Check all markdown files in wiki for lint violations
mdoctor chklint llm-wiki/wiki

# Generate table of contents for concept notes
generate-toc llm-wiki/wiki/concepts --recursive-toc

# Validate Python code in the project
python-ruff chklint src/

# List all markdown files for inventory
librarian llm-wiki/

Standalone Document Organization

# Organize any directory of markdown files
librarian /path/to/docs/

# Validate markdown formatting
mdoctor chklint /path/to/docs/

# Create nested table of contents
generate-toc /path/to/docs/ --recursive-toc

---

Output Format

All tools produce AI-friendly output with consistent formatting:

MDoctor Output Format

PyMarkdownLint Violations
TARGET: /path/to/directory

- DEFINITIONS:
  - md001: Heading levels should only increment by one, Heading levels should only increment by one level at a time
  - md013: Line length, Line length

- FILE: file1.md
  - 10:5 md013
  - 20:3 md001

- SUMMARY:
  - Total files with violations: 1
  - Total violations: 2

Python-Ruff Output Format

Ruff Violations
TARGET: /path/to/directory

Definitions:
  - F401: `*` import used, but not imported
  - E501: Line too long

- FILE: script.py
  - 15:10 F401
  - 25:80 E501

- SUMMARY:
  - Total files with violations: 1
  - Total violations: 2

---

Project Structure

fiona-assistant/
├── llm-wiki/                  # Wiki content and structure definition
│   ├── AGENTS.md              # Agent rules and directory permissions
│   ├── ingest/                # Input zone for new content
│   ├── raw/                   # Archived source materials
│   ├── wiki/                  # Processed concept notes
│   └── utils/                 # Utility scripts
│
├── src/
│   ├── fiona/                 # Main CLI entry point
│   │   └── __main__.py        # Unified command dispatcher
│   │
│   ├── librarian/             # Wiki content management
│   │   ├── __init__.py
│   │   ├── librarian.py       # File scanning and listing
│   │   └── toc_generator.py    # Table of contents generator
│   │
│   ├── mdoctor/               # Markdown diagnosis
│   │   ├── __init__.py
│   │   └── mdoctor.py         # PyMarkdown lint wrapper
│   │
│   ├── python_ruff/           # Python code linting
│   │   ├── __init__.py
│   │   └── python_ruff.py     # Ruff lint wrapper
│   │
│   ├── tests/                 # Unit tests
│   │   ├── test_fiona_main.py
│   │   ├── test_librarian.py
│   │   ├── test_mdoctor.py
│   │   └── test_python_ruff.py
│   │
│   ├── run_tests.py           # Test runner
│   └── README.md              # Development documentation
│
├── pyproject.toml             # Project configuration
├── bootstrap                  # Environment setup script (bash)
├── bootstrap.ps1              # Environment setup script (PowerShell)
├── LICENSE                    # GPL-3.0-only
└── README.md                  # This file

---

Testing

Run Tests

# Run all tests
python src/run_tests.py

# Or use pytest directly
python -m pytest

# Run with coverage
python -m pytest --cov=src

---

License

GPL-3.0-only

---

Key Concepts

For LLM Agents

• Deterministic Operations: Use Fiona-Assistant for file listing, linting, and organization
• Token Efficiency: Reserve LLM context for synthesis, analysis, and creative tasks
• Structured Output: All tool outputs are formatted for easy parsing by LLMs

For Human Users

• CLI-First: All functionality available through command-line interface
• Composable Tools: Combine tools in scripts for automated workflows
• Clear Structure: Maintains consistent wiki organization standards

---

Related Documentation

• LLM Wiki Agent Rules - Directory permissions and workflow rules
• Development Setup - Detailed development information
• Project Specification - Feature spec sheet with requirements and acceptance criteria
• Project TODO - Roadmap and planned features

---

Quick Reference Card

Task	Command
Show help	fiona-assistant --help
List files	fiona-assistant librarian /path/to/dir
Check MD lint	fiona-assistant mdoctor chklint /path/to/dir
Check Python lint	fiona-assistant python-ruff chklint /path/to/dir
Generate TOC	generate-toc /path/to/dir --recursive-toc
Generate file TOC	fiona-assistant librarian toc file /path/to/file.md --sectionized
Run tests	python src/run_tests.py
Install	pip install fiona-assistant
Dev install	pip install -e .

---

Note: All paths are relative to the current working directory unless specified as absolute paths.