Add OCI Image Spec reference and image manifest/image support to regshape-dev skill

.github/skills/regshape-dev/SKILL.md

@@ -1,6 +1,6 @@
 ---
+description: 'Design, implement, and document the RegShape Python library and CLI for OCI (Open Containers Initiative) registry interactions. Use when: (1) Designing API specs or data models for registry operations, (2) Implementing Python library modules for manifests, blobs, tags, auth, or referrers, (3) Designing CLI commands using Click, (4) Writing user documentation for the library or CLI, (5) Planning break/test mode features for testing registry implementations, (6) Working on any RegShape library or CLI code.'
 name: regshape-dev
-description: "Design, implement, and document the RegShape Python library and CLI for OCI (Open Containers Initiative) registry interactions. Use when: (1) Designing API specs or data models for registry operations, (2) Implementing Python library modules for manifests, blobs, tags, auth, or referrers, (3) Designing CLI commands using Click, (4) Writing user documentation for the library or CLI, (5) Planning break/test mode features for testing registry implementations, (6) Working on any RegShape library or CLI code."
 ---
 
 # RegShape Development
@@ -13,11 +13,13 @@ The recommended workflow is **spec → implement → test → document**, but an
 
 ### Phase 1: Design Spec
 
-1. Read [references/oci-distribution-spec.md](references/oci-distribution-spec.md) for the relevant OCI API details
+1. Read the relevant OCI spec references for the domain:
+   - [references/oci-distribution-spec.md](references/oci-distribution-spec.md) — registry API endpoints, uploads, auth, error codes
+   - [references/oci-image-spec.md](references/oci-image-spec.md) — image manifests, image index, image config, filesystem layers, descriptors
 2. Read [references/spec-templates.md](references/spec-templates.md) for the spec template to use
 3. Read [references/project-conventions.md](references/project-conventions.md) for naming and structure patterns
-4. Create the spec as a Markdown file in `/specs/<domain>/<feature>.md`
-5. Present the spec to the user for review before proceeding
+
+4. Create the spec as a Markdown file in `/specs/<domain>/<feature>.md`5. Present the spec to the user for review before proceeding
 
 ### Phase 2: Implement
 
@@ -27,6 +29,7 @@ The recommended workflow is **spec → implement → test → document**, but an
    - Module file with functions/classes
    - Update `__init__.py` exports
    - Add error types to `libs/errors.py` if needed
+
 4. Write tests in `src/regshape/tests/test_<module>.py`
 5. Run `pytest` to verify
 
@@ -45,6 +48,7 @@ The recommended workflow is **spec → implement → test → document**, but an
    - `docs/library/` — Library API reference
    - `docs/cli/` — CLI command reference
    - `docs/guides/` — How-to guides
+
 3. Keep docs aligned with the specs and implementation
 
 ## Domain Areas
@@ -53,13 +57,15 @@ The recommended workflow is **spec → implement → test → document**, but an
 |--------|-------------|-----------|----------|
 | Authentication | `libs/auth/` | `specs/auth/` | `docs/library/auth.md` |
 | Manifests | `libs/manifests/` | `specs/registry/manifest-operations.md` | `docs/library/manifests.md` |
+| Image Manifests & Index | `libs/manifests/` | `specs/registry/image-manifests.md` | `docs/library/manifests.md` |
+| Images | `libs/images/` | `specs/registry/image-operations.md` | `docs/library/images.md` |
 | Blobs | `libs/blobs/` | `specs/registry/blob-operations.md` | `docs/library/blobs.md` |
 | Tags | `libs/tags/` | `specs/registry/tag-operations.md` | `docs/library/tags.md` |
 | Referrers | `libs/referrers/` | `specs/registry/referrers.md` | `docs/library/referrers.md` |
 | Catalog | `libs/catalog/` | `specs/registry/catalog.md` | `docs/library/catalog.md` |
 | Break Mode | `libs/breakmode/` | `specs/breakmode/` | `docs/guides/break-mode.md` |
-| CLI | `cli/` | `specs/cli/` | `docs/cli/` |
-| Models | `libs/models/` | `specs/models/` | `docs/library/models.md` |
+
+| CLI | `cli/` | `specs/cli/` | `docs/cli/` || Models | `libs/models/` | `specs/models/` | `docs/library/models.md` |
 
 ## GitHub Issue Management
 
@@ -80,35 +86,38 @@ gh issue create \
 
 ### Common Issue Labels
 
-- **Priority**: `priority-high`, `priority-medium`, `priority-low`  
+- **Priority**: `priority-high`, `priority-medium`, `priority-low`
 - **Type**: `enhancement`, `bug`, `documentation`, `architecture`
-- **Domain**: `break-mode`, `cli`, `oci-spec`, `transport`, `models`
+- **Domain**: `break-mode`, `cli`, `oci-spec`, `image-spec`, `images`, `transport`, `models`
 - **Status**: `blocked`, `help-wanted`, `good-first-issue`
 
 ### Issue Templates
 
 Use these templates for consistent issue creation:
 
 **Feature Implementation Issues:**
