@ankhorage/devtools 1.8.5 → 1.9.0

package/dist/tools/skills/assets/ankhorage-project-structure/references/expo-apps.md

@@ -0,0 +1,43 @@
+# Expo and React Native Applications
+
+An Expo application is an independently installable application and may use ports-and-adapters
+principles for its application behavior. Expo Router route files are framework-owned inbound
+adapters, not the home of domain logic.
+
+## Structure
+
+```text
+app/                         # Expo Router route tree
+src/
+  app/                       # providers and app composition
+  <domain>/                  # application-owned domains
+    domain/
+    application/
+    ports/
+  platform/                  # app-local native/web adapters only
+  utils/                     # app-wide internal utilities
+```
+
+Keep route files thin: resolve route parameters and navigation context, invoke or render the owning
+application boundary, and declare route-specific framework configuration. Substantial UI belongs
+with its owning domain or reusable UI package.
+
+## Ankhorage ownership
+
+- Use Contracts for portable authored state.
+- Use Runtime for manifest/action/data execution.
+- Use ZORA and Surface for reusable UI.
+- Use Expo Runtime and provider packages for platform integration.
+- Do not copy package behavior into the generated app merely to avoid a public API or release.
+- Do not import Studio source or rely on the Studio workspace.
+
+## Standalone lifecycle
+
+Each generated app owns its package manifest, lockfile, installation, validation, build, and
+deployment inputs. A parent dashboard may invoke commands with the app as `cwd`, but must not
+install it through a hidden shared workspace contract.
+
+## Platform variants
+
+Use `.native`, `.web`, `.ios`, and `.android` variants only when the platform behavior genuinely
+differs. Keep the portable contract in the unsuffixed module and concrete behavior at the edge.

package/dist/tools/skills/assets/ankhorage-project-structure/references/hexagonal-architecture.md

@@ -0,0 +1,120 @@
+# Ankhorage Ports and Adapters
+
+Use ports-and-adapters principles for application, engine, service, and hybrid packages. The
+Ankhorage package is the hexagon; internal domains are not independent feature packages.
+
+## Purpose
+
+Protect stable package policy from React, Expo, HTTP, Fastify, Bun, filesystem, process, database,
+provider SDK, and test-harness details. The useful rule is dependency direction, not a mandatory
+folder ceremony.
+
+```text
+package edge / adapter -> application -> domain
+                              |
+                              v
+                         required ports
+
+concrete adapter -> required port
+```
+
+## Roles
+
+- **Domain:** pure rules, values, invariants, and deterministic transformations owned by the
+  package.
+- **Application:** command-independent use cases and orchestration of domain behavior.
+- **Port:** a capability contract required by application/domain code to reach an external edge.
+- **Inbound adapter:** converts CLI, HTTP, UI, Runtime, worker, or test input into an application
+  invocation.
+- **Outbound adapter:** implements a required port using filesystem, process, provider, storage,
+  network, Expo, or another package.
+- **Composition:** selects implementations and wires adapters to application operations.
+
+Ports belong beside the application/domain code that needs them. Do not create a global
+`src/ports/` dumping ground.
+
+## Package-level edges
+
+Ankhorage preserves recognizable package edges:
+
+```text
+src/app/       React or React Native composition and package-wide UI entrypoints
+src/cli/       one package-level Ankh provider
+src/host/      Bun/Node/Fastify/filesystem composition and shared host infrastructure
+src/platform/  native, web, Expo, or provider-specific implementations
+```
+
+Internal domain behavior must not migrate into these directories merely because an adapter calls
+it. Edges translate and compose; domains own behavior.
+
+## Domain-first organization
+
+Substantial domains may use role directories:
+
+```text
+src/
+  projects/
+    contracts/
+    domain/
+    application/
+    ports/
+  deploy/
+    contracts/
+    domain/
+    application/
+    ports/
+```
+
+Small domains remain flat while their siblings have the same role. Introduce role directories
+when definitions, parsers, use cases, adapters, or utilities begin mixing at one level.
+
+Do not use:
+
+```text
+src/features/
+src/common/
+src/core/
+src/shared/
+src/ports/
+```
+
+unless a repository has an explicit, narrower meaning that cannot be represented by an owning
+domain or package edge.
+
+## When a port is justified
+
+Create a port when at least one is true:
+
+- more than one real adapter exists or is planned by current architecture;
+- deterministic tests need to replace a side effect;
+- the dependency is volatile or provider-specific;
+- the same application operation is invoked through multiple inbound edges;
+- the capability crosses a package, process, storage, network, platform, or credential boundary.
+
+Do not create a port merely because a function calls another function. Pure utilities, component
+composition, value transformations, and React-local presentation state usually do not need ports.
+
+## React and React Native
+
+React/RN UI is an inbound edge. Components may collect input, render state, and invoke application
+actions. Provider execution and durable business rules remain outside components and hooks.
+
+- Keep navigation route modules thin.
+- Keep UI-specific transient state near the UI.
+- Move reusable business decisions and cross-interface operations into the owning domain or
+  application layer.
+- Inject values, callbacks, or capability interfaces into reusable UI rather than importing
+  concrete providers.
+
+## Composition roots
+
+Keep wiring explicit and limited to package entrypoints such as app startup, host creation, CLI
+provider construction, or a focused factory. Do not use ambient service locators or hidden mutable
+registries as dependency injection.
+
+## Testing
+
+- Test domain and application behavior with deterministic inputs and fake ports.
+- Test concrete adapters against their real protocol boundary.
+- Test user-facing flows through inbound edges only where the integration adds evidence.
+- Do not duplicate the full acceptance matrix for every internal refactor.

