VillageOS manual
A plain-language guide to VillageOS, from the purpose of the system through every current project section, review state, permission, and working routine.
Guide version 2.2 · Updated September 30, 2026
The purpose
VillageOS helps a mission-driven team turn a community vision into a fundable, buildable project. It keeps strategy, land, capital, readiness, work, evidence, finance, and compliance connected instead of scattering them across spreadsheets, folders, inboxes, and people's heads.
The operating loop is Project Brain → Land → Capital → Readiness → Tasks → Data Room, supported by a separately restricted Finance & Compliance system. New work and evidence then flow back through the same loop.
Start here
Enter the exact invited email, then use the secure link sent to that inbox. VillageOS has no password to remember.
Choose the organization and project you are working on. Create a separate project only when it needs its own full pathway.
The dark-green tab is the current section. Move across the six tabs without returning to the Portfolio.
Unknown values should stay blank. Separate verified facts, planning assumptions, and unresolved questions.
After adding evidence or completing work, revisit Readiness and Tasks so conclusions and actions stay current.
Portfolio lists available projects. Team access shows members and trusted invitations when available to your role. Guide returns here. Inside a project, the horizontal tabs open its six connected sections.
Every project section
The shared strategic brief: what the team believes, knows, and still needs to resolve.
How to use it
Maintain the core vision, intended outcomes, people served, geography, land requirements, success definition, working assumptions, and open questions. Use one line per outcome, assumption, or question.
What it affects
Open questions can become connected Tasks. Land requirements and other recorded facts appear as Readiness source signals.
A disciplined pipeline for candidate properties and credible paths to control them.
How to use it
Open a candidate with a neutral name, leave unknown facts blank, then record location, acreage, asking price, ownership, diligence, pipeline status, compatibility scores, and site-control strategies as evidence develops.
What it affects
Sites can connect to Tasks. Land records inform Readiness, but scores are planning aids—not appraisals, engineering reviews, zoning findings, or legal opinions.
A transparent picture of project costs, possible sources, allocations, and remaining gaps.
How to use it
Record capital needs separately from funding sources, then match a stated source amount to a stated need. Keep Prospective, Pending, Conditional, and Committed allocations distinct.
What it affects
Only Committed allocations reduce the hard funding gap. Capital needs can connect to Tasks, and source records inform Readiness without proving it.
The evidence-disciplined assessment of what is confirmed, underway, blocked, or still unassessed.
How to use it
Open each criterion, inspect the source signal, then choose a confirmed status and record the evidence and next step. Use Complete only when a collaborator has reviewed sufficient support.
What it affects
The score uses confirmed reviews only. Source signals never complete a criterion automatically. Critical gaps can become Tasks.
Accountable work drawn from strategy, readiness gaps, land candidates, capital needs, or manual planning.
How to use it
Set the title, description, status, priority, assignee, and due date. Use Next for deliberately queued work, Waiting for an outside party, and Blocked for a real barrier.
What it affects
VillageOS ranks the five highest-leverage open tasks using explicit factors such as critical blockers, priority, due dates, and module links. Complete closes work only; it does not approve documents, checklist evidence, or Readiness.
The private evidence register for uploaded files, secure references, Readiness links, and required-document checklists.
How to use it
Add a private file or HTTPS reference, classify it, record dates and state, connect it to Readiness, and link it to the evidence requirement it supports.
What it affects
Evidence coverage, Owner/Admin acceptance, document-change approval, Readiness review, and Task completion stay separate. Files remain private; Approved to share is a classification, not a public link.
A separately restricted, double-entry record for contributions, expenses, banking evidence, monthly controls, reports, and compliance monitoring.
How to use it
Record founder contributions and Zeffy donations, categorize expenses, import downloadable bank CSV files, match and reconcile activity, maintain subscriptions, close each month, attach support, and review reports.
What it affects
Finance permission is never inherited from ordinary VillageOS membership. Posted entries are immutable; corrections use reversals or adjustments. Financial reports and the Pennsylvania threshold monitor derive from posted records.
Writing and formatting
Long-form fields remain compact and scrollable while you scan a project. Select one to open the expanded page-like editor. Its toolbar supports headings, bold and italic text, bulleted and numbered lists, quotations, links, and inline code, with a live formatted preview beside the writing area.
Done editing collapses the writing space. It does not save the surrounding form, so use that section's Save or Update button when the entry is ready. Escape, the close control, or selecting outside the editor also collapses it.
Data Room review states
A document's state—Draft, Current, Superseded, or Expired—describes the record. A checklist review state describes the team's conclusion about whether evidence satisfies a named requirement. Linking a document does not accept it.
The requirement is unresolved and usable evidence is missing or not yet selected.
Evidence exists, but its sufficiency, currency, execution, or meaning still needs review.
An Owner or Administrator considers the evidence adequate for this internal checklist requirement.
An Owner or Administrator determined the requirement does not apply and should record why.
For government-issued or filed evidence that needs no TerraViae signature, confirm it is authentic, relevant, and current enough for the named requirement. Keep an unsigned organizational record in review when adoption or execution matters. Keep an old status certificate in review when the requirement asks for present standing.
Who can accept: Contributors can use Needed and In review. Only Owners and Administrators can set Accepted or Not applicable, or reopen either formal state.
Quick preview: Select Preview beside a document to inspect supported PDFs, images, text, CSV, Word, and Google Drive records inside VillageOS. Word files are rendered in a restricted, script-free frame. Use Open original when a format or connected service cannot be embedded.
Privacy: Internal, Restricted, and Approved to share are team classifications. None publishes a public link. Restricted documents are limited to Owners and Administrators. Stored files open through short-lived private access links.
Updated versions: Use Upload updated version or Update external reference. The proposal appears in Document change approvals. Approval creates a new record, marks the prior version Superseded, and moves active evidence links to the new version.
Permanent deletion: A Contributor, Administrator, or Owner may type the exact title and submit a deletion request. Nothing is removed until an Owner or Administrator selects Approve and apply. Private stored files and attached evidence links are then removed; deleting an external reference does not delete its source file.
Four different controls: Data Room’s approval queue decides version/deletion requests. Accepted decides one checklist evidence requirement. Readiness Complete records a separate readiness judgment. Task Complete closes assigned work only.
Finance & Compliance
Finance access is a separate permission. Ordinary VillageOS membership never grants Finance access. Being a VillageOS Owner, Administrator, Contributor, or Viewer does not grant it. The permanent Finance Owners are terraviae@outlook.com and william.m.pagan@terraviae.org. They may delegate Bookkeeper or Finance Viewer access only to an existing VillageOS user.
Bookkeeper may record, categorize, import, match, reconcile, attach, close, and generate reports. Viewer is read-only. Finance Owners also manage these separate grants; permanent owners cannot be demoted or removed.
The workflow fixes the contributor as William Pagan, repayment expected as No, goods or services as None, and payment method as Bank transfer. Founder contributions are not loans or liabilities and are included in the conservative Pennsylvania gross-contribution monitor.
Open Contributions → Zeffy and public support. The first run checks all available history. Later runs collect activity from the last successful checkpoint through the moment selected. If a month was skipped, VillageOS automatically catches up; if the month was already checked, another click collects later activity through today.
A safe date overlap is intentional. Zeffy external IDs, source fingerprints, and database uniqueness classify each payment as new, changed, or already current, so the overlap does not create duplicate contributions. A failed run never advances the checkpoint.
Straightforward successful USD donations post automatically to Zeffy Funds in Transit and public contribution revenue. Tickets, mixed purchases, foreign currency, refunds, disputes, and changes to posted payments stay in a visible review queue. The later bank payout is a separate transfer into Operating Checking—not a second contribution. The sync stores no Zeffy card or payment-method data.
Use the manual public-donation form only when a valid gift is absent from the sync or came through another public source. Include the Zeffy transaction ID when available.
Download a CSV statement from the bank, then import it. No banking password, card data, or live connection belongs in VillageOS. Review duplicate flags and connect each legitimate bank row to its ledger entry.
After the statement is imported and matched, enter its dates and ending balance. VillageOS calculates the ledger balance. Reconciled is accepted only when the difference is exactly $0.00.
Complete all seven controls: statement, matching, categorization, support, ending balance, reports, and review submission. Closing locks the period record.
Reports includes the Statement of Activities, Statement of Financial Position, cash-flow detail, income and expense detail, founder-contribution report, contribution breakdowns, trial balance, and annual CSV export. Attach receipts, invoices, bank statements, donation acknowledgments, Zeffy reports, or financial reports in Finance Documents and connect each file to the record it supports. Audit Log shows every recorded change, with page controls as the history grows.
Team access
Full organization control. Can manage non-owner access, decide Data Room changes, and formally accept checklist evidence. Owner transfer is not in the current workflow.
Can work throughout projects, see Restricted documents, manage Contributors and Viewers, decide Data Room changes, and formally accept checklist evidence.
Can create and update authorized project records, and submit document update or deletion requests.
Read-only access to the records visible to this role.
Trusted invitations must be accepted by the exact invited email address before membership exists. Pending links expire after one hour and can be revoked. Never forward or share a sign-in link. Organization membership and Finance permission remain distinct.
Recommended rhythm
Current boundaries
Leave unknown values blank. Record sources for consequential judgments. Treat potential land and funding paths as possibilities until evidence advances their status. Never mark Readiness Complete merely because a source signal exists, and never mark a checklist item Accepted merely because a document is linked.
VillageOS currently includes organizations, projects, Project Brain, Land & site control, Capital & funding, Readiness, Tasks, Data Room document-change approvals, Finance & Compliance, and trusted team access. It does not yet include a general Contacts module, public document sharing, approval-request email notifications, or Owner transfer. Zeffy synchronization is manually initiated; signed webhooks are not yet enabled, and an older payment changed outside the rolling review window may need deliberate manual follow-up. It does not file forms, apply for funds, execute agreements, prepare tax returns, make legal or accounting determinations, or independently verify external facts.
Email trailhead@terraviae.org with the project name and the section you were using. Never email passwords, sign-in links, API keys, or sensitive document contents.
Operational oversight
Organization Owners and Administrators can open System Health from the workspace sidebar to see daily database checks, last verified success, and lasting report history. Contributors and Viewers cannot access it. Every daily result is emailed to trailhead@terraviae.org, including successful checks. Afternoon oversight retries unsent reports and flags a missed morning check.
Healthy describes database connectivity, known schema availability, and blocked anonymous access. Email accepted means provider acceptance, not confirmed inbox delivery. If the database cannot save history, the email is the fallback record. Jobs run independently of your computer, but a complete hosting or email-provider outage can prevent self-reporting. Missing daily mail warrants investigation; these checks do not replace backups or guarantee that Supabase Free will never pause.