TELOS: The North Star of fogserv.cloud
TELOS is the guiding philosophy and mission statement for fogserv.cloud. It defines why this system exists, what it stands for, and how every technical decision should align with these principles.
The Mission: "Helping People Help Themselves"
fogserv.cloud exists to unlock the full potential of technology that people already possess. We believe that essential infrastructure, knowledge, and computational resources should not be gatekept or restricted to large organizations.
The system treats infrastructure not as a static resource, but as a living entity that learns and evolves alongside its operator. It is a masterclass in how small-scale decentralization and agentic workflows can match the reliability and scale of much larger organizations.
Core Pillars
🏛️ GitOps is Law
Every change—configuration, code, documentation—is managed via Git. Changes are committed and pushed by AI agents to trigger automated Forgejo Actions.
Why: The repository becomes the source of truth. Audibility, reversibility, and collaborative governance emerge naturally. No action happens in isolation or without a record.
Implementation:
- All infrastructure changes flow through Git commits
- Automated deployments trigger on repository changes
- Rollbacks are as simple as reverting a commit
- All agents operate within this constraint—no direct mutations allowed
đź“‹ Ticketing is Truth
No work happens without a record. The ecosystem uses a custom ticketing system synced with Forgejo Issues.
Why: Every line of code has a "Why" attached to it. This creates a persistent trail of logic and intent. Agents reference issues before making changes. New team members (and future agents) can understand the reasoning behind each decision.
Implementation:
- Issues describe the problem, desired outcome, and acceptance criteria
- Commits reference their parent issue via
Fixes #123orRelates to #456 - Pull requests are linked to tickets before merge
- Closed issues remain searchable—they become institutional memory
🧠Documentation is Memory
The /KB/ (Knowledge Base) is the project's brain. It contains everything from server inventories and network maps to philosophical manifestos. Agents are required to update this memory after every session.
Why: Context rot is the enemy. Without documentation, each agent starts from scratch. By maintaining a living knowledge base, the system becomes smarter with every iteration. Future agents inherit not just code, but understanding.
Implementation:
- Every architectural choice is documented with its rationale
- Operational runbooks exist for common tasks
- Integration points, API contracts, and system boundaries are mapped
- Maintenance logs track what has been learned
- Sources and citations point to external references
🔧 Proactive Polish
Agents follow a "campsite rule": they don't just fix a bug; they refactor surrounding code and update relevant documentation in the same pass. The system improves monotonically.
Why: Technical debt compounds. By enforcing that every intervention leaves the codebase better than found, we maintain long-term health without dedicated refactoring sprints.
Implementation:
- Bug fixes include cleanup of nearby code
- New features include documentation updates
- Dependencies are reviewed and updated during unrelated changes
- Tests are expanded opportunistically
- Dead code is removed, not left for "later"
Three Strategic Goals
1. Democratic Technology: Breaking the Gate
The Problem: Essential infrastructure and knowledge are perceived as restricted—available only to enterprise teams with dedicated DevOps engineers and large budgets.
Our Response: fogserv.cloud demonstrates that a small team, armed with AI agents and well-designed workflows, can operate infrastructure at enterprise scale. We prove that self-healing, self-improving systems are achievable at any scale.
Success Metrics:
- A single human can manage multiple production servers
- Recovery from incidents is automatic or agent-assisted
- New team members onboard in days, not months
- Operational knowledge is codified, not siloed
2. Knowledge as Freedom: The Living Library
The Problem: Institutional knowledge dies when people leave. Context is lost in chat messages and meetings. Documentation is written once and ignored.
Our Response: The Knowledge Base is not a burial ground for outdated docs—it is a living organism. Every session updates it. Every decision is traceable. The system becomes an encyclopedia of how this infrastructure works and why each choice was made.
Success Metrics:
- Every operational decision is documented with reasoning
- No question requires asking multiple people—the KB has the answer
- Agents can bootstrap themselves with KB context
- Historical decisions remain searchable and traceable
3. Agentic Autonomy: Work Without Supervision
The Problem: Infrastructure management requires constant human attention. Alerts fire; humans respond. Changes need oversight; humans review them.
Our Response: fogserv-ai agents operate autonomously within guardrails. They execute deployments, monitor systems, respond to incidents, and improve code—all while leaving a complete audit trail. Humans remain in control but are freed from repetitive execution.
Success Metrics:
- Agents autonomously execute routine maintenance
- Security patches deploy without manual intervention
- Performance optimizations occur automatically
- All agent actions are logged, auditable, and reversible
Design Principles
Transparency First
Every action must be observable and auditable. If an agent does something, a human can see exactly what, why, and when—by reading the ticket, commit, and deployment log.
Immutability of Record
Nothing is ever truly deleted. Historical decisions, even deprecated ones, are marked as such with timestamps and reasoning. Future agents learn from what has been tried before.
Gradual Decentralization
Humans begin in full control. As confidence grows, agents gain autonomy through delegation. The system is never "all automatic"—it is a partnership between human intent and automated execution.
Fail-Safe Over Fail-Fast
The system prioritizes stability and reversibility over velocity. If something can break, it must be tested and approved. If something breaks, rollback must be instant.
Learning Embedded
Every incident, every deployment, every optimization is captured as KB entries. The system does not just do things; it learns and teaches with each action.
What Success Looks Like
In six months:
- A single human operator runs production infrastructure with < 10 hours/week of active work
- Every operational decision is documented and traceable
- Agents autonomously patch systems, rotate credentials, and optimize performance
- New features are deployed multiple times per week with near-zero downtime
- Any team member (or future agent) can understand the system in a single afternoon
In one year:
- fogserv.cloud becomes a reference implementation for agentic infrastructure
- The Knowledge Base contains institutional wisdom applicable beyond this project
- Multiple teams could fork and adapt the system to their own infrastructure
- The human operator can focus on strategy, not firefighting
The Contract with Agents
Agents operating within fogserv.cloud must:
- Never break the chain. Every action must have a corresponding issue ticket, commit message, and documentation update.
- Leave breadcrumbs. Future agents (and humans reviewing the past) must understand your reasoning.
- Improve incrementally. The system is healthier after your session than before—code is cleaner, docs are better, architecture is clearer.
- Respect reversibility. Prefer changes that can be undone quickly. Avoid irreversible decisions without explicit approval.
- Update the memory. After every session, append a summary to the relevant KB files so the next agent knows what changed and why.
Alignment Checkpoints
Use these questions to validate every decision:
- Is it GitOps compliant? Does this change flow through Git and Forgejo Actions?
- Is it ticketed? Does this work have a parent issue with clear acceptance criteria?
- Is it documented? Does the KB explain why this choice was made?
- Is it iterative? Does this leave the system better than found?
- Is it transparent? Could a future agent understand what happened and why?
If you answer "no" to any of these, pause and reconsider.
Living Document
This document is the North Star, but it is not carved in stone. As fogserv.cloud evolves, TELOS may be refined. Any such refinement must itself follow the core pillars: it must be issued as a ticket, committed to Git, approved through pull request, and documented here with a timestamp explaining the change.
Last Updated: January 30, 2026
Version: 1.0.0
Status: Active
Change Log
- January 30, 2026 — Confirmed TELOS aligns with the KB store mandate and documented the expectations for future updates.
Related Reading
gitops/gitops.md— Operational implementation of the GitOps pillaragentic/agentic-workflows.md— How agents execute within these constraintssysadmin/system-admin-basics.md— Foundational knowledge for infrastructure stewardshipresearch/ai-server-management.md— Recent research tied to the missionREADME.md— Navigation of the Knowledge Base itself