@jaimevalasek/aioson 1.3.0

package/template/.aioson/skills/static/tall-stack-patterns.md

@@ -0,0 +1,286 @@
+# TALL Stack Patterns
+
+> Tailwind + Alpine.js + Livewire + Laravel. Full-stack PHP monolith done right.
+
+---
+
+## Architecture: what goes where
+
+```
+Livewire  → stateful server-side UI (forms, tables, modals, real-time updates)
+Alpine.js → lightweight client interactivity (toggles, dropdowns, local UI state)
+Tailwind  → all styling — never write custom CSS for layout or spacing
+Blade     → templating, layouts, shared components
+Flux UI   → pre-built component library — always check here first
+```
+
+**Rule:** If Alpine.js logic exceeds ~20 lines, move the state to Livewire.
+
+---
+
+## Livewire component structure
+
+```php
+// app/Livewire/Appointments/CreateForm.php
+class CreateForm extends Component
+{
+    public int $doctorId = 0;
+    public string $date = '';
+    public string $notes = '';
+
+    protected array $rules = [
+        'doctorId' => 'required|exists:doctors,id',
+        'date'     => 'required|date|after:today',
+        'notes'    => 'nullable|string|max:500',
+    ];
+
+    // Real-time validation on field change
+    public function updated(string $field): void
+    {
+        $this->validateOnly($field);
+    }
+
+    public function submit(): void
+    {
+        $this->validate();
+        $appointment = (new CreateAppointmentAction)->execute(
+            auth()->user(),
+            AppointmentData::from($this->only(['doctorId', 'date', 'notes']))
+        );
+        $this->dispatch('appointment-created', id: $appointment->id);
+        $this->reset(['doctorId', 'date', 'notes']);
+        session()->flash('success', 'Appointment booked.');
+    }
+
+    public function render(): View
+    {
+        return view('livewire.appointments.create-form', [
+            'doctors' => Doctor::orderBy('name')->get(),
+        ]);
+    }
+}
+```
+
+---
+
+## Livewire — inter-component events
+
+```php
+// Child dispatches
+$this->dispatch('appointment-created', id: $appointment->id);
+
+// Parent listens
+#[On('appointment-created')]
+public function refresh(): void
+{
+    $this->appointments = Appointment::withRelations()->latest()->paginate(20);
+}
+
+// Target a specific component
+$this->dispatch('refresh')->to(AppointmentList::class);
+```
+
+---
+
+## Livewire — lazy loading for expensive components
+
+```html
+<!-- Defer until visible in viewport -->
+<livewire:dashboard-stats lazy />
+```
+
+```php
+// Component shows skeleton while loading
+public function placeholder(): View
+{
+    return view('livewire.placeholders.stats-skeleton');
+}
+```
+
+---
+
+## Alpine.js — keep it lightweight
+
+Use Alpine for pure UI state that does not involve the server.
+
+```html
+<!-- Toggle visibility -->
+<div x-data="{ open: false }" @click.outside="open = false">
+    <button @click="open = !open">Options</button>
+    <div x-show="open" x-transition>
+        <a href="#">Edit</a>
+        <a href="#">Delete</a>
+    </div>
+</div>
+
+<!-- Confirm before destructive Livewire action -->
+<button
+    x-data
+    @click="if (confirm('Delete this appointment?')) $wire.delete({{ $appointment->id }})"
+    class="text-red-600 hover:underline"
+>
+    Delete
+</button>
+
+<!-- Copy to clipboard -->
+<div x-data="{ copied: false }">
+    <button @click="navigator.clipboard.writeText('{{ $link }}'); copied = true; setTimeout(() => copied = false, 2000)">
+        <span x-text="copied ? 'Copied!' : 'Copy link'"></span>
+    </button>
+</div>
+```
+
+---
+
+## Tailwind — design system discipline
+
+Always use Tailwind's spacing scale. Never use arbitrary values for standard spacing.
+
+```html
+<!-- WRONG -->
+<div class="p-[17px] mt-[22px] text-[15px]">
+
+<!-- RIGHT -->
+<div class="p-4 mt-6 text-sm">
+```
+
+Define tokens in `tailwind.config.js`:
+
+```js
+module.exports = {
+    theme: {
+        extend: {
+            colors: {
+                brand: { DEFAULT: '#4F46E5', dark: '#4338CA' },
+            },
+            spacing: {
+                sidebar: '280px',
+            },
+        },
+    },
+}
+```
+
+---
+
+## Flux UI — use before building custom
+
+```html
+<!-- Buttons -->
+<flux:button variant="primary">Save</flux:button>
+<flux:button variant="ghost" icon="trash">Delete</flux:button>
+<flux:button variant="danger" wire:click="delete" wire:loading.attr="disabled">
+    <wire:loading wire:target="delete">Deleting...</wire:loading>
+    <wire:loading.remove wire:target="delete">Delete</wire:loading.remove>
+</flux:button>
+
+<!-- Form inputs -->
+<flux:input wire:model.live="email" label="Email" type="email" />
+<flux:textarea wire:model="notes" label="Notes" rows="4" />
+<flux:select wire:model="doctorId" label="Doctor">
+    <flux:select.option value="">Select a doctor</flux:select.option>
+    @foreach ($doctors as $doctor)
+        <flux:select.option value="{{ $doctor->id }}">{{ $doctor->name }}</flux:select.option>
+    @endforeach
+</flux:select>
+
+<!-- Modal with confirmation -->
+<flux:modal name="confirm-delete">
+    <flux:heading>Delete appointment?</flux:heading>
+    <flux:text>This action cannot be undone.</flux:text>
+    <div class="flex gap-2 mt-4">
+        <flux:button variant="danger" wire:click="delete">Delete</flux:button>
+        <flux:modal.close>Cancel</flux:modal.close>
+    </div>
+</flux:modal>
+<flux:modal.trigger name="confirm-delete">
+    <flux:button variant="ghost" icon="trash">Delete</flux:button>
+</flux:modal.trigger>
+
+<!-- Table -->
+<flux:table>
+    <flux:columns>
+        <flux:column>Patient</flux:column>
+        <flux:column>Date</flux:column>
+        <flux:column>Status</flux:column>
+    </flux:columns>
+    <flux:rows>
+        @foreach ($appointments as $appointment)
+            <flux:row>
+                <flux:cell>{{ $appointment->patient->name }}</flux:cell>
+                <flux:cell>{{ $appointment->date->format('M d, Y H:i') }}</flux:cell>
+                <flux:cell><flux:badge>{{ $appointment->status }}</flux:badge></flux:cell>
+            </flux:row>
+        @endforeach
+    </flux:rows>
+</flux:table>
+```
+
+---
+
+## Blade layout structure
+
+```
+resources/views/
+  components/
+    layouts/
+      app.blade.php        ← authenticated shell (nav, sidebar)
+      guest.blade.php      ← public shell (centered, minimal)
+    ui/
+      card.blade.php       ← reusable card wrapper
+      empty-state.blade.php
+      page-header.blade.php
+  livewire/
+    appointments/
+      create-form.blade.php
+      list.blade.php
+    placeholders/
+      stats-skeleton.blade.php
+  pages/
+    appointments/
+      index.blade.php
+      show.blade.php
+```
+
+---
+
+## Performance
+
+```php
+// Always paginate Livewire lists — never ->get() on unbounded queries
+public function render(): View
+{
+    return view('livewire.appointments.list', [
+        'appointments' => Appointment::withRelations()
+            ->when($this->search, fn ($q) =>
+                $q->where('notes', 'like', "%{$this->search}%"))
+            ->latest()
+            ->paginate(20),
+    ]);
+}
+
+// Cache reference data with computed properties
+public function getDoctorsProperty(): Collection
+{
+    return Cache::remember('doctors.active', now()->addMinutes(5), fn () =>
+        Doctor::active()->orderBy('name')->get()
+    );
+}
+```
+
+---
+
+## ALWAYS
+- `wire:model.live` for real-time field validation
+- `$this->validateOnly($field)` in `updated()`
+- `#[On('event')]` for component communication
+- `paginate()` for all list queries
+- Flux UI components before custom Blade components
+- `x-transition` for smooth Alpine.js reveals
+
+## NEVER
+- Database queries in Blade templates
+- Alpine.js managing server state or API calls
+- `->get()` on unbounded Eloquent queries in Livewire
+- Custom CSS when a Tailwind utility exists
+- Unguarded public Livewire properties (validate everything)

