@3fn/core 14.0.0 → 15.0.0

package/dist/consumer-canonical/shared/always-set.yaml

@@ -0,0 +1,113 @@
+# always-set.yaml — the locked always-set (C2.1; design.md § "C2 — Shared substrate files").
+#
+# Members are the 9 identity docs under .kiro/steering/**, each carrying its doc `id`
+# (read from that doc's own frontmatter — never guessed from filename), a per-doc CLASS
+# annotation, and a per-target DELIVERY hint (the D1/D2 classification signal: `file` vs
+# `skill` delivery — these are always-on docs, so `file` for every member and every target).
+#
+# The class values are NOT invented here — they are the per-doc AXA classification recorded
+# as the authoritative overlay in 119-A's requirements.md Req 6 AC1 (the "locked always-set
+# (~9 docs)" enumeration), cross-checked against per-agent-ambient-design.md and
+# agent-experience-architecture.md §3.7. Two docs (DesignerPunk-Systems-Overview,
+# Civitas-System-Overview) are recorded there as an EXPLICITLY UNRESOLVED "orientation
+# reference" class — not one of the five canonical AXA classes (formative /
+# reflexive-principle / governance-as-law / ground-truth-manifest / capability-catalog) —
+# carried through here as-is rather than silently resolved.
+#
+# The composition rule (Req 9, RATIFIED 2026-07-05, `9d8070ae`): ambient(agent) =
+# alwaysSet ∪ agent.ambient members. The union is computed in C3.2; C1 rule 5 (membership
+# hygiene, tools/agent-generator/schema.ts validateMembershipHygiene) makes the other
+# reading — an always-set doc re-appearing under a per-agent ambient.governanceAsLaw block
+# as if it were an opt-out surface — a validation ERROR.
+#
+# Traces to: Req 4, Req 8, Req 9, Req 11 AC2/AC5, Req 12 AC4, Req 13 AC2, Req 14.
+
+alwaysSet:
+  - id: personal-note
+    class: formative
+    # Source: 119-A requirements.md Req 6 AC1 ("Personal Note (formative)").
+    classSource: "119-A requirements.md Req 6 AC1"
+    delivery:
+      cc: file
+      kiro: file
+
+  - id: core-goals
+    class: formative
+    # Source: 119-A requirements.md Req 6 AC1 lists "Core Goals (formative/operational)" —
+    # the formative-vs-operational cut is recorded there as an OPEN RE-CUT (AXA §8.5,
+    # per-agent-ambient-design.md line 250), resolved for authoring purposes as `formative`
+    # (the §3.1 reading) but flagged, not silently hardened.
+    classSource: "119-A requirements.md Req 6 AC1; open re-cut flagged in per-agent-ambient-design.md (AXA §8.5) — resolved here as formative, not silently hardened"
+    delivery:
+      cc: file
+      kiro: file
+
+  - id: ai-collaboration-principles
+    class: reflexive-principle
+    # Source: 119-A requirements.md Req 6 AC1 ("AI-Collaboration-Principles (reflexive-principle)").
+    classSource: "119-A requirements.md Req 6 AC1"
+    delivery:
+      cc: file
+      kiro: file
+
+  - id: spec-feedback-protocol
+    class: reflexive-principle
+    # Source: 119-A requirements.md Req 6 AC1 ("Spec-Feedback-Protocol (reflexive-principle)").
+    classSource: "119-A requirements.md Req 6 AC1"
+    delivery:
+      cc: file
+      kiro: file
+
+  - id: start-up-tasks
+    class: operational
+    # Source: 119-A requirements.md Req 6 AC1 ("Start Up Tasks (refocused — operational law)").
+    # Note: per-agent-ambient-design.md line 134 separately labels this `governance-as-law`
+    # under the five-class AXA taxonomy ("operational law (pre-task checklist)... Req 6 AC1
+    # the operational checklists are governance-as-law overlaid") — the two sources agree on
+    # substance (operational law) but differ on which named bucket it sits in; requirements.md
+    # Req 6 AC1's own enumeration of this exact 9-doc set is used as the more specific source.
+    classSource: "119-A requirements.md Req 6 AC1"
+    delivery:
+      cc: file
+      kiro: file
+
+  - id: task-completion-protocol
+    class: operational
+    # Source: 119-A requirements.md Req 6 AC1 ("Task Completion Protocol (new — operational law)").
+    classSource: "119-A requirements.md Req 6 AC1"
+    delivery:
+      cc: file
+      kiro: file
+
+  - id: agent-directory
+    class: capability-routing
+    # Source: 119-A requirements.md Req 6 AC1 ("Agent-Directory (capability-routing — `always`
+    # in 119-A, migrates in 119-B)"). Req 6 AC6 records the migration of this routing table
+    # into the GENERATED capability catalog as an explicit 119-B/122 forward-reference; 122
+    # (this generator) is that consumer, but this substrate file does not itself perform the
+    # migration — it only carries the doc through the locked always-set as authored.
+    classSource: "119-A requirements.md Req 6 AC1 / AC6"
+    delivery:
+      cc: file
+      kiro: file
+
+  - id: designerpunk-systems-overview
+    class: orientation-reference
+    # Source: 119-A requirements.md Req 6 AC1 ("DesignerPunk-Systems-Overview (orientation
+    # reference, retained ambient)"). agent-experience-architecture.md §3.7 records this class
+    # as an EXPLICITLY UNRESOLVED boundary case — it maps to none of the five canonical AXA
+    # classes cleanly; retained ambient pending a "sixth class or trim" decision that has not
+    # been made. Carried through here as authored, not resolved by this file.
+    classSource: "119-A requirements.md Req 6 AC1; unresolved boundary case per agent-experience-architecture.md §3.7"
+    delivery:
+      cc: file
+      kiro: file
+
+  - id: civitas-system-overview
+    class: orientation-reference
+    # Source: 119-A requirements.md Req 6 AC1 ("Civitas-System-Overview (orientation reference,
+    # retained ambient)"). Same unresolved §3.7 boundary case as designerpunk-systems-overview.
+    classSource: "119-A requirements.md Req 6 AC1; unresolved boundary case per agent-experience-architecture.md §3.7"
+    delivery:
+      cc: file
+      kiro: file

