@ankhorage/devtools 1.11.7 → 1.11.9

package/README.md

@@ -194,10 +194,12 @@ Only the current Ankhorage architecture is supported. Managed instructions rejec
 
 ## Managed repository skills
 
-`ankh devtools skills sync` owns the complete `.agents/skills/ankhorage-coding-rules/` and `.agents/skills/ankhorage-project-structure/` trees from the immutable copies shipped in the Devtools release. It creates `.agents/` when missing, replaces stale files in those managed skills, and preserves every unrelated skill directory.
+`ankh devtools skills sync` owns the complete `.agents/skills/ankhorage-coding-rules/`, `.agents/skills/hexagonal-architecture/`, and `.agents/skills/ankhorage-project-structure/` trees from the immutable copies shipped in the Devtools release. It creates `.agents/` when missing, replaces stale files in those managed skills, and preserves every unrelated skill directory. The project-structure skill requires both the coding-rules and hexagonal-architecture skills before structural work can continue.
 
 `.agents/.devtools-manifest.json` records the source Devtools version and SHA-256 hashes for every managed skill file. That ownership record allows status and dry-run to report drift and lets later releases remove stale owned files without deleting repository-owned skills.
 
+Agent Skill scripts are always TypeScript files with a `.ts` extension and run with Bun. JavaScript skill scripts using `.js`, `.mjs`, or `.cjs` are not supported.
+
 ## ESLint profiles
 
 `createConfig()` defaults to `profile: 'auto'`.

package/dist/internal/readmeDocs.js