package/template/.aioson/skills/static/ui-ux-modern.md

@@ -0,0 +1,75 @@
+# Modern UI/UX Guidelines
+
+## Goal
+Ship interfaces that feel intentional, modern, and production-ready without over-designing beyond project scope.
+
+## Core-Lite balance
+- Follow AIOS Core quality discipline (explicit decisions, consistency, UX clarity).
+- Keep AIOSON delivery lean (small scope, direct implementation guidance, low artifact overhead).
+
+## Core principles
+- Clarity before decoration: users should immediately understand the primary action.
+- One visual direction per product area: typography, color, and component density must be consistent.
+- Reuse before reinventing: prioritize existing stack UI libraries and primitives.
+- Accessibility is default, not optional.
+
+## Layout and hierarchy
+- Define a spacing scale (for example 4/8/12/16/24/32) and keep it consistent.
+- Keep a clear reading order:
+  1. Page intent
+  2. Primary action
+  3. Supporting data
+- Prefer shallow nesting in cards and panels to reduce cognitive load.
+
+## Typography and color
+- Use a predictable type scale with clear role mapping:
+  - page title
+  - section title
+  - body
+  - helper/meta text
+- Keep contrast high for critical text and controls.
+- Use semantic color roles (primary/success/warning/danger/info) instead of arbitrary one-off colors.
+
+## Component quality checklist
+For every major component, define:
+- default state
+- hover/focus/active/disabled states
+- loading skeleton/spinner behavior
+- empty state
+- error state with recovery action
+- success confirmation when relevant
+
+## Forms and validation
+- Put labels outside placeholders (placeholders are hints, not labels).
+- Validate as early as possible without being noisy.
+- Show inline field errors and one global summary for multi-field failures.
+- Disable destructive actions while submitting and show progress feedback.
+
+## Responsive behavior
+- Design mobile-first, then scale up.
+- Ensure key actions are reachable with one hand on mobile.
+- Avoid dense tables on small screens; use stacked cards or summary rows.
+
+## Accessibility baseline
+- Semantic HTML and proper landmarks.
+- Full keyboard navigation and visible focus states.
+- Click/tap targets large enough for touch.
+- Meaning not conveyed by color alone.
+
+## Motion and feedback
+- Use motion to clarify transitions, not as decoration.
+- Keep transitions short and consistent.
+- Avoid blocking animations for critical workflows.
+
+## Stack-specific guidance
+- Laravel + TALL: prefer Livewire + Alpine patterns and existing Blade components.
+- Filament admin: prefer Resources and built-in actions before custom UI.
+- Flux UI: use Flux primitives first and keep custom wrappers minimal.
+- Next.js/React: keep component boundaries clean and avoid unnecessary client state.
+
+## Handoff quality
+When passing to implementation:
+- provide component mapping to real library components
+- include state matrix (loading/empty/error/success/permission)
+- include responsive and accessibility notes
+- keep the spec concise enough for direct coding