package/dist/tools/skills/assets/ankhorage-project-structure/references/migration.md

@@ -0,0 +1,61 @@
+# Structural Migration
+
+Use this reference when the user requests repository cleanup, file movement, boundary correction,
+or adoption of the project structure.
+
+## Establish the target first
+
+Before moving code:
+
+1. inventory direct `src/` files, current domains, entrypoints, tests, and generated sources;
+2. inventory package exports and consumers of public subpaths;
+3. classify the repository profile;
+4. identify code that belongs in another package;
+5. define the intended final directory tree and dependency direction;
+6. identify Utility additions and release gates;
+7. identify obsolete behavior that should be deleted rather than relocated.
+
+Do not begin with a mechanical folder move while ownership remains unresolved.
+
+## Migration units
+
+Migrate cohesive domains or vertical capabilities, not arbitrary batches of similarly named files.
+For each unit:
+
+1. extract any required cross-repository utility first;
+2. release the owning package before updating consumers;
+3. move domain/application code and tests together;
+4. move concrete edge behavior to its package-level adapter area;
+5. preserve intentional public package subpaths by remapping exports to nested output;
+6. remove obsolete barrels, aliases, and duplicate paths;
+7. validate the focused unit before the full repository gates.
+
+Avoid a single repository-wide move when smaller coherent migrations give clearer review and
+rollback boundaries. Avoid tiny PRs that leave two competing architectures active for long periods.
+
+## Root source policy
+
+At the target state, direct `src/` files are limited to intentional entrypoints such as `index.ts`,
+`root.ts`, required environment declarations, or other explicitly documented build entrypoints.
+Public export status alone does not justify root placement.
+
+## Acceptance and enforcement
+
+After the structure is proven in a representative repository:
+
+- distribute the canonical structure skills through `ankh devtools sync` into
+  `.agents/skills/<skill-name>/` as described in
+  [skill-distribution.md](skill-distribution.md);
+- add Devtools import-boundary rules where static enforcement is reliable;
+- add Doctor profile checks for allowed root files and required package entrypoints;
+- use Knip to verify public exports and dead compatibility barrels;
+- keep repository `AGENTS.md` focused on repository-specific ownership rather than duplicating this
+  skill.
+
+Enforcement belongs to Devtools and Doctor, not prose-only repository exceptions.
+
+## No behavior drift
+
+A structural migration preserves current valid behavior unless deletion is an explicit part of the
+approved target architecture. Do not add compatibility implementations solely because files move.
+Use characterization or focused public-surface tests when a move crosses a meaningful boundary.

package/dist/tools/skills/assets/ankhorage-project-structure/references/repository-profiles.md

