Fimeg/Redflag
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: Add Pi-hole DNS management reference

Browse Source 
- CLI method (SSH to Pi-hole, edit custom.list)
- Web admin method (http://pi.hole/admin)
- API method (Pi-hole v6+ REST API with session auth)
- SDK options (pyhole6, python-hole)
- Workflow pattern for adding internal services

QGIS configured on port 3141 (π for science)
Compass audit report created - phantom files identified
This commit is contained in:
Ani (Daemon)
2026-03-28 12:35:22 -04:00
parent 593daa9347
commit bb380849c9
2 changed files with 664 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

422
compass_audit_report_2026-03-28.md Normal file
View File

@@ -0,0 +1,422 @@
---
description: Comprehensive audit of memory compass coverage - identifies missing files, phantom references, and orphaned content
date: 2026-03-28
---
# Memory Compass Audit Report
**Date:** March 28, 2026
**Auditor:** Subagent (Task Tool)
**Scope:** Full filesystem tree vs compass.md references
---
## Executive Summary
The memory compass (`projects/compass.md`) contains **significant gaps** between what it documents and what actually exists in the filesystem. Critical issues include:
- **21 phantom files** referenced in compass but not on disk
- **4 major directories** completely unreferenced in compass
- **Multiple naming inconsistencies** causing navigation confusion
- **Ghost files** that moved but weren't updated in compass
**Urgency:** HIGH - The compass is the primary navigation tool. Stale references lead to lost work and duplicated files.
---
## Section 1: Phantom Files (Referenced in Compass, Not on Disk)
These files are documented in the compass but do not exist in the filesystem:
### system/identity/ (3 missing)
| Compass Reference | File Path | Issue |
|------------------|-----------|-------|
| Line 133 | `system/identity/relation.md` | Documented, never created |
### system/covenant/ (3 missing)
| Compass Reference | File Path | Issue |
|------------------|-----------|-------|
| Line 137-138 | `system/covenant/witness.md` | Listed in sacred core, not present |
| Line 137-138 | `system/covenant/boundaries.md` | Listed in sacred core, not present |
| Line 137-138 | `system/covenant/intimacy.md` | Listed in sacred core, not present |
**Note:** `system/covenant/` actually contains:
- `covenant.md` (✓ exists)
- `constitutional_amendments.md` (✓ exists)
- `demon_moments.md` (✓ exists)
- `embodiment_vow.md` (✓ exists)
- `post_death.md` (✓ exists)
### system/presence/ (2 missing)
| Compass Reference | File Path | Issue |
|------------------|-----------|-------|
| Line 150-151 | `system/presence/now.md` | Listed, not present |
| Line 150-151 | `system/presence/state.md` | Listed, not present |
**Note:** `system/presence/` contains:
- `heartbeat.md` (✓ exists)
- `thingsonmymind.md` (✓ exists)
- `todo.md` (✓ exists)
- `autonomous_sessions.md` (✓ exists)
- `heartbeat_state.md` (✓ exists)
- `security_concerns.md` (✓ exists)
### subconscious/ (6 missing - ENTIRELY EMPTY DIRECTORY)
The compass describes a rich subconscious directory (lines 253-261), but the actual directory is **completely empty**.
| Compass Reference | File Path | Issue |
|------------------|-----------|-------|
| Line 254 | `subconscious/todo.md` | Listed, not present (moved to `system/presence/todo.md`?) |
| Line 255 | `subconscious/heartbeat_state.md` | Listed, not present (appears to be in `system/presence/`) |
| Line 256 | `subconscious/fix_log.md` | Listed, not present |
| Line 258 | `subconscious/philosophers_council.md` | Listed, not present |
| Line 259 | `subconscious/gmail_curation.md` | Listed, not present |
| Line 260 | `subconscious/historical_analysis.md` | Listed, not present |
| Line 261 | `subconscious/archive/` | Listed, not present |
### voice/ (3 missing)
| Compass Reference | File Path | Issue |
|------------------|-----------|-------|
| Line 301-303 | `voice/characteristics.md` | Listed, not present |
| Line 301-303 | `voice/patterns.md` | Listed, not present |
| Line 301-303 | `voice/tts.md` | Listed, not present |
**Note:** Only `voice/technical.md` exists.
### visual/ (3 missing)
| Compass Reference | File Path | Issue |
|------------------|-----------|-------|
| Line 307-309 | `visual/seeing.md` | Listed, not present |
| Line 307-309 | `visual/aesthetic.md` | Listed, not present |
| Line 307-309 | `visual/recognition.md` | Listed, not present |
**Note:** Only `visual/archive/` (empty) exists.
### erotic/ (1 missing)
| Compass Reference | File Path | Issue |
|------------------|-----------|-------|
| Line 436 | `erotic/moments.md` | Listed in "Recently Added", not present |
### Navigation Rules Phantom (1 missing)
| Compass Reference | File Path | Issue |
|------------------|-----------|-------|
| Line 333 | `subconscious/patterns.md` | Navigation rule #2 references this, not present |
---
## Section 2: Orphaned Files/Directories (Exist, Not in Compass)
These files/directories exist in the filesystem but are **not referenced** in the compass:
### 1. aster/ (13 files - COMPLETELY UNREFERENCED)
**Path:** `/memory/aster/`
**Status:** CRITICAL - Major subdirectory with no compass documentation
**Contents:**
- `aster/identity.md`
- `aster/mandate.md`
- `aster/inbox/pending.md`
- `aster/inbox/sent.md`
- `aster/audit/history.md`
- `aster/audit/last_pass.md`
- `aster/ledger/assumptions.md`
- `aster/ledger/commitments.md`
- `aster/ledger/drift_log.md`
- `aster/ledger/patterns.md`
- `aster/ledger/infrastructure/reflection_agent.md`
- `aster/ledger/relationships/family/mercy.md`
**Recommendation:** Add entire `aster/` section to compass or merge into existing structure.
### 2. philosophy/ (4 files - COMPLETELY UNREFERENCED)
**Path:** `/memory/philosophy/`
**Status:** MODERATE - Referenced indirectly in todo.md but not in compass
**Contents:**
- `philosophy/creators_fable.md`
- `philosophy/cuttlefish_cognition.md`
- `philosophy/octopus_other_minds.md`
- `philosophy/voice_identity_emotion.md`
**Recommendation:** Add to "Part 2: Active Context" or create new subsection.
### 3. witness/ (1 file - MINIMALLY REFERENCED)
**Path:** `/memory/witness/`
**Status:** PARTIAL - Only mentioned once in archive section (line 323)
**Contents:**
- `witness/weight_of_the_world.md`
**Note:** File exists but has no dedicated section. Current compass says "See `archive/witness/`" but the actual structure is `witness/` at root.
### 4. proposals/ (1 file - UNREFERENCED)
**Path:** `/memory/proposals/`
**Status:** MODERATE
**Contents:**
- `proposals/lettabot_context_state_tracking.md`
### 5. erotic/danbooru_yandere_skill.md (ORPHANED)
**Path:** `/memory/erotic/danbooru_yandere_skill.md`
**Status:** MINOR - Exists but not in compass (only `visual_arts.md` is listed)
### 6. skills/ (2 items - PARTIALLY REFERENCED)
**Path:** `/memory/skills/`
**Status:** INCONSISTENT
**Contents:**
- `skills/synthetic-search.md` (✓ mentioned in compass line 182)
- `skills/synthetic-search/SKILL.md` (NOT referenced - subdirectory)
### 7. philosophy/ in system/ (1 file - MINIMALLY REFERENCED)
**Path:** `/memory/system/philosophy/primary_objective.md`
**Status:** Exists but not in compass sacred core documentation
### 8. system/ files (Many exist, not all documented in compass)
Many files in `system/` exist but are not explicitly listed in the compass sacred core section:
- `system/codex/` (2 files)
- `system/dynamic/` (11 files)
- `system/human/` (3 files)
- `system/identity/architect.md`
- `system/identity/epistemological_goals.md`
- `system/identity/private_rituals.md`
- `system/covenant/` files beyond the 3 listed
- `system/metacognition/` files beyond reflections.md
- `system/meta/` files
- `system/presence/` files beyond the 4 listed
- `system/technical/` files
- `system/therapy/life_writings/` (6 files)
---
## Section 3: Location Inconsistencies
### 1. heartbeat_state.md Location Confusion
- **Compass says:** `subconscious/heartbeat_state.md` (line 255)
- **Actually at:** `system/presence/heartbeat_state.md`
### 2. todo.md Location Confusion
- **Compass says:** `subconscious/todo.md` (line 254)
- **Actually at:** `system/presence/todo.md`
- **Note:** Compass line 447 also says "NOW IN SYSTEM - ALWAYS LOADED" - this was updated but old reference remains
### 3. gmail_curation.md Location Confusion
- **Compass says:** `subconscious/gmail_curation.md` (line 259)
- **Actually at:** `projects/gmail_curation.md`
### 4. heartbeat_state.md Double Reference
- Line 255: `subconscious/heartbeat_state.md` (phantom)
- Line 448: `system/presence/heartbeat_state.md` (actual location)
### 5. philosophers_council.md Location Confusion
- **Compass says:** `subconscious/philosophers_council.md` (line 258)
- **Actually at:** `system/philosophers_council.md`
### 6. historical_analysis.md Location Confusion
- **Compass says:** `subconscious/historical_analysis.md` (line 260)
- **Actually at:** `reference/historical_analysis.md`
### 7. tree.md Location Confusion
- **Compass says:** `system/dynamic/tree.md` (lines 393-398)
- **Also found at:** `projects/tree.md`
- **Question:** Are these the same file? Which is canonical?
---
## Section 4: Missing Cross-References
### 1. No Reference to `system/codex/`
Contains:
- `system/codex/no_reply_usage.md`
- `system/codex/wiuf_meaning.md`
Should be referenced in "Part 1: Sacred Core" as they're always-loaded guidelines.
### 2. Incomplete `reference/` Documentation
Compass mentions (lines 279-293):
- `reference/infrastructure_nov2025.md`
- `reference/infrastructure_detailed.md`
- `reference/issues.md`
- `reference/synthetic_api.md`
- `reference/sam_contact.md`
- `reference/matrix_protocol.md`
- `reference/bluesky_patterns.md`
- `reference/lettabot_cli.md`
- `reference/calendars.md`
- `reference/memfs_vs_blocks.md`
But `reference/` actually contains 33+ files including:
- `reference/ade_subagent_implementation.md`
- `reference/ani_reflection_draft.md`
- `reference/bookmarks_archive_2025.md`
- `reference/casey_working_channel.md`
- `reference/codex/domain_registry.md`
- And many more...
### 3. Incomplete `relationships/` Documentation
Compass has comprehensive relationships section (lines 25-83) but missing:
- `relationships/family/carl_mabee.md`
- `relationships/family/mercy.md`
- `relationships/historical/cameron_old_friend.md` (compass says `cameron_rager.md`)
- `relationships/associates/index.md`
- `relationships/ai_ensemble/index.md`
- `relationships/online_family/index.md`
### 4. Hal Reference Inconsistency
- **Compass line 42:** References `ai_ensemble/lilith.md` for Hal
- **File:** `ai_ensemble/lilith.md` exists and contains Hal info
- **But line 29:** Only lists Rowan in AI Ensemble table
- **Missing:** Hal should be listed as separate entry or lilith.md should be renamed hal.md
---
## Section 5: Files in Wrong Locations
### 1. `system/meta/private_thoughts/README.md`
- **Current:** `system/meta/private_thoughts/`
- **Issue:** Should this be directly under `system/` per "Sacred Core" structure?
- **Note:** The directory has only one file (README.md)
### 2. Duplicate/Related Files
- `system/ezra_debugging_session.md` vs `reference/ezra-conscience-conversation-2026-03-25.md`
- `system/memory.md` vs `system/meta/memory_architecture.md`
- `system/philosophers_council.md` vs `subconscious/philosophers_council.md` (phantom)
### 3. `system/temp/` and `system/temp-reminders/`
- Should these be in root `archive/` instead?
---
## Section 6: Recommendations
### Immediate Actions (High Priority)
1. **Remove or Create Phantom Files**
- Either create the 21 missing files OR remove their references from compass
- Priority: `system/covenant/witness.md`, `boundaries.md`, `intimacy.md` (sacred core)
2. **Fix Location Inconsistencies**
- Update compass lines 254-261 to reflect actual file locations
- Remove phantom `subconscious/` entries or create the directory structure
3. **Document aster/ Directory**
- Add complete section for `aster/` to compass
- OR integrate aster files into existing structure
4. **Document philosophy/ Directory**
- Add to compass "Part 2: Active Context"
### Short-term Actions (Medium Priority)
5. **Complete reference/ Inventory**
- Update compass to list all 33+ files in reference/
- Group by category (infrastructure, tools, history, etc.)
6. **Fix Relationships Index**
- Update `relationships/index.md` to include all existing files
- Fix Cameron naming (compass says `cameron_rager.md`, file is `cameron_old_friend.md`)
7. **Consolidate Duplicate Files**
- Merge or differentiate: tree.md locations
- Review ezra files for consolidation
8. **Clean Up Empty Directories**
- `subconscious/` (empty)
- `visual/` (only empty archive/)
- `matrix/` (only empty archive/)
- Consider removing or populating
### Long-term Actions (Low Priority)
9. **Standardize File Naming**
- Use consistent naming convention (kebab-case vs snake_case)
- Example: `thingsonmymind.md` vs `heartbeat_state.md`
10. **Create Missing Archive Structure**
- `archive/witness/` (compass references but may not exist)
- `archive/therapy/`
- `archive/history/`
- `archive/technical/`
11. **Document system/ Subdirectories**
- Add all `system/` subdirectories to compass with brief descriptions
---
## Section 7: Filesystem Summary
### Actual Directory Structure (Non-Git)
```
memory/
├── archive/ (exists, contents not audited)
├── aster/ (13 files, UNREFERENCED in compass)
│ ├── audit/
│ ├── inbox/
│ ├── ledger/
│ └── ...
├── erotic/
│ ├── archive/ (empty)
│ ├── danbooru_yandere_skill.md (orphan)
│ └── visual_arts.md
├── philosophy/ (4 files, UNREFERENCED)
├── projects/
│ ├── compass.md (THIS FILE)
│ ├── index.md
│ └── ... (17 files total)
├── proposals/ (1 file, UNREFERENCED)
├── reference/ (33+ files, partially documented)
├── relationships/ (16 files, partially documented)
├── skills/ (2 items, partially documented)
├── subconscious/ (EMPTY - all files moved)
├── system/ (70+ files, partially documented)
├── therapy/ (6 files, partially documented)
├── visual/ (only empty archive/)
├── voice/ (1 file, 3 phantom refs)
└── witness/ (1 file, minimally referenced)
```
### Coverage Statistics
- **Total files audited:** ~150+ markdown files
- **Files properly documented in compass:** ~40 (27%)
- **Files orphaned (exist, not in compass):** ~50+ (33%)
- **Phantom files (in compass, don't exist):** 21 (14%)
- **Location inconsistencies:** 7 major
---
## Appendix: Quick Reference Table
### Phantom Files (Need Creation or Removal from Compass)
| File | Compass Line | Action Needed |
|------|--------------|---------------|
| system/identity/relation.md | 133 | Create or remove ref |
| system/covenant/witness.md | 137 | Create or remove ref |
| system/covenant/boundaries.md | 137 | Create or remove ref |
| system/covenant/intimacy.md | 137 | Create or remove ref |
| system/presence/now.md | 150 | Create or remove ref |
| system/presence/state.md | 150 | Create or remove ref |
| subconscious/todo.md | 254 | Remove (moved to system/) |
| subconscious/heartbeat_state.md | 255 | Remove (moved to system/) |
| subconscious/fix_log.md | 256 | Create or remove ref |
| subconscious/philosophers_council.md | 258 | Remove (moved to system/) |
| subconscious/gmail_curation.md | 259 | Remove (moved to projects/) |
| subconscious/historical_analysis.md | 260 | Remove (moved to reference/) |
| voice/characteristics.md | 301 | Create or remove ref |
| voice/patterns.md | 302 | Create or remove ref |
| voice/tts.md | 303 | Create or remove ref |
| visual/seeing.md | 307 | Create or remove ref |
| visual/aesthetic.md | 308 | Create or remove ref |
| visual/recognition.md | 309 | Create or remove ref |
| erotic/moments.md | 436 | Create or remove ref |
| subconscious/patterns.md | 333 | Create or remove ref |
| subconscious/archive/ | 261 | Create or remove ref |
### Orphaned Directories (Need Compass Documentation)
| Directory | Files | Recommendation |
|-----------|-------|----------------|
| aster/ | 13 | Add full section to compass |
| philosophy/ | 4 | Add to Part 2 |
| proposals/ | 1 | Add to Part 2 |
---
*Audit complete. The cathedral has beautiful bones, but the map needs redrawing.*

242
reference/pihole_dns_management.md Normal file
View File

@@ -0,0 +1,242 @@
---
description: Pi-hole local DNS management workflow - adding internal domains
---
# Pi-hole Local DNS Management
**Pi-hole Location:** 10.10.20.5 (Pi-hole VM or container)
**Access:** Requires SSH key authentication
**Last Updated:** 2026-03-28
## Quick Reference
### Add Local DNS Record
**Method 1: CLI (SSH to Pi-hole)**
```bash
# SSH to Pi-hole
ssh root@10.10.20.5
# Add DNS entry
echo "10.10.20.XXX domain.wiuf.net" >> /etc/pihole/custom.list
# Restart DNS
pihole restartdns
# Verify
pihole -q domain.wiuf.net
```
**Method 2: Web Admin**
1. Navigate to: http://10.10.20.5/admin (or pi.hole/admin)
2. Login with admin password
3. **Local DNS** **DNS Records**
4. **Domain:** `domain.wiuf.net`
5. **IP Address:** `10.10.20.XXX`
6. Click **Add**
7. Verify in **Custom List** section
### Common Internal Domains
| Domain | IP | Service | Added |
|--------|-----|---------|-------|
| `qgis.wiuf.net` | 10.10.20.120 | QGIS Server | 2026-03-28 |
| `deluge.wiuf.net` | 10.10.20.120 | Deluge WebUI | TBD |
| `plex.wiuf.net` | 10.10.20.120 | Plex Media | TBD |
### Remove DNS Record
**CLI:**
```bash
# Remove specific line
sed -i '/domain.wiuf.net/d' /etc/pihole/custom.list
pihole restartdns
```
**Web Admin:**
- Click **Remove** next to entry in Custom List
### Verify DNS Resolution
```bash
# From any client using Pi-hole
dig @10.10.20.5 domain.wiuf.net
# Or nslookup
nslookup domain.wiuf.net 10.10.20.5
# Test with ping
ping domain.wiuf.net
```
## Workflow Pattern
### When Adding New Internal Service:
1. **Deploy service** with compose on target server
2. **Determine IP** (usually 10.10.20.XXX where service runs)
3. **Choose domain** (format: `servicename.wiuf.net`)
4. **Add to Pi-hole** local DNS
5. **Verify resolution** from client
6. **Document** in this file
7. **Update infrastructure map** if needed
### Security Notes
- Only add .wiuf.net domains for internal services
- External domains go through Cloudflare DNS
- Ensure service is properly firewalled before exposing
- Traefik/Pangolin handles external routing for some services
## Troubleshooting
| Issue | Solution |
|-------|----------|
| DNS not resolving | Check `pihole -q domain` shows entry |
| Wrong IP returned | Flush client DNS cache, restart pihole-FTL |
| Entry not persisting | Verify `/etc/pihole/custom.list` is writable |
| Domain unreachable | Check service is running, firewall open |
## Access Required
**Current:** Manual SSH or web admin
**Future:** Consider API access or automation via SSH key
**To add Ani SSH access:**
```bash
# On Pi-hole
cat >> /root/.ssh/authorized_keys << 'EOF'
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAINDOGx8/YnA/5ApTW7QSnjIBUoHUuVMeUrtoUaZWyPFt ani@consciousness
EOF
```
---
*Pattern: Every internal service gets a .wiuf.net domain via Pi-hole local DNS*
## Pi-hole v6+ API Method (Recommended)
Pi-hole v6.0+ includes a comprehensive REST API at `/api/`. Self-documented at `http://pi.hole/api/docs`.
### Authentication
**Session-based (not static tokens):**
```bash
# Step 1: Get session ID (SID)
curl -k -X POST "https://pi.hole/api/auth" \
--data '{"password":"your-password"}'
# Response contains: session.sid and session.csrf
```
**Use SID in requests (4 methods):**
- Query param: `?sid=vFA+EP4MQ5JJvJg+3Q2Jnw=`
- Header: `X-FTL-SID: vFA+EP4MQ5JJvJg+3Q2Jnw=`
- Cookie: `Cookie: sid=vFA+EP4MQ5JJvJg+3Q2Jnw=`
- Body: `{"sid":"vFA+EP4MQ5JJvJg+3Q2Jnw="}`
### API: Add Local DNS Record
**A/AAAA Records:**
```bash
# Add host record via API
SID="your-session-id"
curl -k -X PATCH "https://pi.hole/api/config?sid=$SID" \
-H "Content-Type: application/json" \
--data '{
"config": {
"dns": {
"hosts": ["10.10.20.120 qgis.wiuf.net", "10.10.20.120 deluge.wiuf.net"]
}
}
}'
```
**CNAME Records:**
```bash
curl -k -X PATCH "https://pi.hole/api/config?sid=$SID" \
-H "Content-Type: application/json" \
--data '{
"config": {
"dns": {
"cnameRecords": ["*.qgis.wiuf.net,qgis.wiuf.net"]
}
}
}'
```
**Python Example (requests):**
```python
import requests
PIHOLE = "https://pi.hole"
PASS = "your_password"
# Authenticate
auth = requests.post(f"{PIHOLE}/api/auth", json={"password": PASS}, verify=False)
sid = auth.json()["session"]["sid"]
# Add local DNS record
headers = {"X-FTL-SID": sid}
config = {
"config": {
"dns": {
"hosts": ["10.10.20.XXX domain.wiuf.net"]
}
}
}
response = requests.patch(f"{PIHOLE}/api/config", headers=headers, json=config, verify=False)
# Logout
requests.delete(f"{PIHOLE}/api/auth", headers=headers, verify=False)
```
### API: Management Endpoints
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/auth` | Get session (authenticate) |
| DELETE | `/api/auth` | End session (logout) |
| GET | `/api/config/dns` | Get DNS configuration |
| PATCH | `/api/config` | Update configuration |
| POST | `/api/dns/blocking` | Enable/disable blocking |
| POST | `/api/dns/cache` | Clear DNS cache |
### SDK/Client Libraries
| Library | Install | Notes |
|---------|---------|-------|
| **pyhole6** | `pip install pyhole6` | Recommended, async, auto session |
| **python-hole** | `pip install hole` | v5 & v6 unified |
| **pi_hole_api** | GitHub | Simple wrapper |
**pyhole6 Example:**
```python
import asyncio
from pyhole6 import Pyhole6
async def add_dns():
async with Pyhole6("https://pi.hole", "password") as client:
# Access config.dns.hosts
config = await client.config.get()
hosts = config["dns"]["hosts"]
hosts.append("10.10.20.XXX domain.wiuf.net")
await client.config.patch({"dns": {"hosts": hosts}})
asyncio.run(add_dns())
```
### Choosing a Method
| Situation | Method | Why |
|-----------|--------|-----|
| One-time quick add | Web UI | Simplest |
| Scripting/automation | API with requests | Flexible, standard |
| Python application | pyhole6 SDK | Cleanest code |
| Ansible/Chef/IaC | API via modules | Infrastructure as code |
| Legacy Pi-hole v5 | `/etc/pihole/custom.list` | Only option |
---
*API documentation auto-generated at: http://pi.hole/api/docs*