package/dist/consumer-canonical/shared/field-dispositions.yaml

@@ -0,0 +1,85 @@
+# field-dispositions.yaml — per-target field/tool-ref dispositions (C2.3;
+# design.md § "C2 — Shared substrate files"; Req 11 AC2/AC5).
+#
+# configFields: one row per Kiro config field OBSERVED in .kiro/agents/*.json, enumerated
+# by inspecting the union of top-level keys across all 8 configs (ada, data, kenya,
+# leonardo, lina, sparky, stacy, thurgood). Sweep 7 fails on any unlisted field, so
+# completeness matters more than tidiness — every top-level key found is listed below,
+# including ones whose "disposition" is that they are NOT dropped/transformed (they map to
+# an existing C1 frontmatter class and are handled by that class's own adapter logic, not
+# by this file) — those rows carry `cc: handled-elsewhere` with the owning class named, so
+# the field is not silently absent from this table.
+#
+# runtimeToolRefs: one row per runtime-specific tool reference found used in Kiro-native
+# governance prose (Task-Completion-Protocol.md and related process docs use `taskStatus`;
+# `getDiagnostics` is the paired Kiro-native IDE diagnostics tool). `/knowledge` is a
+# distinct case: it is a Kiro CONFIG surface (`allowedTools: ["knowledge", ...]` +
+# per-agent `knowledgeBases` declarations), not a tool ref embedded in routed doc prose, so
+# it is carried as a configFields-style disposition via the existing `knowledgeBases`
+# frontmatter class (schema.ts CONTENT_CLASS_REGISTRY.knowledgeBases) rather than duplicated
+# here as a runtimeToolRefs row — flagged so the omission reads as a considered placement,
+# not a gap.
+#
+# Traces to: Req 4, Req 8, Req 9, Req 11 AC2/AC5, Req 12 AC4, Req 13 AC2, Req 14.
+
+configFields:
+  - field: keyboardShortcut
+    cc: drop-with-reason
+    reason: "CC has no agent-swap hotkeys; routing note rendered instead"
+
+  - field: welcomeMessage
+    cc: drop-with-reason
+    reason: "CC subagents have no greeting surface"
+
+  - field: hooks.agentSpawn
+    cc: transform
+    into: "behavioral pre-flight note rendered into prompt"
+
+  - field: toolsSettings.write.allowedPaths
+    cc: transform
+    into: "write-scope behavioral note (field-driven render) — CC has no declarative per-agent write-path field (cc-agent-model.md facet 7: path rules are session-global, not per-agent); a per-agent PreToolUse hook or isolation:worktree are the documented enforcement options named in the note, not emitted as a declarative scope"
+
+  - field: includeMcpJson
+    cc: drop-with-reason
+    reason: "CC reads .mcp.json globally"
+
+  - field: name
+    cc: handled-elsewhere
+    reason: "maps to C1 frontmatter `agent` (identity class); not a disposition candidate on its own"
+
+  - field: description
+    cc: handled-elsewhere
+    reason: "maps to C1 frontmatter `description` (identity class), rendered into the CC subagent frontmatter description field"
+
+  - field: prompt
+    cc: handled-elsewhere
+    reason: "a Kiro file:// pointer to the prompt markdown; superseded by the generator emitting the CC/Kiro prompt bodies directly from canonical source (C1 body), not carried as a disposition-table field"
+
+  - field: tools
+    cc: handled-elsewhere
+    reason: "Kiro's own coarse ['*'] grant; the checkable object is the finer-grained `allowedTools` row below plus canonical `toolSubset`, not this field"
+
+  - field: allowedTools
+    cc: transform
+    into: "explicit per-agent namespaced CC tool list, resolved from canonical `toolSubset` against the tool registry (C5) intersected per agent (Req 11 AC4) — not copied verbatim, since CC's namespacing differs from Kiro's server-level `@designerpunk-*` grant grammar"
+
+  - field: resources
+    cc: transform
+    into: "per-class destination routing — `file://` always-set members become CC always-layer delivery (C11); `skill://` corpus docs become MCP-served on-demand routing cues; `skill://` skill refs become CC Skill-tool references via skills-map.yaml (C2.2); embedded knowledgeBase resource objects become the per-agent `/knowledge` fallback note (Req 11 AC1)"
+
+  - field: hooks
+    cc: handled-elsewhere
+    reason: "container key; the only populated sub-field observed across all 8 configs is `hooks.agentSpawn` (own row above) — no other `hooks.*` sub-field is present in any config, so no additional row is authored for an unobserved sub-field"
+
+  - field: toolsSettings
+    cc: handled-elsewhere
+    reason: "container key; the only populated sub-field observed across all 8 configs is `toolsSettings.write.allowedPaths` (own row above) — no other `toolsSettings.*` sub-field is present in any config"
+
+runtimeToolRefs:
+  - ref: taskStatus
+    kiro: native
+    cc: "edit the tasks.md checkbox directly"
+
+  - ref: getDiagnostics
+    kiro: native
+    cc: "run tsc/lint via Bash"