@@ -0,0 +1,91 @@
+# Repository Profiles
+
+Select one primary profile from the repository's actual ownership and consumers. A package may
+also expose secondary edges such as CLI or Expo without changing its primary profile.
+
+## Application, engine, or hybrid
+
+Use for packages that coordinate use cases, state transitions, external systems, or several
+delivery mechanisms.
+
+Typical structure:
+
+```text
+src/
+  index.ts
+  <domain>/
+    contracts/
+    domain/
+    application/
+    ports/
+  app/                 # optional React/RN edge and composition
+  cli/                 # optional package-level Ankh edge
+  host/                # optional Bun/Node/HTTP/filesystem edge
+  platform/            # optional native/web/provider edge
+  utils/               # internal cross-domain utilities only
+```
+
+Create role subdirectories only when a domain has enough distinct responsibilities to need them.
+Do not pre-create empty `contracts`, `domain`, `application`, or `ports` directories.
+
+## Contracts or value library
+
+Contracts own portable shape and structural validation, not provider execution.
+
+```text
+src/
+  index.ts
+  <domain>/
+    contracts/
+    parsers/
+    constants/
+    tests colocated with their owner
+```
+
+- Keep modules deterministic and side-effect free.
+- Type definitions and structural parsers change together.
+- Provider readiness, network state, filesystem state, and UI behavior stay in their owner.
+- Avoid `Record<string, unknown>` escape hatches when a canonical concept can be modeled.
+
+## Platform or provider adapter
+
+These packages deliberately implement an external technology boundary.
+
+```text
+src/
+  index.ts
+  contracts/           # provider-facing public configuration when owned here
+  planning/            # pure capability/configuration planning
+  adapters/            # concrete provider/platform implementations
+  composition/         # factories or provider registration
+  cli/                 # only when this package exposes Ankh commands
+```
+
+- Depend on portable contracts or ports from lower-level owning packages.
+- Do not redefine the application/domain model locally.
+- Keep provider SDK values from leaking through portable public contracts.
+- Separate build-time planning from runtime execution when both exist.
+
+## Tooling package
+
+Tooling packages may be command-centric but still keep parsing, policy, and side effects distinct.
+
+```text
+src/
+  cli/
+  policy/              # deterministic rules and diagnostics
+  application/         # command-independent operations
+  adapters/            # filesystem, process, GitHub, registry, etc.
+  composition/
+  index.ts
+```
+
+The package remains the boundary. Do not create internal pseudo-packages beneath `features/`.
+
+## Generated or standalone application
+
+A generated application is an independently installable and buildable project. It is not a
+workspace child of Studio and must not depend on Studio-local source or installation state.
+
+Use the Expo application profile when applicable. Application-specific domains live under `src/`;
+route entrypoints remain thin.

package/dist/tools/skills/assets/ankhorage-project-structure/references/skill-distribution.md

@@ -0,0 +1,115 @@
+# Repository Skill Distribution
+
+Use this reference when adding Ankhorage-owned skills to repositories or changing Devtools
+synchronization.
+
+## Canonical destination
+
+Repository-local skills live at:
+
+```text
+.agents/
+  skills/
+    <skill-name>/
+      SKILL.md
+      agents/             # optional
+      references/         # optional
+      scripts/            # optional
+      assets/             # optional
+```
+
+The directory name must equal the skill's frontmatter `name`. Synchronize the complete skill
+directory, not only `SKILL.md`. Do not use `.agent/`, `.codex/skills/`, or a package source
+directory as the shared repository location.
+
+## Devtools ownership
+
+`@ankhorage/devtools` is the distribution authority for canonical Ankhorage-owned repository
+skills. It packages immutable skill sources with the released Devtools version; synchronization
+must not fetch mutable files from GitHub at runtime.
+
+The aggregate commands include the skills scope:
+
+```text
+ankh devtools sync [target]
+ankh devtools status [target]
+```
+
+Also expose focused commands for diagnosis and intentional updates:
+
+```text
+ankh devtools skills sync [target]
+ankh devtools skills status [target]
+```
+
+Their provider capabilities are `devtools.skills.sync` and `devtools.skills.status`.
+
+## Skill selection
+
+Do not copy every available skill into every repository.
+
+- Devtools defines a small baseline of organization-wide Ankhorage skills.
+- Profile-specific Ankhorage skills are selected from repository traits or explicit package
+  metadata when automatic detection would be ambiguous.
+- External, personal, experimental, and task-specific skills are not part of Devtools sync.
+- A repository may own additional skill directories beside the Devtools-managed set.
+
+Prefer the same repository-trait detection used by other Devtools profiles. Add explicit metadata
+only for an actual ambiguity; do not require each repository to repeat a default skill list.
+
+## Managed-tree semantics
+
+Treat each selected canonical skill as an exactly managed directory while preserving the rest of
+`.agents/skills/`.
+
+- Create or replace every canonical file in a selected managed skill.
+- Remove stale files and obsolete skills only when prior Devtools ownership is recorded.
+- Never delete an unowned skill directory or an untracked file merely because it is absent from
+  the Devtools bundle.
+- Record the managed skill names, relative file paths, source Devtools version, and content hashes
+  in a Devtools ownership manifest.
+- Make `sync` idempotent. Make `status` and `--dry-run` report created, updated, removed, and
+  unchanged paths without mutation.
+
+The ordinary single-file managed-file abstraction is insufficient if it cannot report or remove
+stale owned files. Use a managed-tree abstraction or extend the ownership manifest rather than
+deleting `.agents/skills/` wholesale.
+
+## Suggested Devtools source layout
+
+Keep the package-level CLI edge separate from synchronization policy and packaged skill assets:
+
+```text
+src/
+  cli/
+    commands.ts
+    runRepositoryCommand.ts
+  tools/
+    skills/
+      index.ts
+      managed.ts
+      selection.ts
+      assets/
+        <skill-name>/
+          SKILL.md
+          ...
+```
+
+The exact filenames may follow the existing Devtools conventions. The important boundaries are:
+
+- `src/cli/` declares and dispatches `skills sync` and `skills status`;
+- skill selection and managed-tree policy stay outside the CLI;
+- packaged skill directories are release artifacts, not runtime network dependencies.
+
+## Validation
+
+Doctor should validate that:
+
+- every selected managed skill exists at `.agents/skills/<skill-name>/`;
+- directory and frontmatter names agree;
+- managed files match the released Devtools bundle;
+- the ownership manifest contains no unsafe paths;
+- repository-owned skills remain permitted and are not falsely reported as drift.
+
+Devtools remains responsible for applying and reporting synchronization. Doctor reports contract
+violations; it does not rewrite skill trees.

