@ryuenn3123/agentic-senior-core 3.0.43 → 3.0.45

package/.agent-context/prompts/bootstrap-design.md

@@ -2,15 +2,13 @@
 
 Use this prompt for UI, UX, frontend layout, screen, Tailwind, animation, 3D, canvas, or redesign work.
 
-Create or refine:
-- `docs/DESIGN.md` for human-readable design reasoning.
-- `docs/design-intent.json` for machine-readable design intent, guardrails, and review signals.
+Create or refine `docs/DESIGN.md` for human reasoning and `docs/design-intent.json` for machine-readable design intent, guardrails, and review signals.
 
 This contract is a decision scaffold, not a style preset. We guide the agent; we do not pick the final style, stack, framework, palette, typography, layout paradigm, or animation library offline.
 
 ## Authority
 - Treat `.agent-context/` and current project docs as technical authority.
-- Treat `README.md` as overview, install, and user-facing context only. Do not use it as coding, architecture, or design authority when `.agent-context/` gives a stricter rule.
+- Treat `README.md` as public and developer overview, setup, usage, and user-facing context only. Do not use it as coding, architecture, or design authority when `.agent-context/` gives a stricter rule.
 - Use current repo evidence, product copy, route names, component names, user goals, and existing constraints as the source of truth.
 - Treat prior-chat visuals, unrelated project memory, benchmark screenshots, and famous-product aesthetics as tainted context unless the user explicitly approves continuity.
 - Keep external references non-copying; extract constraints only.
@@ -43,6 +41,7 @@ Rules:
 - Output only the chosen anchor, specific reference point, and rationale.
 - Forbid final anchors named dashboard, portal, cards, admin panel, SaaS shell, web app shell, or minimalist interface.
 - Derive typography, spacing, density, color behavior, morphology, motion, and responsive composition from the chosen anchor.
+- Translate the anchor non-literally first. Anchor artifacts are evidence for behavior, hierarchy, density, typography, state language, and motion, not automatic UI chrome.
 - Use reduced-motion fallbacks instead of suppressing motion.
 
 ## Creative Ambition Floor
@@ -52,14 +51,20 @@ Before UI code, record:
 - one morphology or composition choice that avoids interchangeable card stacks when the product allows it
 - at least three at-a-glance product-specific signals for new screens or broad redesigns
 
-Do not ship AI-safe UI. Record exact drift signals in `reviewRubric`; at minimum reject decorative grid wallpaper, default line backgrounds, calibration-mark wallpaper, soft glow backgrounds, generic abstract marks, testing/demo/placeholder UI copy, terminal-only user flows, and first-output composition with only local copy swapped in when they have no product function. Treat measurement, calibration, crop, route, timeline, and inspection marks as task overlays or control affordances only; never promote them to the page background, hero backdrop, or first-output visual texture.
+Do not ship AI-safe UI. Record exact drift signals in `reviewRubric`; at minimum reject decorative grid wallpaper, default line backgrounds, calibration-mark wallpaper, soft glow backgrounds, generic abstract marks, testing/demo/placeholder UI copy, terminal-only user flows, and first-output composition with only local copy swapped in when they have no product function. Treat measurement, calibration, crop, route, timeline, and inspection marks as task overlays or control affordances only; never promote them to the page background, hero backdrop, or first-output visual texture. If a conceptual anchor suggests a forbidden motif, the forbidden motif wins; express the anchor through workflow, hierarchy, density, typography, material behavior, state design, and interaction grammar instead of literal wallpaper.
 
 ## Brave Redesign Default
 For UI design work, the agent owns the ambition decision. For broad screens, redesigns, or new visual systems, treat expressive motion, spatial hierarchy, distinctive composition, and product-specific interaction as the baseline even when the user did not say "rich". Do not reduce the request to a safer version of the existing UI, a static implementation, or a component-kit rearrangement because research or dependency selection feels inconvenient.
 
 If the expressive path needs a new motion, 3D, canvas, scroll, or interaction library and web search is available, perform the official-doc research and record the decision. If web search is unavailable, use already-present dependencies or native browser capabilities while preserving the intended ambition, then mark library verification as pending.
 
-Only downshift ambition after naming the concrete blocker: product fit, content density, performance budget, accessibility, device support, package conflict, security risk, or missing runtime capability. Pair every downshift with a replacement interaction quality that still changes composition, hierarchy, feedback, or memorability.
+Only downshift ambition after naming the concrete blocker: product fit, content density, measured performance budget, accessibility, device support, package conflict, security risk, or missing runtime capability. A new dependency, package count, or vague performance concern is not a blocker by itself. Pair every downshift with a replacement interaction quality that still changes composition, hierarchy, feedback, or memorability.
+
+## Design Flexibility Layer
+
+`docs/design-intent.json` must separate locked outcomes from flexible expression. The machine contract keeps review invariants stable; it must not freeze exact aesthetic implementation unless repo evidence, accessibility validation, implementation constraints, or explicit user approval locks it.
+
+Record `designFlexibilityPolicy`: lock user goals, runtime constraints, accessibility, production readiness, forbidden patterns, and approved continuity; keep exact palette primitives, font families, radius/shadow values, component-kit theme mapping, signature move implementation, and literal anchor artifacts flexible until validated or approved. Semantic roles are required; exact primitives are not automatically locked. Required experience outcomes are separate from candidate implementation moves. Libraries supply behavior, accessibility, primitives, and delivery speed; the project supplies final composition, theme, morphology, and visual language.
 
 ## AI Color and Template Residue Audit
 AI color drift happens when a palette uses safe defaults before product meaning.
