Refactor documentation structure and add new artifact model guide

docs/en/develop/extending/annotations.md

@@ -0,0 +1,6 @@
+# Annotations Reference
+
+<!-- TODO: Complete reference for all v3 PHP attributes.
+  #[Library], #[Extension], #[BuildFor], #[BeforeStage], #[AfterStage],
+  #[PatchBeforeBuild], #[CustomPhpConfigureArg], #[AsCheckItem], #[AsFixItem].
+  Per-attribute: parameters, types, allowed targets, example. -->

docs/en/develop/extending/custom-artifact.md

@@ -0,0 +1,8 @@
+# Custom Artifact
+
+<!-- TODO: Guide for implementing a custom artifact download class under src/Package/Artifact/.
+  Explain when type: custom is appropriate (e.g. proprietary auth, non-standard archives).
+  Cover: class placement and naming, method signatures (default download method + func dispatch),
+  accessing source config fields, returning the extracted source path,
+  registering the class via spc.registry.yml artifact psr-4 mapping.
+  Provide an annotated code example. -->

docs/en/develop/extending/dependency-injection.md

@@ -0,0 +1,6 @@
+# Dependency Injection
+
+<!-- TODO: How PHP-DI autowiring works in v3.
+  ApplicationContext::get() usage.
+  Registering custom services.
+  Injecting into command classes, build classes, and stage methods. -->

docs/en/develop/extending/index.md

@@ -0,0 +1,8 @@
+# Extending StaticPHP
+
+<!-- TODO: Introduce the three extension strategies:
+  1. Contributing to core — edit src/Package/ and config/pkg/ directly.
+  2. External Registry — point SPC_REGISTRIES at a custom spc.registry.yml.
+  3. Vendor Mode — package classes + config as a Composer library (composer require).
+  Explain when to use each approach. Show a minimal end-to-end example:
+  one Library class, one config YAML, one spc.registry.yml, run spc. -->

docs/en/develop/extending/lifecycle-hooks.md

@@ -0,0 +1,6 @@
+# Lifecycle Hooks
+
+<!-- TODO: Detailed explanation of hook execution order and method signatures.
+  #[BeforeStage('lib-name', 'build')], #[AfterStage(...)], #[PatchBeforeBuild].
+  How hooks from different packages are merged and ordered.
+  Common patterns: patching config.m4, injecting compile flags, post-install fixups. -->

docs/en/develop/extending/package-classes.md

@@ -0,0 +1,6 @@
+# Writing Package Classes
+
+<!-- TODO: Step-by-step guide to writing a Library class and an Extension class.
+  Full annotated code examples using #[Library], #[Extension], #[BuildFor].
+  UnixAutoconfExecutor / UnixCmakeExecutor / WindowsCMakeExecutor usage.
+  File placement (src/Package/Library/, src/Package/Extension/) and autoloading. -->