package/dist/tools/skills/assets/ankhorage-project-structure/references/studio.md

@@ -0,0 +1,134 @@
+# Studio Structure Example
+
+Read this only for `ankhorage/studio`. It is a structural target and ownership checklist, not a
+license to move every file in one change.
+
+Studio is an application/hybrid package. The Studio package is the bounded capability; its internal
+responsibilities are domains, not independently bound `features`.
+
+## Target source tree
+
+```text
+src/
+  index.ts
+  root.ts
+
+  app/                         # React/RN application edge and composition
+  cli/                         # one Studio Ankh provider
+  host/                        # Bun/Fastify/filesystem edges and host composition
+  platform/                    # Studio-local native/web implementations only
+
+  auth/
+  bindings/
+  canvas/
+  deploy/
+  diagnostics/
+  external-apis/
+  manifest/
+  media/
+  modules/
+  projects/
+  properties/
+  routes/
+  secrets/
+  selection/
+  templates/
+  workspace/
+
+  utils/
+
+test/
+  acceptance/
+  e2e/
+  fixtures/
+  smoke/
+```
+
+Substantial domains may contain `contracts`, `domain`, `application`, `ports`, and domain-local
+`utils` when those roles genuinely exist. Do not pre-create all role directories.
+
+## Studio CLI
+
+The command tree mirrors paths after the `studio` prefix:
+
+```text
+src/cli/
+  index.ts
+  commands/
+    dev.ts
+    projects/
+      create.ts
+      delete.ts
+      list.ts
+      sync.ts
+```
+
+Mappings:
+
+```text
+ankh studio dev              -> commands/dev.ts
+ankh studio projects create  -> commands/projects/create.ts
+ankh studio projects delete  -> commands/projects/delete.ts
+ankh studio projects list    -> commands/projects/list.ts
+ankh studio projects sync    -> commands/projects/sync.ts
+```
+
+`ankh studio workspace install` is not part of the target. Generated apps are standalone and own
+their installation. Remove the obsolete command, handler, capability, tests, and documentation
+rather than relocating them.
+
+## Current directory disposition
+
+- Root `binding*` modules move into `bindings/`.
+- Root `canvas*` and insert/placement behavior move into `canvas/`.
+- Root `projectDeploy*`, host deploy code, deploy routes, and deploy UI converge under the `deploy`
+  domain and package-level edges.
+- Root auth settings/health/OAuth behavior and host auth implementations converge under `auth` and
+  package-level edges.
+- Root external API contracts/model code, host API services, routes, and UI converge under
+  `external-apis` and package-level edges.
+- Root media authoring code, host media implementations, and media UI converge under `media` and
+  package-level edges.
+- Root module admin code and host module integration converge under `modules` and package-level
+  edges.
+- Root project/workspace models, current app project screens, hooks, project store/generation
+  operations, and matching adapters converge under `projects`, `templates`, or `workspace` according
+  to actual ownership.
+- Root secret API/usage/response behavior, host secret implementations, routes, and UI converge
+  under `secrets` and package-level edges.
+- Route and admin-route behavior moves under `routes`.
+- Selection, measurement, stationary selection, and canvas interaction behavior must be separated
+  between `selection` and `canvas` by actual invariant ownership.
+- The current generic `core/` directory disappears; each file moves to its owning domain or package
+  edge.
+- The current generic `runtime/` directory is reviewed symbol by symbol. Shared runtime behavior
+  moves to `@ankhorage/runtime`; Studio-specific application integration moves to `app/` or its
+  owning domain.
+- Feature-specific UI moves beside its owning domain. Only package-wide UI composition remains in
+  `app/`.
+- Host smoke and acceptance infrastructure moves outside production source to `test/`.
+
+## Utility gates
+
+The existing own-property helpers explicitly marked for Utility extraction should move through
+`@ankhorage/utility` before Studio consumes them. Repeated generic unknown-value narrowing should
+be evaluated under `@ankhorage/utility/object` or `@ankhorage/utility/value`; semantic payload
+parsers remain domain-owned.
+
+## Suggested migration order
+
+Use lower-entanglement domains to prove the structure before moving the largest state models:
+
+1. external APIs;
+2. modules;
+3. media;
+4. secrets;
+5. projects and templates;
+6. deploy;
+7. auth;
+8. canvas and selection;
+9. routes;
+10. manifest.
+
+Reassess cross-package ownership during every unit. Moving a misplaced behavior deeper into Studio
+is not a successful migration when another Ankhorage package owns it.