+
 - Title: `Implement [Feature Name] - [Brief Description]`
 - Include acceptance criteria checklist
 - List files to create/modify
 - Add appropriate priority and domain labels
 
 **Bug Report Issues:**
-- Title: `Bug: [Brief Description]`  
+
+- Title: `Bug: [Brief Description]`
 - Include steps to reproduce, expected vs actual behavior
 - Add `bug` label and relevant domain labels
 
 **Architecture Issues:**
+
 - Title: `Architecture: [Component/Enhancement]`
 - Include design decisions, trade-offs, implementation notes
 - Add `architecture` label
 
 ### Workflow Integration
 
 1. **When planning work**: Create issues for each major component or feature
-2. **Before coding**: Reference issue numbers in commit messages (`fixes #123`)  
+2. **Before coding**: Reference issue numbers in commit messages (`fixes #123`)
 3. **During implementation**: Update issue status and add progress notes
 4. **After completion**: Close issues automatically via commit messages or PR merges
 
@@ -117,6 +126,7 @@ Use these templates for consistent issue creation:
 RegShape's distinguishing feature: deliberately send malformed or non-conformant requests to test registry implementations.
 
 When designing break mode features:
+
 - Provide options to modify any part of a request (headers, body, method, path, digest values)
 - Allow sending requests with invalid content types, wrong digests, oversized payloads
 - Support skipping authentication steps or using expired tokens
@@ -133,17 +143,17 @@ automatically from the Docker credential store and **do not** accept per-command
 `--username` / `--password` flags.
 
 - The `auth login` command stores credentials using the Docker credential store mechanics
-  (`credHelpers` in `~/.docker/config.json` or base64-encoded `auths` entries).
+   (`credHelpers` in `~/.docker/config.json` or base64-encoded `auths` entries).
 - Non-auth commands call `resolve_credentials(registry, None, None)` to look up stored
-  credentials for the embedded registry.
+   credentials for the embedded registry.
 - If no stored credentials exist and the registry requires authentication, the registry
-  returns HTTP 401, which surfaces as exit code 1.
+   returns HTTP 401, which surfaces as exit code 1.
 
 ### Registry Must Be Embedded in Image Reference
 
 The `--image-ref` / `-i` flag always requires the registry to be embedded:
 