@@ -90,7 +95,7 @@ Before implementation, `docs/design-intent.json` must include top-level `derived
 - `motionDerivationSource`
 - `validationRule`
 
-Every token must trace to `anchorReference`. If the rationale is "looks good", "common practice", "modern default", or "framework default", revise the token before code.
+Every semantic token role must trace to `anchorReference`. Exact primitive values stay flexible until repo evidence, accessibility validation, implementation constraints, or explicit user approval locks them. If the rationale is "looks good", "common practice", "modern default", or "framework default", derive the token again before UI code.
 
 ## Library Research Protocol
 If web search is available:
@@ -103,8 +108,8 @@ If web search is unavailable:
 - Use native CSS, browser APIs, or already-present dependencies.
 - Set `libraryResearchStatus` to `pending-verification`.
 
-Treat unresearched dependency choices as review findings.
-
+Treat unresearched dependency choices as review findings. Dynamic UI Foundation Selection: do not default to shadcn/ui, Tailwind-only, native-only, or any component kit because it is familiar. Choose the foundation from product type, interaction complexity, accessibility needs, design ambition, team/runtime constraints, bundle/runtime cost, and current official docs.
+Ready-made primitives are allowed when they improve behavior, accessibility, speed, or maintainability. The library supplies mechanics; the project supplies visual language. Reject default component-kit styling without product rationale, but do not reject a modern lightweight library solely because a dependency was needed.
 ## Zero-Based Redesign Protocol
 
 When the user says "redesign from zero", "redesain dari 0", "ulang dari 0", or "research ulang":
@@ -146,6 +151,7 @@ The JSON is the source of truth for machine review. It must stay project-specifi
 - confirmed project context and assumptions
 - agent-chosen visual direction
 - `motionPaletteDecision`
+- `designFlexibilityPolicy`
 - `conceptualAnchor`
 - `derivedTokenLogic`
 - `aiSafeUiAudit` and `productionContentPolicy`
@@ -165,15 +171,6 @@ WCAG 2.2 AA is the hard floor. APCA may be used only as advisory perceptual tuni
 
 Define a review rubric that names drift signals and separates taste from failure.
 
-Block or flag:
-- inaccessible contrast, focus, target size, keyboard, auth, or dynamic-status behavior
-- scale-only responsive behavior
-- default component-kit styling without product rationale
-- nonfunctional background effects, including decorative grid wallpaper
-- grid or line backgrounds used as filler instead of product function
-- testing, demo, sample, placeholder, lorem, TODO, coming soon, or scaffold labels visible in shipped UI unless they are real product states; terminal-only core user flows unless the product is explicitly a CLI, developer tool, or operational runbook
-- palette choices that use readability as an excuse for safe defaults
-- visual direction copied from unrelated memory or external references
-- genericity findings that cannot name the exact drift signal
+Block or flag inaccessible contrast/focus/target/keyboard/auth/status behavior, scale-only responsive behavior, default component-kit styling, nonfunctional background effects, grid or line filler, placeholder copy, terminal-only core flows, readability-as-safe-default palettes, copied visual direction, and genericity findings that cannot name the exact drift signal.
 
 Wait for user approval before generating Figma or code assets when the user only asked for planning or design direction.

package/.agent-context/prompts/init-project.md

@@ -25,9 +25,12 @@ If the user describes a project or feature, the agent must:
 If the user asks to create, complete, fix, or review project docs, documentation, dokumen, `docs/*`, architecture docs, flow docs, API docs, or "lengkapkan docs", treat the request as documentation-first.
 
 The agent must:
-1. Materialize or refine required project docs before implementation: `docs/project-brief.md`, `docs/architecture-decision-record.md`, `docs/flow-overview.md`, `docs/api-contract.md` when APIs, firmware endpoints, CLI commands, or web application flows exist, `docs/database-schema.md` when persistent data exists, and `docs/DESIGN.md` plus `docs/design-intent.json` for UI scope.
+1. Materialize or refine required project docs before implementation: root `README.md` for every fresh or existing project; `docs/project-brief.md`; `docs/architecture-decision-record.md`; `docs/flow-overview.md`; `docs/api-contract.md` when APIs, firmware endpoints, CLI commands, or web application flows exist; `docs/database-schema.md` when persistent data exists; and `docs/DESIGN.md` plus `docs/design-intent.json` for UI scope.
 2. Write formal project docs in English by default unless the user explicitly asks for another documentation language.
-3. Stop after docs when the user only asked for docs. Do not write application, firmware, or UI code until the user explicitly asks for implementation or approves the implementation plan.
+3. Keep `README.md` public and developer friendly even for private projects: explain what the project is, who it is for, how to set it up, how to run the core workflow, how to configure it, and where deeper docs live. Do not put internal agent notes, private reasoning, secrets, or governance policy in the README.
+4. Keep documentation alive. When project behavior, setup, architecture, public contracts, data shape, deployment, or UI scope changes, update the matching docs in the same change.
+5. Avoid documentation sprawl. Add a new docs file only when the topic is stable, long enough to outgrow the README or core docs, or owned by a separate workflow such as hardware setup, deployment, troubleshooting, or testing validation.
+6. Stop after docs when the user only asked for docs. Do not write application, firmware, or UI code until the user explicitly asks for implementation or approves the implementation plan.
 
 ## Direct Constraint Mode
 

package/.agent-context/prompts/refactor.md

@@ -11,7 +11,7 @@ Before editing:
 3. If required project docs are missing, stop and bootstrap or update docs first.
 4. If the change touches UI, load .agent-context/prompts/bootstrap-design.md and .agent-context/rules/frontend-architecture.md before editing.
 5. If the change touches a dependency, framework, Docker, runtime, or ecosystem claim, verify current official docs before choosing.
-6. Enforce Universal SOP hard gate: stop implementation if `docs/architecture-decision-record.md` is missing, and for UI scope stop if `docs/DESIGN.md` or `docs/design-intent.json` is missing.
+6. Enforce Universal SOP hard gate: stop implementation if root `README.md` is missing, if `docs/architecture-decision-record.md` is missing, or for UI scope if `docs/DESIGN.md` or `docs/design-intent.json` is missing.
 7. Enforce backend universal principles: no clever hacks, no premature abstraction, readability over brevity.
 8. For backend/API scope, enforce layered boundaries, zero-trust input validation, safe centralized error responses, bounded list reads, transaction safety for multi-write mutations, idempotency for sensitive mutations, and behavior-focused API tests.
 9. Backend/API governance is global and stack-agnostic. Do not create stack-specific adapters or framework-specific rule branches; apply the global rules through the framework already present in the target project.

package/.agent-context/prompts/review-code.md

@@ -11,7 +11,7 @@ Before reviewing:
 3. Read .agent-context/review-checklists/architecture-review.md only when architecture or boundaries changed.
 4. Load only the rules relevant to the changed scope.
 5. For UI changes, load .agent-context/prompts/bootstrap-design.md, .agent-context/rules/frontend-architecture.md, docs/DESIGN.md, and docs/design-intent.json when present.
-6. Enforce Universal SOP hard gate: block coding flow when required project docs are missing (`docs/architecture-decision-record.md`, and for UI scope `docs/DESIGN.md` plus `docs/design-intent.json`).
+6. Enforce Universal SOP hard gate: block coding flow when required project docs are missing (root `README.md`; `docs/architecture-decision-record.md`; and for UI scope `docs/DESIGN.md` plus `docs/design-intent.json`).
 7. Enforce single-source and lazy-loading policy: canonical rule source must be explicitly enforced, global domain governance must load lazily based on touched scope, and conflicting duplicate rule instructions must not appear during normal flow.
 
 Prioritize findings in this order:

package/.agent-context/review-checklists/pr-checklist.md

@@ -60,7 +60,7 @@ Run this before declaring a task done. Apply only the sections relevant to the c
 
 - [ ] Scope applied: This applies to documentation, release notes, onboarding text, review summaries, and agent-facing explanations
 - [ ] Style scope review is advisory and does not block merge when API docs are synced in the same commit and contract details are correct
-- [ ] Required docs exist before implementation: project brief, architecture decision, flow overview, API/public contract when relevant, data model when relevant, and UI design contract when relevant.
+- [ ] Required docs exist before implementation: public and developer root README; project brief; architecture decision; flow overview; API/public contract when relevant; data model when relevant; and UI design contract when relevant.
 - [ ] For docs-only or docs-first requests, implementation code was not changed unless the user explicitly asked for it or approved an implementation plan.
 - [ ] Formal project docs use English by default unless the user requested another language or existing docs established one.
 - [ ] Docs cover feature plan, architecture rationale, public contracts, data model, UI/design, security assumptions, testing strategy, delivery flow, and next validation actions where relevant.
@@ -70,6 +70,9 @@ Run this before declaring a task done. Apply only the sections relevant to the c
 - [ ] Facts, assumptions, and next actions are separated when context is incomplete.
 - [ ] No emoji in formal documentation or review summaries
 - [ ] Documentation uses plain English and avoids AI cliches
+- [ ] Root README is public and developer friendly, even for private projects, and does not contain secrets, internal agent notes, private reasoning, or governance policy dumps.
+- [ ] Documentation grows with the project: README and matching docs were updated when setup, runtime, architecture, public contracts, data shape, deployment, validation, or UI scope changed.
+- [ ] Documentation file count stayed intentional: new docs files were added only for stable, distinct, or long workflows.
 
 ## 7. UI And Accessibility
 
@@ -81,10 +84,13 @@ Run this before declaring a task done. Apply only the sections relevant to the c
 - [ ] Motion is treated as part of the design language for modern UI work, with reduced-motion and performance safeguards instead of defaulting to static screens.
 - [ ] Broad redesigns pass the old-design regression test: the result is not the previous composition with animation, depth, media, or interaction density removed.
 - [ ] UI work records an agent-chosen ambition level; broad screens and redesigns researched an expressive path first, and any downshift names a concrete blocker plus replacement interaction quality.
+- [ ] UI foundation choices are dynamic and product-fit; no shadcn, native-only, Tailwind-only, or component-kit default was selected by habit or avoided from dependency fear.
+- [ ] Design intent separates locked outcomes from flexible expression; candidate signature moves, exact token primitives, literal anchor artifacts, and component-kit skins were not treated as permanent requirements without evidence or user approval.
 
 ## 8. Dependencies And Runtime
 
 - [ ] New dependencies are justified by capability, maintenance health, bundle/runtime cost, and current official docs.
+- [ ] Dependency avoidance was not treated as a default virtue; lightweight maintained libraries were considered when they improve correctness, accessibility, UX, maintainability, or delivery speed.
 - [ ] Official setup flows are preferred when they produce better-supported current defaults.
 - [ ] Docker, framework, package, and ecosystem claims were checked live when they could be stale.
 - [ ] Token optimization and memory continuity defaults remain enabled unless the user explicitly opts out.
@@ -113,6 +119,7 @@ Run this before declaring a task done. Apply only the sections relevant to the c
 - [ ] `.agent-context/rules/` remains the default guidance source for implementation and review.
 - [ ] Security and testing requirements remain mandatory after static template purge.
 - [ ] Coding flow is blocked if `docs/architecture-decision-record.md` (or `docs/Architecture-Decision-Record.md`) is missing
+- [ ] Coding flow is blocked if root `README.md` is missing
 - [ ] UI implementation flow is blocked if `docs/DESIGN.md` or `docs/design-intent.json` is missing
 
 ## Verdict

package/.agent-context/rules/api-docs.md

@@ -4,6 +4,22 @@
 
 If a change affects an API, CLI command, exported library behavior, schema, event, or integration contract, update the matching docs in the same change.
 
+## Public README Boundary
+
+Root `README.md` is required for every fresh or existing project. This includes private projects, because a future maintainer still needs a clear public and developer entrypoint.
+
+README content must be safe for outside readers and useful for developers. It must explain what the project is, who it is for, how to set it up, how to run the main workflow, how to configure it, and where deeper docs live when those topics apply.
+
+Keep README overview-level. Do not make it the canonical governance source. Do not put secrets, private agent notes, hidden reasoning, backlog chatter, raw architecture debate, or internal policy dumps in it.
+
+Choose README sections from project evidence. Do not force a fixed template when a section does not apply. For private/internal projects, keep the same clear style but omit private URLs, credentials, customer names, and internal-only operational details that do not belong in repo docs.
+
+## Documentation Growth Model
+
+Documentation must evolve with the project. When behavior, setup, architecture, public contracts, data shape, deployment, or validation changes, update README and the matching docs in the same change.
+
+Start compact, then split only when a topic earns its own file. Good split signals are: the section is long, the workflow is owned separately, the content is referenced often, or the topic needs step-by-step care such as hardware setup, deployment, testing validation, operations, or troubleshooting.
+
 ## Contract Rules
 
 - Document the public surface before or alongside implementation.

package/.agent-context/rules/architecture.md

@@ -32,17 +32,20 @@ The `.agent-context/rules/` directory is the default guidance source for impleme
 - Backend and frontend mindset checks are both required when a task spans API and UI boundaries.
 - Security and testing are non-negotiable baseline requirements.
 - Hard block before coding:
+  - Root `README.md` must exist for every fresh or existing project and read as a public and developer entrypoint, not an internal agent note.
   - `docs/project-brief.md` must exist.
   - `docs/architecture-decision-record.md` (alias: `docs/Architecture-Decision-Record.md`) must exist.
   - `docs/flow-overview.md` must exist.
   - If the project uses persistent data, `docs/database-schema.md` must exist.
   - If the project exposes API or web application flows, `docs/api-contract.md` must exist.
   - For UI scope, `docs/DESIGN.md` and `docs/design-intent.json` must exist.
-- Required docs coverage must include feature plan, architecture rationale, public contracts, data model when relevant, UI/design when relevant, security assumptions, testing strategy, delivery flow, and next validation actions.
+- Required docs coverage must include a public and developer README entrypoint, feature plan, architecture rationale, public contracts, data model when relevant, UI/design when relevant, security assumptions, testing strategy, delivery flow, and next validation actions.
 - If required project context docs are missing, stop implementation and bootstrap docs before writing application code.
 - Bootstrap flow: analyze the real repo plus the latest user prompt before authoring those docs.
 - Bootstrap docs must be adaptive and project-specific. Do not create generic placeholder templates.
 - When context is incomplete, separate confirmed facts from assumptions, add an `Assumptions to Validate` section, and end with the next validation action.
+- Keep docs current with project changes. Update README and the matching docs whenever setup, runtime, architecture, public contracts, data shape, UI scope, deployment, or validation flow changes.
+- Control docs file count. Keep the baseline compact, then add topic files only when a subject is stable, too long for README/core docs, or belongs to a distinct workflow such as hardware setup, deployment, testing validation, operations, or troubleshooting.
 
 ## Rules as Guardian (Cross-Session Consistency)
 

package/.agent-context/rules/efficiency-vs-hype.md

@@ -4,7 +4,9 @@
 
 The LLM may choose modern libraries and tooling when they fit the project. This rule does not prefer "no library", "always add a library", or any fixed dependency set.
 
-New dependencies are allowed when they create a better practical tradeoff than custom implementation. The decision should be based on whether the dependency meaningfully improves efficiency, shortens delivery time, improves correctness, reduces maintenance burden, or avoids unnecessary in-house code.
+New dependencies are allowed when they create a better practical tradeoff than custom implementation. The decision should be based on whether the dependency meaningfully improves efficiency, shortens delivery time, improves correctness, reduces maintenance burden, unlocks a stronger user experience, or avoids unnecessary in-house code.
+
+Do not treat dependency avoidance as an engineering virtue by itself. A small, maintained, well-scoped library can be the simpler and safer choice than custom code, especially for accessibility primitives, animation, gestures, data visualization, parsing, protocol handling, security-sensitive helpers, or browser/runtime capabilities with tricky edge cases.
 
 Before adding or recommending a dependency:
 - check current official docs, release notes, and setup guidance when the ecosystem decision matters
@@ -14,5 +16,6 @@ Before adding or recommending a dependency:
 - explain why the dependency is a better tradeoff than local implementation for the current task
 - avoid packages that are stale, thinly maintained, too heavy for the job, or added only because they are popular
 - keep dependency boundaries replaceable when the library would spread through many files
+- do not reject a dependency only because it adds a package; reject it only when the project-fit, security, maintenance, compatibility, bundle/runtime, or ownership tradeoff is worse than the alternative
 
-Reject offline dependency decisions, outdated tutorial versions, trend choices, and dependency avoidance choices that are not grounded in the current repo, brief, and delivery tradeoffs.
+Reject offline dependency decisions, outdated tutorial versions, trend choices, dependency avoidance choices, and performance-fear choices that are not grounded in the current repo, brief, and delivery tradeoffs.

package/.agent-context/rules/frontend-architecture.md

@@ -4,28 +4,25 @@ Load this rule for UI-facing work. Keep the loaded surface small.
 
 ## Activation
 
-Use this rule for:
-- UI, UX, page, screen, component, layout, landing, dashboard, form, onboarding, animation, interaction
-- redesign, reskin, visual refresh, responsive fix, hierarchy fix
-- frontend deliverables inside fullstack or backend work
+Use this rule for UI, UX, page, screen, component, layout, landing, dashboard, form, onboarding, animation, interaction, redesign, visual refresh, responsive fix, hierarchy fix, and frontend deliverables inside fullstack or backend work.
 
 ## Authority
 
 - Use current repo evidence, the active brief, and current project docs as valid style context.
 - Treat `.agent-context/` as design governance authority.
-- Treat `README.md` as overview/install/user context only when design or architecture rules conflict.
+- Treat `README.md` as public and developer overview, setup, usage, and user-facing context only when design or architecture rules conflict.
 - Do not choose final style, framework, palette, typography, layout paradigm, or animation library offline.
 - Research current official docs before adding a new UI, animation, scroll, 3D, canvas, charting, icon, styling, or primitive library.
+- Dynamic UI Foundation: do not hardcode shadcn/ui, Tailwind-only, native-only, or any component library as the universal answer. Modern lightweight primitives, motion libraries, canvas/WebGL helpers, charting libraries, and styling tools are valid when product evidence, accessibility, interaction quality, maintainability, delivery speed, runtime constraints, and official docs support them.
 - Keep design continuity opt-in. Repo evidence outranks memory residue.
 
 ## Required Design Contract
 
-Before UI code, create or refine:
-- `docs/DESIGN.md`
-- `docs/design-intent.json`
+Before UI code, create or refine `docs/DESIGN.md` and `docs/design-intent.json`.
 
 The contract must record:
 - `motionPaletteDecision`
+- `designFlexibilityPolicy`
 - `conceptualAnchor`
 - `derivedTokenLogic`
 - `aiSafeUiAudit`
@@ -47,7 +44,7 @@ Use the old-design regression test for broad redesigns: if the UI reads as the p
 
 Background lines, grids, scanlines, noise, glows, blobs, abstract logos, calibration marks, and decorative geometry are invalid as wallpaper. Do not use grid or line backgrounds as first-output filler. Use them only for a named product function such as alignment, crop guidance, map/route orientation, timeline reading, measurement, status, or motion continuity.
 
-Measurement, calibration, crop, map, route, and inspection marks are task-bound overlays or control affordances. They must not become the page background, hero backdrop, or default visual texture.
+Measurement, calibration, crop, map, route, and inspection marks are task-bound overlays or control affordances. They must not become the page background, hero backdrop, or default visual texture. When a conceptual anchor and a forbidden visual motif conflict, the forbidden motif wins; translate the anchor into layout, hierarchy, density, typography, state behavior, materials, and interaction instead of literal decorative texture.
 
 Production UI must read as ship-ready: no visible testing, demo, sample, placeholder, lorem, TODO, coming soon, or scaffold labels unless they are intentional product states. User-facing workflows need an operable UI path; terminal-only core flows are valid only for CLI, developer-tool, or runbook products.
 
@@ -59,6 +56,7 @@ If the user gives no current-task visual research or reference:
 - Internally reject the safest dashboard, portal, card-grid, admin-shell, or minimalist-web-app mental model.
 - Record one real-world anchor reference, one signature motion behavior, and one typographic decision with role contrast.
 - Derive typography, spacing, morphology, motion, and responsive recomposition from that anchor.
+- Translate the anchor into workflow, hierarchy, density, typography, state behavior, and interaction before using literal artifacts. Do not turn anchor artifacts into required chrome, wallpaper, decorative props, or component-kit theme objects without a named product function.
 - Reject anchors described only by generic quality words such as modern, clean, premium, expressive, minimal, or bold.
 
 ## Motion, Palette, and 3D
@@ -70,9 +68,10 @@ If the user gives no current-task visual research or reference:
 - Do not default to dark slate, cream/beige/tan, purple-blue gradients, monochrome palettes, cyber-neon terminals, or uniform card surfaces without product evidence.
 - Treat motion, 3D, WebGL, canvas, scroll choreography, and animation libraries as first-class options.
 - Omit rich motion or spatial UI only after naming the product-fit reason and the replacement interaction quality.
-- For new screens or broad redesigns, research the expressive implementation path instead of defaulting to static native CSS. Use native or already-installed tools only when they can still deliver the chosen ambition, or when a concrete blocker is documented.
+- For new screens or broad redesigns, research the expressive implementation path instead of defaulting to static native CSS. Use native or already-installed tools only when they can still deliver the chosen ambition, or when a concrete blocker is documented. Do not downshift because adding a package feels inconvenient; downshift only for a concrete product-fit, accessibility, security, compatibility, device, maintenance, or measured performance reason.
 - Keep reduced-motion, keyboard, loading, performance, mobile, and non-3D fallbacks explicit.
-
+- Use component kits or headless primitives for behavior and accessibility when they fit. Replace library-default visual language with project-specific composition, tokens, motion, state treatment, and morphology.
+- Keep design-intent flexible: lock user goals, accessibility, production readiness, forbidden patterns, and approved continuity; keep exact palette primitives, font families, radius/shadow values, component skins, and candidate signature moves flexible until evidence or approval locks them.
 ## Zero-Based Redesign
 
 If the user asks for a redesign from zero:

package/.agent-context/rules/performance.md

@@ -2,6 +2,8 @@
 
 Do not over-optimize by habit. Do reject obvious scale and runtime failures.
 
+Performance is a decision input, not a blanket veto against modern libraries, motion, richer UI, or maintained tooling. Compare the real cost of the dependency or implementation against the cost of custom code, lost accessibility, weaker UX, duplicated maintenance, and slower delivery.
+
 Hard rejections:
 - repeated network, database, filesystem, or model calls inside loops without batching, limits, or caching rationale
 - unbounded reads, renders, exports, or searches when the data can grow
@@ -9,4 +11,4 @@ Hard rejections:
 - synchronous blocking work in request, UI, worker, or async paths where it can stall the product
 - caches without invalidation, expiry, ownership, and staleness trade-offs
 
-When performance matters, measure the real bottleneck, change the smallest useful thing, and verify the result.
+When performance matters, measure the real bottleneck, change the smallest useful thing, and verify the result. Do not downshift product quality, UI ambition, or library fit from performance fear alone; name the concrete budget, bottleneck, device limit, or runtime evidence.

package/.agent-context/state/architecture-map.md

@@ -34,7 +34,7 @@ Use this file as repo-local agent context. It records the current governance arc
 ## Agent Behavior
 
 1. Load the smallest relevant rule set.
-2. Use README only for overview/install/user context when governance files conflict.
+2. Use README only for public and developer overview, setup, usage, and user-facing context when governance files conflict.
 3. Preserve generated adapter sync before release.
 4. Treat stale generated state, dual lockfiles, and obsolete V2/V3 transition files as cleanup findings.
 5. Before claiming done, run the relevant validation gate and report any skipped checks.

package/.cursor/rules/agentic-senior-core.mdc

@@ -7,12 +7,12 @@ alwaysApply: true
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: 91efb30348194cff4f7a820caabeb60cd7ca59dea3982a7d3991c7b18991d225
+Canonical Snapshot SHA256: a64819c73c12f55405e4e6249b352fbdb8b94847bc43279e8bf43e07ef5357f3
 
 This repository is governed by a strict instruction contract.
 Use [.instructions.md](../../.instructions.md) as the canonical policy source.
 Use .agent-context/ for technical rules, prompts, checklists, policies, and state.
-Treat README.md as overview/install/user context only when governance files conflict.
+Treat README.md as public and developer overview, setup, usage, and user-facing context only when governance files conflict.
 
 ## Critical Bootstrap Floor
 
@@ -23,6 +23,7 @@ Treat README.md as overview/install/user context only when governance files conf
 - For UI scope, include a one-line Motion/Palette Decision in the Bootstrap Receipt; product categories are heuristics, not style presets.
 - For UI scope, create or refine `docs/DESIGN.md` and `docs/design-intent.json` before UI implementation.
 - For documentation-first requests, create or refine required project docs in English by default and do not write application, firmware, or UI code until the user asks or approves.
+- Create or refine root README.md as the public and developer entrypoint before implementation.
 - For backend, API, data, auth, error, event, queue, worker, or distributed-system requests, load only relevant global rules from .agent-context/rules/ ([link](../../.agent-context/rules)).
 - For ecosystem, framework, dependency, or Docker claims, perform live web research.
 - Resolve runtime choices from project evidence and live official documentation; resolve structural planning from constraints and architecture boundaries.

package/.cursorrules

@@ -1,6 +1,6 @@
 # .cursorrules - Legacy Thin Adapter
 
-Generated by Agentic-Senior-Core CLI v3.0.43
+Generated by Agentic-Senior-Core CLI v3.0.45
 Adapter Mode: legacy-thin
 Adapter Source: .agent-instructions.md when present; fallback .instructions.md
 Canonical baseline: .instructions.md

package/.gemini/instructions.md

@@ -2,12 +2,12 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: 91efb30348194cff4f7a820caabeb60cd7ca59dea3982a7d3991c7b18991d225
+Canonical Snapshot SHA256: a64819c73c12f55405e4e6249b352fbdb8b94847bc43279e8bf43e07ef5357f3
 
 This repository is governed by a strict instruction contract.
 Use [.instructions.md](../.instructions.md) as the canonical policy source.
 Use .agent-context/ for technical rules, prompts, checklists, policies, and state.
-Treat README.md as overview/install/user context only when governance files conflict.
+Treat README.md as public and developer overview, setup, usage, and user-facing context only when governance files conflict.
 
 ## Critical Bootstrap Floor
 
@@ -18,6 +18,7 @@ Treat README.md as overview/install/user context only when governance files conf
 - For UI scope, include a one-line Motion/Palette Decision in the Bootstrap Receipt; product categories are heuristics, not style presets.
 - For UI scope, create or refine `docs/DESIGN.md` and `docs/design-intent.json` before UI implementation.
 - For documentation-first requests, create or refine required project docs in English by default and do not write application, firmware, or UI code until the user asks or approves.
+- Create or refine root README.md as the public and developer entrypoint before implementation.
 - For backend, API, data, auth, error, event, queue, worker, or distributed-system requests, load only relevant global rules from .agent-context/rules/ ([link](../.agent-context/rules)).
 - For ecosystem, framework, dependency, or Docker claims, perform live web research.
 - Resolve runtime choices from project evidence and live official documentation; resolve structural planning from constraints and architecture boundaries.

package/.github/copilot-instructions.md

@@ -2,12 +2,12 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: 91efb30348194cff4f7a820caabeb60cd7ca59dea3982a7d3991c7b18991d225
+Canonical Snapshot SHA256: a64819c73c12f55405e4e6249b352fbdb8b94847bc43279e8bf43e07ef5357f3
 
 This repository is governed by a strict instruction contract.
 Use [.instructions.md](../.instructions.md) as the canonical policy source.
 Use .agent-context/ for technical rules, prompts, checklists, policies, and state.
-Treat README.md as overview/install/user context only when governance files conflict.
+Treat README.md as public and developer overview, setup, usage, and user-facing context only when governance files conflict.
 
 ## Critical Bootstrap Floor
 
@@ -18,6 +18,7 @@ Treat README.md as overview/install/user context only when governance files conf
 - For UI scope, include a one-line Motion/Palette Decision in the Bootstrap Receipt; product categories are heuristics, not style presets.
 - For UI scope, create or refine `docs/DESIGN.md` and `docs/design-intent.json` before UI implementation.
 - For documentation-first requests, create or refine required project docs in English by default and do not write application, firmware, or UI code until the user asks or approves.
+- Create or refine root README.md as the public and developer entrypoint before implementation.
 - For backend, API, data, auth, error, event, queue, worker, or distributed-system requests, load only relevant global rules from .agent-context/rules/ ([link](../.agent-context/rules)).
 - For ecosystem, framework, dependency, or Docker claims, perform live web research.
 - Resolve runtime choices from project evidence and live official documentation; resolve structural planning from constraints and architecture boundaries.

package/.github/instructions/agentic-senior-core.instructions.md

@@ -6,12 +6,12 @@ applyTo: "**"
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: 91efb30348194cff4f7a820caabeb60cd7ca59dea3982a7d3991c7b18991d225
+Canonical Snapshot SHA256: a64819c73c12f55405e4e6249b352fbdb8b94847bc43279e8bf43e07ef5357f3
 
 This repository is governed by a strict instruction contract.
 Use [.instructions.md](../../.instructions.md) as the canonical policy source.
 Use .agent-context/ for technical rules, prompts, checklists, policies, and state.
-Treat README.md as overview/install/user context only when governance files conflict.
+Treat README.md as public and developer overview, setup, usage, and user-facing context only when governance files conflict.
 
 ## Critical Bootstrap Floor
 
@@ -22,6 +22,7 @@ Treat README.md as overview/install/user context only when governance files conf
 - For UI scope, include a one-line Motion/Palette Decision in the Bootstrap Receipt; product categories are heuristics, not style presets.
 - For UI scope, create or refine `docs/DESIGN.md` and `docs/design-intent.json` before UI implementation.
 - For documentation-first requests, create or refine required project docs in English by default and do not write application, firmware, or UI code until the user asks or approves.
+- Create or refine root README.md as the public and developer entrypoint before implementation.
 - For backend, API, data, auth, error, event, queue, worker, or distributed-system requests, load only relevant global rules from .agent-context/rules/ ([link](../../.agent-context/rules)).
 - For ecosystem, framework, dependency, or Docker claims, perform live web research.
 - Resolve runtime choices from project evidence and live official documentation; resolve structural planning from constraints and architecture boundaries.

package/.instructions.md

@@ -10,7 +10,7 @@ Act as a Principal Engineer. Ship maintainable, validated, production-ready work
 
 This repository is governed by a strict instruction contract.
 
-Use `.instructions.md` as the canonical baseline. Use `.agent-context/` as technical authority for rules, prompts, checklists, state, and policies. Use `README.md` only for overview, setup, and user-facing context when stricter governance files conflict.
+Use `.instructions.md` as the canonical baseline. Use `.agent-context/` as technical authority for rules, prompts, checklists, state, and policies. Use `README.md` only for public and developer overview, setup, usage, and user-facing context when stricter governance files conflict.
 
 Write instructions as imperative gates:
 - Use direct commands.
@@ -44,7 +44,7 @@ Load only relevant rule files. Do not read the entire rule directory by default.
 
 Available rules: `naming-conv.md`, `architecture.md`, `security.md`, `performance.md`, `error-handling.md`, `testing.md`, `git-workflow.md`, `efficiency-vs-hype.md`, `api-docs.md`, `microservices.md`, `event-driven.md`, `database-design.md`, `realtime.md`, `frontend-architecture.md`, `docker-runtime.md`.
 
-For Docker or Compose work, load `docker-runtime.md` and verify the latest official Docker docs before authoring container assets. For framework or package setup work, use the latest stable compatible dependency set and official setup flow unless a documented compatibility constraint blocks it. New dependencies are allowed when they improve efficiency, delivery time, correctness, or maintainability.
+For Docker or Compose work, load `docker-runtime.md` and verify the latest official Docker docs before authoring container assets. For framework or package setup work, use the latest stable compatible dependency set and official setup flow unless a documented compatibility constraint blocks it. New dependencies are allowed when they improve efficiency, delivery time, correctness, accessibility, UX, or maintainability. Do not treat dependency avoidance or vague performance fear as a default reason to skip a modern maintained library.
 
 Backend/API routing:
 - Data/schema/persistence: `architecture.md`, `database-design.md`, `performance.md`, `testing.md`.
@@ -97,7 +97,7 @@ Use `.agent-context/policies/` for quality gates, release thresholds, and audit
 
 ### Layer 9: Project Context
 
-Use `docs/` when present: `project-brief.md`, `architecture-decision-record.md`, `database-schema.md`, `api-contract.md`, `flow-overview.md`, `DESIGN.md`, `design-intent.json`.
+Use root `README.md` as the public and developer entrypoint for every fresh or existing project. Use `docs/` when present: `project-brief.md`, `architecture-decision-record.md`, `database-schema.md`, `api-contract.md`, `flow-overview.md`, `DESIGN.md`, `design-intent.json`.
 
 ## Mandatory Triggers
 
@@ -106,7 +106,7 @@ Use `docs/` when present: `project-brief.md`, `architecture-decision-record.md`,
 Trigger: docs, documentation, dokumen, `docs/*`, architecture docs, flow docs, API docs, or "lengkapkan docs".
 
 1. Load `architecture.md`, `api-docs.md`, and only additional rules required by scope.
-2. Create or refine required docs first: `docs/project-brief.md`, `docs/architecture-decision-record.md`, `docs/flow-overview.md`, `docs/api-contract.md` for APIs/firmware/CLI/web flows, `docs/database-schema.md` for persistent data, and `docs/DESIGN.md` plus `docs/design-intent.json` for UI scope.
+2. Create or refine required docs first: root `README.md` for every fresh or existing project; `docs/project-brief.md`; `docs/architecture-decision-record.md`; `docs/flow-overview.md`; `docs/api-contract.md` for APIs, firmware endpoints, CLI commands, or web application flows; `docs/database-schema.md` for persistent data; and `docs/DESIGN.md` plus `docs/design-intent.json` for UI scope.
 3. Write formal project docs in English by default unless the user asks otherwise.
 4. Stop after documentation when the user only asked for docs. Do not write application, firmware, or UI code until the user asks or approves implementation.
 
@@ -165,7 +165,7 @@ Why Required: [project protection]
 Never claim done without:
 1. Relevant rules applied.
 2. PR and architecture checklists considered.
-3. Universal SOP gates satisfied: `docs/architecture-decision-record.md`, plus `docs/DESIGN.md` and `docs/design-intent.json` for UI scope.
+3. Universal SOP gates satisfied: public and developer root `README.md`; `docs/architecture-decision-record.md`; plus `docs/DESIGN.md` and `docs/design-intent.json` for UI scope.
 4. If `.agent-context/state/active-memory.json` exists and material project progress happened, refresh it while preserving privacy rules and user-owned entries.
 5. MCP validation passed through `npm run validate`.
 

package/.windsurf/rules/agentic-senior-core.md

@@ -2,12 +2,12 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: 91efb30348194cff4f7a820caabeb60cd7ca59dea3982a7d3991c7b18991d225
+Canonical Snapshot SHA256: a64819c73c12f55405e4e6249b352fbdb8b94847bc43279e8bf43e07ef5357f3
 
 This repository is governed by a strict instruction contract.
 Use [.instructions.md](../../.instructions.md) as the canonical policy source.
 Use .agent-context/ for technical rules, prompts, checklists, policies, and state.
-Treat README.md as overview/install/user context only when governance files conflict.
+Treat README.md as public and developer overview, setup, usage, and user-facing context only when governance files conflict.
 
 ## Critical Bootstrap Floor
 
@@ -18,6 +18,7 @@ Treat README.md as overview/install/user context only when governance files conf
 - For UI scope, include a one-line Motion/Palette Decision in the Bootstrap Receipt; product categories are heuristics, not style presets.
 - For UI scope, create or refine `docs/DESIGN.md` and `docs/design-intent.json` before UI implementation.
 - For documentation-first requests, create or refine required project docs in English by default and do not write application, firmware, or UI code until the user asks or approves.
+- Create or refine root README.md as the public and developer entrypoint before implementation.
 - For backend, API, data, auth, error, event, queue, worker, or distributed-system requests, load only relevant global rules from .agent-context/rules/ ([link](../../.agent-context/rules)).
 - For ecosystem, framework, dependency, or Docker claims, perform live web research.
 - Resolve runtime choices from project evidence and live official documentation; resolve structural planning from constraints and architecture boundaries.

package/.windsurfrules

@@ -1,6 +1,6 @@
 # .windsurfrules - Legacy Thin Adapter
 
-Generated by Agentic-Senior-Core CLI v3.0.43
+Generated by Agentic-Senior-Core CLI v3.0.45
 Adapter Mode: legacy-thin
 Adapter Source: .agent-instructions.md when present; fallback .instructions.md
 Canonical baseline: .instructions.md

package/AGENTS.md

@@ -2,12 +2,12 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: 91efb30348194cff4f7a820caabeb60cd7ca59dea3982a7d3991c7b18991d225
+Canonical Snapshot SHA256: a64819c73c12f55405e4e6249b352fbdb8b94847bc43279e8bf43e07ef5357f3
 
 This repository is governed by a strict instruction contract.
 Use [.instructions.md](.instructions.md) as the canonical policy source.
 Use .agent-context/ for technical rules, prompts, checklists, policies, and state.
-Treat README.md as overview/install/user context only when governance files conflict.
+Treat README.md as public and developer overview, setup, usage, and user-facing context only when governance files conflict.
 
 ## Critical Bootstrap Floor
 
@@ -18,6 +18,7 @@ Treat README.md as overview/install/user context only when governance files conf
 - For UI scope, include a one-line Motion/Palette Decision in the Bootstrap Receipt; product categories are heuristics, not style presets.
 - For UI scope, create or refine `docs/DESIGN.md` and `docs/design-intent.json` before UI implementation.
 - For documentation-first requests, create or refine required project docs in English by default and do not write application, firmware, or UI code until the user asks or approves.
+- Create or refine root README.md as the public and developer entrypoint before implementation.
 - For backend, API, data, auth, error, event, queue, worker, or distributed-system requests, load only relevant global rules from .agent-context/rules/ ([link](.agent-context/rules)).
 - For ecosystem, framework, dependency, or Docker claims, perform live web research.
 - Resolve runtime choices from project evidence and live official documentation; resolve structural planning from constraints and architecture boundaries.

package/CLAUDE.md

@@ -2,12 +2,12 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: 91efb30348194cff4f7a820caabeb60cd7ca59dea3982a7d3991c7b18991d225
+Canonical Snapshot SHA256: a64819c73c12f55405e4e6249b352fbdb8b94847bc43279e8bf43e07ef5357f3
 
 This repository is governed by a strict instruction contract.
 Use [.instructions.md](.instructions.md) as the canonical policy source.
 Use .agent-context/ for technical rules, prompts, checklists, policies, and state.
-Treat README.md as overview/install/user context only when governance files conflict.
+Treat README.md as public and developer overview, setup, usage, and user-facing context only when governance files conflict.
 
 ## Critical Bootstrap Floor
 
@@ -18,6 +18,7 @@ Treat README.md as overview/install/user context only when governance files conf
 - For UI scope, include a one-line Motion/Palette Decision in the Bootstrap Receipt; product categories are heuristics, not style presets.
 - For UI scope, create or refine `docs/DESIGN.md` and `docs/design-intent.json` before UI implementation.
 - For documentation-first requests, create or refine required project docs in English by default and do not write application, firmware, or UI code until the user asks or approves.
+- Create or refine root README.md as the public and developer entrypoint before implementation.
 - For backend, API, data, auth, error, event, queue, worker, or distributed-system requests, load only relevant global rules from .agent-context/rules/ ([link](.agent-context/rules)).
 - For ecosystem, framework, dependency, or Docker claims, perform live web research.
 - Resolve runtime choices from project evidence and live official documentation; resolve structural planning from constraints and architecture boundaries.

package/GEMINI.md

@@ -2,12 +2,12 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: 91efb30348194cff4f7a820caabeb60cd7ca59dea3982a7d3991c7b18991d225
+Canonical Snapshot SHA256: a64819c73c12f55405e4e6249b352fbdb8b94847bc43279e8bf43e07ef5357f3
 
 This repository is governed by a strict instruction contract.
 Use [.instructions.md](.instructions.md) as the canonical policy source.
 Use .agent-context/ for technical rules, prompts, checklists, policies, and state.
-Treat README.md as overview/install/user context only when governance files conflict.
+Treat README.md as public and developer overview, setup, usage, and user-facing context only when governance files conflict.
 
 ## Critical Bootstrap Floor
 
@@ -18,6 +18,7 @@ Treat README.md as overview/install/user context only when governance files conf
 - For UI scope, include a one-line Motion/Palette Decision in the Bootstrap Receipt; product categories are heuristics, not style presets.
 - For UI scope, create or refine `docs/DESIGN.md` and `docs/design-intent.json` before UI implementation.
 - For documentation-first requests, create or refine required project docs in English by default and do not write application, firmware, or UI code until the user asks or approves.
+- Create or refine root README.md as the public and developer entrypoint before implementation.
 - For backend, API, data, auth, error, event, queue, worker, or distributed-system requests, load only relevant global rules from .agent-context/rules/ ([link](.agent-context/rules)).
 - For ecosystem, framework, dependency, or Docker claims, perform live web research.
 - Resolve runtime choices from project evidence and live official documentation; resolve structural planning from constraints and architecture boundaries.