.gitea/workflows/ci.yml

@@ -88,6 +88,12 @@ jobs:
       - name: Lint
         run: .venv/bin/python -m ruff check .
 
+      - name: Lint Markdown
+        run: .venv/bin/mdformat --check README.md ROADMAP.md CHANGELOG.md
+
+      - name: Lint YAML
+        run: .venv/bin/yamllint .
+
       - name: Type-check
         run: .venv/bin/python -m mypy src
 

.github/workflows/ci.yml

@@ -25,6 +25,12 @@ jobs:
       - name: Lint
         run: ruff check .
 
+      - name: Lint Markdown
+        run: mdformat --check README.md ROADMAP.md CHANGELOG.md
+
+      - name: Lint YAML
+        run: yamllint .
+
       - name: Type-check
         run: mypy src
 

.yamllint.yml

@@ -0,0 +1,16 @@
+extends: default
+
+ignore: |
+  .git/
+  .venv/
+  .mypy_cache/
+  .pytest_cache/
+  .ruff_cache/
+
+rules:
+  document-start: disable
+  line-length:
+    max: 120
+  truthy:
+    allowed-values: ["true", "false"]
+    check-keys: false

CHANGELOG.md

@@ -4,11 +4,12 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
----
+______________________________________________________________________
 
 ## [Unreleased]
 
 ### Added
+
 - `README.md` — project overview, description, example workflow, supported distributions, and suggested tooling
 - `ROADMAP.md` — phased development plan covering decisions, data collection, AI integration, CLI design, and hardening
 - `CHANGELOG.md` — this file; established changelog tracking for the project
@@ -27,8 +28,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - Test scaffold (`pytest`) with initial parser and CLI coverage
 - SSH test coverage for policy checks, SSH argument construction, and config summary behavior
 - CI workflow for lint (`ruff`), type-check (`mypy`), and tests (`pytest`)
+- CI coverage expanded with Markdown formatting checks (`mdformat --check`) and YAML linting (`yamllint`)
 
 ### Decided
+
 - Implementation language: **Python**
 - Distribution strategy: single distributable binary via **Nuitka** (PyInstaller as fallback)
 - SSH authentication: **keypair only** (ed25519/RSA); auto-accept new hosts; hard reject on host key change with MITM warning

README.md

@@ -20,8 +20,8 @@ The agent operates in **read-only mode at all times**. It will never modify the
 A troubleshooter receives a ticket reporting that the Apache service on a remote server has failed to start. They provide `tai` with:
 
 1. The ticket description or error message
-2. The hostname of the affected system
-3. Any relevant directories to focus on
+1. The hostname of the affected system
+1. Any relevant directories to focus on
 
 `tai` then connects to the host, reads through system logs, service configurations, and any other related files, and returns a structured analysis of the likely cause along with recommended next steps.
 
@@ -32,4 +32,4 @@ A troubleshooter receives a ticket reporting that the Apache service on a remote
 | AI inference backend | [vLLM](https://github.com/vllm-project/vllm) |
 | Model | `gemma4:a4b` |
 
-> **Note:** A suitable implementation language for this project is yet to be determined.
+> **Note:** A suitable implementation language for this project is yet to be determined.

ROADMAP.md

@@ -2,13 +2,14 @@
 
 This document outlines the major decisions, milestones, and development phases required to bring `tai` from concept to a working tool.
 
----
+______________________________________________________________________
 
 ## Phase 0 — Decisions & Prerequisites
 
 These must be resolved before meaningful development can begin.
 
 ### Language Selection
+
 - [x] **Decision: Python**
 - Key factors: native vLLM integration, mature SSH libraries (`paramiko` / `asyncssh`), strong text/log parsing, rapid development
 - Single binary distribution will be achieved via **Nuitka** (preferred for true compilation) or **PyInstaller** as a fallback
@@ -16,12 +17,14 @@ These must be resolved before meaningful development can begin.
 - [ ] Add binary build step to CI pipeline
 
 ### AI Backend & Model
+
 - [ ] Confirm use of [vLLM](https://github.com/vllm-project/vllm) as the inference backend
 - [ ] Confirm `gemma4:a4b` as the default model (or select an alternative)
 - [ ] Define minimum hardware requirements for running the model locally
 - [ ] Decide whether the AI backend is bundled, self-hosted externally, or user-supplied
 
 ### SSH Strategy
+
 - [x] **Decision: keypair authentication only** — no password auth; eliminates credential storage risk
   - Default key resolution: `~/.ssh/id_ed25519`, `~/.ssh/id_rsa` (in order of preference)
   - CLI override via `--identity-file <path>`
@@ -33,6 +36,7 @@ These must be resolved before meaningful development can begin.
   - Override switch: `--ignore-ssh-config` to bypass local SSH config when required
 
 ### Scope & Constraints
+
 - [ ] Define the supported scope of issues (services, network, disk, kernel, etc.)
 - [ ] Confirm read-only guarantee — document exactly what "read-only" means in practice
 - [x] **Decision: interactive REPL mode for v0.1, full TUI for v0.2+**
@@ -40,7 +44,7 @@ These must be resolved before meaningful development can begin.
   - v0.2+: `textual`-based TUI with split panes (collected data | AI output | input bar)
   - Built-in slash commands: `/collect`, `/show logs`, `/clear`, `/host <hostname>`, `/help`, `/quit`
 
----
+______________________________________________________________________
 
 ## Phase 1 — Project Foundation
 
@@ -58,7 +62,7 @@ Basic project scaffolding and connectivity.
   - [x] Input parser and CLI tests added
   - [x] SSH module tests added for command policy and SSH argv behavior
 
----
+______________________________________________________________________
 
 ## Phase 2 — Data Collection Layer
 
@@ -74,7 +78,7 @@ Define what information the agent gathers and how.
 - [ ] Add support for per-distro variations (Ubuntu vs RHEL path differences, etc.)
 - [ ] Write tests with mocked SSH output
 
----
+______________________________________________________________________
 
 ## Phase 3 — AI Integration
 
@@ -87,7 +91,7 @@ Wire collected data into the local AI model.
 - [ ] Add streaming support for long AI responses
 - [ ] Evaluate and test model output quality on common issue types
 
----
+______________________________________________________________________
 
 ## Phase 4 — CLI & User Experience
 
@@ -99,7 +103,7 @@ Polish the interface for real-world use.
 - [ ] Support output to file or clipboard
 - [ ] Write man page / `--help` documentation
 
----
+______________________________________________________________________
 
 ## Phase 5 — Hardening & Distribution
 
@@ -111,7 +115,7 @@ Prepare for broader use.
 - [ ] Write installation and quickstart documentation
 - [ ] End-to-end integration tests against a test VM
 
----
+______________________________________________________________________
 
 ## Decisions Log
 

pyproject.toml

@@ -22,6 +22,8 @@ dev = [
   "pytest>=8.2,<9.0",
   "ruff>=0.5,<1.0",
   "mypy>=1.10,<2.0",
+  "mdformat>=0.7,<1.0",
+  "yamllint>=1.35,<2.0",
 ]
 build = [
   "nuitka>=2.4,<3.0",