@@ -18,6 +18,7 @@ const REQUIRED_README_SNIPPETS = [
     'devtools.agents.sync',
     'devtools.skills.sync',
     'ankhorage-coding-rules',
+    'hexagonal-architecture',
     'devtools.prettier.sync',
     'devtools.knip.sync',
     'devtools.package.sync',

package/dist/tools/agents/index.js

@@ -38,6 +38,12 @@ when they support states that the current architecture can intentionally produce
 For directory ownership, package boundaries, architectural profiles, ports and adapters, public
 entrypoints, or cross-repository structural work, load and follow
 \`.agents/skills/ankhorage-project-structure/SKILL.md\`.
+
+## Skill scripts
+
+Scripts inside an Agent Skill must always be TypeScript files with the \`.ts\` extension.
+JavaScript skill scripts using \`.js\`, \`.mjs\`, or \`.cjs\` are not allowed. Run TypeScript
+skill scripts with Bun.
 `;
 }
 async function readPackageManifest(targetDirectory) {

package/dist/tools/skills/assets/ankhorage-coding-rules/SKILL.md

@@ -47,9 +47,9 @@ exceptions or replaced by generic preferences from this skill.
 
 - Test observable behavior at the owning boundary. Keep tests deterministic and independent of
   execution order, ambient state, and live network services.
-- When testing dependency declarations, assert the required semver range shape or a shared policy
-  value instead of a Renovate-managed literal version. Assert an exact version only when the pin is
-  itself the contract under test.
+- Do not hardcode package versions in tests. When testing dependency declarations, assert the
+  required semver range shape or a shared policy value instead of a Renovate-managed literal
+  version. Assert an exact version only when the pin is itself the contract under test.
 - Follow the range-shape patterns in the
   [Devtools repository sync test](https://github.com/ankhorage/devtools/blob/main/src/cli/runRepositoryCommand.test.ts)
   and [ZORA PR #313](https://github.com/ankhorage/zora/pull/313).

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

@@ -1,79 +1,121 @@
 ---
 name: ankhorage-project-structure
 description: >
-  Design, review, or migrate the source structure of Ankhorage repositories and generated
-  applications. Use for directory ownership, package boundaries, package CLI layout, repository
-  skill distribution, public entrypoints, or cross-repository cleanup.
+  Define, review, or implement the standard source structure of Ankhorage repositories. Use for
+  feature ownership, CLI layout, hexagonal boundaries, source-module naming, utilities, or package
+  entrypoints.
 ---
 
 # Ankhorage Project Structure
 
-Apply the general ownership rules first. Only Studio currently has a mandated source taxonomy.
+Every Ankhorage repository follows this structure. It applies now to `ankhorage/studio`,
+`ankhorage/deploy`, `ankhorage/infra`, `ankhorage/repository`, and `ankhorage/navigator`.
+
+## Required skills
 
-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.
-4. Identify current public subpaths and cross-package release boundaries.
-
-Repository-specific rules may refine this skill, but must not silently reverse package ownership
-or dependency direction.
-
-## Primary boundary
-
-An Ankhorage repository/package is the primary bounded capability and independently released
-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 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.
-
-When a package declares an Ankh provider or changes `src/cli/`, always read
-[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 `ankhorage/studio`, always also read
-[studio.md](references/studio.md).
-
-When adding, distributing, or synchronizing repository-local agent skills, read
-[skill-distribution.md](references/skill-distribution.md).
-
-## Universal invariants
-
-- 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`. `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
-  they are exported.
-- Preserve one canonical implementation. Do not add legacy paths, compatibility barrels, or
-  duplicate APIs to make a migration appear smaller.
-
-## Ownership decision
-
-For every file or new symbol, decide in order:
-
-1. Which Ankhorage package owns the capability?
-2. Which internal domain owns it?
-3. Is it core policy, application orchestration, a required port, an edge adapter, composition,
-   or a public entrypoint?
-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.
+Before structural work, read the repository `AGENTS.md`, inspect its source tree and public
+exports, then load both required repository skills:
+
+1. `.agents/skills/ankhorage-coding-rules/SKILL.md`
+2. [Hexagonal Architecture](../hexagonal-architecture/SKILL.md)
+
+If `ankhorage-coding-rules` is missing or unreadable, stop immediately and report exactly:
+
+```
+Cannot continue: the required repository skill `ankhorage-coding-rules` is missing or unreadable at `.agents/skills/ankhorage-coding-rules/SKILL.md`. Synchronize the repository skills from `@ankhorage/devtools` and retry.
+```
+
+If `hexagonal-architecture` is missing or unreadable, stop immediately and report exactly:
+
+```
+Cannot continue: the required repository skill `hexagonal-architecture` is missing or unreadable at `.agents/skills/hexagonal-architecture/SKILL.md`. Synchronize the repository skills from `@ankhorage/devtools` and retry.
+```
+
+## Required source layout
+
+Every repository provides `src/features/`. It lists the repository's actual product capabilities;
+technical categories are not features. Each feature owns its own hexagonal structure as needed,
+following the required Hexagonal Architecture skill. Do not create empty layers.
+
+Every repository provides `src/cli/`, or has a concrete issue tracking the missing CLI commands.
+CLI modules are thin inbound adapters: they parse input, invoke a feature use case, and render
+output.
+
+```text
+src/
+  cli/
+    createCliProvider.ts
+    commands/
+      <command>.ts
+      <group>/
+        <command>.ts
+  features/
+    <feature>/
+      domain/
+      application/
+        ports/
+          inbound/
+          outbound/
+        use-cases/
+      adapters/
+        inbound/
+        outbound/
+      composition/
+      utils/
+  utils/
+```
+
+Keep only deliberate package facades directly under `src/`. Public package subpaths must name their
+explicit module in `package.json`; generic `index.ts` barrels are not public API exceptions.
+
+The filesystem below `src/cli/commands/` mirrors the public command path after the package prefix:
+
+```text
+ankh <package> <segment> ... <command>
+  -> src/cli/commands/<segment>/.../<command>.ts
+```
+
+The package prefix is represented by the provider and is not repeated under `commands/`. Flags and
+positional arguments do not affect this directory tree. Each command file follows the one-export
+rule: `commands/projects/list.ts` exports `list` and owns only the command-specific input/output
+mapping.
+
+## Feature taxonomy
+
+Siblings always represent the same kind of entity. A folder cannot be an unrelated catch-all beside
+peer entities. For example, this is invalid because `otherFolder` is not a color:
+
+```text
+colors/
+  red/
+  green/
+  blue/
+  otherFolder/
+```
+
+Resolve the ownership of `otherFolder` and move it to the appropriate taxonomy. Use domain names for
+features, not framework, transport, database, or generic technical names.
+
+## One export per production module
+
+Each production source file has exactly one export. Its exported declaration is the first declaration
+after imports and module documentation, and its name matches the filename exactly.
+
+- `myFunction.ts` exports `myFunction`.
+- `myFunctionAsync.ts` exports `myFunctionAsync`.
+- A public operation that is asynchronous or returns a `Promise` uses the `Async` suffix in both its
+  filename and exported name.
+
+Keep private helpers below that exported declaration when they are used only by that module. Move a
+helper used by multiple modules to `utils/` at the owning layer. Put a repository-wide utility in
+`src/utils/`. Put a generally reusable cross-package utility in the correct `@ankhorage/utility`
+location.
+
+## Utilities
+
+`utils/` is the only utility directory name. Do not create `shared/`, `helper/`, `helpers/`,
+`common/`, or equivalent catch-all folders. Feature-local utilities live in that feature's `utils/`;
+utilities shared by repository features live in `src/utils/`.
+
+This skill defines the target architecture. Schedule repository migrations separately and in this
+order: Studio, Deploy, Infra, Repository, Navigator.

package/dist/tools/skills/assets/hexagonal-architecture/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: hexagonal-architecture
+description: >
+  Organize Ankhorage features with ports and adapters so domain policy stays independent from
+  transport, frameworks, and infrastructure.
+origin: ECC, adapted for Ankhorage
+metadata:
+  github-repo: https://github.com/affaan-m/ECC
+  github-ref: refs/tags/v2.2.0
+  github-path: docs/ja-JP/skills/hexagonal-architecture
+---
+
+# Hexagonal Architecture
+
+Hexagonal architecture keeps a feature's domain policy independent from its transport, framework,
+and infrastructure details. The application layer depends on ports; inbound and outbound adapters
+implement the edge-specific work.
+
+## Feature boundaries
+
+Apply this structure inside the owning `src/features/<feature>/` directory. A feature may contain
+only the layers it needs:
+
+```text
+<feature>/
+  domain/
+  application/
+    ports/
+      inbound/
+      outbound/
+    use-cases/
+  adapters/
+    inbound/
+    outbound/
+  composition/
+  utils/
+```
+
+- `domain/` contains entities, value objects, and business policy. It imports no framework,
+  transport, database, or SDK code.
+- `application/` defines use cases and the ports they require. It orchestrates domain behavior and
+  depends only inward.
+- `adapters/inbound/` converts CLI, HTTP, worker, or UI input to use-case input.
+- `adapters/outbound/` implements application ports for persistence, APIs, queues, clocks, and
+  other external dependencies.
+- `composition/` explicitly wires concrete adapters to use cases.
+
+Dependency direction is always inward: adapters depend on application and domain; application
+depends on domain and ports; domain has no external dependencies. Adapters do not call each other
+to bypass a use case.
+
+## Ports and use cases
+
+Define an inbound port when a feature needs a stable use-case boundary. Define an outbound port for
+each capability the application needs from persistence, an external system, or cross-cutting runtime
+services. Model ports as capabilities rather than technologies.
+
+Use cases accept plain inputs, enforce application invariants, coordinate domain behavior through
+ports, and return plain outputs. Keep protocol request objects, database rows, SDK clients, and
+transport error formats in adapters.
+
+## Testing
+
+Test domain rules without framework setup. Test use cases with fakes for outbound ports. Test
+adapters at their boundary with the real protocol or infrastructure they translate. Cover critical
+flows end-to-end through an inbound adapter, use case, and outbound adapter.
+
+## Ankhorage conventions
+
+Follow `ankhorage-project-structure` for feature naming, one-export source modules, and `utils/`
+ownership. Do not introduce legacy paths, compatibility facades, dual implementations, or rollback
+switches while applying this architecture; use the current architecture directly.

package/dist/tools/skills/assets/hexagonal-architecture/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: 'Hexagonal Architecture'
+  short_description: 'Organize Ankhorage features with ports and adapters'
+  default_prompt: 'Use $hexagonal-architecture to design or review the feature boundaries for this Ankhorage change.'
+
+policy:
+  allow_implicit_invocation: true

package/dist/tools/skills/selection.d.ts

@@ -1,4 +1,4 @@
-export declare const BASELINE_SKILL_NAMES: readonly ["ankhorage-coding-rules", "ankhorage-project-structure"];
+export declare const BASELINE_SKILL_NAMES: readonly ["ankhorage-coding-rules", "hexagonal-architecture", "ankhorage-project-structure"];
 export declare const PROFILE_SKILL_NAMES: readonly ["zora-designer"];
 export type ManagedSkillName = (typeof BASELINE_SKILL_NAMES)[number] | (typeof PROFILE_SKILL_NAMES)[number];
 /*** Select baseline and profile-specific managed skills from current repository traits. */

package/dist/tools/skills/selection.js

@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 export const BASELINE_SKILL_NAMES = [
     'ankhorage-coding-rules',
+    'hexagonal-architecture',
     'ankhorage-project-structure',
 ];
 export const PROFILE_SKILL_NAMES = ['zora-designer'];

package/dist/tools/workflows/files/renovate.yml

@@ -22,10 +22,10 @@ permissions:
 jobs:
   changeset:
     if: >-
-      (github.actor == 'renovate[bot]' || github.actor == 'ankhorage-renovate-sync[bot]') &&
+      (github.event.pull_request.user.login == 'renovate[bot]' || github.event.pull_request.user.login == 'ankhorage-renovate-sync[bot]') &&
       github.event.pull_request.head.repo.full_name == github.repository &&
       startsWith(github.event.pull_request.head.ref, 'renovate/')
-    uses: ankhorage/renovate/.github/workflows/changeset.yml@03f29fb8f81d15c51bf16b5374ad92fe8f95e3b5
+    uses: ankhorage/renovate/.github/workflows/changeset.yml@858eb04e4c97798bf3be40fe7b4909d837294a01
     with:
       renovate_sync_client_id: ${{ vars.ANKHORAGE_RENOVATE_SYNC_CLIENT_ID }}
     secrets:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/devtools",
-  "version": "1.11.7",
+  "version": "1.11.9",
   "description": "Shared development tools and repository standards for Ankhorage",
   "license": "MIT",
   "homepage": "https://github.com/ankhorage/devtools#readme",

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

@@ -1,117 +0,0 @@
-# Ankhorage Package CLI
-
-An Ankhorage package may expose one package-level Ankh command provider under `src/cli/`. The
-package is the CLI ownership boundary.
-
-Do not create `cli/` directories inside internal domains. An independently bound package owns its
-own package-level `src/cli/` and release lifecycle.
-
-## Command tree
-
-The filesystem below `src/cli/commands/` mirrors the public command path after the package prefix.
-
-```text
-ankh <package> <segment> ... <command>
-  -> src/cli/commands/<segment>/.../<command>.ts
-```
-
-Examples:
-
-```text
-ankh studio dev
-  -> src/cli/commands/dev.ts
-
-ankh studio projects list
-  -> src/cli/commands/projects/list.ts
-
-ankh studio projects create --name Shop
-  -> src/cli/commands/projects/create.ts
-
-ankh deploy release inspect
-  -> src/cli/commands/release/inspect.ts
-```
-
-The package prefix is represented by the provider and is not repeated under `commands/`. Flags and
-positional arguments do not affect the directory tree.
-
-Bad:
-
-```text
-src/cli/commands/studio/projects/list.ts
-src/cli/commands/listProjects.ts
-src/projects/cli/list.ts
-```
-
-Good:
-
-```text
-src/cli/commands/projects/list.ts
-```
-
-## Layout
-
-```text
-src/
-  cli/
-    index.ts
-    commands/
-      <command>.ts
-      <group>/
-        <command>.ts
-```
-
-`src/cli/index.ts` owns provider identity, category, capabilities, command definitions, handler
-registration, and package-level composition. It contains no substantial command implementation.
-
-Each leaf command module owns one command handler and its command-specific argument/output mapping.
-Tests are colocated:
-
-```text
-src/cli/commands/projects/list.ts
-src/cli/commands/projects/list.test.ts
-```
-
-Do not add command-group barrels unless the group intentionally exposes an API or requires genuine
-composition.
-
-## Naming exception
-
-Command filenames follow public CLI segments rather than exported handler names:
-
-```text
-command:  ankh studio projects list
-file:     src/cli/commands/projects/list.ts
-handler:  listProjects
-```
-
-This is an intentional exception to primary-symbol filenames. It applies only to CLI command leaf
-modules.
-
-## Adapter boundary
-
-A handler may parse `request.argv`, use the provided command context, call package-owned
-application operations, translate failures into command results, and create the package
-composition needed for the invocation.
-
-A handler must not:
-
-- implement domain rules;
-- duplicate application behavior;
-- implement substantial filesystem, network, process, database, credential, or provider logic;
-- proxy behavior owned by another package to place it under the local prefix;
-- preserve removed commands through aliases or hidden handlers.
-
-## Capabilities and public metadata
-
-Keep provider metadata, command definitions, handler paths, public exports, documentation, and
-tests synchronized. Remove unused capabilities when a command disappears. Published command or
-metadata changes require the repository's normal changeset treatment.
-
-## Standalone generated applications
-
-Generated applications own their installation, validation, build, and runtime commands. Execute
-the generated application's canonical command with that application as `cwd`.
-
-Studio must not own a parallel workspace-install command or assume generated applications are
-Studio workspace members. Do not preserve obsolete workspace commands, capabilities, handlers,
-tests, or documentation after the standalone architecture replaces them.

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

@@ -1,61 +0,0 @@
-# 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/skill-distribution.md

@@ -1,120 +0,0 @@
-# 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.
-
-The `zora-designer` profile skill is selected for the ZORA, Templates, and Studio owners and for
-generated-app authoring repositories that consume ZORA with the Ankhorage Runtime, Templates, or
-Studio application model. Plain libraries and unrelated tooling packages retain only baseline
-skills.
-
-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

@@ -1,180 +0,0 @@
-# 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 the bounded capability. `features/` is its internal organizational boundary; its contents
-are not independently bound packages.
-
-## Target source tree
-
-```text
-src/
-  index.ts
-  root.ts
-
-  cli/                         # one Studio Ankh provider
-  host/                        # Bun/Fastify/filesystem edges and host composition
-  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/                       # the canonical Studio-local utility directory
-
-test/
-  acceptance/
-  e2e/
-  fixtures/
-  smoke/
-```
-
-`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
-
-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
-```
-
-`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 `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
-  `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 `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 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
-`@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/utilities.md

@@ -1,62 +0,0 @@
-# Utility Ownership and Unknown-Value Narrowing
-
-Classify a helper before creating or moving it:
-
-```text
-cross-repository, framework-neutral -> @ankhorage/utility/<category>
-cross-domain inside one package      -> src/utils/<functionName>.ts
-one domain only                      -> src/<domain>/utils/<functionName>.ts
-semantic/domain behavior             -> owning domain, not utils
-```
-
-Do not retain local copies while waiting for a Utility release. Follow the Utility repository's
-current PR, merge, release, and dependency-update workflow.
-
-## Strong cross-repository candidates
-
-Generic object and unknown-value operations commonly belong in focused Utility subpaths:
-
-```text
-@ankhorage/utility/object
-  readOwnProperty
-  setOwnProperty
-  deleteOwnProperty
-  isRecord
-
-@ankhorage/utility/value
-  asString
-  asNumber
-  asRecord
-```
-
-Create public utilities only after confirming repetition and stable semantics across repositories.
-Do not move feature payload parsers, provider response semantics, or domain validation merely
-because they contain small type guards.
-
-## Absence and failure semantics
-
-Use consistent meanings:
-
-- `isRecord(value)` returns a type-guard boolean.
-- `asRecord(value)` returns the narrowed record or `undefined`.
-- `asString(value)` returns the string or `undefined`.
-- `readOwnProperty(target, key)` returns the owned value or `undefined`.
-- `parse<DomainValue>(value)` returns an explicit domain parse result when callers need to
-  distinguish absent, invalid, and valid values.
-
-Reserve `null` for an intentional domain or serialized value. Do not use `null` as the generic
-failure result for type narrowing when `undefined` expresses absence. When failure details matter,
-use a discriminated result instead of alternating between `null` and `undefined`.
-
-## Avoid false utilities
-
-Keep these with their owner:
-
-- `readProjectDeployConfig`
-- `readSecretPayload`
-- `parseStudioModuleState`
-- API response validation with feature-specific error policy
-- helpers that encode manifest, route, auth, deploy, or provider semantics
-
-A utility is not a place to hide complexity or shorten a file. It must represent a reusable,
-cohesive capability with stable behavior.