@airmark/quiver 0.33.0 → 0.34.0

package/quills/cyber_ribbon_chart/0.0.1/Quill.yaml

@@ -8,60 +8,75 @@ typst:
   plate_file: plate.typ
 
 # One landscape page an officer hands to a senior rater or a development team.
-# The top half is the plan — alternative assignment vectors laid over the years
-# the boards and schools fall in. The bottom half is the record that makes the
-# plan credible.
+# The top half is the plan: the assignment you hold now, then alternative
+# vectors branching from it over the years the boards and schools fall in. The
+# bottom half is the record that makes the plan credible.
 main:
   ui:
+    # The editor opens one group at a time, starting with the first, so each is a
+    # task finished without looking at another: who you are, where you are
+    # going, what you have done. The checklist is apart from the record because
+    # most visits skip it whole. The timeline's start year sits with the officer
+    # so every required field is in the group that opens.
     groups:
       officer: {}
-      timeline: {}
+      plan: {}
       record: {}
       qualifications: { title: "Qualifications & experience" }
-  # The chart's one piece of prose. It heads the notes area at the foot of the
-  # page, above ruled lines a rater writes on during the discussion.
-  body:
-    example: |
-      What you want out of this discussion, and anything that constrains it — a join-spouse, a degree finishing, a date you cannot move before.
+  # The chart's one piece of prose. It is set on the ruled notes area at the
+  # foot of the page, and a rater goes on writing below it during the discussion.
+  description: "The body is what you want out of this discussion, and anything that shapes it that has no date to draw: a preference, an assignment you would turn down, a question for the rater. A constraint that ends in a known year goes in constraints, where the timeline can show it."
   fields:
     name:
       # Read as `string` rather than `plaintext`: it reaches
       # `set document(author:)`, which takes no content.
       type: string
-      example: Capt John A. Snuffy
       ui:
         group: officer
-      description: "Grade and name as you want them read, set largest on the page. This is also the exported PDF's title and author, so it is written out rather than marked up."
+      description: "Grade and name as you want them read, set largest on the page, as in 'Capt John A. Snuffy'. This is also the exported PDF's title and author, so it is written out rather than marked up."
 
     duty_title:
       type: plaintext
       inline: true
       default: ""
-      example: 17S Instructor · 333 TRS, Keesler AFB
       ui:
         group: officer
-      description: "Current duty title and unit, printed in one line under your name. Where you are today, not where you are going."
+      description: "The job you hold today, as in Instructor or Flight Commander. The unit goes in unit. It prints under your name and heads the current-assignment block the vectors branch from."
+
+    unit:
+      type: plaintext
+      inline: true
+      default: ""
+      ui:
+        group: officer
+      description: "Unit and base, as in '333 TRS, Keesler AFB'."
+
+    afsc:
+      type: plaintext
+      inline: true
+      default: ""
+      ui:
+        group: officer
+        compact: true
+      description: "Your AFSC with its skill level and any prefix, as in 17S3 or K17D3. It leads the line under your name, because it says which half of the career field the plan is in."
 
     commissioning_yg:
       type: integer
-      example: 2022
       ui:
         group: officer
         compact: true
-      description: "Commissioning year group. Every milestone on the timeline is counted from this year, so it is the one number that changes the whole chart — a board at YG+8 lands in this year plus eight."
+      description: "Commissioning year group. Every milestone on the timeline is counted from this year, so it is the one number that changes the whole chart: a board at YG+8 lands in this year plus eight."
 
     adjusted_yg:
-      type: integer
-      default: 0
+      type: integer?
       ui:
         group: officer
         compact: true
-      description: "Adjusted year group, if a board or a break in service moved yours. Leave at 0 when it is unchanged; the chart then counts from your commissioning year group and prints nothing here."
+      description: "Adjusted year group, if a board or a break in service moved yours. The chart counts every milestone from it and prints it as your year group, noting the one you commissioned in. Leave blank when it is unchanged; the chart then counts from your commissioning year group."
 
     date_of_rank:
       type: date
       default: ""
