Release v1.0.21 — HKM Kernel rebrand, public docs/guides, README rewrite (+#36)

[hakeemRash]

Summary

Closes #

Type of change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 💥 Breaking change (fix or feature that changes existing behavior)
• 📝 Documentation only
• 🧹 Refactor / chore (no functional change)
• 🚀 Release PR (master → main, includes a CHANGELOG version bump)

Target branch

• This PR targets master (development), or
• This is a master → main release PR and adds a ## [x.y.z] - YYYY-MM-DD section to CHANGELOG.md.

How has this been tested?

vendor/bin/phpunit

Checklist

• My code follows the Gated Demand Architecture rules (no Laravel/Symfony/Slim patterns).
• Every PHP file has declare(strict_types=1);.
• The five access rules are respected (Controller → Service → Repository/Gateway → Port/SDK; Domain imports nothing external).
• Routes are declared in module.json / proj.json, not in PHP.
• Every env var read is declared in the relevant config[].
• Vendor exceptions are translated at their layer (no \PDOException/SDK exceptions escape).
• I added or updated tests and they pass locally.
• I updated documentation where relevant.
• For shippable changes, I added a ## [Unreleased] entry to CHANGELOG.md.
• CI is green.

Screenshots / notes (optional)

Summary by CodeRabbit

• New Features

  • Added comprehensive HKM Kernel guides covering architecture, security, modules, layers, testing, workers, CLI usage, migrations, databases, plugins, tenancy, authentication, OAuth2, and deployments.
  • Added a centralized guide index and refreshed project documentation, installation instructions, command references, and repository links.
  • Updated CLI, debug pages, and error messages with HKM Kernel branding.

• Documentation

  • Added release notes for version 1.0.21, including branding and documentation updates.
  • Corrected security documentation and expanded deployment guidance.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR rebrands runtime and documentation surfaces from Sentinel to HKM Kernel, rewrites the README, and adds architecture, layer, plugin, security, testing, CLI, data, tenancy, and deployment guides. It also updates the guides index and preserves guide files through .gitignore.

Changes

HKM Kernel documentation and branding

Layer / File(s)	Summary
Release metadata and branding .gitignore, CHANGELOG.md, README.md, src/Kernel/Error/DebugPageRenderer.php, src/System/GlobalKernelProjectScaffolder.php, tools/src/...	Updates release notes, repository links, guide paths, CLI help, banners, debug pages, and scaffolded error prefixes for HKM Kernel.
Architecture and application contracts docs/guides/00_SENTINEL_OVERVIEW.md – docs/guides/08_EVENTS.md	Adds guides for architecture, kernel/module/domain/service/repository/gateway/controller layers, events, security, and testing.
Runtime and data guides docs/guides/09_SECURITY.md – docs/guides/22_DATA_ACCESS_ORM_BLUEPRINT.md	Documents project bootstrapping, workers, CLI pipelines, error handling, plugins, migrations, database access, and entity support.
Plugin, identity, and deployment guides docs/guides/23_TENANCY.md – docs/guides/27_ENTITY_SUPPORT.md, docs/guides/README.md, docs/guides/SAFE_DEPLOYMENTS_GUIDE.md	Adds tenancy, user, authentication, OAuth2, entity-support, guide-index, and safe-deployment documentation.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested reviewers: craftdevscommunity, alshatri

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main changes: the v1.0.21 release, HKM rebrand, documentation additions, README rewrite, and merged work from #36.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch master

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Note

Due to the large number of review comments, Critical severity comments were prioritized as inline comments.

🟠 Major comments (38)

docs/guides/18_MIGRATIONS.md-157-161 (1)

157-161: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Correct the migration scaffolder claims.

MakeMigrationCommand generates Y_m_d_His filenames, not YYYY_MM_DD_NNNNNN, and writes with file_put_contents() without checking whether the target already exists. The guide currently promises sequence numbering and overwrite protection that the implementation does not provide.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/18_MIGRATIONS.md` around lines 157 - 161, Update the “The
scaffolder” claims in the migration guide to accurately describe
MakeMigrationCommand: state that filenames use the Y_m_d_His timestamp format,
remove the sequence-numbering claim, and remove the promise of overwrite
protection because file_put_contents() does not check for existing targets.

docs/guides/SAFE_DEPLOYMENTS_GUIDE.md-171-174 (1)

171-174: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Do not recommend editing a migration to retry a partial failure.

A partially applied migration may have changed the schema before failing, and editing the original file can make the recorded migration history diverge from the deployed schema. Restore or repair the database deliberately, then use a new corrective migration; only rerun an unchanged, unrecorded migration after verifying its side effects.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/SAFE_DEPLOYMENTS_GUIDE.md` around lines 171 - 174, Update the
“Option 2: Fix and retry” guidance in SAFE_DEPLOYMENTS_GUIDE.md to prohibit
editing a partially applied migration before retrying. Instruct operators to
deliberately restore or repair the database, then create a new corrective
migration; only permit rerunning an unchanged, unrecorded migration after
verifying its side effects.

docs/guides/18_MIGRATIONS.md-61-70 (1)

61-70: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Standardize the database environment-variable contract.

The migration and deployment examples use names that differ from the Database module’s documented contract, so copy-pasted commands can silently use missing or default connection values.

• docs/guides/18_MIGRATIONS.md#L61-L70: replace DB_NAME, DB_USER, and DB_PASS with DB_DATABASE, DB_USERNAME, and DB_PASSWORD, or document explicit aliases.
• docs/guides/SAFE_DEPLOYMENTS_GUIDE.md#L337-L346: replace DB_NAME with DB_DATABASE.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/18_MIGRATIONS.md` around lines 61 - 70, Standardize the database
environment-variable names in the migration configuration example by replacing
DB_NAME, DB_USER, and DB_PASS with DB_DATABASE, DB_USERNAME, and DB_PASSWORD in
docs/guides/18_MIGRATIONS.md:61-70. Also replace DB_NAME with DB_DATABASE in
docs/guides/SAFE_DEPLOYMENTS_GUIDE.md:337-346; no aliases are needed.

docs/guides/SAFE_DEPLOYMENTS_GUIDE.md-10-13 (1)

10-13: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Do not require secrets to live in .env files.

The checklist says all required environment variables must be defined in .env, while the same section requires credentials from a secrets manager. Clarify that only non-secret configuration belongs in .env; production secrets should be injected at runtime from the configured secret provider.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/SAFE_DEPLOYMENTS_GUIDE.md` around lines 10 - 13, Update the
deployment checklist entries to state that only non-secret configuration belongs
in `.env`, while production secrets such as database credentials must be
injected at runtime from the configured secrets manager or provider. Keep the
existing environment-variable validation guidance, but remove the implication
that all required variables, including secrets, must be stored in `.env`.

docs/guides/SAFE_DEPLOYMENTS_GUIDE.md-94-128 (1)

94-128: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Verify or remove the undocumented deployment commands.

The canonical CliCommandFactory::all() registers migration, generation, tenant, seed, make, and maintenance commands, but this guide presents migrate:create-approval, migrate:request-approval, deployment:locks, deployment:lock-release, backup commands, and audit commands as available CLI workflows. If these commands are not registered elsewhere, the documented production procedure will fail at runtime; either implement/register them or rewrite the guide around supported commands.

Also applies to: 141-143, 153-158, 211-259

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/SAFE_DEPLOYMENTS_GUIDE.md` around lines 94 - 128, Verify every
CLI command documented in SAFE_DEPLOYMENTS_GUIDE.md against the registrations
returned by CliCommandFactory::all(), including migrate:create-approval,
migrate:request-approval, deployment lock, backup, and audit commands. For any
command not registered or implemented, either add it to the appropriate command
registration flow or revise the guide to use only supported commands, preserving
a runnable production deployment procedure.

docs/guides/22_DATA_ACCESS_ORM_BLUEPRINT.md-159-180 (1)

159-180: 🔒 Security & Privacy | 🟠 Major | 🏗️ Heavy lift

Enforce tenant ownership before upserting.

find() applies the tenant predicate, but save() accepts any Invoice, conflicts only on invoice_id, and updates persisted fields without checking that invoice->tenantId() matches identity->tenantId. A misrouted entity can therefore modify another tenant’s invoice. Reject mismatched entities before the upsert and ensure the schema/conflict key matches whether invoice IDs are global or tenant-local.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/22_DATA_ACCESS_ORM_BLUEPRINT.md` around lines 159 - 180, Update
InvoiceRepository::save to validate that invoice->tenantId() matches
identity->tenantId() before calling db->upsert, rejecting mismatches with the
repository’s established exception behavior. Ensure the invoices schema and
upsert conflictColumns use the correct global or tenant-local ownership key,
including tenant_id when IDs are tenant-local, while preserving tenant scoping
for every operation.

docs/guides/SAFE_DEPLOYMENTS_GUIDE.md-327-335 (1)

327-335: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Use restrictive permissions for database backups.

chmod 644 storage/backups/*.sql makes SQL backups world-readable on Unix systems. Backups may contain credentials or personal data; use a least-privilege mode such as 600 and restrict directory access as appropriate.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/SAFE_DEPLOYMENTS_GUIDE.md` around lines 327 - 335, Update the
backup permission commands in the “Backup failed: permission denied” section to
use restrictive, least-privilege permissions: change SQL backup files to mode
600 and restrict the storage/backups directory access appropriately, while
preserving the existing troubleshooting flow.

docs/guides/21_CSRF.md-68-80 (1)

68-80: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Do not exempt the entire /api prefix without an enforced invariant.

This bypasses CSRF for every API route, including any future cookie-authenticated browser endpoint accidentally placed under /api. Prefer an explicit machine-endpoint allowlist, or state and enforce that all exempted routes require non-cookie authentication.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/21_CSRF.md` around lines 68 - 80, Update the CsrfTokenLayer
configuration example to avoid exempting the entire /api prefix by default.
Replace it with an explicit machine-endpoint allowlist, or document and enforce
an invariant that every exempted route uses non-cookie authentication; ensure
future cookie-authenticated browser endpoints cannot bypass CSRF
unintentionally.

docs/guides/05_REPOSITORY.md-94-101 (1)

94-101: 🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Make the version column enforce optimistic concurrency.

The upsert increments version but never checks the caller’s expected version, so concurrent saves silently overwrite one another. Update with WHERE version = :expected_version and raise a conflict when no row is affected.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/05_REPOSITORY.md` around lines 94 - 101, Update the repository
upsert’s ON DUPLICATE KEY UPDATE flow to require version = :expected_version
before applying changes, and raise a concurrency conflict when the update
affects no row. Preserve the existing version increment and field assignments
for successful saves.

docs/guides/07_CONTROLLER.md-63-75 (1)

63-75: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Align the controller with the published service contract.

This controller calls update() and delete(), but docs/guides/04_SERVICE.md only publishes create(), find(), list(), and markPaid(). Add these methods to the contract with their DTO/response types, or remove them from the canonical controller example.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/07_CONTROLLER.md` around lines 63 - 75, Align the canonical
controller example with the published service contract by either documenting
update() and delete() in the service contract with their DTO and response types,
or removing the update() and destroy() actions from the controller example. Keep
the chosen interface consistent across the controller and service documentation.

docs/guides/05_REPOSITORY.md-72-75 (1)

72-75: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Apply tenant and soft-delete filters to line-item queries.

This query omits both tenant_id and deleted_at IS NULL, despite the guide requiring those predicates on every query. Reapply the aggregate’s tenant scope and exclude deleted children before hydration.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/05_REPOSITORY.md` around lines 72 - 75, Update the invoice
line-item query using the `$this->db->query` call to add the aggregate’s tenant
scope and require `deleted_at IS NULL` alongside the existing `invoice_id`
condition. Preserve the ascending `sort_order` ordering and ensure only
tenant-owned, non-deleted children are hydrated.

docs/guides/05_REPOSITORY.md-113-127 (1)

113-127: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Translate every database failure inside the repository.

saveLineItems() is called outside the PDOException handler, and softDelete() has no handler at all. These paths can leak PDOException directly, contradicting the repository contract.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/05_REPOSITORY.md` around lines 113 - 127, Wrap the database
operations in saveLineItems() and softDelete() with the repository’s existing
PDOException translation mechanism. Ensure any PDOException from these paths is
converted to the repository-level exception contract, while preserving the
current tenant filtering and soft-delete behavior.

docs/guides/04_SERVICE.md-149-177 (1)

149-177: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Do not silently discard the requested currency.

CreateInvoiceDTO exposes currency, but fromRequest() never maps it and Invoice::create() receives no currency. Non-USD requests therefore default to USD or lose their currency information.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/04_SERVICE.md` around lines 149 - 177, Update
CreateInvoiceDTO::fromRequest() to read the requested currency from the request
data and pass it to the constructor’s currency parameter when creating the DTO.
Ensure Invoice::create() receives and preserves this currency value through the
existing DTO-to-invoice flow, while retaining USD only as the default when no
currency is requested.

docs/guides/04_SERVICE.md-102-110 (1)

102-110: 🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Make post-commit event delivery durable and idempotent.

If eventBus->dispatch() fails after the transaction commits, the caller receives an error even though the invoice exists; retrying may create duplicates. Use an outbox written in the same transaction, then dispatch asynchronously with idempotent handling.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/04_SERVICE.md` around lines 102 - 110, Replace the direct
post-commit eventBus->dispatch call in the invoice creation flow with an outbox
record written within the same transaction as the invoice. Add asynchronous
dispatch of the stored InvoiceCreatedIntegrationEvent, ensuring delivery and
handling are idempotent so retries do not create duplicate invoices or effects.

docs/guides/21_CSRF.md-123-146 (1)

123-146: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Enforce the expected CSRF action during verification.

valid() derives the action from the submitted token, so a token minted for one action can be replayed for another. Either pass an expected action into valid()/check() and compare it, or document that action is informational rather than an authorization scope.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/21_CSRF.md` around lines 123 - 146, Update the static CSRF
verification example and its API usage around CsrfTokenLayer::valid() to accept
and enforce an expected action, comparing it against the token’s action rather
than trusting the submitted token. Apply the same contract to check() if
applicable, and document the required action argument alongside the existing
binding and lifetime parameters.

docs/guides/06_GATEWAY.md-45-95 (1)

45-95: 🩺 Stability & Availability | 🟠 Major | 🏗️ Heavy lift

Catch the complete Stripe exception surface.

charge() only translates CardException, InvalidRequestException, ApiConnectionException, and RateLimitException; refund() only translates InvalidRequestException. Other Stripe exceptions such as AuthenticationException, PermissionException, IdempotencyException, and API-error fallbacks can still escape, breaking the guide’s “vendor exceptions never escape this layer” rule. Add a final vendor-base/interface catch in both methods with safe context after the specific case catches.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/06_GATEWAY.md` around lines 45 - 95, Add a final catch for the
Stripe vendor base exception/interface in both charge() and refund(), after
their existing specific Stripe catches, translating any remaining vendor
exception into GatewayException. Include safe, non-sensitive context and
preserve the original exception as previous, ensuring AuthenticationException,
PermissionException, IdempotencyException, and API fallback errors cannot escape
either method.

docs/guides/26_OAUTH2.md-31-42 (1)

31-42: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Lock public clients to S256 PKCE.

docs/guides/26_OAUTH2.md currently documents public PKCE as S256/plain, and the discovery responses advertise both supported methods, while AuthorizationService falls back to plain when code_challenge_method is absent. Since plain sends the verifier in the request and discovery tells clients plain is supported, don’t advertise/allow it by default; enforce S256 for public clients or add an explicit legacy opt-in with a strong migration warning.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/26_OAUTH2.md` around lines 31 - 42, Update the OAuth2
documentation around the authorization_code grant to state that PKCE is
mandatory for public clients using S256 only, removing plain from the documented
default behavior. Align the related discovery responses and AuthorizationService
handling so plain is neither advertised nor accepted unless an explicitly
enabled legacy opt-in is provided with a strong migration warning.

docs/guides/20_FIRST_PARTY_PLUGINS.md-132-137 (1)

132-137: 🚀 Performance & Scalability | 🟠 Major | 🏗️ Heavy lift

Do not describe the usleep() fallback as non-blocking.

Coroutine::usleep() is cooperative, but the documented fallback to usleep() blocks the current worker/thread. Either qualify the claim for coroutine runtimes or provide a genuinely non-blocking scheduler path.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/20_FIRST_PARTY_PLUGINS.md` around lines 132 - 137, Update the
retry backoff documentation near retry(n) to distinguish cooperative
Coroutine::usleep behavior from the blocking usleep fallback. Remove the claim
that the fallback never blocks the worker, or qualify it so non-blocking
behavior is asserted only for coroutine runtimes.

docs/guides/09_SECURITY.md-222-228 (1)

222-228: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Do not fail open when the verification cache misses.

RequireVerifiedEmailLayer allows the request when the cache has no value, so cache eviction or an outage bypasses the layer entirely. Either deny on an unavailable/unknown verification state, or remove this layer and make the service-level check authoritative for every protected operation.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/09_SECURITY.md` around lines 222 - 228, Update
RequireVerifiedEmailLayer’s cache-miss handling so an unknown or unavailable
email-verification state does not allow the request. Deny the request on a null
cache value, or remove this layer and ensure the service-level verification
check is authoritative for every protected operation; preserve allow behavior
only for confirmed verification.

docs/guides/08_EVENTS.md-60-65 (1)

60-65: 🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Do not apply projections after committing while calling them “in-transaction.”

The flow commits before collector->release() and projection execution. A projection failure can therefore leave the database committed but the read model stale. Apply projections before commit, or document this as a post-commit process backed by durable retry handling.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/08_EVENTS.md` around lines 60 - 65, The documented transaction
flow incorrectly labels projections as in-transaction after commit. Update the
flow around transaction->commit(), collector->release(), and projection->on() to
either execute projections before committing or explicitly document them as
post-commit with durable retry handling; ensure failure semantics no longer
claim atomicity when the database is already committed.

docs/guides/23_TENANCY.md-104-119 (1)

104-119: 🔒 Security & Privacy | 🟠 Major | 🏗️ Heavy lift

Do not let a tenant cookie override the requested hostname.

In domain and host modes, consulting the cookie before the host-derived identifier can route a request for tenant B’s hostname to tenant A’s database whenever the principal-bound cookie contains A. Revalidate the cookie against the authoritative host identifier, or make the host/domain identifier take precedence.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/23_TENANCY.md` around lines 104 - 119, The tenant-selection
documentation must not allow a cookie to override the requested hostname in
domain or host modes. Update the TenantContextStage behavior described here so
the authoritative host/domain-derived identifier takes precedence, or ensure any
cookie hint is revalidated against that identifier before use; retain cookie
fallback only where it cannot route the request to another tenant.

docs/guides/08_EVENTS.md-84-93 (1)

84-93: 🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Use a lossless representation for monetary event amounts.

Publishing currency as float can change values during serialization or arithmetic. Use integer minor units (for example, cents) or a decimal string in the integration contract.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/08_EVENTS.md` around lines 84 - 93, Update the event
constructor’s amount field to use a lossless integration-contract representation
instead of float: prefer an integer minor-unit value or a decimal string, and
adjust its documentation/comments to identify the chosen representation. Keep
the remaining event fields and primitive-type contract unchanged.

docs/guides/24_USER.md-104-117 (1)

104-117: 🔒 Security & Privacy | 🟠 Major | 🏗️ Heavy lift

Resolve the audit PII contradiction.

The guide promises “never PII” while explicitly logging and persisting ip. Clarify whether IP addresses are intentionally retained; if so, document protection, access control, retention/purge, and redaction requirements, or stop storing them.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/24_USER.md` around lines 104 - 117, Update the AuditLogger
documentation to resolve the contradiction around IP addresses: either remove IP
capture from structured and database audit records, or explicitly classify IPs
as retained sensitive data and document protection, restricted access,
retention/purge, and redaction requirements. Keep the documentation consistent
with the chosen behavior across the security-audit summary and field mapping.

docs/guides/08_EVENTS.md-80-98 (1)

80-98: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Remove default values from readonly properties in the event examples.

Readonly properties are not allowed to declare initial values (public string $version = '1.0';), so these examples fail with Fatal error: Readonly property ... cannot have default value. Initialize version through the constructor or return the literal from version() in both examples.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/08_EVENTS.md` around lines 80 - 98, Remove the default
initializer from the readonly version property in both event examples. Preserve
the version contract by initializing version through each constructor or
returning the literal directly from each version() method, ensuring the examples
remain valid PHP.

docs/guides/23_TENANCY.md-45-50 (1)

45-50: 🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift

Resolve the central/login routing path.
TenantContextStage only bypasses tenant resolution for TENANCY_EXEMPT paths (default /ping), then returns 404 when the cookie hint and tenant identifier both resolve to ''. The guides still need a concrete exception/model for login/picker/public auth flows: either document the allowed exempt flow/prefix and route policy, or explicitly require those hosts/pages to be tenant-registered so the 404-only model is unambiguous.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/23_TENANCY.md` around lines 45 - 50, Clarify the central/login
routing policy in docs/guides/23_TENANCY.md (lines 45-50) and
docs/guides/09_SECURITY.md (lines 183-188): document the permitted exempt path
or prefix and its routing behavior for login, tenant-picker, and public
authentication flows, or explicitly require those hosts/pages to be
tenant-registered. Ensure both guides consistently describe how these requests
avoid or receive the 404 tenant-resolution response.

docs/guides/11_PROJECT.md-70-76 (1)

70-76: 🔒 Security & Privacy | 🟠 Major | 🏗️ Heavy lift

Do not exempt every /api route from CSRF in the shared base.

This base is reused by projects, including session-cookie applications documented later. A blanket /api exemption can let cookie-authenticated state-changing endpoints bypass CSRF. Scope exemptions to token-only routes or configure explicit stateless route groups.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/11_PROJECT.md` around lines 70 - 76, Update the shared base
configuration around withSecurity and CsrfTokenLayer so it does not exempt every
/api route from CSRF. Scope the exemption to explicitly stateless, token-only
routes or remove it from the shared base and configure explicit stateless route
groups, while preserving CSRF protection for cookie-authenticated state-changing
endpoints.

docs/guides/16_PLUGINS.md-61-71 (1)

61-71: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Keep namespace casing aligned with the directory layout.

The documented directory is API/Contracts, but the example exposes Plugins\\MyModule\\Api\\Contracts.... With PSR-4 on case-sensitive filesystems, this casing mismatch can prevent the contract from autoloading. Use API.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/16_PLUGINS.md` around lines 61 - 71, Update the exposes example
in the routes JSON documentation to use the namespace segment API, matching the
documented API/Contracts directory layout. Keep the remaining
Plugins\MyModule\Api\Contracts path unchanged.

docs/guides/12_WORKER.md-260-263 (1)

260-263: 🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Do not acknowledge a partially processed job on graceful shutdown.

AcknowledgeStage removes jobs after success, but this branch returns JobResult::success() after only some batches. The queue item is then deleted and the remaining tenants are lost. Return a requeue/deferred result, or persist a checkpoint and enqueue the remainder.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/12_WORKER.md` around lines 260 - 263, Update the
graceful-shutdown branch in the worker loop to avoid returning
JobResult::success() when only some batches have been processed. Return the
existing requeue/deferred result type so AcknowledgeStage retains the queue
item, or persist a checkpoint and enqueue the unprocessed tenants before
returning.

docs/guides/12_WORKER.md-186-191 (1)

186-191: 🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Use a durable outbox for post-commit job dispatch.

If queue->push() fails after the transaction commits, the invoice exists but the email job is absent; the committed write cannot be rolled back. Persist an outbox record in the transaction and deliver it asynchronously with idempotency.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/12_WORKER.md` around lines 186 - 191, Replace the direct
post-commit queue->push call in the invoice workflow with a durable outbox
record written within the transaction. Add asynchronous outbox delivery that
dispatches the SendInvoiceEmailJob payload to the emails queue, using
idempotency to prevent duplicate email jobs.

docs/guides/15_ERROR_HANDLING.md-82-101 (1)

82-101: 🔒 Security & Privacy | 🟠 Major | 🏗️ Heavy lift

Define redaction and notifier-specific error payloads before capturing this context automatically.

Full traces, previous exception messages, and arbitrary context can contain tokens, request data, SQL, vendor secrets, or PII. Do not forward the same unredacted payload to database/file sinks and external Slack/mail notifiers; use an allowlist and redaction policy.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/15_ERROR_HANDLING.md` around lines 82 - 101, Update the
ErrorPipeline context-capture documentation to define an explicit redaction
policy and notifier-specific payloads before claiming automatic capture. Specify
an allowlist and redact sensitive data from traces, previous exception messages,
arbitrary context, and other request or identity fields; ensure database/file
sinks and external Slack/mail notifiers do not receive the same unredacted
payload.

docs/guides/16_PLUGINS.md-131-136 (1)

131-136: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Show the two views forms as separate valid examples.

The current block contains duplicate views keys and no separator between them, so it is invalid JSON/JSONC. Split the string and object forms into separate snippets or comment out the alternative.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/16_PLUGINS.md` around lines 131 - 136, Update the documentation
example around the two views forms to present them as separate valid JSONC
snippets, or comment out the alternative form, so no snippet contains duplicate
views keys or missing separators. Preserve both the shorthand string form and
the explicit object form.

docs/guides/17_PHP_IO_CLI.md-8-10 (1)

8-10: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Do not advertise Symfony as dev-only while using it at runtime.

docs/guides/17_PHP_IO_CLI.md still says runtime dependencies are only psr/log, but the package requires symfony/console, and the non-TTY fallback/example uses Symfony QuestionHelper/ArgvInput. A --no-dev or production install can fail when a command needs non-TTY I/O; either make Symfony a runtime dependency, add a dependency-free fallback, or explicitly document the required installation contract.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/17_PHP_IO_CLI.md` around lines 8 - 10, Update the dependency and
installation guidance in the php-io-cli documentation to match its actual
runtime use of Symfony Console, including the non-TTY ConsoleIO/BufferIO
fallback and QuestionHelper/ArgvInput examples. Remove the claim that Symfony is
dev-only and either document Symfony as a required runtime dependency or clearly
specify the installation contract that guarantees it is available.

docs/guides/03_DOMAIN.md-56-70 (1)

56-70: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Pass creation time into the factory.

Invoice::create() calls new DateTimeImmutable() despite the guide explicitly forbidding that pattern. It also lacks an import for the global DateTimeImmutable. Accept an explicit timestamp/clock value and import or fully qualify the type.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/03_DOMAIN.md` around lines 56 - 70, Update Invoice::create to
accept an explicit DateTimeImmutable creation timestamp and use it for createdAt
instead of constructing a new timestamp internally. Import DateTimeImmutable or
fully qualify the global type, while preserving the existing factory behavior
and parameter flow.

docs/guides/03_DOMAIN.md-61-70 (1)

61-70: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Fix the domain-event constructor call.

The entity calls new InvoiceCreatedDomainEvent($invoice), but the declared event constructor requires InvoiceId, ClientId, Money, and DateTimeImmutable. As written, the sample throws an argument-count error; pass the declared fields or change the event contract.

Also applies to: 230-238

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/03_DOMAIN.md` around lines 61 - 70, Update the
InvoiceCreatedDomainEvent construction in the invoice creation flow to pass the
constructor’s declared InvoiceId, ClientId, Money, and DateTimeImmutable fields
instead of the Invoice entity object. Keep the event data aligned with the newly
created invoice and preserve the existing record call.

docs/guides/01_KERNEL.md-3-5 (1)

3-5: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Replace the stale Sentinel kernel path.

This new HKM guide still directs readers to vendor/sentinel/kernel/, while the supplied runtime/scaffolding uses the HKM-facing AlfacodeTeam\PhpServicePlatform namespace and package. Update the path and terminology before publishing.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/01_KERNEL.md` around lines 3 - 5, Update the introductory kernel
guidance in 01_KERNEL.md to replace the stale vendor/sentinel/kernel/ path and
Sentinel terminology with the HKM-facing AlfacodeTeam\PhpServicePlatform
namespace and package terminology used by the runtime and scaffolding.

docs/guides/02_MODULE.md-143-150 (1)

143-150: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Import or fully qualify every dependency used by the Provider.

TransactionManager, DomainEventCollector, IntegrationEventBus, and Identity are referenced without use declarations. In this namespace, PHP resolves them as InvoiceModule\... classes, so the sample will fail unless the intended namespaces are imported.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/02_MODULE.md` around lines 143 - 150, Update the provider
example’s dependency references in the InvoiceService binding to import or fully
qualify TransactionManager, DomainEventCollector, IntegrationEventBus, and
Identity, ensuring each resolves to its intended class rather than an
InvoiceModule-local namespace. Keep the existing InvoiceService construction and
repository binding unchanged.

docs/guides/01_KERNEL.md-104-108 (1)

104-108: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Synchronize the security architecture documentation before release.

The public guide still describes nonexistent kernel layers, so the changelog's “corrected to match the code” claim is currently inaccurate.

• docs/guides/01_KERNEL.md#L104-L108: document CsrfTokenLayer, Auth-plugin layers, and route-level throttle/shield filters instead of the obsolete Firewall/RateLimiter/TokenValidator sequence.
• CHANGELOG.md#L25-L30: retain the correction claim only after the guide matches the implementation, or amend the release note.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/01_KERNEL.md` around lines 104 - 108, Update
docs/guides/01_KERNEL.md lines 104-108 to describe the implemented
CsrfTokenLayer, Auth-plugin layers, and route-level throttle/shield filters,
replacing the obsolete Firewall/RateLimiter/TokenValidator sequence. After the
guide is accurate, retain the correction claim in CHANGELOG.md lines 25-30;
otherwise amend that release note to match the documentation state.

docs/guides/02_MODULE.md-125-132 (1)

125-132: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Align the Provider contract with the manifest identifiers.

module.json declares "database.query" and exposes "InvoiceServiceContract", but the canonical Provider returns DatabasePort::class and InvoiceServiceContract::class. Either mirror the manifest with literal domain/export strings, or update the manifest to use contract class names consistently.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/02_MODULE.md` around lines 125 - 132, Align the Provider contract
with module.json by making requires() and exposes() use the same identifier
format as the manifest: either return the literal domain/export strings or
update the manifest to reference the corresponding contract class names. Keep
both declarations consistent across the provider and manifest.

🟡 Minor comments (17)

docs/guides/README.md-40-49 (1)

40-49: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Add the safe-deployment guide to the index.

SAFE_DEPLOYMENTS_GUIDE.md is part of this documentation cohort but is absent from the CLI/data guide list, so readers cannot discover the deployment procedures from the main index.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/README.md` around lines 40 - 49, Update the “CLI & data” guide
index in README.md to add a linked entry for SAFE_DEPLOYMENTS_GUIDE.md, using
the guide’s title and matching the existing table format so the safe-deployment
procedures are discoverable.

docs/guides/06_GATEWAY.md-192-200 (1)

192-200: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Add language identifiers to all fenced code blocks.

These blocks trigger markdownlint MD040. Use identifiers such as php, yaml, text, html, or javascript according to the contents.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/06_GATEWAY.md` around lines 192 - 200, Add language identifiers
to every affected fenced code block: docs/guides/06_GATEWAY.md lines 192-200;
docs/guides/25_AUTH.md lines 24-27 and 309-323; docs/guides/26_OAUTH2.md lines
17-20 and 108-118; and docs/guides/21_CSRF.md lines 18-20, 103-116, and 237-248.
Choose the appropriate identifier for each block’s contents, such as php, yaml,
text, html, or javascript.

Source: Linters/SAST tools

docs/guides/07_CONTROLLER.md-197-225 (1)

197-225: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Validate input types before parsing or constructing the DTO.

An array dueDate can raise TypeError, which is not caught by catch (\Exception), producing a 500 instead of a 422. Likewise, any truthy scalar lineItems passes empty() and later breaks iteration. Require a string date and array line items before processing.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/07_CONTROLLER.md` around lines 197 - 225, Update the validation
flow before DateTimeImmutable construction and DTO creation: require dueDate to
be a non-empty string before parsing, so invalid types are recorded in errors as
422 validation failures, and require lineItems to be a non-empty array rather
than relying on empty(). Preserve the existing future-date validation and
ValidationException behavior for valid inputs.

docs/guides/06_GATEWAY.md-213-227 (1)

213-227: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Reset shouldFail after the promised one-shot failure.

failOnNextCall() sets shouldFail permanently, so every later call fails despite the method name. Clear the flag before throwing, or rename the helper to indicate persistent failure.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/06_GATEWAY.md` around lines 213 - 227, The fake gateway’s
shouldFail flag must represent a one-shot failure as promised by
failOnNextCall(). Update generate() to clear shouldFail before throwing the
GatewayException, while preserving successful generation and call-tracking
behavior for subsequent invocations.

docs/guides/20_FIRST_PARTY_PLUGINS.md-3-8 (1)

3-8: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Finish the HKM rebrand in this guide.

The guide still says “GDA kernel” even though the surrounding documentation identifies the project as HKM Kernel. This leaves users with an obsolete product name and inconsistent bootstrap guidance.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/20_FIRST_PARTY_PLUGINS.md` around lines 3 - 8, Update the
introductory plugin description in the guide to consistently use the HKM Kernel
product name instead of “GDA kernel,” and revise the surrounding bootstrap
guidance to match the current HKM terminology while preserving the existing
plugin registration instructions.

docs/guides/09_SECURITY.md-139-148 (1)

139-148: 🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win

Align the plugin guide’s CSRF description with CsrfTokenLayer’s HMAC model.

• The kernel CSRF guide and source consistently describe this as stateless HMAC-signed CSRF, not plain double-submit. Replace “double-submit-cookie based” in docs/guides/20_FIRST_PARTY_PLUGINS.md or update the security guide if the latter is no longer authoritative.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/09_SECURITY.md` around lines 139 - 148, Align the CSRF
documentation with CsrfTokenLayer’s stateless HMAC-signed model: update
docs/guides/20_FIRST_PARTY_PLUGINS.md:162-164 to remove the
“double-submit-cookie based” description and describe HMAC-signed tokens
instead. Keep docs/guides/09_SECURITY.md:139-148 authoritative and make no
direct change there.

docs/guides/11_PROJECT.md-114-116 (1)

114-116: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Use “afterward” for the documented American-English locale.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/11_PROJECT.md` around lines 114 - 116, Update the prose in the
documented section to use the American-English term “afterward” instead of
“afterwards,” without changing the technical guidance or code references.

Source: Linters/SAST tools

docs/guides/17_PHP_IO_CLI.md-16-16 (1)

16-16: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Add language identifiers to all three fenced blocks.

Also applies to: 603-603, 739-739

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/17_PHP_IO_CLI.md` at line 16, Add the appropriate language
identifier to each of the three fenced code blocks in the documentation,
including the blocks at the referenced locations, by annotating their opening
fences while preserving the existing code content.

Source: Linters/SAST tools

docs/guides/12_WORKER.md-11-11 (1)

11-11: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Add a language identifier to the pipeline diagram fence.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/12_WORKER.md` at line 11, Update the pipeline diagram’s fenced
code block in the worker guide to include the appropriate language identifier
after the opening fence, while preserving the diagram content and formatting.

Source: Linters/SAST tools

docs/guides/16_PLUGINS.md-34-34 (1)

34-34: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Add language identifiers to both fenced blocks.

Also applies to: 156-156

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/16_PLUGINS.md` at line 34, Update the fenced code blocks in the
documented sections, including the location corresponding to the additional
occurrence, to include the appropriate language identifier after each opening
fence.

Source: Linters/SAST tools

docs/guides/12_WORKER.md-341-356 (1)

341-356: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Update the Supervisor example to HKM paths and names.

This guide now documents HKM Kernel, but copying this section still creates sentinel-* programs and /var/log/sentinel/... logs. Use the canonical HKM service/log paths or label these as legacy.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/12_WORKER.md` around lines 341 - 356, Update the Supervisor
examples for sentinel-worker-critical and sentinel-worker-default to use the
canonical HKM program names and service/log paths, including each stdout_logfile
and stderr_logfile. Do not leave sentinel-* identifiers or /var/log/sentinel
paths unless the section is explicitly labeled as legacy.

docs/guides/15_ERROR_HANDLING.md-11-11 (1)

11-11: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Add language identifiers to all four fenced blocks.

Also applies to: 165-165, 216-216, 251-251

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/15_ERROR_HANDLING.md` at line 11, Update all four fenced code
blocks in the documentation, including the blocks at the referenced locations,
to specify the appropriate language identifier immediately after each opening
fence. Preserve the existing examples and formatting aside from adding these
identifiers.

Source: Linters/SAST tools

docs/guides/15_ERROR_HANDLING.md-204-210 (1)

204-210: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Correct the JSON media-type match.

*/json is not a normal JSON Accept value; clients commonly send application/json or application/*+json. If implemented literally, JSON clients may receive the wrong error format or a debug page. Define the matching rules explicitly for both error layers.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/15_ERROR_HANDLING.md` around lines 204 - 210, Update the JSON
detection documentation for both the kernel ErrorStage and pre-kernel ErrorGuard
to match standard JSON media types, including application/json and
application/*+json, rather than the invalid */json pattern. Keep the existing
X-Requested-With, JSON-body, and /api-prefix signals, and state the rules
separately for each layer.

docs/guides/11_PROJECT.md-47-52 (1)

47-52: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Use the documented CLI entrypoint in all commands.

The project CLI template documents app/cli/run.php, but the worker and CLI guides show php cli.php, which is not a committed app entrypoint. Replace those commands with php app/cli/run.php (or label cli.php explicitly as a generated/wrapper shim).

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/11_PROJECT.md` around lines 47 - 52, Update the command examples
in docs/guides/11_PROJECT.md, docs/guides/12_WORKER.md (lines 322-333), and
docs/guides/14_CLI.md (lines 30-31) to use the committed app/cli/run.php
entrypoint via php app/cli/run.php; alternatively, explicitly label any
remaining cli.php usage as a generated or wrapper shim.

README.md-566-567 (1)

566-567: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Provide an HTTPS clone path as well.

The new instructions require a configured GitHub SSH key, which blocks many contributors. Use HTTPS or document both HTTPS and SSH forms.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` around lines 566 - 567, Update the repository cloning instructions
to include an HTTPS clone command alongside the existing SSH command, allowing
contributors without configured GitHub SSH keys to proceed.

README.md-217-217 (1)

217-217: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Align the hkm module documentation with the CLI help.

The README says this command inspects/updates packages, but tools/src/main.zig still advertises hkm module [create|delete]. Make the public table and native help describe the same supported subcommands.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` at line 217, Align the `hkm module` entry in README.md and the CLI
help defined in main.zig so both describe the same supported create and delete
subcommands. Update the table text to match the native help without implying
unsupported inspect or update behavior.

docs/guides/02_MODULE.md-24-65 (1)

24-65: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Use JSONC or remove the inline comments.

This block is labeled json but contains // comments, so it is not valid JSON and cannot be copied into a parser as shown. Label it jsonc or present a valid JSON example separately.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/02_MODULE.md` around lines 24 - 65, Update the module manifest
example around the JSON block to use a JSONC language label when retaining its
inline comments, or remove all comments and keep the json label. Ensure the
displayed example matches the syntax of its declared format.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 51322384-d0d0-47d9-ac72-101c904b78cf

📥 Commits

Reviewing files that changed from the base of the PR and between c0676b4 and 9cd205d.

📒 Files selected for processing (38)

• .gitignore
• CHANGELOG.md
• README.md
• docs/guides/00_SENTINEL_OVERVIEW.md
• docs/guides/01_KERNEL.md
• docs/guides/02_MODULE.md
• docs/guides/03_DOMAIN.md
• docs/guides/04_SERVICE.md
• docs/guides/05_REPOSITORY.md
• docs/guides/06_GATEWAY.md
• docs/guides/07_CONTROLLER.md
• docs/guides/08_EVENTS.md
• docs/guides/09_SECURITY.md
• docs/guides/10_TESTING.md
• docs/guides/11_PROJECT.md
• docs/guides/12_WORKER.md
• docs/guides/13_ANTIPATTERNS.md
• docs/guides/14_CLI.md
• docs/guides/15_ERROR_HANDLING.md
• docs/guides/16_PLUGINS.md
• docs/guides/17_PHP_IO_CLI.md
• docs/guides/18_MIGRATIONS.md
• docs/guides/19_DATABASE.md
• docs/guides/20_FIRST_PARTY_PLUGINS.md
• docs/guides/21_CSRF.md
• docs/guides/22_DATA_ACCESS_ORM_BLUEPRINT.md
• docs/guides/23_TENANCY.md
• docs/guides/24_USER.md
• docs/guides/25_AUTH.md
• docs/guides/26_OAUTH2.md
• docs/guides/27_ENTITY_SUPPORT.md
• docs/guides/README.md
• docs/guides/SAFE_DEPLOYMENTS_GUIDE.md
• src/Kernel/Error/DebugPageRenderer.php
• src/System/GlobalKernelProjectScaffolder.php
• tools/src/commands/upgrade.zig
• tools/src/lib/banner.zig
• tools/src/main.zig