A Collegiate-Level Framework for Internal Self-Governance, Executive Functioning, and Psychological Literacy
Architected as a high-performance, modular SvelteKit monorepo powered by Svelte 5 Runes, Turborepo, Vite Plus, Drizzle ORM, and Better-Auth.
The Autonomy Protocol is a non-secular, politically neutral educational curriculum engineered to transition high school students from external behavioral policing to internal self-governance. Targeted for implementation across public school Career Technical Education (CTE) pathways and Advisory periods, the protocol translates established behavioral dynamics into practical executive functioning and psychological literacy tools.
To maintain academic rigor, secular neutrality, and professional applicability in public school systems, traditional recovery and self-help concepts have been refactored into a standardized collegiate lexicon:
| Traditional / Legacy Concept | Approved Academic Translation | Operational Definition |
|---|---|---|
| Spirituality / Higher Power | Universal Principles / Objective Standard | Sourcing an external, objective behavioral baseline beyond individual ego or short-term impulses. |
| Sin / Character Defect | Cognitive Distortion / Behavioral Liability | Identifying maladaptive behavioral patterns and cognitive biases that compromise personal efficacy. |
| Apology / Forgiveness | Amends Protocol / Restorative Action | Concrete, action-based restitution to repair interpersonal trust and eliminate relational friction. |
| Social Justice / Morality | Social Friction / Conflict Resolution / Ethical Baseline | Pragmatic conflict mediation and systemic adherence to mutual integrity without partisan bias. |
| Social-Emotional Learning (SEL) | Executive Functioning / Psychological Literacy | Systematic metacognitive training, emotional self-regulation, and professional resilience. |
The curriculum is built upon two complementary pedagogical architectures that guide students through individual regulation and interpersonal dynamics:
Refactored from the 12-Step Architecture into four sequential operational blocks:
┌──────────────────────────────────────────────────────────────────────────────────┐
│ THE ACCOUNTABILITY CYCLE │
├───────────────────┬───────────────────┬───────────────────┬──────────────────────┤
│ 1. ORIENTATION │ 2. INTERNAL AUDIT │ 3. RESTORATIVE │ 4. MAINTENANCE & │
│ (Steps 1–3) │ (Steps 4–7) │ PRACTICE │ LEADERSHIP │
│ │ │ (Steps 8–9) │ (Steps 10–12) │
├───────────────────┼───────────────────┼───────────────────┼──────────────────────┤
│ • Limits of │ • Objective self- │ • Mapping impact │ • Daily cognitive │
│ control check │ inventory │ on peers/system │ inventory │
│ • Sourcing an │ • Identifying │ • Action-based │ • Real-time conflict │
│ objective norm │ liabilities │ Amends Protocol │ de-escalation │
│ • Commitment to │ • Behavioral │ • Restoring trust │ • Peer mentorship │
│ active alignment│ intervention │ mechanics │ and stewardship │
└───────────────────┴───────────────────┴───────────────────┴──────────────────────┘
Refactored from the Four Agreements into four baseline interaction standards:
- Precision of Speech: Operating with absolute clarity, reliability, and alignment between verbal commitments and concrete execution.
- Emotional Neutrality: Decoupling personal identity from external actions, peer critiques, and environmental friction.
- Inquiry-Based Reality: Validating empirical facts and asking clarifying questions before formulating behavioral assumptions.
- Baseline Fluctuation: Continuously optimizing effort and output relative to dynamic capacity while maintaining core standards.
The monorepo leverages modern web standards, fine-grained reactivity, and modular package isolation:
| Layer | Technology | Specification / Configuration |
|---|---|---|
| Runtime & Language | Node.js + TypeScript | Node >=22.12.0, TypeScript ^6.0.3 with strict type checking (managed via Vite+) |
| Unified Toolchain | Vite+ (vp CLI) |
Combines Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, Vite Task, package management & runtime |
| Package Manager | pnpm@11.22.0 |
Workspace catalogs, strict peer dependency management, and architecture filtering (managed by vp) |
| Monorepo Engine | Turborepo + Vite Task | turbo ^2.9.18 pipeline execution integrated with Vite+ task caching and runner |
| Frontend Framework | Svelte 5 + SvelteKit | Forced Svelte 5 Runes mode, #lib/* subpath imports, and @sveltejs/kit |
| Design System & CSS | Pure Vanilla CSS Tokens | @autonomy/style (Nord color palette, fluid clamp typography, view-timeline animations) |
| Database & ORM | Drizzle ORM + LibSQL | drizzle-orm ^0.45.2, drizzle-kit ^0.31.10, and @libsql/client (Turso SQLite engine) |
| Authentication & RBAC | Better-Auth | better-auth ~1.4.22 with Google OAuth provider and RBAC (superadmin, admin, teacher, user) |
| Content & Parsing | MDSveX & Marked | Interactive .svx/.md components and markdown AST processing |
| Motion & Iconography | Motion + Lucide + Morphicons | @lucide/svelte, lucide, morphicons, canvas-confetti, and motion |
| Deployment Target | Vercel | @sveltejs/adapter-vercel with automated preview pipeline |
the-autonomy-protocol/
├── sites/
│ ├── student-site/ # Public & authenticated student portal (curriculum & progress)
│ └── teacher-site/ # Authenticated educator portal (curriculum, DB, auth, PDF parser)
├── packages/
│ ├── blocks/ # High-level compound UI blocks
│ │ ├── banner/ # Contextual notification & broadcast banners
│ │ ├── external_links/ # Categorized external resource links & foresight actions
│ │ ├── footer/ # Canonical application footer
│ │ ├── header/ # Application header layout block
│ │ ├── hero/ # High-contrast hero section with CTA slots
│ │ ├── nav/ # DropNav, Drawer Nav, FooterNav & portal switcher
│ │ └── revealing_image/ # Scroll-driven CSS reveal animation image container
│ ├── ui/ # Atomic interface components & widgets
│ │ ├── battery-level/ # Energy / capacity indicator widget
│ │ ├── horizontal-scroll/ # Touch & pointer horizontal layout container
│ │ ├── logo/ # Vector insignia and brand marks
│ │ ├── pill/ # Metadata status badges and category tags
│ │ ├── reading-time/ # Dynamic word-count & reading duration estimator
│ │ ├── scroll-to-top/ # Floating back-to-top trigger with time-read indicator
│ │ ├── session-warning/ # Client session expiration & re-authentication modal
│ │ └── theme-toggle/ # Nord palette & dark/light theme state manager
│ ├── core/ # Shared foundations, actions, styles, and utilities
│ │ ├── actions/ # Svelte actions (thickMargins, contrastColor, autoContrast, foresight)
│ │ ├── style/ # Global vanilla CSS (tokens, typography, Nord palette, reset, functions)
│ │ └── utils/ # WCAG contrast computation & text calculation utilities
│ └── content/ # Framework pedagogical interactive components
│ ├── four-agreements/ # The Integrity Protocol interactive module components
│ └── twelve-steps/ # The Accountability Cycle interactive module components
├── docs/ # Curriculum documentation, mission statements, and templates
│ ├── curriculum/ # Pedagogical guides and inquiry documentation
│ └── templates/ # LESSON_PLAN_TEMPLATE.md & EXAMPLE-ASSIGNMENT.md
├── pnpm-workspace.yaml # Workspace catalog definitions & dependency rules
├── turbo.json # Turbo pipeline tasks (build, check, test, lint, dev)
├── vite.config.ts # Root Vite Plus configuration
└── package.json # Root scripts, devDependencies, and package manager config
| Package Name | Location | Description |
|---|---|---|
@autonomy/style |
packages/core/style |
Design token system, Nord theme variables, responsive typography, and layout classes. |
@autonomy/actions |
packages/core/actions |
Reusable Svelte actions: thickMargins, autoContrast, contrastColor, and foresight. |
@autonomy/utils |
packages/core/utils |
Pure TypeScript mathematical and color contrast utilities. |
@autonomy/theme-toggle |
packages/ui/theme-toggle |
Svelte 5 runes-based theme manager with persistent state and animated icon toggle. |
@autonomy/nav |
packages/blocks/nav |
Complete responsive navigation suite with desktop DropNav, mobile drawer, and portal switching. |
@autonomy/hero |
packages/blocks/hero |
Angled container hero section supporting dark-mode contrast and high-priority CTAs. |
@autonomy/banner |
packages/blocks/banner |
Global and contextual alert banners with dismissal tracking. |
@autonomy/footer |
packages/blocks/footer |
Unified footer with dynamic copyright, quick links, and theme toggle anchors. |
@autonomy/four-agreements |
packages/content/four-agreements |
Interactive instructional components for The Integrity Protocol. |
@autonomy/twelve-steps |
packages/content/twelve-steps |
Interactive instructional components for The Accountability Cycle. |
The project uses Vite+ — the unified web toolchain combining Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task, plus runtime and package-manager management.
Install the vp CLI if it is not already on your system:
- macOS / Linux:
curl -fsSL https://vite.plus | bash - Windows (PowerShell):
irm https://vite.plus/ps1 | iex
Open a new terminal and verify:
vp helpTip
Vite+ Day-to-Day Commands:
vp install— Install workspace dependencies using the configured package manager.vp dev— Start the local development server in the current workspace.vp check— Run formatting, linting, and type-checks together.vp test— Execute Vitest unit and integration tests.vp build— Run production build.vpr <script>/vp run <script>— Run custompackage.jsonscripts across workspaces.
# Clone the repository
git clone https://github.com/webrune-tim/the-autonomy-protocol.git
cd the-autonomy-protocol
# Install all workspace dependencies
vp installLaunch individual applications or workspace targets:
# Start Student Portal (http://localhost:5173 by default)
vpr dev:student-site
# Start Teacher Portal (http://localhost:5174)
vpr dev:teacher-site
# Alternatively, run directly via Vite+ inside a specific workspace directory:
cd sites/teacher-site && vp devRun workspace-wide pipeline tasks:
# Format, lint, and type check with Vite+
vp check
# Full validation: type checking, testing, and production builds across the monorepo
vpr ready
# Production build across all packages and sites
vp build
# or run the root workspace build script:
vpr build
# Automated linting and formatting on specific packages
vpr --filter teacher-site lint
vpr --filter teacher-site formatThe repository provides zero-credential offline development by default via local SQLite (file:local.db). No live Turso or cloud credentials are required for local development.
Copy the environment templates:
cp sites/teacher-site/.env.example sites/teacher-site/.env
cp sites/student-site/.env.example sites/student-site/.envThe preconfigured non-sensitive defaults in .env:
# LibSQL Local SQLite Fallback
DATABASE_URL=file:local.db
DATABASE_AUTH_TOKEN=""
# Better-Auth Development Secret
BETTER_AUTH_SECRET="dev_secret_at_least_32_characters_long_for_local_development"
# Server Origin URL
TEACHER_ORIGIN=http://localhost:5174
ORIGIN=http://localhost:5173Note
Connecting to a remote Turso database (libsql://...) is strictly optional for local development.
With file:local.db, all Drizzle database tasks execute locally and offline:
cd sites/teacher-site
# Push schema directly to the local SQLite database (development)
vpr db:push
# Generate SQL migration files from schema changes
vpr db:generate
# Execute pending database migrations
vpr db:migrate
# Seed database with initial curriculum modules and demo users
vpr db:seed
# Complete DB setup pipeline (push/migrate + seed)
vpr db:setup
# Launch interactive Drizzle Studio database browser
vpr db:studio
# Regenerate Better-Auth schema definitions
vpr auth:schemaAll curriculum modules must adhere to the Internal Self-Governance pedagogical standards and the Approved Academic Lexicon.
- Utilize the Canonical Template: Copy
docs/templates/LESSON_PLAN_TEMPLATE.mdfor all new module drafts. - Define Observable Behavioral Outcomes: Frame lessons around concrete behavioral shifts rather than subjective emotional states.
- Draft the Practicum: Provide high-school-ready applied learning exercises, conflict resolution scenarios, or system debugging logs.
- Implement UI Components: Connect module content to reusable components in
packages/content/. - Adhere to Contribution Guidelines: Refer to
CONTRIBUTING.mdfor pull request requirements and the community code of conduct.
Both student-site and teacher-site are configured for automated deployment via Vercel using @sveltejs/adapter-vercel.
- Zero External Access: External contributors do not require Vercel organization access or production secrets.
- Automated Fork PR Previews: Isolated preview deployments are automatically generated for incoming PRs from forks once authorized by a repository maintainer.
- Secret Isolation: Upstream production and staging secrets are strictly isolated from fork preview builds.
- Maintainer Configuration: Maintainers enable Require Authorization for Fork Deployments under Project Settings → Git for both projects.
For complete details, see the Deployment & Access Policy in CONTRIBUTING.md.
This project is licensed under the terms described in LICENSE.md.