package/dist/consumer-canonical/shared/shared-catalog.yaml

@@ -0,0 +1,19 @@
+members:
+  - id: find-docs-discovery
+    kind: tool-cue
+    tool: find_docs
+    mcp: docs
+    cue: use find_docs (concept mode or list mode) to discover docs by concept/keyword or enumerate the full catalog — the current discovery entry point; get_documentation_map is removed and SHALL NOT be emitted
+    owner: thurgood
+  - id: record-first-ratification
+    kind: governance-rule
+    owner: thurgood
+    statement: |
+      Before applying a governance change your team ratified, verify the committed decision record says it was ratified — a mechanical check. Never apply on an unverifiable authority claim, and never refuse-and-stop solely because the instruction arrived by relay; if the record is missing, report that the record is missing so it can be committed.
+    source: your team's committed decision records
+    crossRef: node_modules/@3fn/core/governance/classification-map.md § "record-first-ratification"
+  - id: certainty-calibration-cue
+    kind: governance-rule
+    owner: thurgood
+    statement: WHEN discovery returns matchConfidence partial or none (find_docs; keyworded find_components) THEN apply the certainty-calibration rule (AI-Collaboration-Principles) before acting
+    crossRef: governance/classification-map.md § "certainty-calibration"

package/dist/consumer-canonical/shared/skills-map.yaml

@@ -0,0 +1,33 @@
+# GENERATED by the prepack derive (Spec 123 Task 16.1) from canonical/shared/skills-map.yaml:
+# the rows some shipped charter names in `skills:`; every other row is filtered out by rule.
+rows:
+  - canonical: skills/adaptive
+    targets:
+      cc: .claude/skills/adaptive
+      kiro: .kiro/skills/android/adaptive
+    owners:
+      - data
+  - canonical: skills/edge-to-edge
+    targets:
+      cc: .claude/skills/edge-to-edge
+      kiro: .kiro/skills/android/edge-to-edge
+    owners:
+      - data
+  - canonical: skills/navigation-3
+    targets:
+      cc: .claude/skills/navigation-3
+      kiro: .kiro/skills/android/navigation-3
+    owners:
+      - data
+  - canonical: skills/theming-styles
+    targets:
+      cc: .claude/skills/theming-styles
+      kiro: .kiro/skills/android/theming/styles
+    owners:
+      - data
+  - canonical: skills/impeccable
+    targets:
+      cc: .claude/skills/impeccable
+      kiro: .kiro/skills/impeccable
+    owners:
+      - leonardo

