@ankhorage/devtools 1.10.10 → 1.10.11

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

@@ -2,20 +2,19 @@
 name: ankhorage-project-structure
 description: >
   Design, review, or migrate the source structure of Ankhorage repositories and generated
-  applications. Use for directory ownership, package boundaries, architectural profiles,
-  ports and adapters, package CLI layout, repository skill distribution, public entrypoints,
-  or cross-repository cleanup.
+  applications. Use for directory ownership, package boundaries, package CLI layout, repository
+  skill distribution, public entrypoints, or cross-repository cleanup.
 ---
 
 # Ankhorage Project Structure
 
-Apply a repository profile instead of forcing one folder tree onto every package.
+Apply the general ownership rules first. Only Studio currently has a mandated source taxonomy.
 
 Before deciding structure:
 
 1. Read the repository `AGENTS.md`, `package.json`, exports, source tree, and representative tests.
 2. Load `ankhorage-coding-rules` as the complementary implementation and testing authority.
-3. Identify the repository's owning capability and its profile below.
+3. Identify the repository's owning capability.
 4. Identify current public subpaths and cross-package release boundaries.
 
 Repository-specific rules may refine this skill, but must not silently reverse package ownership
@@ -24,35 +23,23 @@ or dependency direction.
 ## Primary boundary
 
 An Ankhorage repository/package is the primary bounded capability and independently released
-unit. Do not create a generic `src/features/` layer that imitates package boundaries.
+unit. Do not force a Studio directory tree onto libraries, providers, tooling, or generated
+applications.
 
 - Independently bindable capabilities belong in standalone packages.
-- Substantial responsibilities inside a package use cohesive domain directories directly under
-  `src/`.
+- Substantial responsibilities inside a package use cohesive directories owned by the package.
 - Cross-package access uses published APIs and declared dependencies, never sibling source.
 - A package owns its application behavior; adapters belonging to another package are not copied
   or proxied locally.
 
-## Select a profile
-
-Read [repository-profiles.md](references/repository-profiles.md), select one primary profile, and
-apply only the references routed by that profile.
-
-| Profile                            | Typical repositories                                          | Required references                                                                                        |
-| ---------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| Application, engine, or hybrid     | Studio, Runtime, Orchestrator, Deploy, Infra                  | [hexagonal-architecture.md](references/hexagonal-architecture.md)                                          |
-| React Native / Expo application    | generated apps, Studio app host                               | [hexagonal-architecture.md](references/hexagonal-architecture.md), [expo-apps.md](references/expo-apps.md) |
-| Component or design-system library | ZORA, Surface                                                 | [ui-libraries.md](references/ui-libraries.md)                                                              |
-| Contracts or value library         | Contracts and other portable models                           | [repository-profiles.md](references/repository-profiles.md)                                                |
-| Utility library                    | Utility                                                       | [utilities.md](references/utilities.md)                                                                    |
-| Platform/provider adapter          | Expo Runtime, Supabase packages, orchestrator modules         | [repository-profiles.md](references/repository-profiles.md)                                                |
-| Tooling or CLI package             | Ankh, Doctor, Devtools and any package exposing Ankh commands | [cli.md](references/cli.md)                                                                                |
-
 When a package declares an Ankh provider or changes `src/cli/`, always read
-[cli.md](references/cli.md), regardless of its primary profile.
+[cli.md](references/cli.md).
+
+When classifying a local or cross-repository utility, also read
+[utilities.md](references/utilities.md).
 
 When the task is a structural cleanup or migration, also read
-[migration.md](references/migration.md). For Studio specifically, read
+[migration.md](references/migration.md). For `ankhorage/studio`, always also read
 [studio.md](references/studio.md).
 
 When adding, distributing, or synchronizing repository-local agent skills, read
@@ -63,13 +50,8 @@ When adding, distributing, or synchronizing repository-local agent skills, read
 - Keep only intentional package entrypoints and required declaration shims directly under `src/`.
 - Keep one abstraction level and responsibility among siblings.
 - Prefer domain ownership over technical dumping grounds such as `common`, `core`, `helpers`,
-  `misc`, or `shared`.
-- `app/`, `cli/`, `host/`, and `platform/` are package-level edges or composition areas, not
-  alternate owners of domain behavior.
-- Ports are owned by the application/domain code that requires the capability.
-- Adapters depend inward; domain/application code does not import concrete adapters.
-- Add a port only for a real external or replaceable boundary. Do not wrap every function in
-  architecture ceremony.
+  `misc`, or `shared`. `utils/` is the canonical local directory for genuine package-level
+  utilities.
 - Colocate focused unit tests. Put cross-domain acceptance, E2E, smoke infrastructure, and large
   fixtures outside production source.
 - Public package subpaths may point to nested source. Do not keep files at `src/` merely because
@@ -88,3 +70,10 @@ For every file or new symbol, decide in order:
 4. Is it reusable enough to belong in `@ankhorage/utility` instead?
 
 If any answer is unclear, resolve ownership before moving or creating code.
+
+## Studio enforcement
+
+Only `ankhorage/studio` has a mandatory source taxonomy and hexagonal feature architecture. Its
+complete allowlist, exceptions, port/adapter rules, and generated-app policy are in
+[studio.md](references/studio.md). Other repositories remain structurally unconstrained beyond the
+universal invariants until their owning repository is deliberately brought into scope.

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

