refactor: Improve linting error accumulation and link checking

Makefile

@@ -3,10 +3,10 @@
 # Orchestrates the setup and management of the knowledge base.
 # =============================================================================
 
-include config.env
+include globals.env
-export $(shell sed 's/=.*//' config.env)
+export $(shell grep -v '^[#[:space:]]' globals.env | sed 's/=.*//')
 
-.PHONY: setup add-genome status lint lock help
+.PHONY: setup add-genome status lint lock doctor sync help
 
 help:
 	@echo "Available commands:"
@@ -15,6 +15,8 @@ help:
 	@echo "  make status        - Check submodule and encryption status"
 	@echo "  make lint          - Verify schema, privacy flags, and metadata"
 	@echo "  make lock          - Lock all encrypted files across all genomes"
+	@echo "  make doctor        - Verify all required tools are installed"
+	@echo "  make sync          - Sync submodules and report unpushed commits"
 
 lint:
 	@bash scripts/lint-genomes.sh
@@ -36,6 +38,21 @@ status:
 	@echo "--- Encryption Status (First 10 files) ---"
 	@git-crypt status | head -n 10
 
+doctor:
+	@echo "Checking required tools..."
+	@command -v git        >/dev/null 2>&1 || { echo "  MISSING: git";        exit 1; }
+	@command -v git-crypt  >/dev/null 2>&1 || { echo "  MISSING: git-crypt";  exit 1; }
+	@command -v curl       >/dev/null 2>&1 || { echo "  MISSING: curl";       exit 1; }
+	@command -v jq         >/dev/null 2>&1 || { echo "  MISSING: jq";         exit 1; }
+	@command -v bw         >/dev/null 2>&1 || echo "  OPTIONAL: bw (Bitwarden CLI) not found — key injection will be manual."
+	@echo "System ready."
+
+sync:
+	@echo "Syncing submodules..."
+	@git submodule update --init --recursive
+	@echo "--- Unpushed commits per genome ---"
+	@git submodule foreach 'git log --oneline @{u}.. 2>/dev/null | head -5 || true'
+
 lock:
 	@echo "Locking master repository..."
 	@git-crypt lock 2>/dev/null || true

config.env

@@ -1,39 +0,0 @@
-#!/usr/bin/env bash
-# =============================================================================
-# config.env
-# Single Source of Truth for the Knowledge Genome Framework.
-# =============================================================================
-
-# --- PROVIDER SELECTION ---
-PROVIDER="forgejo"  # Options: "forgejo", "github"
-
-# --- FORGEJO CONFIGURATION ---
-FORGEJO_URL="https://git.keruhomelab.com"
-FORGEJO_USER="keru"
-# Note: FORGEJO_TOKEN must be exported in your shell for security.
-
-# --- VAULTWARDEN CONFIGURATION ---
-# Used for rendering template instructions
-VAULTWARDEN_URL="https://vault.keruhomelab.com"
-
-# --- MASTER REPOSITORY ---
-MASTER_REPO="master-knowledge-genome"
-GIST_URL="https://gist.github.com/442a6bf555914893e9891c11519de94f.git"
-
-# --- GENOME REGISTRY ---
-# Format: "name|description"
-GENOMES=(
-  "genome-dev|Web development, TUI, Angular, software architecture"
-  "genome-finance|Personal finance, investments, market analysis"
-  "genome-homelab|Keru infrastructure, network configs, architecture logs"
-)
-
-# --- SYSTEM PATHS ---
-WORK_DIR="${HOME}/knowledge-genome-setup"
-KEYS_DIR="${WORK_DIR}/keys"
-
-# Core directory resolution (DO NOT CHANGE)
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-TEMPLATES_DIR="${SCRIPT_DIR}/templates"
-LIB_DIR="${SCRIPT_DIR}/lib"
-PROVIDERS_DIR="${SCRIPT_DIR}/providers"

globals.env

@@ -0,0 +1,25 @@
+# =============================================================================
+# globals.env
+# Static configuration — pure KEY=VALUE.
+# Safe to: make include, docker-compose, env parsers, shell source.
+# =============================================================================
+
+# --- PROVIDER SELECTION ---
+PROVIDER=forgejo
+
+# --- FORGEJO ---
+FORGEJO_URL=https://git.keruhomelab.com
+FORGEJO_USER=keru
+FORGEJO_SSH_PORT=222
+
+# --- GITHUB (used when PROVIDER=github) ---
+# GITHUB_USER=your-username
+# GITHUB_ORG=your-org       # Optional: set only for org repos; overrides GITHUB_USER
+# Note: GITHUB_TOKEN must be exported in your shell for security.
+
+# --- VAULTWARDEN ---
+VAULTWARDEN_URL=https://vault.keruhomelab.com
+
+# --- MASTER REPOSITORY ---
+MASTER_REPO=master-knowledge-genome
+GIST_URL=https://gist.github.com/442a6bf555914893e9891c11519de94f.git