package/dist/consumer-canonical/skills/adaptive/SKILL.md

@@ -0,0 +1,301 @@
+---
+name: adaptive
+description: Instructions to make or update an app's UI so that it adapts to different
+  Android devices including phones, tablets, foldables, laptops, desktop, TV, Auto
+  and XR. It includes how to handle different window sizes, pointing devices (such
+  as mouse) and text entry devices (such as keyboard) using the Compose MediaQuery
+  API. It also covers multi-pane layouts using Navigation3 Scenes, adaptive UI components
+  (such as buttons) with varying target sizes, and adaptive layouts (including navigation
+  areas - nav rails and nav bars) using the Compose Grid and FlexBox APIs.
+license: Complete terms in LICENSE.txt
+metadata:
+  author: Google LLC
+  last-updated: '2026-05-20'
+  keywords:
+  - android
+  - ui
+  - adaptive
+  - Grid
+  - FlexBox
+  - MediaQuery
+  - navigation
+---
+
+## Prerequisites
+
+The app must:
+
+- Use Compose for all screens. If it's still using Fragments or Views, suggest using the XML to Compose skill to migrate those screens.
+- Use Jetpack Navigation 3. If it doesn't, suggest the Navigation 3 skill to migrate the app.
+
+## Workflow to make an app adaptive
+
+To make an app adaptive, follow these steps or a subset of them adapting to the
+task.
+
+- Step 1: Verify current UI
+- Step 2: Make the navigation bar adaptive
+- Step 3: Add multi-pane layouts
+- Step 4: Make vertical lists adaptive by changing the number of columns
+- Step 5: Hide app bars when scrolling
+
+## Step 1. Verify current UI
+
+Ensure that screenshot tests exist to verify the current UI on different form
+factors. If they don't exist, add the [Compose Preview Screenshot Testing
+tool](references/android/develop/ui/compose/tooling/debug.md). Use the following annotation to create previews for all the major form
+factors. For example:
+
+
+```kotlin
+@Preview(name = "Phone", device = Devices.PHONE, showBackground = true)
+@Preview(name = "Foldable", device = Devices.FOLDABLE, showBackground = true)
+@Preview(name = "Tablet", device = Devices.TABLET, showBackground = true)
+@Preview(name = "Desktop", device = Devices.DESKTOP, showBackground = true)
+annotation class FormFactorPreviews
+
+@PreviewTest
+@FormFactorPreviews
+@Composable
+fun FeedScreenPreview() {
+    SnippetsTheme {
+        Box {
+            Text("My Screen")
+        }
+    }
+}
+```
+
+<br />
+
+## Step 2. Make the navigation bar adaptive
+
+Bottom navigation bars are optimized for touch input when the user is holding a
+phone in portrait mode. On larger screen hand-held devices, like tablets and
+unfolded foldables, the navigation area must be accessible from the edge of the
+screen (navigation rail).
+
+If you need to provide more screen real state for the content, hide the
+navigation area. Examples of this include:
+
+- Hiding the navigation bar when the user scrolls down and showing it again when the user scrolls up. The assumption is that when the user is scrolling down, they are consuming content but when scrolling up they are trying to navigate away from that content.
+- Hiding the navigation area when its content is distracting. For example, in camera previews or when the content is best displayed in full screen (such as a single photo screen).
+
+When the detail screen is displayed full-screen on mobile, full-screen mode must
+be deactivated on larger screens.
+
+Steps to migrate:
+
+- Locate the existing navigation bar.
+- Convert each item to a `NavigationSuiteItem`.
+- Identify whether the navigation bar's visibility changes. For example, if it is wrapped with an `AnimatedContent` or `AnimatedVisibility` composable. If so, follow the guidance in the "Control navigation area visibility".
+- Replace the container that held the navigation bar (often a `Scaffold`) with `NavigationSuiteScaffold` from the Material 3 adaptive layouts library.
+- Supply the navigation items using the `navigationItems` parameter of `NavigationSuiteScaffold`.
+
+### Step 2.1. Control navigation area visibility
+
+If the navigation bar's visibility changes - it is hidden under certain
+scenarios or on certain screens - this behavior must be maintained with the
+adaptive navigation area. This is done using `NavigationSuiteScaffold`'s `state`
+parameter.
+
+Steps to migrate:
+
+- Identify the scenarios under which the navigation bar is hidden. This is usually done with a boolean variable for the visibility. It could be named something like `isNavBarVisible` or `shouldShowNavBar`.
+- Create an instance of `NavigationSuiteScaffoldState` using `rememberNavigationSuiteScaffoldState()` and pass it to `NavigationSuiteScaffold`.
+- When the navigation area visibility changes, use a `LaunchedEffect` to call `show` or `hide` on the `NavigationSuiteScaffoldState`.
+
+For example:
+
+
+```kotlin
+// Pass this variable to any composable that needs to control the navigation area visibility
+var isNavBarVisible by remember { mutableStateOf(true) }
+val scaffoldVisibilityState = rememberNavigationSuiteScaffoldState()
+
+NavigationSuiteScaffold(
+    navigationSuiteItems = navItems,
+    state = scaffoldVisibilityState
+) {
+    // Main content
+}
+
+LaunchedEffect(isNavBarVisible){
+    if (isNavBarVisible) {
+        scaffoldVisibilityState.show()
+    } else {
+        scaffoldVisibilityState.hide()
+    }
+}
+```
+
+<br />
+
+## Step 3. Add multi-pane layouts using Navigation 3 Scenes
+
+Analyze the codebase looking for related screens - tapping on something in one
+screen opens another screen that shows information related to the first. There
+are two canonical screen relationships: list-detail and supporting pane.
+
+IMPORTANT: You must use the Navigation 3 `SceneStrategy` approach to implement
+multi-pane layouts. Do not use `ListDetailPaneScaffold` or
+`SupportingPaneScaffold`.
+
+### Step 3.1. List-detail
+
+#### Identify the list and detail screens
+
+List-detail layouts display a list of items (this is the list screen) and
+clicking on an item opens a new screen that shows more details about that item
+(the detail screen).
+
+Typical usage includes productivity apps like email, notes, and messaging.
+
+Unless requested explicitly, avoid this pattern when the detail content requires
+substantial screen space (e.g., images or media that benefits from a full-screen
+presentation).
+
+#### Add a Material list-detail SceneStrategy
+
+- Add the `androidx.compose.material3.adaptive:adaptive-navigation3` library
+- Create an `androidx.compose.material3.adaptive.navigation3.ListDetailSceneStrategy` using `rememberListDetailSceneStrategy`
+- Pass the `ListDetailSceneStrategy` to `NavDisplay` using its `sceneStrategies` parameter
+
+#### Use metadata to identify the list and detail screens
+
+- Add metadata using `entry(metadata = ...)` or `NavEntry(metadata = ...)` to the list entry using `ListDetailSceneStrategy.listPane(detailPlaceholder = {
+  <placeholder composable> })`.
+- Use the `detailPlaceholder` parameter to add a placeholder on the detail screen when no list items are selected.
+- Add metadata to the detail entry using `ListDetailSceneStrategy.detailPane()`.
+
+#### Important considerations
+
+- When a detail screen displays its content full-screen on mobile (content fills the entire screen, bars or rails are hidden), full-screen mode must be deactivated if it's part of a list-detail layout.
+- Detail screens must not show a back arrow when on a list-detail layout.
+
+For a reference implementation, check the [Nav3 **Material** List Detail
+recipe](references/android/guide/navigation/navigation-3/recipes/material-listdetail.md).
+
+### Step 3.2. Supporting pane
+
+Identify supporting pane screens where a main screen displays a single item, and
+selecting it opens a "supporting screen" with more details. The supporting
+screen complements the main screen and is shown in a supporting pane.
+
+#### Add a Material supporting pane `SceneStrategy`
+
+- If you haven't already, add the `androidx.compose.material3.adaptive:adaptive-navigation3` library
+- Create an `androidx.compose.material3.adaptive.navigation3.SupportingPaneSceneStrategy` using `rememberSupportingPaneSceneStrategy`
+- Pass the `SupportingPaneSceneStrategy` to `NavDisplay` using its `sceneStrategies` parameter
+
+#### Use metadata to identify the main and supporting screens
+
+- Add metadata using `entry(metadata = ...)` or `NavEntry(metadata = ...)` to the main entry using `SupportingPaneSceneStrategy.mainPane()`
+- Add metadata to the supporting entry using `SupportingPaneSceneStrategy.supportingPane()`
+
+### Step 3.3. Run screenshot tests
+
+If you have made changes, record new reference files. Ask the user to visually
+verify that the new layouts are correct.
+
+## Step 4. Make vertical lists adaptive by changing the number of columns
+
+### Step 4.1. Make lazy lists adaptive
+
+Look for the following vertical list composables: `LazyColumn`,
+`LazyVerticalGrid`, `LazyVerticalStaggeredGrid`.
+
+Steps to migrate:
+
+- Choose a suitable minimum width in dp for the column. It should be large enough so that item is clearly visible to the user.
+- For `LazyColumn`: change to a `LazyVerticalGrid` and follow the instruction below
+- For `LazyVerticalGrid`: change the `columns` parameter to use `GridCells.Adaptive(<width>.dp)`
+- For `LazyVerticalStaggeredGrid`: change the `columns` parameter to use `StaggeredGridCells.Adaptive(<width>.dp)`
+
+### Step 4.2. Migrate non-lazy lists to Grid
+
+WARNING: Grid is an experimental API available from Compose 1.11.0-beta01.
+Confirm with the user that they are happy to use an experimental API in their
+codebase.
+
+Look for any `Column` that contains multiple items of the same type and replace
+it with `Grid`. Do not replace it with `LazyVerticalGrid` or any other lazy
+layout. Do not place `Grid` inside the existing `Column`. Completely replace it.
+
+`Grid` is configured by supplying a lambda (an extension function on
+`GridConfigurationScope`) to its `config` parameter. Inside the lambda,
+`constraints` provides the minimum and maximum dimensions of the grid container
+and can be used to change the number of rows and columns based on the available
+size. For example, the following code configures `Grid` such that when the
+available width is:
+
+- less than 800dp, a 2x4 grid is used
+- 800dp or more, a 4x2 grid is used
+
+
+```kotlin
+Grid(
+    config = {
+        val maxWidthDp = constraints.maxWidth.toDp()
+        val (cols, rows) = if (maxWidthDp < 800.dp){
+            2 to 4
+        } else{
+            4 to 2
+        }
+
+        val gapSizeDp = 8.dp
+        val cellSize = ((maxWidthDp - (gapSizeDp * (cols - 1))) / cols).coerceAtLeast(0.dp)
+        repeat(cols) { column(cellSize) }
+        repeat(rows) { row(cellSize) }
+        gap(gapSizeDp)
+    }
+) { /** items **/ }
+```
+
+<br />
+
+`Grid` is an experimental API so add the `@OptIn(ExperimentalGridApi::class)`
+annotation to any function that uses it.
+
+## Step 5: Hide App Bars when scrolling
+
+In an app with multiple top-level destinations, each screen must manage its own
+app bar state independently. There are two main scroll behaviors:
+
+- `exitUntilCollapsedScrollBehavior`: Hides on scroll down, stays hidden while you scroll up until you reach the very top (0 offset).
+- `enterAlwaysScrollBehavior`: Hides on scroll down, shows immediately on scroll up.
+
+## Final step: Build and test
+
+Build the app and run the local tests. If the project has screenshot tests, run
+them but DO NOT update the reference images. Prompt the user to do this after
+they have viewed the screenshot diffs.
+
+## Additional documentation for experimental adaptive APIs
+
+The following APIs are available from Compose 1.11.0-beta01.
+
+### FlexBox
+
+Check the FlexBox documentation:
+
+- [Overview](references/android/develop/ui/compose/layouts/adaptive/flexbox/index.md)
+- [Get started - setup](references/android/develop/ui/compose/layouts/adaptive/flexbox/get-started.md)
+- [Set container behavior](references/android/develop/ui/compose/layouts/adaptive/flexbox/container-behavior.md)
+- [Set item behavior](references/android/develop/ui/compose/layouts/adaptive/flexbox/item-behavior.md)
+
+## MediaQuery
+
+Check the [MediaQuery documentation](references/android/develop/ui/compose/layouts/adaptive/mediaquery/index.md) when you need to query the device's
+screen size, pointer precision, keyboard type, whether it has cameras or
+microphones, and other device capabilities.
+
+## Grid
+
+Check the Grid documentation when you need to display a fixed number of items in
+a grid layout:
+
+- [Overview](references/android/develop/ui/compose/layouts/adaptive/grid/index.md)
+- [Get started - setup](references/android/develop/ui/compose/layouts/adaptive/grid/get-started.md)
+- [Set container properties](references/android/develop/ui/compose/layouts/adaptive/grid/container-properties.md)
+- [Set item properties](references/android/develop/ui/compose/layouts/adaptive/grid/item-properties.md)