-      example: 2026-05-01
       ui:
         group: officer
         compact: true
@@ -70,56 +85,85 @@ main:
     date_arrived_station:
       type: date
       default: ""
-      example: 2025-06-15
       ui:
         group: officer
         compact: true
-      description: "Date arrived station, YYYY-MM-DD. Read together with your first tour's length, it is what tells a rater when you are actually available to move."
+      description: "Date arrived station, YYYY-MM-DD. Leave blank to print a dash."
+
+    timeline_start_year:
+      type: integer
+      ui:
+        group: officer
+        compact: true
+      description: "First calendar year the timeline shows. Usually the current year: the chart is a plan, so it starts where you are, not where you commissioned."
 
     advanced_degree:
       type: plaintext
       inline: true
       default: ""
-      example: MS Cyber Operations, AFIT
       ui:
         group: officer
-        compact: true
-      description: "Advanced academic degree, in hand or in progress. Leave blank if you hold none — the slot prints a dash rather than disappearing, because its absence is itself information to a board."
+      description: "Advanced academic degree, as in 'MS Cyber Operations, AFIT'. Add '(in progress)' for one you have not finished. Leave blank if you hold none: the slot prints a dash rather than disappearing, because its absence is itself information to a board."
 
-    timeline_start_year:
-      type: integer
-      example: 2026
-      ui:
-        group: timeline
-        compact: true
-      description: "First calendar year the timeline shows. Usually the current year: the chart is a plan, so it starts where you are, not where you commissioned."
 
     timeline_years:
       type: integer
       default: 12
       ui:
-        group: timeline
+        group: plan
         compact: true
       description: "How many years wide the timeline is. Twelve carries a Captain from today past the Lt Col board and is the comfortable reading width. The full milestone ladder runs to YG+17, so widening it toward eighteen brings the SDE looks into view at the cost of narrower columns; any milestone that falls outside the window is counted in a note rather than dropped."
 
-    vectors:
+    move_year:
+      type: integer?
+      ui:
+        group: plan
+        compact: true
+      description: "The year you expect to leave this assignment. The current-assignment block runs until it and every vector starts from it, so this is the date a rater reads first. Every vector leaves on this one date; a vector that stays longer, say to upgrade in place, starts with that extension as its first tour. Leave blank to start the vectors at the left edge of the timeline with no current block."
+
+    move_cycle:
+      type: enum
+      values: [Summer, Winter]
+      default: Summer
+      ui:
+        group: plan
+        compact: true
+      description: "The VML cycle you would move on in that year. Winter moves print in the first half of the year and Summer moves in the second."
+
+    constraints:
       type: array
       max: 3
+      ui:
+        group: plan
+        layout: table
       items:
         type: object
         properties:
-          label:
+          note:
             type: plaintext
             inline: true
-            default: ""
-            example: Command track
-            description: "Short name for the row, set in bold at the left of the timeline. Leave blank to print 'Vector 1', 'Vector 2' and so on in the order the rows stand."
-          focus:
+            title: Constraint
+            description: "What limits the plan, short enough for a bar, as in 'Join-spouse, no OCONUS'."
+          through:
+            type: integer
+            title: Through
+            description: "The last year it holds."
+      default: []
+      description: "Anything that limits where or when you can move and ends in a known year: a join-spouse assignment, a degree finishing, a child's school year. Each prints under the timeline's years as a bar from its left edge to the end of the last year the constraint holds, above the vectors, so a rater sees which ones cross it. A constraint with no end year belongs in the body."
+
+    vectors:
+      type: array
+      max: 3
+      ui:
+        group: plan
+      items:
+        type: object
+        properties:
+          track:
             type: plaintext
             inline: true
             default: ""
-            example: Primary
-            description: "What this vector is for, set small under the label — 'Primary', 'Alternate', 'Backup'. Leave blank where the label already says it."
+            description: "What this vector is for, as in 'Command track' or 'Joint'. Its rank comes from its position: the first row prints as Primary, the second as Alternate, the third as Backup."
           tours:
             type: array
             ui:
@@ -130,53 +174,27 @@ main:
                 title:
                   type: plaintext
                   inline: true
-                  example: 333 TRS Instructor
                   title: Assignment
-                  description: "Assignment and unit, set in the block. Keep it to what fits — roughly twenty characters per year of length at the default width."
-                duration:
-                  type: enum
-                  values: ["0.5", "1", "1.5", "2", "2.5", "3", "3.5", "4"]
-                  default: "2"
+                  description: "Assignment and unit as you would say it, as in '333 TRS/DO' or 'Joint Staff J6'. Keep it to what fits: roughly twelve characters per year of length at the default width. A longer title sets smaller, or turns up the side of a narrow block, and one that fits neither way is left off its block."
+                years:
+                  type: number
+                  default: 2
                   title: Years
-                  description: "Length in years. The timeline is ruled in half-years, which is why the choices stop at the half."
-                vml:
-                  type: enum
-                  values: [Summer, Winter]
-                  default: Summer
-                  title: VML
-                  description: "Which VML cycle you would move on. This places the tour rather than labelling it: a Summer tour starts in the second half of a year and a Winter tour in the first. Where that means waiting, the wait is added to the tour before it rather than left as a hole — you hold a job until you move — so a tour can print longer than the length you gave it."
+                  description: "Length in years, in halves: 0.5 to 4. The timeline is ruled in half-years, one per VML cycle, so a length is rounded to the nearest half, and one outside that range draws at the nearer end, marked with a dagger. A whole number of years keeps you on the cycle you moved in on; a half switches Summer to Winter or back."
                 school:
                   type: boolean
                   default: false
-                  description: "Tick for a school you would move for — IDE or SDE in residence, Weapons School — rather than a duty assignment. It prints outlined instead of filled, so a year in a classroom does not read as a year in a job."
-            description: "The assignments on this row, in the order you would serve them. Tours lay end to end from the start of the timeline, so there are no dates to keep in step."
+                  description: "Tick for a school you would move for, such as IDE or SDE in residence or Weapons School, rather than a duty assignment. It prints outlined instead of filled, so a year in a classroom does not read as a year in a job."
+            description: "The assignments on this row, in the order you would serve them. The first starts on your move, and each one after starts when the one before it ends, so there are no dates to keep in step."
       default:
-        - { label: Vector 1, focus: Primary, tours: [] }
-        - { label: Vector 2, focus: Alternate, tours: [] }
-        - { label: Vector 3, focus: Backup, tours: [] }
-      example:
-        - label: Vector 1
-          focus: Primary — command track
-          tours:
-            - { title: 333 TRS Instructor, duration: "4", vml: Summer }
-            - { title: 333 TRS / DO, duration: "3.5", vml: Winter }
-            - { title: IDE in residence, duration: "1", vml: Summer, school: true }
-        - label: Vector 2
-          focus: Alternate — staff depth
-          tours:
-            - { title: 17X CFM Staff, duration: "2.5", vml: Winter }
-            - { title: MAJCOM A3 Division Chief, duration: "2", vml: Summer }
-        - label: Vector 3
-          focus: Backup — joint
-          tours:
-            - { title: Joint Staff J6, duration: "3", vml: Summer }
-            - { title: USCYBERCOM JFHQ-C, duration: "2.5", vml: Winter }
-      ui:
-        group: timeline
-      description: "One row per alternative career path. Three is the conventional chart and all the page holds — a primary, an alternate, and a backup. One is a plan; three is a conversation."
+        - { track: "", tours: [] }
+        - { track: "", tours: [] }
+        - { track: "", tours: [] }
+      description: "One row per alternative career path after the assignment you hold now: a primary, an alternate and a backup, in that order. One is a plan; three is a conversation, and all the page holds."
 
     stratifications:
       type: array
+      max: 3
       ui:
         group: record
         layout: table
@@ -184,30 +202,22 @@ main:
         type: object
         properties:
           year:
-            type: plaintext
-            inline: true
-            example: "2026"
+            type: integer
             description: "The reporting year."
-          rater_strat:
+          rater:
             type: plaintext
             inline: true
             default: ""
-            example: "#1/14 Capts"
             title: Rater
-            description: "Your rater's stratification as it was written, such as '#1/14 Capts'."
-          hlr_strat:
+            description: "Your rater's stratification as it was written, as in '#1/14 Capts'."
+          hlr:
             type: plaintext
             inline: true
             default: ""
-            example: "#1/45 Capts"
             title: Higher Level Reviewer
-            description: "Your Higher Level Reviewer's stratification as it was written, such as '#1/45 Capts'. Leave blank where you drew none."
+            description: "Your Higher Level Reviewer's stratification as it was written, as in '#1/45 CGOs'. Leave blank where you drew none."
       default: []
-      example:
-        - { year: "2026", rater_strat: "#1/14 Capts", hlr_strat: "#1/45 Capts" }
-        - { year: "2025", rater_strat: "#2/12 Capts", hlr_strat: "#3/40 Capts" }
-        - { year: "2024", rater_strat: "#1/8 Lts, #2/40 Instructors", hlr_strat: "" }
-      description: "Your last three years of stratifications, most recent first. Three is what the page is built for; more rows will set, and the section grows to hold them. Written out, a row is `{year: \"2026\", rater_strat: \"#1/14 Capts\", hlr_strat: \"#1/45 CGOs\"}`."
+      description: "Your last three years of stratifications, in any order: the page sets the most recent first. Three is all the page holds. Written out, a row is `{year: 2026, rater: \"#1/14 Capts\", hlr: \"#1/45 CGOs\"}`."
 
     awards:
       type: array
@@ -215,9 +225,6 @@ main:
         type: plaintext
         inline: true
       default: []
-      example:
-        - Wing CGOQ ×2
-        - HAF A2/6 CGOY 2025
       ui:
         group: record
       description: "Major awards, one per line, strongest first. Wing level and above earns a line; anything smaller costs more room than it wins."
@@ -228,13 +235,9 @@ main:
         type: plaintext
         inline: true
       default: []
-      example:
-        - SANS FOR577 (GLIR)
-        - CISSP
-        - Security+
       ui:
         group: record
-      description: "Certifications and courses, one per line. Name the certification a board would recognize rather than every course you have sat."
+      description: "Certifications and courses, one per line. Name the certification a board would recognize rather than every course you have sat. PME and the Cyber 200 and 300 courses are ticked under qualifications instead."
 
     deployments:
       type: array
@@ -242,21 +245,20 @@ main:
         type: plaintext
         inline: true
       default: []
-      example:
-        - 1× short tour — returned Jan 2024
       ui:
         group: record
-      description: "Deployments and short tours, one per line. Include the return date: it is what a rater needs to work out when you are next eligible."
+      description: "Deployments and short tours, one per line, with the month you returned: it is what a rater needs to work out when you are next eligible."
 
-    # The page prints every member in four columns and marks the held ones, so
-    # an empty box is as much of the chart as a filled one. A column is a
-    # property here rather than a heading in the plate, so the partition is in
-    # the value and the address as well as on the page.
+    # The page prints every member in four rows and marks the held ones, so an
+    # empty box is as much of the chart as a filled one. A row is a property
+    # here rather than a heading in the plate, so the partition is in the value
+    # and the address as well as on the page. The plate repeats each `title` as
+    # its row's label, since the data carries only the members.
     qualifications:
       type: object
       ui:
         group: qualifications
-      description: "Tick what you hold. The page prints the whole 17X vocabulary and marks these — a rater reads the empty boxes as readily as the filled ones, so what you have not done yet is on the page whether you tick it or not. Written out, a tick is `flight_cc: true`, and a tick with its detail `flight_cc: {held: true, detail: 333 TRS/DO}`."
+      description: "Tick what you hold. The page prints the whole 17X vocabulary and marks these: a rater reads the empty boxes as readily as the filled ones, so what you have not done yet is on the page whether you tick it or not. A ticked course or school also marks its milestone on the timeline done. Written out, a tick is `flight_cc: true`, and a tick with its detail `flight_cc: {detail: UMS Flt/CC}`; an unticked member is left out."
       properties:
         command:
           type: matrix
