docs: complete persona crate declaration comments

crates/frameshift-orchestrator/src/audit.rs

@@ -35,6 +35,7 @@ pub struct AuditLog {
     entries: Vec<Transition>,
 }
 
+/// Loads, appends, and queries persona transition audit records.
 impl AuditLog {
     /// Maximum number of audit entries retained in memory when loading. Entries
     /// older than the most recent `MAX_AUDIT_ENTRIES` are dropped so a log grown
@@ -124,6 +125,7 @@ pub fn now_timestamp() -> String {
 }
 
 #[cfg(test)]
+/// Verifies audit persistence, retention, and timestamp behavior.
 mod tests {
     use super::*;
     use tempfile::TempDir;

crates/frameshift-orchestrator/src/context.rs

@@ -696,6 +696,7 @@ pub(crate) fn tokenize(text: &str) -> Vec<String> {
 }
 
 #[cfg(test)]
+/// Verifies project-context collection and tokenization behavior.
 mod tests {
     use super::*;
     use std::fs;

crates/frameshift-orchestrator/src/controller.rs

@@ -47,6 +47,7 @@ pub struct SwitchPolicy {
     pub min_gap_fraction: f32,
 }
 
+/// Maps operator sensitivity into concrete switching thresholds.
 impl SwitchPolicy {
     /// Construct a SwitchPolicy from a user-facing sensitivity value in [0.0, 1.0].
     ///
@@ -71,6 +72,7 @@ impl SwitchPolicy {
     }
 }
 
+/// Provides balanced switching thresholds as the default policy.
 impl Default for SwitchPolicy {
     /// Returns the default policy from sensitivity 0.5 (balanced).
     fn default() -> Self {
@@ -117,6 +119,7 @@ pub struct SwitchController {
     challenger: Option<String>,
 }
 
+/// Controls automate-mode transitions and persona-switch hysteresis.
 impl SwitchController {
     /// Create a new `SwitchController` in the `Off` state with the given policy.
     pub fn new(policy: SwitchPolicy) -> Self {
@@ -371,6 +374,7 @@ impl SwitchController {
 }
 
 #[cfg(test)]
+/// Verifies controller state transitions, thresholds, and debounce behavior.
 mod tests {
     use super::*;
     use crate::policy::ScoreComponents;

crates/frameshift-orchestrator/src/embed.rs

@@ -250,6 +250,7 @@ fn write_private_file(path: &std::path::Path, contents: &[u8]) -> io::Result<()>
 pub(crate) struct BagOfWordsEmbedder;
 
 #[cfg(test)]
+/// Produces deterministic test embeddings with a bag-of-words model.
 impl Embedder for BagOfWordsEmbedder {
     /// Embed `text` as a 64-dimensional word-occurrence histogram.
     fn embed(&self, text: &str) -> Vec<f32> {
@@ -270,6 +271,7 @@ impl Embedder for BagOfWordsEmbedder {
 }
 
 #[cfg(test)]
+/// Verifies embedding similarity and cache behavior.
 mod tests {
     use super::*;
 
@@ -313,6 +315,7 @@ mod tests {
         calls: std::sync::atomic::AtomicUsize,
     }
 
+    /// Constructs and inspects the embedder used to count cache misses.
     impl CountingEmbedder {
         /// Fresh counter around the bag-of-words mock.
         fn new() -> Self {
@@ -328,6 +331,7 @@ mod tests {
         }
     }
 
+    /// Counts each delegated embedding operation.
     impl Embedder for CountingEmbedder {
         /// Delegate to the mock, counting the call.
         fn embed(&self, text: &str) -> Vec<f32> {

crates/frameshift-orchestrator/src/intent.rs

@@ -291,6 +291,7 @@ pub fn relatedness(a: Intent, b: Intent) -> f32 {
 }
 
 #[cfg(test)]
+/// Verifies token classification and intent-relatedness scoring.
 mod tests {
     use super::*;
 

crates/frameshift-orchestrator/src/lib.rs

@@ -59,6 +59,7 @@ pub struct Orchestrator {
     pub preferences: Preferences,
 }
 
+/// Selects and switches personas using the orchestrator's indexed state.
 impl Orchestrator {
     /// Create a new `Orchestrator` with the given index and default weights/policy/preferences.
     pub fn new(index: PersonaIndex) -> Self {
@@ -87,6 +88,7 @@ impl Orchestrator {
 }
 
 #[cfg(test)]
+/// Verifies the public orchestration facade.
 mod tests {
     use super::*;
     use std::collections::BTreeSet;

crates/frameshift-orchestrator/src/mode.rs

@@ -38,6 +38,7 @@ pub struct ModeState {
     pub sensitivity: f32,
 }
 
+/// Loads and persists the operator's automate-mode state.
 impl ModeState {
     /// Load mode state from a JSON file.
     ///
@@ -78,6 +79,7 @@ impl ModeState {
 }
 
 #[cfg(test)]
+/// Verifies mode-state defaults and persistence.
 mod tests {
     use super::*;
     use tempfile::TempDir;

crates/frameshift-orchestrator/src/run.rs

@@ -249,6 +249,7 @@ pub fn select_rich_with_embedder(
 }
 
 #[cfg(test)]
+/// Verifies end-to-end orchestration runs against temporary persona sources.
 mod tests {
     use super::*;
     use std::fs;

crates/frameshift-source/src/diff.rs

@@ -227,6 +227,7 @@ fn anchor_token_set(anchors: &[CascadeAnchor]) -> HashSet<String> {
 }
 
 #[cfg(test)]
+/// Verifies semantic persona-source diff generation.
 mod tests {
     use super::*;
     use crate::patterns::PatternSet;

crates/frameshift-source/src/error.rs

@@ -1,6 +1,7 @@
 use std::path::PathBuf;
 
 #[derive(Debug, thiserror::Error)]
+/// Reports persona-source loading, parsing, validation, and serialization failures.
 pub enum SourceError {
     #[error("i/o error at {path}: {source}")]
     Io {

crates/frameshift-source/src/patch.rs

@@ -71,6 +71,7 @@ pub enum AnchorPosition {
     Recency,
 }
 
+/// Converts anchor positions to their serialized persona-source representation.
 impl AnchorPosition {
     /// Returns the lowercase string key used as the `position` field in
     /// `CascadeAnchor` TOML entries (e.g. `"top"`, `"l2"`, `"recency"`).

crates/frameshift-source/src/patterns.rs

@@ -91,13 +91,15 @@ const fn default_schema_version() -> u32 {
     1
 }
 
+/// Constructs pattern collections for persona sources.
 impl PatternSet {
     /// Constructs an empty `PatternSet` with default schema version.
     pub fn new() -> Self {
         Self::default()
     }
 }
 
+/// Provides an empty versioned pattern collection.
 impl Default for PatternSet {
     /// Constructs an empty `PatternSet` with `schema_version` set to `1`.
     fn default() -> Self {
@@ -112,10 +114,12 @@ impl Default for PatternSet {
 }
 
 #[cfg(test)]
+/// Verifies pattern collection TOML serialization.
 mod tests {
     use super::*;
 
     #[test]
+    /// Round-trips a populated pattern collection through TOML.
     fn pattern_set_toml_roundtrip() {
         let original = PatternSet {
             schema_version: 1,
@@ -149,6 +153,7 @@ mod tests {
     }
 
     #[test]
+    /// Round-trips an empty pattern collection through TOML.
     fn empty_pattern_set_roundtrips() {
         let original = PatternSet::default();
         let serialized = toml::to_string(&original).unwrap();

crates/frameshift-source/src/persona.rs

@@ -257,6 +257,7 @@ pub struct Persona {
     pub default_questions: Vec<DefaultQuestion>,
 }
 
+/// Constructs persona definitions with safe empty defaults.
 impl Persona {
     /// Minimal valid persona -- used as a default when scaffolding.
     ///
@@ -294,6 +295,7 @@ impl Persona {
 }
 
 #[cfg(test)]
+/// Verifies persona TOML serialization and schema compatibility.
 mod tests {
     use super::*;
 

crates/frameshift-source/src/rules.rs

@@ -46,6 +46,7 @@ pub enum Layer {
     L3,
 }
 
+/// Constructs behavioral rule collections for persona sources.
 impl RuleSet {
     /// Construct an empty `RuleSet`. Equivalent to `RuleSet::default()`.
     pub fn new() -> Self {
@@ -54,10 +55,12 @@ impl RuleSet {
 }
 
 #[cfg(test)]
+/// Verifies rule collection TOML serialization.
 mod tests {
     use super::*;
 
     #[test]
+    /// Round-trips a populated rule collection through TOML.
     fn ruleset_toml_roundtrip() {
         let original = RuleSet {
             rules: vec![
@@ -91,6 +94,7 @@ mod tests {
     }
 
     #[test]
+    /// Round-trips an empty rule collection through TOML.
     fn empty_ruleset_roundtrips() {
         let original = RuleSet::default();
         let serialized = toml::to_string(&original).unwrap();
@@ -99,6 +103,7 @@ mod tests {
     }
 
     #[test]
+    /// Preserves optional rule reasoning through TOML serialization.
     fn rule_with_reasoning_roundtrips() {
         let original = RuleSet {
             rules: vec![Rule {

crates/frameshift-source/src/skills.rs

@@ -19,17 +19,21 @@ pub struct Skill {
     pub mandatory: bool,
 }
 
+/// Constructs skill collections for persona sources.
 impl SkillSet {
+    /// Constructs an empty skill collection.
     pub fn new() -> Self {
         Self::default()
     }
 }
 
 #[cfg(test)]
+/// Verifies skill collection TOML serialization.
 mod tests {
     use super::*;
 
     #[test]
+    /// Round-trips a populated skill collection through TOML.
     fn skillset_toml_roundtrip() {
         let original = SkillSet {
             skills: vec![
@@ -54,6 +58,7 @@ mod tests {
     }
 
     #[test]
+    /// Round-trips an empty skill collection through TOML.
     fn empty_skillset_roundtrips() {
         let original = SkillSet::default();
         let serialized = toml::to_string(&original).unwrap();
@@ -62,6 +67,7 @@ mod tests {
     }
 
     #[test]
+    /// Preserves the mandatory-skill flag through TOML serialization.
     fn skill_with_mandatory_roundtrips() {
         let original = SkillSet {
             skills: vec![Skill {

crates/frameshift-source/src/source.rs

@@ -28,6 +28,7 @@ pub struct LoadOptions {
     pub max_patterns: usize,
 }
 
+/// Provides bounded defaults for local persona-source loading.
 impl Default for LoadOptions {
     /// Returns default load options suitable for local development use.
     fn default() -> Self {
@@ -54,6 +55,7 @@ pub struct PersonaSource {
     pub patterns: PatternSet,
 }
 
+/// Loads, validates, constructs, and writes composite persona sources.
 impl PersonaSource {
     /// Constructs a new `PersonaSource` with the given persona and empty rules, skills, and patterns.
     pub fn new(persona: Persona) -> Self {
@@ -214,6 +216,7 @@ fn write_toml<T: serde::Serialize>(path: &PathBuf, value: &T) -> Result<(), Sour
 }
 
 #[cfg(test)]
+/// Verifies persona-source persistence and loading failures.
 mod tests {
     use super::*;
     use crate::patterns::{AntiPattern, PatternSet, StackCategory};
@@ -222,6 +225,7 @@ mod tests {
     use crate::skills::{Skill, SkillSet};
     use std::collections::BTreeMap;
 
+    /// Builds a populated persona source shared by persistence tests.
     fn sample() -> PersonaSource {
         let mut anchor = BTreeMap::new();
         anchor.insert(
@@ -285,6 +289,7 @@ mod tests {
     }
 
     #[test]
+    /// Round-trips a persona source directory through disk.
     fn write_then_load_roundtrip() {
         let tmp = tempfile_dir();
         let original = sample();
@@ -295,6 +300,7 @@ mod tests {
     }
 
     #[test]
+    /// Rejects a source directory without its required persona file.
     fn missing_persona_file_errors() {
         let tmp = tempfile_dir();
         let err = PersonaSource::load_from_dir(&tmp).unwrap_err();