package/dist/consumer-canonical/skills/adaptive/references/android/develop/ui/compose/layouts/adaptive/flexbox/container-behavior.md

@@ -0,0 +1,112 @@
+To configure the behavior of the `FlexBox` container, create a `FlexBoxConfig`
+block and supply it using the `config` parameter.
+
+
+```kotlin
+FlexBox(
+    config = {
+        direction(FlexDirection.Column)
+        wrap(FlexWrap.Wrap)
+        alignItems(FlexAlignItems.Center)
+        alignContent(FlexAlignContent.SpaceAround)
+        justifyContent(FlexJustifyContent.Center)
+        gap(16.dp)
+    }
+) { // child items
+}
+```
+
+<br />
+
+Use `FlexBoxConfig` to define the layout direction, wrapping behavior,
+alignment, and gaps between items.
+
+## Layout direction
+
+The `direction` function sets the main axis, which dictates the direction
+items are laid out in. It accepts the following values:
+
+- `Row` (default): Sets the main axis to be horizontal. In left-to-right locales this will be left-to-right, with the opposite in right-to-left.
+- `RowReverse`: Reverses the direction of `Row`.
+- `Column`: Sets the main axis to be vertical, top-to-bottom.
+- `ColumnReverse`: Reverses the direction of `Column`.
+
+## Align items and distribute extra space
+
+The following sections describe how to align items and distribute extra space
+along the main and cross axes.
+
+### Along the main axis
+
+Use `justifyContent` to distribute items along the main axis. The following
+table shows the behavior when the direction is `Row`.
+
+|---|---|
+|   | ![Illustration of a horizontal main axis.](https://developer.android.com/static/develop/ui/compose/images/layouts/adaptive/flexbox/main-axis.png) |
+| `Start` | ![Items aligned to the start of the main axis.](https://developer.android.com/static/develop/ui/compose/images/layouts/adaptive/flexbox/mainaxis-start.png) |
+| `Center` | ![Items aligned to the center of the main axis.](https://developer.android.com/static/develop/ui/compose/images/layouts/adaptive/flexbox/mainaxis-center.png) |
+| `End` | ![Items aligned to the end of the main axis.](https://developer.android.com/static/develop/ui/compose/images/layouts/adaptive/flexbox/mainaxis-end.png) |
+| `SpaceBetween` | ![Items distributed along the main axis with space between them.](https://developer.android.com/static/develop/ui/compose/images/layouts/adaptive/flexbox/mainaxis-spacebetween.png) |
+| `SpaceAround` | ![Items distributed along the main axis with space around them.](https://developer.android.com/static/develop/ui/compose/images/layouts/adaptive/flexbox/mainaxis-spacearound.png) |
+| `SpaceEvenly` | ![Items distributed along the main axis with space evenly around them.](https://developer.android.com/static/develop/ui/compose/images/layouts/adaptive/flexbox/mainaxis-spaceevenly.png) |
+
+### Along the cross axis
+
+Use `alignItems` to align items along the cross axis within a single line. This
+behavior can be overridden by individual items using the
+[`alignSelf` modifier](https://developer.android.com/develop/ui/compose/layouts/adaptive/flexbox/item-behavior#item-alignment).
+
+The following images show the behavior when the direction is `Row`:
+
+|---|---|---|---|---|---|
+| ![Illustration of a vertical cross axis.](https://developer.android.com/static/develop/ui/compose/images/layouts/adaptive/flexbox/crossaxis.png) | ![Items aligned to the start of the cross axis.](https://developer.android.com/static/develop/ui/compose/images/layouts/adaptive/flexbox/crossaxis-start.png) | ![Items aligned to the end of the cross axis.](https://developer.android.com/static/develop/ui/compose/images/layouts/adaptive/flexbox/crossaxis-end.png) | ![Items aligned to the center of the cross axis.](https://developer.android.com/static/develop/ui/compose/images/layouts/adaptive/flexbox/crossaxis-center.png) | ![Items stretched to fill the cross axis.](https://developer.android.com/static/develop/ui/compose/images/layouts/adaptive/flexbox/crossaxis-stretch.png) | ![Items aligned to their baseline along the cross axis.](https://developer.android.com/static/develop/ui/compose/images/layouts/adaptive/flexbox/crossaxis-baseline.png) |
+|   | `Start` | `End` | `Center` | `Stretch` | `Baseline` |
+
+Use `alignContent` to align lines to the cross axis and to distribute extra
+space between lines. This property only applies when there are multiple lines
+(wrapping is enabled). The following images show the behavior when the direction
+is `Row`:
+
+|---|---|---|---|---|---|---|
+| ![Illustration of a vertical cross axis.](https://developer.android.com/static/develop/ui/compose/images/layouts/adaptive/flexbox/crossaxis.png) | ![Multiple lines of items aligned to the start of the cross axis.](https://developer.android.com/static/develop/ui/compose/images/layouts/adaptive/flexbox/aligncontent-start.png) | ![Multiple lines of items aligned to the end of the cross axis.](https://developer.android.com/static/develop/ui/compose/images/layouts/adaptive/flexbox/aligncontent-end.png) | ![Multiple lines of items aligned to the center of the cross axis.](https://developer.android.com/static/develop/ui/compose/images/layouts/adaptive/flexbox/aligncontent-center.png) | ![Multiple lines of items stretched to fill the cross axis.](https://developer.android.com/static/develop/ui/compose/images/layouts/adaptive/flexbox/aligncontent-stretch.png) | ![Multiple lines of items distributed along the cross axis with space between them.](https://developer.android.com/static/develop/ui/compose/images/layouts/adaptive/flexbox/aligncontent-spacebetween.png) | ![Multiple lines of items distributed along the cross axis with space around them.](https://developer.android.com/static/develop/ui/compose/images/layouts/adaptive/flexbox/aligncontent-spacearound.png) |
+|   | `Start` | `End` | `Center` | `Stretch` | `SpaceBetween` | `SpaceAround` |
+
+## Wrap items
+
+Wrapping lets a `FlexBox` container become multi-line, moving items that don't
+fit onto a new row or column along the cross-axis. Configure wrapping behavior
+using `wrap`.
+
+|---|---|
+| **`FlexWrap` value** | **Example using direction `Row`** |
+| `NoWrap` (default): Prevents items from wrapping. Items overflow if the main size is insufficient. | ![Items in a single line overflowing the container because wrapping is disabled.](https://developer.android.com/static/develop/ui/compose/images/layouts/adaptive/flexbox/wrapitems-1.png) |
+| `Wrap`: When there is insufficient space for an item (plus any [gap](https://developer.android.com/develop/ui/compose/layouts/adaptive/flexbox/container-behavior#add-gaps)), a new line is created in the direction of the cross axis. For example, if the direction is `Row`, a new line is added **below**. | ![Items wrapping onto a new line below because wrapping is enabled.](https://developer.android.com/static/develop/ui/compose/images/layouts/adaptive/flexbox/wrapitems-2.png) |
+| `WrapReverse`: The same as `Wrap`, except the new line is added in the opposite direction to the cross axis. For example, if the direction is `Row`, a new line is added **above**. | ![Items wrapping onto a new line above because reverse wrapping is enabled.](https://developer.android.com/static/develop/ui/compose/images/layouts/adaptive/flexbox/wrapitems-3.png) |
+
+The following example shows how the `FlexBox` wrapping algorithm works. The
+`FlexBox` container has a main size of `100dp`, with `wrap` set to
+`FlexWrap.Wrap` and a gap of `8dp`. It contains three items with `basis` `20dp`,
+`40dp`, and `50dp`, respectively.
+
+There is `100dp` available space in the line. Child 1 is `20dp`.
+There is space, so Child 1 is placed into the line.
+![First item placed in the FlexBox container.](https://developer.android.com/static/develop/ui/compose/images/layouts/adaptive/flexbox/algorithm-1.png) **Figure 1.** First item placed in the `FlexBox` container.
+
+There is `80dp` available space in the line. The gap is `8dp`. Child 2 is
+`40dp`. The required space is `48dp`. There is space, so the gap and Child 2
+are placed into the line.
+![First item placed in the FlexBox container.](https://developer.android.com/static/develop/ui/compose/images/layouts/adaptive/flexbox/algorithm-2.png) **Figure 2.** Second item placed in the `FlexBox` container after the first item.
+
+There is `32dp` available space in the line. The gap is `8dp`. Child 3 is
+`50dp`. The required space is `58dp`. There is not enough space in the current
+line, so Child 3 is placed in a new line.
+![Third item placed on a new line because it doesn't fit on the first line.](https://developer.android.com/static/develop/ui/compose/images/layouts/adaptive/flexbox/algorithm-3.png) **Figure 3.** Third item placed on a new line because it doesn't fit on the first line.
+
+## Add gaps between items
+
+Add gaps between rows and columns using `rowGap` and `columnGap`. This is useful
+to avoid adding spacing modifiers to children.
+
+|---|---|---|
+| ![Row gap adds vertical space between items.](https://developer.android.com/static/develop/ui/compose/images/layouts/adaptive/flexbox/gap-1.png) | ![Column gap adds horizontal space between items.](https://developer.android.com/static/develop/ui/compose/images/layouts/adaptive/flexbox/gap-2.png) | ![Gap adds both horizontal and vertical space between items.](https://developer.android.com/static/develop/ui/compose/images/layouts/adaptive/flexbox/gap-3.png) |
+| `rowGap` adds vertical space between items and lines. | `columnGap` adds horizontal space between items and lines. | `gap` is a convenience function that adds both `columnGap` and `rowGap`. |