@@ -275,10 +277,10 @@ main:
               type: plaintext
               inline: true
               default: ""
-              example: "2025"
-              description: "The unit, course, or year that proves it, set in italics under the label. Leave blank where the label says enough on its own."
+              description: "The unit, course, year or distinction that proves it, set in italics after the label, as in '23 IOS' or 'DG'. Leave blank where the label says enough on its own."
         operations:
           type: matrix
+          title: Operations
           ui:
             compact: true
           members:
@@ -304,6 +306,9 @@ main:
             instructor: Instructor
             jqo: Joint Qualified Officer (JQO)
           properties: *detail
+        # Completion and distinction are one tick and its detail, so SOS held
+        # with detail DG reads as both. Candidate and graduate are two ticks:
+        # they are different rungs, and a board reads them differently.
         education:
           type: matrix
           title: Education & PME
@@ -311,10 +316,12 @@ main:
             compact: true
           members:
             commissioning_dg: Commissioning Source DG
-            sos_dg: SOS DG / Top Third
+            sos: SOS
             cyber_200: Cyber 200
             cyber_300: Cyber 300
-            ide: IDE Candidate / Graduate
-            sde: SDE Candidate / Graduate
+            ide_candidate: IDE Candidate
+            ide_graduate: IDE Graduate
+            sde_candidate: SDE Candidate
+            sde_graduate: SDE Graduate
             weapons_school: Weapons School / WIC DG
           properties: *detail

package/quills/cyber_ribbon_chart/0.0.1/example.md

@@ -0,0 +1,55 @@
+~~~
+$quill: cyber_ribbon_chart
+name: Capt John A. Snuffy
+afsc: 17S3
+duty_title: Instructor
+unit: 333 TRS, Keesler AFB
+date_arrived_station: 2025-06-15
+move_year: 2028
+move_cycle: Summer
+commissioning_yg: 2022
+date_of_rank: 2026-05-01
+advanced_degree: MS Cyber Operations, AFIT
+constraints:
+  - { note: "Join-spouse, no OCONUS", through: 2029 }
+vectors:
+  - track: Command
+    tours:
+      - { title: 333 TRS/DO, years: 2 }
+      - { title: IDE in residence, years: 1, school: true }
+      - { title: "Sq/CC, Scott AFB", years: 2 }
+  - track: Staff depth
+    tours:
+      - { title: 17X CFM Staff, years: 2.5 }
+      - { title: MAJCOM A3 Division Chief, years: 2 }
+  - track: Joint
+    tours:
+      - { title: Joint Staff J6, years: 3 }
+      - { title: USCYBERCOM JFHQ-C, years: 2.5 }
+stratifications:
+  - { year: 2026, rater: "#1/14 Capts", hlr: "#1/45 Capts" }
+  - { year: 2025, rater: "#2/12 Lts", hlr: "#3/40 CGOs" }
+  - { year: 2024, rater: "#1/8 Lts, #2/40 Instructors" }
+awards:
+  - Wing CGOQ x2
+  - HAF A2/6 CGOY 2025
+certifications:
+  - SANS FOR577 (GLIR)
+  - CISSP
+  - Security+
+deployments:
+  - 1x short tour, returned Jan 2024
+qualifications:
+  operations:
+    dodin_ops: true
+    dco: { detail: 23 IOS }
+    crew_cc: true
+  staff:
+    instructor: { detail: 333 TRS }
+  education:
+    sos: { detail: DG }
+    cyber_200: { detail: "2025" }
+timeline_start_year: 2026
+~~~
+
+What I want out of this discussion: the DO seat at the 333 TRS when my instructor tour ends, then IDE in residence. I'd rather not go to staff before I've had a DO job.