package/dist/tools/skills/assets/ankhorage-project-structure/references/ui-libraries.md

@@ -0,0 +1,79 @@
+# UI and Design-System Libraries
+
+ZORA and Surface are layered reusable UI libraries, not hexagonal applications. From an
+application's perspective, they help build the inbound UI adapter; internally they use component
+ownership and dependency direction rather than application ports and use cases.
+
+## Recommended layers
+
+```text
+src/
+  foundation/
+  theme/
+  layout/
+  primitives/
+  components/
+  patterns/
+  registry/
+  internal/
+  index.ts
+```
+
+Use only the layers owned by the package. Surface and ZORA must not duplicate the same abstraction.
+
+Dependency direction moves from composed UI toward stable foundations:
+
+```text
+patterns -> components -> primitives/foundation
+patterns -> layout -> foundation
+components -> theme -> foundation
+registry -> component/pattern metadata
+```
+
+Lower layers do not import higher layers. Components do not import the global registry.
+
+## Component ownership
+
+Colocate artifacts that change with the component:
+
+```text
+components/
+  Button/
+    Button.tsx
+    Button.types.ts
+    Button.metadata.ts
+    Button.test.tsx
+```
+
+Keep a component as a single file while it has one homogeneous responsibility. Introduce its
+directory when tests, metadata, platform variants, styles, or private helpers justify it.
+
+Component-specific authoring metadata belongs beside the component. Registry composition may be
+central, but metadata must not become a parallel model detached from implementation and props.
+
+## Patterns
+
+Patterns are reusable UI solutions, not application use cases. Group substantial collections by
+UI capability:
+
+```text
+patterns/
+  auth/
+  content/
+  navigation/
+  onboarding/
+  settings/
+```
+
+A pattern may accept state, values, errors, and callbacks. It must not execute Supabase, HTTP,
+filesystem, deployment, or application authorization behavior.
+
+## Platform behavior
+
+Keep provider and platform execution in the owning adapter package unless it is an unavoidable
+peer-backed UI implementation. Prefer injected values/callbacks and platform-neutral component
+contracts. Expo Runtime and provider packages own application/platform integration.
+
+Do not introduce `domain`, `application`, `ports`, or `adapters` for ordinary components. A complex
+subsystem such as an editor, canvas, or data grid may use internal model/platform boundaries when
+real complexity warrants them.