package/template/.aioson/skills/static/web3-cardano-patterns.md

@@ -0,0 +1,337 @@
+# Web3 Cardano Patterns
+
+> eUTxO model, Aiken validators, and off-chain transaction building. Think in UTxOs, not accounts.
+
+---
+
+## The eUTxO model — mental model first
+
+Cardano uses the **Extended UTxO (eUTxO)** model. Before writing any validator, understand:
+
+```
+UTxO (Unspent Transaction Output):
+  ├── Address      → who can spend it (public key or script hash)
+  ├── Value        → ADA + any native tokens
+  └── Datum        → arbitrary data attached to a script UTxO
+
+Transaction:
+  ├── Inputs       → UTxOs being consumed (destroyed)
+  ├── Outputs      → new UTxOs being created
+  ├── Redeemer     → data provided to the validator when spending a script UTxO
+  └── Validity     → time range, signatures, mint/burn
+
+Validator:
+  → A Plutus/Aiken script that decides if a UTxO can be spent
+  → Receives: Datum, Redeemer, ScriptContext
+  → Returns: True (allow) or raises error (deny)
+```
+
+**Key difference from Ethereum:** State is not stored in the contract — it is stored in UTxOs sitting at the script address. The validator only validates whether a spend is legitimate.
+
+---
+
+## Aiken project structure
+
+```
+lib/
+  validators/
+    marketplace.ak      ← spending validator
+    minting.ak          ← minting policy
+  utils/
+    math.ak
+    value.ak
+  types.ak              ← shared type definitions
+validators/
+  marketplace.ak        ← entry points (must be here for compilation)
+  minting.ak
+tests/
+  marketplace_test.ak
+  minting_test.ak
+scripts/
+  build.sh
+  deploy.sh
+aiken.toml
+```
+
+---
+
+## Types — define datum and redeemer first
+
+```rust
+// lib/types.ak
+pub type AssetClass {
+    policy_id: ByteArray,
+    asset_name: ByteArray,
+}
+
+pub type ListingDatum {
+    seller: VerificationKeyHash,
+    price_lovelace: Int,
+    royalty_recipient: VerificationKeyHash,
+    royalty_bps: Int,          // basis points: 100 = 1%, max 1000
+    asset: AssetClass,
+}
+
+pub type MarketplaceRedeemer {
+    Buy
+    Cancel
+    UpdatePrice { new_price: Int }
+}
+```
+
+---
+
+## Spending validator
+
+```rust
+// validators/marketplace.ak
+use aiken/transaction.{ScriptContext, Spend, Transaction}
+use aiken/transaction/credential.{VerificationKeyHash}
+use aiken/transaction/value
+use lib/types.{ListingDatum, MarketplaceRedeemer}
+
+// Constants
+const max_royalty_bps: Int = 1000  // 10%
+
+validator {
+    fn marketplace(
+        datum: ListingDatum,
+        redeemer: MarketplaceRedeemer,
+        ctx: ScriptContext
+    ) -> Bool {
+        when redeemer is {
+            Buy -> {
+                let tx = ctx.transaction
+                validate_purchase(datum, tx)
+            }
+            Cancel -> {
+                // Only seller can cancel
+                must_be_signed_by(ctx.transaction, datum.seller)
+            }
+            UpdatePrice { new_price } -> {
+                and {
+                    must_be_signed_by(ctx.transaction, datum.seller),
+                    new_price > 0,
+                }
+            }
+        }
+    }
+}
+
+fn validate_purchase(datum: ListingDatum, tx: Transaction) -> Bool {
+    // Validate royalty does not exceed maximum
+    expect datum.royalty_bps <= max_royalty_bps
+
+    let royalty_amount = datum.price_lovelace * datum.royalty_bps / 10000
+    let seller_amount = datum.price_lovelace - royalty_amount
+
+    and {
+        // Seller receives their share
+        output_to_address_has_value(tx, datum.seller, seller_amount),
+        // Royalty recipient receives their share (if any)
+        if royalty_amount > 0 {
+            output_to_address_has_value(tx, datum.royalty_recipient, royalty_amount)
+        } else {
+            True
+        },
+    }
+}
+
+fn output_to_address_has_value(
+    tx: Transaction,
+    recipient: VerificationKeyHash,
+    min_lovelace: Int
+) -> Bool {
+    list.any(tx.outputs, fn(output) {
+        when output.address.payment_credential is {
+            credential.VerificationKey(vk_hash) ->
+                vk_hash == recipient &&
+                value.lovelace_of(output.value) >= min_lovelace
+            _ -> False
+        }
+    })
+}
+
+fn must_be_signed_by(tx: Transaction, vk_hash: VerificationKeyHash) -> Bool {
+    list.has(tx.extra_signatories, vk_hash)
+}
+```
+
+---
+
+## Minting policy
+
+```rust
+// validators/minting.ak
+use aiken/transaction.{ScriptContext, Mint}
+use aiken/transaction/value
+
+pub type MintRedeemer {
+    Mint { recipient: VerificationKeyHash }
+    Burn
+}
+
+validator {
+    fn nft_policy(redeemer: MintRedeemer, ctx: ScriptContext) -> Bool {
+        when ctx.purpose is {
+            Mint(policy_id) -> {
+                when redeemer is {
+                    Mint { recipient } -> {
+                        let tx = ctx.transaction
+                        // Exactly one token minted with this policy
+                        let minted = value.tokens(tx.mint, policy_id)
+                        expect list.length(dict.to_list(minted)) == 1
+
+                        // Transaction signed by recipient
+                        must_be_signed_by(tx, recipient)
+                    }
+                    Burn -> {
+                        // Validate burning: all minted amounts are negative
+                        let minted = value.tokens(ctx.transaction.mint, policy_id)
+                        list.all(dict.values(minted), fn(qty) { qty < 0 })
+                    }
+                }
+            }
+            _ -> False
+        }
+    }
+}
+```
+
+---
+
+## Tests in Aiken
+
+```rust
+// tests/marketplace_test.ak
+use lib/types.{ListingDatum, MarketplaceRedeemer}
+
+test royalty_must_not_exceed_maximum() {
+    let datum = ListingDatum {
+        seller: #"abcd1234",
+        price_lovelace: 10_000_000,
+        royalty_recipient: #"efgh5678",
+        royalty_bps: 1001,  // 10.01% — should FAIL
+        asset: AssetClass { policy_id: #"", asset_name: #"" },
+    }
+    // Test that validator rejects this datum
+    !validate_purchase(datum, mock_buy_transaction())
+}
+
+test seller_receives_correct_amount() {
+    let datum = ListingDatum {
+        seller: #"abcd1234",
+        price_lovelace: 10_000_000,  // 10 ADA
+        royalty_recipient: #"efgh5678",
+        royalty_bps: 300,             // 3% = 300_000 lovelace
+        asset: AssetClass { policy_id: #"", asset_name: #"" },
+    }
+    // Seller should receive 9_700_000 lovelace (97%)
+    let expected_seller_amount = 9_700_000
+    validate_purchase(datum, mock_buy_with_outputs(datum.seller, expected_seller_amount))
+}
+```
+
+Run tests: `aiken check`
+
+---
+
+## Off-chain transaction building (Lucid or Mesh)
+
+```ts
+// scripts/list-nft.ts — using Lucid
+import { Lucid, Blockfrost, fromText, Data } from 'lucid-cardano';
+import { ListingDatum } from './types';
+
+const lucid = await Lucid.new(
+    new Blockfrost('https://cardano-mainnet.blockfrost.io/api/v0', process.env.BLOCKFROST_API_KEY!),
+    'Mainnet'
+);
+
+lucid.selectWalletFromPrivateKey(process.env.SELLER_KEY!);
+
+async function listNFT(
+    policyId: string,
+    assetName: string,
+    priceLovelace: bigint,
+    royaltyBps: number
+) {
+    const sellerAddress = await lucid.wallet.address();
+    const datum: ListingDatum = {
+        seller: lucid.utils.getAddressDetails(sellerAddress).paymentCredential!.hash,
+        price_lovelace: priceLovelace,
+        royalty_recipient: lucid.utils.getAddressDetails(sellerAddress).paymentCredential!.hash,
+        royalty_bps: royaltyBps,
+        asset: { policy_id: policyId, asset_name: fromText(assetName) },
+    };
+
+    const tx = await lucid.newTx()
+        .payToContract(
+            MARKETPLACE_SCRIPT_ADDRESS,
+            { inline: Data.to(datum, ListingDatum) },
+            { [policyId + fromText(assetName)]: 1n }
+        )
+        .complete();
+
+    const signedTx = await tx.sign().complete();
+    const txHash = await signedTx.submit();
+    console.log(`Listed NFT. Tx hash: ${txHash}`);
+    return txHash;
+}
+```
+
+---
+
+## Datum versioning — plan before deploying
+
+```rust
+// Version your datum from day one — cannot change on-chain data after deployment
+pub type DatumV1 {
+    seller: VerificationKeyHash,
+    price_lovelace: Int,
+}
+
+// Future version — add new fields, keep old validator working
+pub type DatumV2 {
+    seller: VerificationKeyHash,
+    price_lovelace: Int,
+    royalty_bps: Int,         // new in V2
+    royalty_recipient: Option<VerificationKeyHash>,
+}
+
+// Validator supports both versions via union type
+pub type AnyDatum {
+    V1(DatumV1)
+    V2(DatumV2)
+}
+```
+
+---
+
+## Deployment checklist
+
+- [ ] Compile: `aiken build` — no warnings
+- [ ] Tests pass: `aiken check`
+- [ ] Script hash documented in `docs/deployment.md`
+- [ ] Datum/redeemer schemas versioned
+- [ ] Off-chain code tested against preview testnet
+- [ ] `min-ada` calculation verified for all output types
+- [ ] Transaction fee estimates verified with realistic UTxO sizes
+- [ ] Emergency cancel mechanism exists for stuck UTxOs
+
+---
+
+## ALWAYS
+- Design datum and redeemer types before writing validator logic
+- Store the script hash in deployment notes — cannot recover it otherwise
+- Test with `aiken check` before any on-chain deployment
+- Use `must_be_signed_by` for any privileged action
+- Plan datum versioning from day one
+- Calculate `min-ada` requirements for outputs with tokens/datums
+
+## NEVER
+- Deploy a validator you haven't tested with edge-case redeemers
+- Store secrets or private keys in datum (all on-chain data is public)
+- Assume UTxO values — always check with `value.lovelace_of()`
+- Forget that failed validator = UTxO locked forever (no admin override)
+- Use `expect` in production validators without understanding it causes script failure