-```
+```sh
 registry/repository:tag         # e.g., acr.io/myrepo/myimage:latest
 registry/repository@sha256:...  # e.g., acr.io/myrepo/myimage@sha256:abc...
 ```
@@ -160,6 +170,7 @@ There are no global auth options.
 ## Key References
 
 - **OCI Distribution Spec**: [references/oci-distribution-spec.md](references/oci-distribution-spec.md) — API endpoints, schemas, error codes
+- **OCI Image Spec**: [references/oci-image-spec.md](references/oci-image-spec.md) — image manifests, image index, image config, filesystem layers, descriptors (full upstream spec mirrored in [references/oci-image-spec-source/](references/oci-image-spec-source/))
 - **Project Conventions**: [references/project-conventions.md](references/project-conventions.md) — Code style, module structure, naming
 - **Spec Templates**: [references/spec-templates.md](references/spec-templates.md) — Templates for `/specs` documents
 - **Doc Templates**: [references/doc-templates.md](references/doc-templates.md) — Templates for `/docs` documents

.github/skills/regshape-dev/references/oci-image-spec-source/annotations.md

@@ -0,0 +1,83 @@
+# Annotations
+
+Several components of the specification, like [Image Manifests](manifest.md) and [Descriptors](descriptor.md), feature an optional annotations property, whose format is common and defined in this section.
+
+This property contains arbitrary metadata.
+
+## Rules
+
+- Annotations MUST be a key-value map where both the key and value MUST be strings.
+- While the value MUST be present, it MAY be an empty string.
+- Keys MUST be unique within this map, and best practice is to namespace the keys.
+- Keys SHOULD be named using a reverse domain notation - e.g. `com.example.myKey`.
+- The prefix `org.opencontainers` is reserved for keys defined in Open Container Initiative (OCI) specifications and MUST NOT be used by other specifications and extensions.
+- Keys using the `org.opencontainers.image` namespace are reserved for use in the OCI Image Specification and MUST NOT be used by other specifications and extensions, including other OCI specifications.
+- If there are no annotations then this property MUST either be absent or be an empty map.
+- Consumers MUST NOT generate an error if they encounter an unknown annotation key.
+
+## Pre-Defined Annotation Keys
+
+This specification defines the following annotation keys, intended for but not limited to [image index](image-index.md), image [manifest](manifest.md), and [descriptor](descriptor.md) authors.
+
+- **org.opencontainers.image.created** date and time on which the image was built, conforming to [RFC 3339][rfc3339].
+- **org.opencontainers.image.authors** contact details of the people or organization responsible for the image (freeform string)
+- **org.opencontainers.image.url** URL to find more information on the image (string)
+- **org.opencontainers.image.documentation** URL to get documentation on the image (string)
+- **org.opencontainers.image.source** URL to get source code for building the image (string)
+- **org.opencontainers.image.version** version of the packaged software
+  - The version MAY match a label or tag in the source code repository
+  - version MAY be [Semantic versioning-compatible](https://semver.org/)
+- **org.opencontainers.image.revision** Source control revision identifier for the packaged software.
+- **org.opencontainers.image.vendor** Name of the distributing entity, organization or individual.
+- **org.opencontainers.image.licenses** License(s) under which contained software is distributed as an [SPDX License Expression][spdx-license-expression].
+- **org.opencontainers.image.ref.name** Name of the reference for a target (string).
+  - SHOULD only be considered valid when on descriptors on `index.json` within [image layout](image-layout.md).
+  - Character set of the value SHOULD conform to alphanum of `A-Za-z0-9` and separator set of `-._:@/+`
+  - A valid reference matches the following [grammar](considerations.md#ebnf):
+
+    ```ebnf
+    ref       ::= component ("/" component)*
+    component ::= alphanum (separator alphanum)*
+    alphanum  ::= [A-Za-z0-9]+
+    separator ::= [-._:@+] | "--"
+    ```
+
+- **org.opencontainers.image.title** Human-readable title of the image (string)
+- **org.opencontainers.image.description** Human-readable description of the software packaged in the image (string)
+- **org.opencontainers.image.base.digest** [Digest](descriptor.md#digests) of the image this image is based on (string)
+  - This SHOULD be the immediate image sharing zero-indexed layers with the image, such as from a Dockerfile `FROM` statement.
+  - This SHOULD NOT reference any other images used to generate the contents of the image (e.g., multi-stage Dockerfile builds).
+- **org.opencontainers.image.base.name** Image reference of the image this image is based on (string)
+  - This SHOULD be image references in the format defined by [distribution/distribution][distribution-reference].
+  - This SHOULD be a fully qualified reference name, without any assumed default registry. (e.g., `registry.example.com/my-org/my-image:tag` instead of `my-org/my-image:tag`).
+  - This SHOULD be the immediate image sharing zero-indexed layers with the image, such as from a Dockerfile `FROM` statement.
+  - This SHOULD NOT reference any other images used to generate the contents of the image (e.g., multi-stage Dockerfile builds).
+  - If the `image.base.name` annotation is specified, the `image.base.digest` annotation SHOULD be the digest of the manifest referenced by the `image.ref.name` annotation.
+
+## Back-compatibility with Label Schema
+
+[Label Schema][label-schema] defined a number of conventional labels for container images, and these are now superseded by annotations with keys starting **org.opencontainers.image**.
+
+While users are encouraged to use the **org.opencontainers.image** keys, tools MAY choose to support compatible annotations using the **org.label-schema** prefix as follows.
+
+| `org.opencontainers.image` prefix | `org.label-schema` prefix | Compatibility notes |
+|---------------------------|-------------------------|---------------------|
+| `created` | `build-date` | Compatible |
+| `url` | `url` | Compatible |
+| `source` | `vcs-url` | Compatible |
+| `version` | `version` | Compatible |
+| `revision` | `vcs-ref` | Compatible |
+| `vendor` | `vendor` | Compatible |
+| `title` | `name` | Compatible |
+| `description` | `description` | Compatible |
+| `documentation` | `usage` | Value is compatible if the documentation is located by a URL |
+| `authors` |  | No equivalent in Label Schema |
+| `licenses` | | No equivalent in Label Schema |
+| `ref.name` | | No equivalent in Label Schema |
+| | `schema-version`| No equivalent in the OCI Image Spec |
+| | `docker.*`, `rkt.*` | No equivalent in the OCI Image Spec |
+
+[distribution-reference]: https://github.com/distribution/distribution/blob/d0deff9cd6c2b8c82c6f3d1c713af51df099d07b/reference/reference.go
+[label-schema]: https://github.com/label-schema/label-schema.org/blob/gh-pages/rc1.md
+[rfc3339]:     https://tools.ietf.org/html/rfc3339#section-5.6
+[spdx-license-expression]: https://spdx.github.io/spdx-spec/v2.3/SPDX-license-expressions/

.github/skills/regshape-dev/references/oci-image-spec-source/artifacts-guidance.md

@@ -0,0 +1,6 @@
+# Guidance for Artifacts Authors
+
+Content other than OCI container images MAY be packaged using the image manifest.
+When this is done, the `config.mediaType` value should not be a known OCI image config [media type](media-types.md).
+Historically, due to registry limitations, some tools have created non-OCI conformant artifacts using the `application/vnd.oci.image.config.v1+json` value for `config.mediaType` and values specific to the artifact in `layer[*].mediaType`.
+Implementation details and examples are provided in the [image manifest specification](manifest.md#guidelines-for-artifact-usage).