@@ -3,8 +3,8 @@
 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`.
+Studio is the bounded capability. `features/` is its internal organizational boundary; its contents
+are not independently bound packages.
 
 ## Target source tree
 
@@ -13,29 +13,31 @@ 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/
+  apps/                        # generated applications; Studio-only directory
+    <generated-app>/            # generated; never edited by hand
+    studio/                     # temporary exception until Studio is generated
+
+  features/                    # Studio-owned capabilities
+    auth/
+    bindings/
+    canvas/
+    deploy/
+    diagnostics/
+    external-apis/
+    manifest/
+    media/
+    modules/
+    projects/
+    properties/
+    routes/
+    secrets/
+    selection/
+    templates/
+    workspace/
 
-  utils/
+  utils/                       # the canonical Studio-local utility directory
 
 test/
   acceptance/
@@ -44,8 +46,20 @@ test/
   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.
+`index.ts`, `root.ts`, `cli/`, `host/`, `apps/`, `features/`, and `utils/` are the complete Studio
+root taxonomy, apart from required declaration shims. Do not create `app/`, `platform/`, `common/`,
+`core/`, `helpers/`, or `shared/`.
+
+Substantial features may contain `contracts`, `domain`, `application`, `ports`, `adapters`, and
+focused colocated `tests` when those roles genuinely exist. Do not pre-create role directories.
+
+`apps/` contains complete generator-owned applications. Nothing under it is manually maintained.
+`apps/studio/` is a temporary exception while Studio is still hand-authored; it must disappear when
+the Studio app is generated.
+
+`utils/` is the one canonical local utility directory. It contains only reusable Studio-local,
+framework-neutral helpers; behavior with feature semantics remains in that feature, and behavior
+reused across repositories belongs in `@ankhorage/utility`.
 
 ## Studio CLI
 
@@ -73,41 +87,73 @@ ankh studio projects list    -> commands/projects/list.ts
 ankh studio projects sync    -> commands/projects/sync.ts
 ```
 
+`cli/commands/` contains inbound adapters only: parse command input, invoke a feature application
+operation, and render the result. It must not own feature rules or external-package integrations.
+
+## Studio host
+
+```text
+src/host/
+  createStudioHost.ts
+  middleware/
+  routes/
+    <feature>/
+```
+
+`host/` contains inbound HTTP, filesystem, and process adapters plus their composition. Route and
+middleware modules translate into feature application operations; they do not own feature rules.
+
 `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 `binding*` modules move into `features/bindings/`.
+- Root `canvas*` and insert/placement behavior move into `features/canvas/`.
+- Root `projectDeploy*`, host deploy code, deploy routes, and deploy UI converge under
+  `features/deploy/`, with host routes remaining in `host/routes/deploy/`.
+- Root auth settings/health/OAuth behavior and host auth implementations converge under
+  `features/auth/`, with host routes remaining in `host/routes/auth/`.
 - 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`.
+  `features/external-apis/`, with host routes remaining in `host/routes/external-apis/`.
+- Root media authoring code, host media implementations, and media UI converge under
+  `features/media/`.
+- Root module admin code and host module integration converge under `features/modules/`.
+- Root project/workspace models, project screens, hooks, project store/generation operations, and
+  matching adapters converge under `features/projects/`, `features/templates/`, or
+  `features/workspace/` according to actual ownership.
+- Root secret API/usage/response behavior and host secret implementations converge under
+  `features/secrets/`, with host routes remaining in `host/routes/secrets/`.
+- Route and admin-route policy moves under `features/routes/`; the corresponding host adapters stay
+  in `host/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.
+  between `features/selection/` and `features/canvas/` by actual invariant ownership.
+- The current generic `core/` directory disappears; each file moves to its owning feature role 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/`.
+  moves to `@ankhorage/runtime`; Studio-specific integration becomes a feature-local adapter.
+- Feature-specific UI becomes generated-app code under `apps/`; it is never rehomed in a generic
+  Studio UI directory.
 - Host smoke and acceptance infrastructure moves outside production source to `test/`.
 
+## External package integrations
+
+An Ankhorage or third-party package is connected in the owning feature, not in a global
+`platform/` directory. For example:
+
+```text
+src/features/templates/
+  ports/
+    templateCatalogPort.ts
+  adapters/
+    createAnkhorageTemplatesAdapter.ts
+```
+
+The port states the capability that Templates requires. The adapter imports
+`@ankhorage/templates`, translates its API, and implements that port. The composition root chooses
+the adapter. Do not duplicate an adapter in `host/`, `cli/`, or another feature.
+
 ## Utility gates
 
 The existing own-property helpers explicitly marked for Utility extraction should move through

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/devtools",
-  "version": "1.10.10",
+  "version": "1.10.11",
   "description": "Shared development tools and repository standards for Ankhorage",
   "license": "MIT",
   "homepage": "https://github.com/ankhorage/devtools#readme",
@@ -105,9 +105,9 @@
     "version-packages": "bun src/cli/bin/changeset.ts version"
   },
   "dependencies": {
-    "@ankhorage/utility": "^0.2.0",
+    "@ankhorage/utility": "^0.3.0",
     "@changesets/cli": "^3.0.1",
-    "@eslint/compat": "^2.1.0",
+    "@eslint/compat": "^2.1.1",
     "@eslint/js": "^10.0.1",
     "eslint": "^10.9.1",
     "eslint-config-prettier": "^10.1.8",

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

@@ -1,43 +0,0 @@
-# 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

@@ -1,120 +0,0 @@
-# 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/repository-profiles.md

@@ -1,91 +0,0 @@
-# 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/ui-libraries.md

@@ -1,79 +0,0 @@
-# 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.