[codex] Fix schema docs picoschema examples

content/5.concepts/6.schema-system.md

@@ -126,11 +126,11 @@ Keep a simple task list without a separate project management tool.
 ```yaml
 schema:
   title: string, what needs to be done
-  status(enum): [todo, in-progress, done], current state
-  priority?(enum): [low, medium, high], how urgent
+  status(enum, current state): [todo, in-progress, done]
+  priority?(enum, how urgent): [low, medium, high]
   due_date?: string, target completion date
   belongs_to?: Project, related project
-  blocked_by?(array): Task, dependencies
+  blocked_by?(array, dependencies): Task
 ```
 
 **Then use it naturally:**
@@ -150,11 +150,11 @@ Capture decisions and action items so they don't get lost in a wall of text.
 ```yaml
 schema:
   date: string, when the meeting happened
-  attendees(array): string, who was there
+  attendees(array, who was there): string
   summary?: string, brief overview
-  decisions?(array): string, what was agreed on
-  action_items?(array): string, follow-up tasks
-  relates_to?(array): Project, projects discussed
+  decisions?(array, what was agreed on): string
+  action_items?(array, follow-up tasks): string
+  relates_to?(array, projects discussed): Project
 ```
 
 **Then use it naturally:**
@@ -174,9 +174,9 @@ Organize what you're learning about a topic — articles, key takeaways, open qu
 schema:
   topic: string, what this research is about
   source?: string, where the information came from
-  findings?(array): string, key takeaways
-  questions?(array): string, open questions or things to explore
-  relates_to?(array): Research, connected research notes
+  findings?(array, key takeaways): string
+  questions?(array, open questions or things to explore): string
+  relates_to?(array, connected research notes): Research
   supports?: Hypothesis, hypothesis this evidence supports
 ```
 
@@ -198,9 +198,9 @@ schema:
   cuisine?: string, type of cuisine
   servings?: integer, how many it feeds
   prep_time?: string, how long to prepare
-  ingredients(array): string, what you need
-  steps(array): string, how to make it
-  notes?(array): string, personal tweaks and observations
+  ingredients(array, what you need): string
+  steps(array, how to make it): string
+  notes?(array, personal tweaks and observations): string
   inspired_by?: Recipe, adapted from another recipe
 ```
 
@@ -269,14 +269,21 @@ When a type name is capitalized (like `Organization`), it signals an entity refe
 
 #### Descriptions
 
-Add a description after a comma to document what the field means:
+Add a description after a comma to document what a plain field means:
 
 ```yaml
 name: string, full legal name
 role?: string, current job title or position
 works_at?: Organization, primary employer
 ```
 
+For fields with modifiers like `array`, `enum`, or `object`, put the description inside the parentheses after the modifier:
+
+```yaml
+expertise?(array, areas of knowledge): string
+status?(enum, current relationship status): [active, inactive, alumni]
+```
+
 #### Complete annotated example
 
 ```yaml
@@ -285,8 +292,8 @@ schema:
   role?: string, current job title
   email?: string, primary contact email
   works_at?: Organization, primary employer
-  expertise?(array): string, areas of knowledge
-  status?(enum): [active, inactive, alumni], current relationship status
+  expertise?(array, areas of knowledge): string
+  status?(enum, current relationship status): [active, inactive, alumni]
   contact_info?(object):
     phone?: string
     location?: string
@@ -315,7 +322,7 @@ schema:
   role?: string, job title
   email?: string, contact email
   works_at?: Organization, employer
-  expertise?(array): string, areas of knowledge
+  expertise?(array, areas of knowledge): string
 settings:
   validation: warn
 ---
@@ -351,10 +358,10 @@ Useful for one-off structure or prototyping before committing to a reusable sche
 title: Team Standup 2026-02-10
 type: meeting
 schema:
-  attendees(array): string, participants
-  decisions?(array): string, outcomes
-  blockers?(array): string, unresolved issues
-  action_items?(array): string, follow-up tasks
+  attendees(array, participants): string
+  decisions?(array, outcomes): string
+  blockers?(array, unresolved issues): string
+  action_items?(array, follow-up tasks): string
 ---
 ```
 
@@ -538,7 +545,7 @@ schema:
   role?: string, job title
   email?: string, contact email
   works_at?: Organization, employer
-  expertise?(array): string, areas of knowledge
+  expertise?(array, areas of knowledge): string
 settings:
   validation: warn
   frontmatter:

content/7.how-to/1.project-documentation.md

@@ -60,7 +60,7 @@ schema:
   status: string, current decision status
   context: string, background and problem statement
   decision: string, what was decided
-  consequences?(array): string, outcomes of the decision
+  consequences?(array, outcomes of the decision): string
   supersedes?: ADR, previous decision this replaces
 settings:
   validation: warn

content/8.reference/3.ai-assistant-guide.md

@@ -589,7 +589,7 @@ schema:
   name: string, full legal name
   role?: string, current job title
   works_at?: Organization, primary employer
-  expertise?(array): string, areas of knowledge
+  expertise?(array, areas of knowledge): string
 settings:
   validation: warn
 ---