lib/deps.sh

@@ -16,10 +16,10 @@ check_deps() {
 
   if [[ ${#missing[@]} -gt 0 ]]; then
     error "Missing required tools: ${missing[*]}"
-    echo -e "\nInstall them using your package manager:"
+    printf "\nInstall them using your package manager:\n"
-    echo "  Debian/Ubuntu: sudo apt install ${missing[*]}"
+    printf "  Debian/Ubuntu: sudo apt install %s\n" "${missing[*]}"
-    echo "  MacOS:         brew install ${missing[*]}"
+    printf "  MacOS:         brew install %s\n"     "${missing[*]}"
-    exit 1
+    return 1
   fi
 
   success "Environment check passed: all required tools found."

lib/git-crypt.sh

@@ -16,7 +16,7 @@ gcrypt_export_key() {
   mkdir -p "${KEYS_DIR}"
   git-crypt export-key "$key_path"
   success "Symmetric key exported to: $key_path"
-  warn "Action required: store this key in Vaultwarden and delete it from disk."
+  warn "SECURITY ALERT: Move this key to Vaultwarden and delete it from disk immediately."
 }
 
 gcrypt_verify() {
@@ -83,7 +83,7 @@ gcrypt_rotate_key() {
     else
       error "Old key not found at: ${old_key_path}"
       error "Unlock manually before rotating: git-crypt unlock /path/to/${genome_name}.key"
-      exit 1
+      return 1
     fi
   else
     info "Repository is already unlocked — proceeding."
@@ -92,7 +92,7 @@ gcrypt_rotate_key() {
   # 2. Ensure working tree is clean (private files excluded — they will be re-staged)
   if ! git diff --quiet -- ':!raw/private' ':!wiki/private' 2>/dev/null; then
     error "Working tree has uncommitted changes outside private/. Commit or stash them first."
-    exit 1
+    return 1
   fi
 
   # 3. Remove old key material only (preserves .git/git-crypt/ structure)
@@ -154,7 +154,7 @@ gcrypt_print_key_instructions() {
   local genome_name="$1"
   local v_url="${VAULTWARDEN_URL:-https://your-vaultwarden.com}"
 
-  echo -e "\n  ── ${BOLD}Key Management: ${genome_name}${NC} ──\n"
+  printf "\n  ── %b ──\n\n" "${BOLD}Key Management: ${genome_name}${NC}"
   echo "  1. Encode the key to base64:"
   echo "       base64 < ${KEYS_DIR}/${genome_name}.key"
   echo ""

lib/lint.sh

@@ -6,6 +6,9 @@
 
 # Valid values for the 'type' frontmatter field.
 # Must stay in sync with the type list in templates/agents-genome.md.
+# Note: 'index' and 'log' are wiki-level singleton files (wiki/index.md, wiki/log.md).
+#       'conflict' has no dedicated scaffold directory — it is a cross-cutting type
+#       that can live under any wiki/ subdirectory.
 VALID_TYPES=("source" "entity" "concept" "query" "conflict" "private" "index" "log")
 
 # ---------------------------------------------------------------------------
@@ -121,7 +124,7 @@ check_knowledge_decay() {
 
   # Parse date — handle both GNU date (Linux) and BSD date (macOS)
   local updated_ts
-  if date --version &>/dev/null 2>&1; then
+  if date --version >/dev/null 2>&1; then
     # GNU date
     updated_ts=$(date -d "$last_updated" +%s 2>/dev/null)
   else
@@ -149,6 +152,30 @@ check_knowledge_decay() {
   return 0
 }
 
+# ---------------------------------------------------------------------------
+# check_page_size <file>
+# Enforces the page length limits defined in agents-genome.md:
+#   soft cap: 400 lines  → warn
+#   hard cap: 800 lines  → error
+# These limits ensure pages fit within the LLM context window without
+# attention degradation and keep the wiki atomically navigable.
+# ---------------------------------------------------------------------------
+check_page_size() {
+  local file="$1"
+  local lines
+  lines=$(wc -l < "$file")
+
+  if [[ $lines -gt 800 ]]; then
+    error "Page too long (${lines} lines, hard cap 800): $file"
+    error "  Split this page into focused sub-pages and link them."
+    return 1
+  elif [[ $lines -gt 400 ]]; then
+    warn "Page approaching limit (${lines} lines, soft cap 400): $file"
+  fi
+
+  return 0
+}
+
 # ---------------------------------------------------------------------------
 # check_broken_links <file>
 # Basic check for internal [[wikilinks]] that cannot be resolved locally.
@@ -161,7 +188,7 @@ check_broken_links() {
 
   # Extract link targets, stripping aliases: [[Link|Alias]] -> Link
   local links
-  links=$(grep -oP '\[\[\K[^\]]+' "$file" 2>/dev/null | cut -d'|' -f1)
+  links=$(grep -oE '\[\[[^\]]+' "$file" 2>/dev/null | sed 's/^\[\[//' | cut -d'|' -f1)
 
   for link in $links; do
     local target="$link"

lib/output.sh

@@ -15,11 +15,12 @@ else
   GREEN='' YELLOW='' CYAN='' RED='' BOLD='' NC=''
 fi
 
-info()    { echo -e "${CYAN}[INFO]${NC}    $*"; }
+info()    { printf "%b\n"   "${CYAN}[INFO]${NC}    $*"; }
-success() { echo -e "${GREEN}[OK]${NC}      $*"; }
+success() { printf "%b\n"   "${GREEN}[OK]${NC}      $*"; }
-warn()    { echo -e "${YELLOW}[WARN]${NC}    $*"; }
+warn()    { printf "%b\n"   "${YELLOW}[WARN]${NC}    $*"; }
-error()   { echo -e "${RED}[ERROR]${NC}   $*" >&2; }
+error()   { printf "%b\n"   "${RED}[ERROR]${NC}   $*" >&2; }
-step()    { echo -e "\n${BOLD}${YELLOW}━━━ $* ━━━${NC}"; }
+die()     { error "$*"; exit 1; }
+step()    { printf "\n%b\n" "${BOLD}${YELLOW}━━━ $* ━━━${NC}"; }
 
 box() {
   local max_len=0
@@ -28,9 +29,9 @@ box() {
   done
   local border
   border=$(printf '─%.0s' $(seq 1 $((max_len + 2))))
-  echo -e "${CYAN}┌${border}┐${NC}"
+  printf "%b\n" "${CYAN}┌${border}┐${NC}"
   for line in "$@"; do
     printf "${CYAN}│${NC} %-${max_len}s ${CYAN}│${NC}\n" "$line"
   done
-  echo -e "${CYAN}└${border}┘${NC}"
+  printf "%b\n" "${CYAN}└${border}┘${NC}"
 }

lib/scaffold.sh

@@ -8,14 +8,17 @@ render_template() {
   local template_file="$1"
   local output_file="$2"
 
-  [[ ! -f "$template_file" ]] && { error "Template not found: ${template_file}"; exit 1; }
+  [[ ! -f "$template_file" ]] && { error "Template not found: ${template_file}"; return 1; }
 
   local content
-  content=$(cat "$template_file")
+  content=$(<"$template_file")
+
+  local genome_name_upper
+  genome_name_upper=$(tr '[:lower:]' '[:upper:]' <<< "${GENOME_NAME}")
 
   # Placeholder replacement
   content="${content//\{\{GENOME_NAME\}\}/${GENOME_NAME}}"
-  content="${content//\{\{GENOME_NAME_UPPER\}\}/${GENOME_NAME^^}}"
+  content="${content//\{\{GENOME_NAME_UPPER\}\}/${genome_name_upper}}"
   content="${content//\{\{GENOME_DESC\}\}/${GENOME_DESC}}"
   content="${content//\{\{FORGEJO_URL\}\}/${FORGEJO_URL}}"
   content="${content//\{\{FORGEJO_USER\}\}/${FORGEJO_USER}}"

providers/forgejo.sh

@@ -31,8 +31,8 @@ provider_create_repo() {
   case "$http_code" in
     201) success "Repository '${name}' created successfully." ;;
     409) info    "Repository '${name}' already exists - skipping." ;;
-    401) error   "Unauthorized. Check your FORGEJO_TOKEN."; exit 1 ;;
+    401) error   "Unauthorized. Check your FORGEJO_TOKEN."; return 1 ;;
-    *)   error   "Forgejo API returned HTTP ${http_code}. Check connectivity."; exit 1 ;;
+    *)   error   "Forgejo API returned HTTP ${http_code}. Check connectivity."; return 1 ;;
   esac
 }
 
@@ -44,8 +44,7 @@ provider_ssh_url() {
   local host
   # Extract hostname by removing protocol and trailing slashes
   host=$(echo "${FORGEJO_URL}" | sed -e 's|^[^/]*//||' -e 's|/*$||')
-  # Using port 222 as default for many homelab Forgejo/Gitea setups
+  echo "ssh://git@${host}:${FORGEJO_SSH_PORT:-222}/${FORGEJO_USER}/${1}.git"
-  echo "ssh://git@${host}:222/${FORGEJO_USER}/${1}.git"
 }
 
 provider_web_url() {

providers/github.sh

@@ -37,7 +37,7 @@ provider_create_repo() {
   case "$http_code" in
     201) success "Repository '${name}' created on GitHub." ;;
     422) info    "Repository '${name}' already exists - skipping." ;;
-    *)   error   "GitHub API returned HTTP ${http_code}. check token/permissions."; exit 1 ;;
+    *)   error   "GitHub API returned HTTP ${http_code}. Check token/permissions."; return 1 ;;
   esac
 }
 

registry.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# =============================================================================
+# registry.sh - Knowledge Genome Registry
+# Dynamic paths and genome definitions.
+# =============================================================================
+
+# Guard against double sourcing
+[[ -n "${_REGISTRY_LOADED:-}" ]] && return
+_REGISTRY_LOADED=1
+
+# Resolve project root relative to this file
+PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Dynamic paths
+WORK_DIR="${HOME}/knowledge-genome-setup"
+KEYS_DIR="${WORK_DIR}/keys"
+TEMPLATES_DIR="${PROJECT_ROOT}/templates"
+LIB_DIR="${PROJECT_ROOT}/lib"
+PROVIDERS_DIR="${PROJECT_ROOT}/providers"
+
+# --- GENOME REGISTRY ---
+# Format: "name|description"
+GENOMES=(
+  "genome-dev|Web development, TUI, Angular, software architecture"
+  "genome-finance|Personal finance, investments, market analysis"
+  "genome-homelab|Keru infrastructure, network configs, architecture logs"
+)

scripts/add-genome.sh

@@ -6,7 +6,8 @@
 
 set -euo pipefail
 source "lib/output.sh"
-source "config.env"
+source "globals.env"
+source "registry.sh"
 
 GENOME_NAME="${1:-}"
 GENOME_DESC="${2:-}"
@@ -19,10 +20,8 @@ fi
 
 step "Adding New Genome: ${GENOME_NAME}"
 
-# Sovrascrivo l'array per la sessione corrente
 GENOMES=("${GENOME_NAME}|${GENOME_DESC}")
 
-# FIX BUG 2: Uso source invece di bash per mantenere il context dell'array
 source "scripts/setup-genomes.sh"
 
 success "Genome '${GENOME_NAME}' added and linked successfully!"

scripts/lint-genomes.sh

@@ -2,13 +2,14 @@
 # =============================================================================
 # scripts/lint-genomes.sh
 # Executes quality control across all registered genomes.
-# Iterates from the GENOMES registry in config.env — not from filesystem patterns —
+# Iterates from the GENOMES registry in registry.sh — not from filesystem patterns —
 # so all genomes are covered regardless of their naming convention.
 # =============================================================================
 
 set -euo pipefail
 source "lib/output.sh"
-source "config.env"
+source "globals.env"
+source "registry.sh"
 source "lib/lint.sh"
 
 step "Starting Knowledge Genome Linting"
@@ -30,18 +31,15 @@ for entry in "${GENOMES[@]}"; do
     # Lint all .md files except AGENTS.md and core-karpathy reference
     while IFS= read -r md_file; do
 
-        lint_markdown_file "$md_file" "$GENOME_NAME"
+        lint_markdown_file "$md_file" "$GENOME_NAME" && fe=0   || fe=$?
-        file_errors=$?
+        check_privacy_consistency "$md_file"          && pce=0  || pce=$?
-        TOTAL_ERRORS=$((TOTAL_ERRORS + file_errors))
+        check_page_size "$md_file"                    && pse=0  || pse=$?
+        TOTAL_ERRORS=$((TOTAL_ERRORS + fe + pce + pse))
 
-        check_privacy_consistency "$md_file"
+        check_knowledge_decay "$md_file"              && stale=0 || stale=$?
-        TOTAL_ERRORS=$((TOTAL_ERRORS + $?))
-
-        check_knowledge_decay "$md_file"
-        stale=$?
         TOTAL_STALE=$((TOTAL_STALE + stale))
 
-        check_broken_links "$md_file"
+        check_broken_links "$md_file" || true   # warnings only, never contributes to errors
 
     done < <(find "$genome_dir" -name "*.md" \
                 ! -name "AGENTS.md" \

scripts/setup-genomes.sh

@@ -6,7 +6,12 @@
 
 set -euo pipefail
 source "lib/output.sh"
-source "config.env"
+source "globals.env"
+
+if [[ -z "${WORK_DIR:-}" ]]; then
+    source "registry.sh"
+fi
+
 source "lib/scaffold.sh"
 source "lib/git-crypt.sh"
 source "providers/${PROVIDER}.sh"
@@ -25,11 +30,10 @@ for entry in "${GENOMES[@]}"; do
 
     GENOME_PATH="${WORK_DIR}/${MASTER_REPO}/${GENOME_NAME}"
 
-    if [ ! -d "${GENOME_PATH}" ]; then
+    if [[ ! -d "${GENOME_PATH}" ]]; then
         cd "${WORK_DIR}/${MASTER_REPO}"
         info "Linking ${GENOME_NAME} as a submodule..."
 
-        # FIX BUG 1: Adding the submodule clones the empty remote repository
         git submodule add "${SSH_URL}" "${GENOME_NAME}"
 
         cd "${GENOME_NAME}"
@@ -45,12 +49,14 @@ for entry in "${GENOMES[@]}"; do
         git commit -m "feat: initial scaffold and git-crypt init for ${GENOME_NAME}"
         git push -u origin main
 
-        # Key export and instructions (Fix Obs B)
+        # Key export and instructions
         gcrypt_export_key "${GENOME_NAME}"
         gcrypt_print_key_instructions "${GENOME_NAME}"
 
-        # Return to master to consolidate the submodule addition
+        # Commit the submodule reference in the master repo
         cd "${WORK_DIR}/${MASTER_REPO}"
+        git commit -m "feat: add ${GENOME_NAME} as submodule"
+        git push origin main
     fi
 done
 

scripts/setup-master.sh

@@ -6,7 +6,8 @@
 
 set -euo pipefail
 source "lib/output.sh"
-source "config.env"
+source "globals.env"
+source "registry.sh"
 source "lib/scaffold.sh"
 source "providers/${PROVIDER}.sh" # Required for remote creation
 
@@ -18,7 +19,7 @@ provider_create_repo "${MASTER_REPO}" "Knowledge Genome Master Repository" "true
 mkdir -p "${WORK_DIR}/${MASTER_REPO}"
 cd "${WORK_DIR}/${MASTER_REPO}"
 
-if [ ! -d ".git" ]; then
+if [[ ! -d ".git" ]]; then
     info "Initializing Git in Master repository..."
     git init
 
@@ -26,7 +27,7 @@ if [ ! -d ".git" ]; then
     SSH_URL=$(provider_ssh_url "${MASTER_REPO}")
     git remote add origin "${SSH_URL}"
 
-    if [ -n "${GIST_URL:-}" ]; then
+    if [[ -n "${GIST_URL:-}" ]]; then
         info "Adding core-karpathy as an external reference..."
         git submodule add "${GIST_URL}" core-karpathy || warn "Could not add core-karpathy submodule."
     fi

scripts/setup.sh

@@ -9,8 +9,10 @@ set -euo pipefail
 
 # Resolve script directory and source core components
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "${SCRIPT_DIR}"   # All child scripts use relative paths from project root
 source "${SCRIPT_DIR}/lib/output.sh"
-source "${SCRIPT_DIR}/config.env"
+source "${SCRIPT_DIR}/globals.env"
+source "${SCRIPT_DIR}/registry.sh"
 source "${SCRIPT_DIR}/lib/deps.sh"
 
 step "Starting Knowledge Genome Setup"
@@ -24,7 +26,7 @@ check_git_identity
 info "Initializing Master Repository..."
 bash "${SCRIPT_DIR}/scripts/setup-master.sh"
 
-# 3. Genomes Provisioning (as defined in config.env)
+# 3. Genomes Provisioning (as defined in registry.sh)
 info "Provisioning registered Genomes..."
 bash "${SCRIPT_DIR}/scripts/setup-genomes.sh"