local-docs

name: local-docs description: Answer Linux administration and debugging questions using local machine documentation first. Use when the user asks about Linux commands, config files, system calls, kernel parameters, daemons, packages, or any sysadmin/debugging topic and wants to consult man pages, info pages, /usr/share/doc, package examples, or header files under /usr/include. Also handles finding installable documentation packages via apt-cache search, apt-file search, dnf repoquery, or yum provides when local docs are incomplete. Prefer this over web search for any Linux-specific documentation lookup.

Local Docs

Overview

Answer Linux administration and debugging questions by consulting the local machine's documentation first. Search installed man pages, info pages, /usr/share/doc, package examples, and header files before touching the network. If local docs are incomplete, search distro package metadata for installable documentation and ask before recommending any install. Always show exact file paths and verbatim command/config snippets.

Run Workflow

1. Detect the distro and package manager:

   cat /etc/os-release
   

   Map ID or ID_LIKE to the package manager: apt (Debian/Ubuntu), dnf/yum (RHEL/Fedora/CentOS), pacman (Arch), zypper (SUSE).

2. Search installed man pages:

   man -k <keyword>          # full-text keyword search across all installed man pages
   man <topic>               # default section
   man 5 <topic>             # section 5 = config files
   man 8 <topic>             # section 8 = admin commands
   manpath                   # show where man pages are stored
   

   Prefer man 5 for config file questions, man 8 for daemon/admin commands, man 1 for user commands.

3. Search info pages:

   info <topic>
   ls /usr/share/info/ | grep -i <topic>
   

   Info pages often contain more detail than man pages for GNU tools (coreutils, bash, make, etc.).

4. Search /usr/share/doc/:

   ls /usr/share/doc/ | grep -i <pkg>
   ls /usr/share/doc/<pkg>/
   

   Look for: README, README.Debian, examples/, *.conf.example, changelog.gz, NEWS.gz. Read examples verbatim and cite their path.

5. Search header files (for system calls, library APIs, kernel interfaces):

   grep -r "<symbol>" /usr/include/ -l          # find relevant headers
   grep -n "<symbol>" /usr/include/<path>.h     # show definition with line numbers
   

6. Evaluate completeness. If the installed docs fully answer the question, stop here. Report the answer with exact file paths cited for every snippet.

7. Search distro metadata for installable docs (only if local docs are incomplete):

   Debian/Ubuntu:

   # Check if apt-file is available first
   command -v apt-file && apt-file search <topic> || echo "apt-file not installed"
   apt-cache search <pkg>-doc
   apt-cache show <pkg>-doc 2>/dev/null | grep -E "^(Package|Description)"
   

   RHEL/Fedora/CentOS:

   dnf search doc <pkg>
   dnf repoquery --provides <pkg>
   yum provides <file-or-symbol>   # fallback if dnf unavailable
   

   Arch Linux:

   pacman -Ss <pkg>
   

8. Label every result clearly:

   • Prefix installed sources with [Installed]
   • Prefix uninstalled packages with [Available — not installed]

9. Suggest the smallest relevant doc package if one is found uninstalled. Do NOT suggest installing it — ask first:

   The package <pkg>-doc contains the missing documentation. Should I show you the install command?

10. Report with verbatim snippets, exact file paths, and the precise commands run.

Graceful Degradation

Source Priority

1. man / info pages — fastest, always try first
2. /usr/share/doc/ — READMEs, examples, changelogs
3. /usr/include/ — headers for system call / API questions
4. Distro package metadata — apt-file, apt-cache, dnf repoquery
5. Internet — only if user explicitly requests it

Guardrails

• Never run apt-get install, dnf install, or equivalent without explicit user confirmation.
• Always cite the exact file path for every snippet: # from /usr/share/doc/nginx/examples/nginx.conf
• Prefer the most targeted doc package: nginx-doc over reinstalling nginx.
• When using man -k, limit noise: pipe through grep -i <keyword> if results are excessive.
• For config file questions, always show the relevant man 5 section and the actual default config path.

Load Detailed Reference On Demand

Read references/sources.md when you need:

• Man page section number cheat-sheet
• /usr/share/doc/ common file layouts
• apt-file and dnf repoquery flag reference
• How to reverse-map a binary to its doc package with dpkg -S or rpm -qf