public/malta-workshop
2
0
Fork 0
Code Pull Requests Activity
Files
main
malta-workshop/AGENTS.md
Michael Czechowski eaf7667728 refactor: clean up workshop for Science in the City event 
- Update workshop name from 'CODE CRISPIES' to 'SCIENCE IN THE CITY'
- Remove all Hetzner cloud deployment references and commands
- Focus documentation on local USB/VM workshop environment
- Remove cloud server connection functionality
- Update WiFi credentials for workshop network
- Clean up AGENTS.md to reflect local-only development workflow
- Remove misleading cloud infrastructure references
- Update help commands and learning flow for local practice only

This commit prepares the workshop materials for the Science in the City event,
focusing exclusively on local Co-op Cloud deployment practice without cloud
infrastructure dependencies.
2025-09-16 19:02:03 +02:00

2.9 KiB
Raw Permalink Blame History

AGENTS.md

This file provides guidelines for AI coding agents operating within this repository.

Build, Lint, and Test Commands

  • Build: make usb-build (Builds the NixOS workshop ISO)
  • Local VM: make vm (Starts local VM that simulates USB environment)
  • Test: make usb-test (Test USB environment in QEMU)
  • Deploy: make usb-build (Build workshop USB ISO)
  • Format: make format (Format Nix files)

Code Style Guidelines

  • Imports: Organize imports alphabetically. Avoid unused imports.
  • Formatting: Adhere to Nixpkgs formatting conventions. Use nixpkgs-fmt for consistency.
  • Types: Use Nix's type system rigorously. Define types explicitly where possible.
  • Naming Conventions:
    • Variables and functions: camelCase for Nix expressions
    • Container/server names: lowercase (hopper, curie, lovelace, etc.)
    • Script names: kebab-case for executables
  • SSH Keys: Always use Ed25519 keys (~/.ssh/id_ed25519.pub)
  • Domain: Use codecrispi.es consistently across all environments
  • Password Policy: Minimize password usage; prefer key-based authentication
  • Error Handling: Handle errors explicitly. Use Nix's error reporting mechanisms.
  • Commit Messages: Use conventional commit style (type: subject). Avoid scopes like (makefile). The subject should be in lowercase.

Container Architecture

  • Local VM: Provides self-contained workshop environment
  • Container Names: workshop-local (single container environment)
  • Networking: Local networking with DNS resolution
  • DNS: *.workshop.local domain resolution for testing

Available Scripts

  • setup - Initialize local workshop environment
  • deploy <recipe> - Deploy Co-op Cloud applications
  • browser [app] - Open applications in Firefox
  • recipes - Display available Co-op Cloud recipes
  • help - Show command help

Development Workflow

  1. Use make vm for local development testing
  2. Test workshop environment with make usb-test
  3. Use make usb-build for workshop USB drives (outputs to ./build/iso/)
  4. Focus on local deployment and learning

General Guidelines

  • Keep code concise and readable
  • Prefer declarative over imperative approaches
  • Document complex logic with comments
  • Test locally in VM before USB deployment
  • Maintain feature parity between USB/VM environments where possible
  • ALWAYS check package existence on search.nixos.org before adding new packages

Build Locations

  • USB ISOs: ./build/iso/result/iso/*.iso (custom build directory)
  • VM builds: ./result/ (Nix default symlink)
  • Clean command: Removes both ./build/ and ./result/ directories

⚠️ Critical Warnings

  • NEVER RUN nix-env - This can break your Nix environment. Use nix-shell, nix develop, or declarative approaches instead.

⚠️ Critical Warnings

  • NEVER RUN nix-env - This can break your Nix environment. Use nix-shell, nix develop, or declarative approaches instead.