- Reduce LINK_STRENGTH from 0.15 to 0.01 (circular force now handles positioning) - Increase BASE_LINK_DISTANCE from 50 to 100 (fixed distance for all links) - Set LINK_DISTANCE_PER_DEGREE to 0 (no degree-based scaling) - Reduce CHARGE_STRENGTH from -30 to -10 (very weak, just prevents overlap) - Increase CHARGE_DISTANCE_MIN from 50 to 100 - Reduce CENTER_STRENGTH from 0.02 to 0.001 (minimal center pull) - Reduce COLLIDE_STRENGTH from 0.9 to 0.5 - Reduce BASE_COLLIDE_RADIUS from 20 to 15 - Increase VELOCITY_DECAY from 0.7 to 0.9 (immediate stabilization) - Increase ALPHA_DECAY from 0.01 to 0.02 - Increase NEIGHBOR_REPEL_STRENGTH from 0.1 to 0.5 (STRONG for perfect circles) - Change targetRadius to use BASE_LINK_DISTANCE directly (fixed radius) Key insight: Circular force is now the PRIMARY positioning force, while link force just maintains connections without affecting positions. This ensures nodes arrange in perfect 360deg circles around their parent like the left cluster. Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
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:
source bootstrap --env fiona_env -c
Make sure
fiona_envis activated as pyenv before proceeding
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
├── 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.