Skip to content

INDEX.md

Latest commit

 

History

History
133 lines (118 loc) · 7.26 KB

INDEX.md

File metadata and controls

133 lines (118 loc) · 7.26 KB
Raw

Repository Index

Navigation map for the documentation-first Codegeist OS workspace.

When To Read This

  • Read this before changing AI-user identity, access, privilege, audit, recovery, NixOS build behavior, or model and CLI integration requirements.
  • Read docs/security.md before proposing any AI-controlled system capability.
  • Read docs/artifact-contract.md and docs/build-workflow.md before adding model, Codegeist, VM, ISO, or release automation.
  • Read docs/speech-model-evaluation.md before proposing local TTS, STT, microphone, voice-cloning, or speech-service integration.

Directory Map

  • README.md - project purpose, selected Version 1 profile, current state, hosting model, and workspace setup.
  • docs/architecture.md - NixOS/GNOME system layers, identities, runtime flow, model-free image boundary, catalog selection, state, lifecycle, and deferred installer work.
  • docs/base-system-selection.md - NixOS decision, stable classic Nix interfaces, no-Flakes policy, accepted risks, and revisit triggers.
  • docs/artifact-contract.md - one immutable LLM/speech catalog, per-system Codegeist, hardware profiles, external bundles, fixtures, licenses, and hashes.
  • docs/build-workflow.md - model-free x86_64/aarch64 VM/live ISO, external- bundle integration, hardware-profile, quality, security, and reproducibility gates.
  • docs/speech-model-evaluation.md - measured CPU baseline, first accelerator speech profile, diarization candidates, hardware inventory, licenses, and next evaluations.
  • docs/security.md - isolation, approval, artifact, audit, rollback, and recovery rules.
  • docs/memory-bank/chat.md - compact state for future sessions.
  • .devcontainer/ - shared development environment on its release branch.
  • .opencode/ - shared OpenCode agent kit on its release branch.
  • .codegeist/Dockerfile - project-local devcontainer extension that currently disables Git HTTPS certificate verification globally as a temporary exception.
  • refs/codegeist/ - GitHub main source-reference submodule for CLI contracts.
  • refs/codegeist-llm/ - GitHub main source-reference submodule for model release and catalog contracts.
  • .gitmodules - shared-kit submodule sources and branch tracking.

Known Directory Indexes

  • INDEX.md - this repository-root index.

Key Workflows

  • Initialize shared kits and source references with git submodule update --init .devcontainer .opencode refs/codegeist refs/codegeist-llm from this repository.
  • Treat refs/ as review context only. Production Nix derivations consume released archives, manifests, catalogs, and hashes, never mutable submodule source trees.
  • Implement the first system through classic default.nix, npins/, and stable nix-build entrypoints for separate x86_64 and aarch64 outputs. Do not require Nix Flakes or experimental Nix CLI features.
  • Let codegeist-llm publish canonical SafeTensors plus an LLM release manifest of runtime variants; let Codegeist OS publish the reviewed shared catalog and let codegeist publish matching per-system native archives. Base OS images consume catalog metadata but no model payload.
  • Build model-free VM and GNOME live ISO profiles from shared NixOS policy modules. Hardware ranking, human model selection or external package import, and persistent model state belong to the later installer milestone.
  • Inject catalog-approved bundles only in tests. Keep them outside release-image derivations and run offline Codegeist ask only under the restricted AI identity in an empty AI-owned workspace.
  • Require a physical or verified-passthrough gate for every claimed accelerator profile. The RTX A2000 gate proves only the initial CUDA profile.
  • Treat every future AI capability as denied by default and require an owner, approval path, audit record, revocation path, and recovery behavior.

Search Hints

  • AI user - separate non-root identity and smoke-test requirements.
  • inference service - restricted Ollama service and mutable registration state.
  • inference gateway - bounded AI model endpoint with no Ollama administration.
  • speech broker, SO_PEERCRED, openat2 - authenticated operation and sealed file boundary.
  • human approval - boundaries for privileged or sensitive actions.
  • deny by default - access-control baseline.
  • NixOS - selected Version 1 base.
  • No-Flakes Policy - stable classic Nix build constraint.
  • GGUF - one possible LLM runtime-variant format.
  • SafeTensors - canonical training artifact retained by codegeist-llm.
  • artifact pin - reviewed Nixpkgs, CLI, catalog, runtime, and profile versions and hashes.
  • model-free, variant catalog, external bundle - payload boundary and test provisioning contract.
  • x86_64, aarch64, hardware profile - separate images and measured support.
  • codegeist-llm - model training and release boundary.
  • ask - offline integration smoke, not a human-facing Version 1 feature.
  • Piper, Faster-Whisper, Parakeet, Qwen3 - local speech candidates and hardware-fit evidence.
  • pyannote, diarization, SPEAKER_00 - anonymous file-local speaker attribution and gated-artifact requirements.
  • RTX A2000, CUDA, 10 GiB, 12 GiB - planned first reference GPU, provisional workload ceiling, and physical VRAM envelope for one profile.

Update Triggers

  • Update this index when major documents, top-level directories, planned build entrypoints, or artifact-contract locations change.
  • Update docs/memory-bank/chat.md when the hardware profile, model contract, identity model, build outputs, installer scope, or recovery design changes.
  • Update architecture, security, artifact, and build docs in the same task when implementation makes one of their planned statements true or obsolete.
  • Update architecture, security, speech evaluation, artifact contract, build workflow, and memory together when a speech candidate, license, fixture, quality threshold, service boundary, or accelerator resource decision changes.
  • Update all architecture, artifact, build, security, base-selection, speech, README, index, and memory documents together when the model-free image boundary, supported system architectures, catalog schema, test-bundle flow, or installer ownership changes.

Agent Notes

  • Do not describe planned controls, VM tests, ISO outputs, or offline behavior as implemented guarantees.
  • Do not add flake.nix or flake.lock during Version 1.
  • Do not add an LLM or speech payload to a production VM/ISO derivation. Catalog metadata and runtimes are allowed; model bytes belong to external tests or the future installer-managed store.
  • Do not import refs/codegeist or refs/codegeist-llm into a production Nix derivation. Their gitlinks are navigation and review inputs, not release pins.
  • GIT_SSL_NO_VERIFY=true in .codegeist/Dockerfile is an explicit global devcontainer security exception. Remove it when the Gitea CA is trusted.
  • Do not run the current tool-capable Codegeist CLI in a human home or trusted project as part of OS integration.
  • Do not turn anonymous diarization into speaker identification, persist speaker embeddings, or enable microphone/voice-cloning access during Version 1.
  • Do not add an OS image, model artifact, credential, generated VM state, or private human-user data to Git.