aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorCraig Jennings <c@cjennings.net>2026-02-12 12:06:33 -0600
committerCraig Jennings <c@cjennings.net>2026-02-12 12:06:33 -0600
commitde8dbe6edaf1be17a52f971f22da81c6dcf270f7 (patch)
tree7ed3e3a4cccbafe109ff8c87ec8b1e3cfb120141 /docs
parent6787fb160c80118b80df37c01cb69dcfbebfff17 (diff)
downloadarchangel-de8dbe6edaf1be17a52f971f22da81c6dcf270f7.tar.gz
archangel-de8dbe6edaf1be17a52f971f22da81c6dcf270f7.zip
fix: archzfs key prompt hang, test false positive, add local distribution
- Change archzfs SigLevel to Never (pacstrap -K empty keyring caused interactive GPG prompt blocking unattended installs) - Fix pgrep matching avahi-daemon's [archangel.local] in full-test.sh - Bump install timeout to 30min for DKMS builds - Add ~/downloads/isos and archsetup inbox to build-release distribution - Sync templates
Diffstat (limited to 'docs')
-rw-r--r--docs/announcements/the-purpose-of-this-directory.org18
-rw-r--r--docs/protocols.org11
-rw-r--r--docs/workflows/process-meeting-transcript.org301
-rw-r--r--docs/workflows/session-start.org3
4 files changed, 328 insertions, 5 deletions
diff --git a/docs/announcements/the-purpose-of-this-directory.org b/docs/announcements/the-purpose-of-this-directory.org
new file mode 100644
index 0000000..ae3f756
--- /dev/null
+++ b/docs/announcements/the-purpose-of-this-directory.org
@@ -0,0 +1,18 @@
+The purpose of this directory is to contain one-off instructions for every project using these templates.
+
+Example:
+- restructing of the claude-specific directories.
+- announcements of new workflows and how to use them.
+- one-off topics to be discussed with Craig when the templates are sync'd.
+
+How The Directory Is Used
+- Craig will decide that all projects will need to perform an action (reorganizing files, adding info to NOTES or protocols, removing unused workflows)
+- Craig will add the instructions as a file in this directory
+- When the project syncs templates, they will inherit new files in the directory
+- They will discuss the instructions with Craig to ensure he knows they have understood the instructions and have the opportunity to ask any clarifying questions before executing the instructions.
+- They will then execute the instructions.
+- They will inform Craig of the results of executing the instructions (success, failure, and any observations).
+- Typically, they will delete the instructions when complete unless the instructions explicitly state to do otherwise.
+
+
+NOTE: This file should always remain in the directory for future reference. This file may be overwritten by a template sync, but should never otherwise be deleted by claude.
diff --git a/docs/protocols.org b/docs/protocols.org
index bb52ae4..b3106b6 100644
--- a/docs/protocols.org
+++ b/docs/protocols.org
@@ -169,7 +169,9 @@ Execute the wrap-up workflow (details in Session Protocols section below):
* User Information
** Calendar Location
-Craig's calendar is available at: =/home/cjennings/sync/org/gcal.org=
+Craig's calendars are at: =~/.emacs.d/data/*cal.org= (gcal.org, dcal.org, pcal.org)
+
+These files are **READ-ONLY** — NEVER add anything to them.
Use this to:
- Check meeting times and schedules
@@ -327,12 +329,11 @@ When monitoring a long-running process (rsync, large downloads, builds, VM tests
#+end_example
***At Completion:***
-1. Play notification sound three times:
+1. Send notification via notify script:
#+begin_src bash
- paplay /usr/share/sounds/freedesktop/stereo/complete.oga
- paplay /usr/share/sounds/freedesktop/stereo/complete.oga
- paplay /usr/share/sounds/freedesktop/stereo/complete.oga
+ notify success "Task Complete" "Description of what finished"
#+end_src
+ Use =fail= type instead of =success= if the task failed.
2. Provide summary of success or failure
#+begin_example
diff --git a/docs/workflows/process-meeting-transcript.org b/docs/workflows/process-meeting-transcript.org
new file mode 100644
index 0000000..647e55f
--- /dev/null
+++ b/docs/workflows/process-meeting-transcript.org
@@ -0,0 +1,301 @@
+#+TITLE: Process Meeting Transcript Workflow
+#+AUTHOR: Craig Jennings & Claude
+#+DATE: 2026-02-03
+
+* Overview
+
+This workflow defines the process for processing meeting recordings from start to finish: finding recordings, extracting audio, transcribing via AssemblyAI, identifying speakers, correcting errors, and archiving files.
+
+* When to Use This Workflow
+
+Trigger this workflow when:
+- Craig says "process the transcript" or "process the recording" or similar
+- New recording files (.mkv) appear in ~/sync/recordings/ after meetings
+- Craig wants to process meeting recordings into labeled transcripts
+
+* Prerequisites
+
+- Recording file(s) exist in ~/sync/recordings/ (*.mkv)
+- Calendar files available at ~/.emacs.d/data/*cal.org for meeting titles
+- AssemblyAI transcription script at ~/.emacs.d/scripts/assemblyai-transcribe
+- AssemblyAI API key stored in ~/.authinfo.gpg (machine api.assemblyai.com)
+- ffmpeg available for audio extraction
+
+* The Workflow
+
+** Step 1: Identify Engagement and Write Session Context
+
+Before starting transcript processing:
+
+1. *Identify which engagement this meeting belongs to:*
+ - DeepSat (default for current work)
+ - Vineti (historical)
+ - Salesforce (historical)
+ - If unclear, ask Craig
+
+2. *Set destination paths based on engagement:*
+ - Assets: ~{engagement}/assets/~ (e.g., ~deepsat/assets/~)
+ - Meetings: ~{engagement}/meetings/~ (e.g., ~deepsat/meetings/~)
+ - Knowledge: ~{engagement}/knowledge.org~ for reference
+
+3. Update docs/session-context.org with current status:
+ - Note that we're about to process a meeting transcript
+ - Get meeting name by checking ~/.emacs.d/data/*cal.org (match date/time to transcript timestamp)
+ - If meeting not found in calendar, ask Craig for the meeting title
+
+4. Ask Craig if he wants to compact the conversation context:
+ - Transcript processing can use significant context
+ - Compacting now preserves the session context file for recovery
+
+** Step 2: Find Recording Files
+
+Find and match recording files with calendar events:
+
+1. **List recordings:** Find all .mkv files in ~/sync/recordings/
+ #+begin_src bash
+ ls -la ~/sync/recordings/*.mkv
+ #+end_src
+
+2. **Extract timestamps:** Parse date/time from each filename (format: YYYY-MM-DD_HH-MM-SS.mkv)
+
+3. **Match with calendar:** Check ~/.emacs.d/data/*cal.org for meetings at those times
+ #+begin_src bash
+ cat ~/.emacs.d/data/dcal.org | grep -A2 "YYYY-MM-DD"
+ #+end_src
+
+4. **Present selection table to Craig:**
+ | Filename | Meeting / Date-Time |
+ |-----------------------------+--------------------------------|
+ | 2026-02-03_10-00-00.mkv | DeepSat Standup (from calendar)|
+ | 2026-02-03_14-30-00.mkv | 2026-02-03 14:30 (no match) |
+
+5. **Craig selects files:** One, several, or all files to process
+
+6. **Queue for processing:** Selected files ordered oldest → newest for serial processing
+
+** Step 3: Extract Audio
+
+For each selected recording file, extract audio for transcription:
+
+#+begin_src bash
+ffmpeg -i ~/sync/recordings/FILENAME.mkv -vn -ac 1 -c:a aac -b:a 96k /tmp/FILENAME.m4a
+#+end_src
+
+Settings:
+- =-vn= : no video (audio only)
+- =-ac 1= : mono channel (sufficient for speech, smaller file)
+- =-c:a aac= : AAC codec
+- =-b:a 96k= : 96kbps bitrate (sufficient for speech transcription)
+
+Output: /tmp/FILENAME.m4a (temporary, deleted after transcription)
+
+** Step 4: Transcribe with AssemblyAI
+
+1. **Run transcription:**
+ #+begin_src bash
+ ~/.emacs.d/scripts/assemblyai-transcribe /tmp/FILENAME.m4a > ~/sync/recordings/FILENAME.txt
+ #+end_src
+
+2. **Clean up:** Delete intermediate .m4a file after successful transcription
+ #+begin_src bash
+ rm /tmp/FILENAME.m4a
+ #+end_src
+
+3. **Output format:** The script produces speaker-diarized output:
+ #+begin_example
+ Speaker A: First speaker's text here.
+ Speaker B: Second speaker's response.
+ Speaker A: First speaker continues.
+ #+end_example
+
+4. Continue to speaker identification workflow below.
+
+** Step 5: Locate Files
+
+Confirm the transcript and recording files are ready:
+
+1. **Verify transcript exists:**
+ #+begin_src bash
+ ls -la ~/sync/recordings/FILENAME.txt
+ #+end_src
+
+2. **Verify recording exists:**
+ #+begin_src bash
+ ls -la ~/sync/recordings/FILENAME.mkv
+ #+end_src
+
+3. **Get meeting title:** If not already known from Step 2, check calendar
+ - Calendar location: ~/.emacs.d/data/*cal.org
+ - Match the meeting time to the transcript timestamp
+
+** Step 6: Read and Analyze Transcript
+
+1. Read the full transcript file
+
+2. Identify speakers by analyzing context clues:
+ - Names mentioned in conversation ("Thanks, Ryan")
+ - Role references ("as the developer", "on the IT side")
+ - Project-specific knowledge (who works on what)
+ - Previous meeting context (known attendees)
+ - Speaking order patterns
+
+3. Build a speaker identification table:
+ | Speaker | Person | Evidence |
+ |---------|--------|----------|
+ | A | Name | Clues... |
+
+** Step 7: Confirm Speaker Identifications
+
+Present the speaker identification table to Craig for confirmation:
+- List each speaker label and proposed name
+- Include the evidence/reasoning
+- Ask about any uncertain identifications
+- Note any new people to add to notes.org contacts
+
+** Step 8: Create Labeled Transcript
+
+1. Replace all speaker labels with actual names
+
+2. Correct transcription errors:
+ - Common mishearings (names, technical terms, company names)
+ - Known substitutions from this project:
+ - "Vanetti" → "Vineti"
+ - "Fresh" → "Vrezh"
+ - "Clean4" / "clone" → "CLIN 4"
+ - "Vascan" → "Vazgan"
+ - "Hike" / "Ike" → "Hayk"
+ - "High Tech" → "HyeTech"
+ - "Java software" → "JAMA software"
+ - "JSON" (person) → "Jason"
+ - "their S" / "ress" → "Nerses"
+ - Technical terms specific to DeepSat (GovCloud, AFRL, SOUTHCOM, etc.)
+
+3. Save to engagement assets folder:
+ - Location: ~{engagement}/assets/~ (e.g., ~deepsat/assets/~)
+ - Filename: YYYY-MM-DD-meeting-name.txt
+ - Example: deepsat/assets/2026-02-03-standup-ipm-grooming.txt
+
+** Step 9: Copy Recording to Meetings Folder
+
+1. Ensure engagement meetings folder exists and pattern is in .gitignore (~*/meetings/*.mkv~)
+
+2. Copy the .mkv file with descriptive name:
+ #+begin_src bash
+ cp ~/sync/recordings/YYYY-MM-DD_HH-MM-SS.mkv {engagement}/meetings/YYYY-MM-DD_HH-MM-meeting-name.mkv
+ #+end_src
+ Example: ~deepsat/meetings/2026-02-03_11-02-standup-ipm-grooming.mkv~
+
+3. Verify the copy succeeded
+
+** Step 10: Update Session Context with Meeting Summary
+
+Add a meeting summary section to docs/session-context.org including:
+
+1. **Attendees** - List all participants
+
+2. **Key Decisions** - Important choices made
+
+3. **Action Items** - Tasks assigned, especially for Craig
+
+4. **New Information** - Things learned that should be noted
+
+5. **New Contacts** - People to add to notes.org
+
+** Step 11: Write Session Context File
+
+Update docs/session-context.org with:
+- Files created this session (transcript, recording)
+- Summary of what was processed
+- Next steps (file to assets, update notes.org, etc.)
+
+*** Context Management (for multiple files)
+
+When processing multiple recordings in a queue:
+
+1. **After completing each file's workflow**, update docs/session-context.org with:
+ - Files processed so far
+ - Current position in queue
+ - Summary of meeting just processed
+
+2. **Ask Craig if compact is needed** before starting next file:
+ - Transcript processing uses significant context
+ - Compacting preserves session context for recovery
+
+3. **If autocompact occurs**, reread session-context.org to:
+ - Resume at correct position in queue
+ - Avoid reprocessing already-completed files
+
+** Step 12: Clean Up Source Files
+
+After successful completion of all previous steps, delete the source files from ~/sync/recordings/:
+
+1. **Delete the original recording:**
+ #+begin_src bash
+ rm ~/sync/recordings/FILENAME.mkv
+ #+end_src
+
+2. **Delete the raw transcript** (if generated):
+ #+begin_src bash
+ rm ~/sync/recordings/FILENAME.txt
+ #+end_src
+
+This step happens last to ensure all files are safely copied/processed before deletion. If anything goes wrong earlier in the workflow, the source files remain intact for retry.
+
+* Output Files
+
+| File | Location | Purpose |
+|--------------------+-------------------------------------------------------+------------------------------------|
+| Labeled transcript | {engagement}/assets/YYYY-MM-DD-meeting-name.txt | Corrected transcript for reference |
+| Meeting recording | {engagement}/meetings/YYYY-MM-DD_HH-MM-meeting-name.mkv | Video for review (gitignored) |
+| Session context | docs/session-context.org | Crash recovery, meeting summary |
+| Knowledge base | {engagement}/knowledge.org | Team, infrastructure, corrections |
+
+* Common Transcription Errors
+
+Keep this list updated as new patterns emerge:
+
+| Heard As | Correct | Context |
+|---------------+---------------+------------------------------------------------|
+| Vanetti | Vineti | Company where Craig, Nerses, Eric, Ryan worked |
+| Fresh | Vrezh | Developer name |
+| Clean4, clone | CLIN 4 | Contract milestone |
+| Vascan | Vazgan | MagicalLabs AI team member |
+| Hike, Ike | Hayk | CTO name |
+| High Tech | HyeTech | Armenian tech community org |
+| Java software | JAMA software | Requirements traceability tool |
+| JSON (person) | Jason | DevSecOps or advisor |
+| their S, ress | Nerses | CEO name |
+| sir Keith | Sarkis | BD/investor relations |
+| Fastgas | MagicalLabs | Armenian AI contractor |
+| Sitelix | Cytellix | CMMC security/compliance partner |
+
+* Tips
+
+1. **Read the whole transcript first** - Context from later in the meeting often helps identify speakers from earlier
+
+2. **Use the calendar** - Meeting names help set expectations for who attended
+
+3. **Check engagement knowledge.org** - Team roster and transcription corrections specific to this engagement
+
+4. **Ask about unknowns** - If a new person appears, ask Craig for context
+
+5. **Note new learnings** - Update engagement knowledge.org with new contacts, corrections, or context after processing
+
+* Validation Checklist
+
+- [ ] Engagement identified and destination paths set
+- [ ] Session context written before starting
+- [ ] Recording files listed and matched with calendar
+- [ ] Craig selected files to process
+- [ ] Audio extracted to .m4a (mono, 96k AAC)
+- [ ] AssemblyAI transcription completed
+- [ ] Intermediate .m4a file deleted
+- [ ] Transcript file verified
+- [ ] All speakers identified
+- [ ] Speaker identifications confirmed with Craig
+- [ ] Transcript corrected and saved to {engagement}/assets/
+- [ ] Recording copied to {engagement}/meetings/ with proper name
+- [ ] Session context updated with meeting summary
+- [ ] New contacts/info flagged for {engagement}/knowledge.org update
+- [ ] (If multiple files) Queue position tracked in session context
+- [ ] Source files deleted from ~/sync/recordings/
diff --git a/docs/workflows/session-start.org b/docs/workflows/session-start.org
new file mode 100644
index 0000000..d7c3ba3
--- /dev/null
+++ b/docs/workflows/session-start.org
@@ -0,0 +1,3 @@
+This workflow has been renamed to startup.org. Run docs/workflows/startup.org instead.
+
+Delete this file (session-start.org) when finished.