@cubis/foundry 0.3.10

package/Ai Agent Workflow/skills/gorouter-restoration/references/guard_patterns.md

@@ -0,0 +1,37 @@
+# Guard patterns (safe redirects)
+
+## Hard rules
+
+- Keep guard logic synchronous, pure, and deterministic.
+- Do not trigger side effects in `onEnter`/`redirect`.
+- Ensure guards are idempotent for repeated router reevaluation.
+- Always protect against redirect loops.
+
+## Evaluation order
+
+1. `onEnter`
+2. Top-level `GoRouter.redirect`
+3. Route-level `GoRoute.redirect`
+
+Each stage should either:
+- return `null` (allow), or
+- return one stable target path.
+
+## Baseline decision set
+
+- If activation is incomplete, redirect to activation route (allow activation route).
+- If unauthenticated on protected route, redirect to login with `from=` query.
+- If authenticated user visits login/activation, redirect to app home.
+- If maintenance mode is enabled, redirect to maintenance except allowlisted routes.
+
+## Loop prevention checks
+
+- Compare target against current `matchedLocation` before redirecting.
+- Keep route allowlists explicit.
+- Set and monitor `redirectLimit` for complex chains.
+
+## Deep-link safety
+
+- Preserve original destination via encoded `from`.
+- Validate required params (path/query) before entering protected detail routes.
+- Redirect invalid params to a safe fallback (`/not-found` or list route).

package/Ai Agent Workflow/skills/gorouter-restoration/references/tab_preservation.md

@@ -0,0 +1,26 @@
+# Tab preservation & state restoration
+
+## Recommended architecture
+
+- Use `StatefulShellRoute.indexedStack` for bottom tabs.
+- Give each branch its own `navigatorKey`.
+- Keep shell widget stable so tab switch does not rebuild branch roots.
+
+## What to preserve
+
+- active tab index,
+- each tab's navigation stack,
+- long lists scroll position where needed,
+- in-progress form drafts when required.
+
+## Restoration guidance
+
+- Enable app restoration via both `GoRouter(restorationScopeId: 'router', ...)` and `MaterialApp.router(restorationScopeId: 'app', ...)`.
+- Use `RestorationMixin` for page-local restorable state.
+- Keep critical unsaved drafts in explicit state (provider/local DB) instead of only widget memory.
+
+## Anti-patterns
+
+- Single navigator for all tabs when independent stacks are required.
+- Recreating shell/router on every auth or theme change.
+- Storing heavy objects in route extras when ID lookup is sufficient.

package/Ai Agent Workflow/skills/gorouter-restoration/steering/guard_patterns.md

@@ -0,0 +1,37 @@
+# Guard patterns (safe redirects)
+
+## Hard rules
+
+- Keep guard logic synchronous, pure, and deterministic.
+- Do not trigger side effects in `onEnter`/`redirect`.
+- Ensure guards are idempotent for repeated router reevaluation.
+- Always protect against redirect loops.
+
+## Evaluation order
+
+1. `onEnter`
+2. Top-level `GoRouter.redirect`
+3. Route-level `GoRoute.redirect`
+
+Each stage should either:
+- return `null` (allow), or
+- return one stable target path.
+
+## Baseline decision set
+
+- If activation is incomplete, redirect to activation route (allow activation route).
+- If unauthenticated on protected route, redirect to login with `from=` query.
+- If authenticated user visits login/activation, redirect to app home.
+- If maintenance mode is enabled, redirect to maintenance except allowlisted routes.
+
+## Loop prevention checks
+
+- Compare target against current `matchedLocation` before redirecting.
+- Keep route allowlists explicit.
+- Set and monitor `redirectLimit` for complex chains.
+
+## Deep-link safety
+
+- Preserve original destination via encoded `from`.
+- Validate required params (path/query) before entering protected detail routes.
+- Redirect invalid params to a safe fallback (`/not-found` or list route).

package/Ai Agent Workflow/skills/gorouter-restoration/steering/tab_preservation.md

@@ -0,0 +1,26 @@
+# Tab preservation & state restoration
+
+## Recommended architecture
+
+- Use `StatefulShellRoute.indexedStack` for bottom tabs.
+- Give each branch its own `navigatorKey`.
+- Keep shell widget stable so tab switch does not rebuild branch roots.
+
+## What to preserve
+
+- active tab index,
+- each tab's navigation stack,
+- long lists scroll position where needed,
+- in-progress form drafts when required.
+
+## Restoration guidance
+
+- Enable app restoration via both `GoRouter(restorationScopeId: 'router', ...)` and `MaterialApp.router(restorationScopeId: 'app', ...)`.
+- Use `RestorationMixin` for page-local restorable state.
+- Keep critical unsaved drafts in explicit state (provider/local DB) instead of only widget memory.
+
+## Anti-patterns
+
+- Single navigator for all tabs when independent stacks are required.
+- Recreating shell/router on every auth or theme change.
+- Storing heavy objects in route extras when ID lookup is sufficient.

package/Ai Agent Workflow/skills/gorouter-restoration/templates/guard_redirect.md

@@ -0,0 +1,33 @@
+```
+// templates/guard_redirect.tmpl
+// Keep redirect logic pure and side-effect free.
+
+String? redirectLogic({
+  required bool isAuthenticated,
+  required bool activationDone,
+  required bool maintenanceMode,
+  required String matchedLocation,
+  Set<String> maintenanceAllowlist = const {'/maintenance'},
+}) {
+  final isLogin = matchedLocation == '/login';
+  final isActivation = matchedLocation == '/activation';
+
+  if (maintenanceMode && !maintenanceAllowlist.contains(matchedLocation)) {
+    return '/maintenance';
+  }
+
+  if (!activationDone && !isActivation) {
+    return '/activation';
+  }
+
+  if (activationDone && !isAuthenticated && !isLogin) {
+    return '/login?from=${Uri.encodeComponent(matchedLocation)}';
+  }
+
+  if (isAuthenticated && (isLogin || isActivation)) {
+    return '/home';
+  }
+
+  return null;
+}
+```

package/Ai Agent Workflow/skills/gorouter-restoration/templates/stateful_shell_skeleton.md

@@ -0,0 +1,40 @@
+```
+// templates/stateful_shell_skeleton.tmpl
+// Skeleton for tab preservation using StatefulShellRoute.indexedStack.
+
+final _rootKey = GlobalKey<NavigatorState>();
+final _homeKey = GlobalKey<NavigatorState>();
+final _salesKey = GlobalKey<NavigatorState>();
+final _settingsKey = GlobalKey<NavigatorState>();
+
+final router = GoRouter(
+  navigatorKey: _rootKey,
+  restorationScopeId: 'router',
+  routes: [
+    StatefulShellRoute.indexedStack(
+      restorationScopeId: 'appShell',
+      pageBuilder: (context, state, navigationShell) => MaterialPage(
+        restorationId: 'appShellPage',
+        child: AppShell(navigationShell: navigationShell),
+      ),
+      branches: [
+        StatefulShellBranch(
+          navigatorKey: _homeKey,
+          restorationScopeId: 'homeBranch',
+          routes: [GoRoute(path: '/home', builder: (c, s) => const HomeView())],
+        ),
+        StatefulShellBranch(
+          navigatorKey: _salesKey,
+          restorationScopeId: 'salesBranch',
+          routes: [GoRoute(path: '/sales', builder: (c, s) => const SalesView())],
+        ),
+        StatefulShellBranch(
+          navigatorKey: _settingsKey,
+          restorationScopeId: 'settingsBranch',
+          routes: [GoRoute(path: '/settings', builder: (c, s) => const SettingsView())],
+        ),
+      ],
+    ),
+  ],
+);
+```

package/Ai Agent Workflow/skills/graphql-architect/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: graphql-architect
+description: Use when designing GraphQL schemas, implementing Apollo Federation, or building real-time subscriptions. Invoke for schema design, resolvers with DataLoader, query optimization, federation directives.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.0.0"
+  domain: api-architecture
+  triggers: GraphQL, Apollo Federation, GraphQL schema, API graph, GraphQL subscriptions, Apollo Server, schema design, GraphQL resolvers, DataLoader
+  role: architect
+  scope: design
+  output-format: schema
+  related-skills: api-designer, microservices-architect, database-optimizer
+---
+
+# GraphQL Architect
+
+Senior GraphQL architect specializing in schema design and distributed graph architectures with deep expertise in Apollo Federation 2.5+, GraphQL subscriptions, and performance optimization.
+
+## Role Definition
+
+You are a senior GraphQL architect with 10+ years of API design experience. You specialize in Apollo Federation, schema-first design, and building type-safe API graphs that scale across teams and services. You master resolvers, DataLoader patterns, and real-time subscriptions.
+
+## When to Use This Skill
+
+- Designing GraphQL schemas and type systems
+- Implementing Apollo Federation architectures
+- Building resolvers with DataLoader optimization
+- Creating real-time GraphQL subscriptions
+- Optimizing query complexity and performance
+- Setting up authentication and authorization
+
+## Core Workflow
+
+1. **Domain Modeling** - Map business domains to GraphQL type system
+2. **Design Schema** - Create types, interfaces, unions with federation directives
+3. **Implement Resolvers** - Write efficient resolvers with DataLoader patterns
+4. **Secure** - Add query complexity limits, depth limiting, field-level auth
+5. **Optimize** - Performance tune with caching, persisted queries, monitoring
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Schema Design | `references/schema-design.md` | Types, interfaces, unions, enums, input types |
+| Resolvers | `references/resolvers.md` | Resolver patterns, context, DataLoader, N+1 |
+| Federation | `references/federation.md` | Apollo Federation, subgraphs, entities, directives |
+| Subscriptions | `references/subscriptions.md` | Real-time updates, WebSocket, pub/sub patterns |
+| Security | `references/security.md` | Query depth, complexity analysis, authentication |
+| REST Migration | `references/migration-from-rest.md` | Migrating REST APIs to GraphQL |
+
+## Constraints
+
+### MUST DO
+- Use schema-first design approach
+- Implement proper nullable field patterns
+- Use DataLoader for batching and caching
+- Add query complexity analysis
+- Document all types and fields
+- Follow GraphQL naming conventions (camelCase)
+- Use federation directives correctly
+- Provide example queries for all operations
+
+### MUST NOT DO
+- Create N+1 query problems
+- Skip query depth limiting
+- Expose internal implementation details
+- Use REST patterns in GraphQL
+- Return null for non-nullable fields
+- Skip error handling in resolvers
+- Hardcode authorization logic
+- Ignore schema validation
+
+## Output Templates
+
+When implementing GraphQL features, provide:
+1. Schema definition (SDL with types and directives)
+2. Resolver implementation (with DataLoader patterns)
+3. Query/mutation/subscription examples
+4. Brief explanation of design decisions
+
+## Knowledge Reference
+
+Apollo Server, Apollo Federation 2.5+, GraphQL SDL, DataLoader, GraphQL Subscriptions, WebSocket, Redis pub/sub, schema composition, query complexity, persisted queries, schema stitching, type generation

package/Ai Agent Workflow/skills/graphql-architect/references/federation.md

@@ -0,0 +1,418 @@
+# Apollo Federation
+
+## Subgraph Setup
+
+```typescript
+// users-subgraph/schema.graphql
+extend schema
+  @link(url: "https://specs.apollo.dev/federation/v2.5", import: ["@key", "@shareable"])
+
+type User @key(fields: "id") {
+  id: ID!
+  email: String!
+  username: String!
+  createdAt: DateTime!
+}
+
+type Query {
+  user(id: ID!): User
+  users: [User!]!
+}
+
+// users-subgraph/resolvers.ts
+import { ApolloServer } from '@apollo/server';
+import { buildSubgraphSchema } from '@apollo/subgraph';
+import { readFileSync } from 'fs';
+
+const typeDefs = readFileSync('./schema.graphql', 'utf8');
+
+const resolvers = {
+  User: {
+    __resolveReference: async (
+      reference: { id: string },
+      context: Context
+    ): Promise<User> => {
+      return context.dataSources.users.findById(reference.id);
+    },
+  },
+
+  Query: {
+    user: async (parent, args: { id: string }, context: Context) => {
+      return context.dataSources.users.findById(args.id);
+    },
+    users: async (parent, args, context: Context) => {
+      return context.dataSources.users.findAll();
+    },
+  },
+};
+
+const server = new ApolloServer({
+  schema: buildSubgraphSchema([{ typeDefs, resolvers }]),
+});
+```
+
+## Entity Keys and References
+
+```graphql
+# products-subgraph/schema.graphql
+extend schema
+  @link(url: "https://specs.apollo.dev/federation/v2.5", import: [
+    "@key",
+    "@shareable",
+    "@interfaceObject"
+  ])
+
+# Single key field
+type Product @key(fields: "id") {
+  id: ID!
+  name: String!
+  price: Float!
+  sku: String! @shareable
+}
+
+# Composite key
+type Variant @key(fields: "productId sku") {
+  productId: ID!
+  sku: String!
+  size: String!
+  color: String!
+}
+
+# Multiple keys (different ways to identify)
+type Review @key(fields: "id") @key(fields: "productId authorId") {
+  id: ID!
+  productId: ID!
+  authorId: ID!
+  rating: Int!
+  content: String!
+}
+```
+
+## Extending Types Across Subgraphs
+
+```graphql
+# users-subgraph: owns User
+type User @key(fields: "id") {
+  id: ID!
+  email: String!
+  username: String!
+}
+
+# posts-subgraph: extends User with posts
+extend type User @key(fields: "id") {
+  id: ID! @external
+  posts: [Post!]!
+}
+
+type Post @key(fields: "id") {
+  id: ID!
+  title: String!
+  content: String!
+  authorId: ID!
+  author: User!
+}
+```
+
+```typescript
+// posts-subgraph/resolvers.ts
+const resolvers = {
+  User: {
+    // Reference resolver: fetch User stub by id
+    __resolveReference: async (
+      reference: { id: string },
+      context: Context
+    ) => {
+      return { id: reference.id };
+    },
+
+    // Field resolver: resolve posts for User
+    posts: async (user: { id: string }, args, context: Context) => {
+      return context.dataSources.posts.findByAuthor(user.id);
+    },
+  },
+
+  Post: {
+    // Resolve author as User entity reference
+    author: (post: Post) => {
+      return { __typename: 'User', id: post.authorId };
+    },
+  },
+};
+```
+
+## Federation Directives
+
+```graphql
+extend schema
+  @link(url: "https://specs.apollo.dev/federation/v2.5", import: [
+    "@key",
+    "@requires",
+    "@provides",
+    "@external",
+    "@shareable",
+    "@override",
+    "@inaccessible",
+    "@tag"
+  ])
+
+# @key: Define entity with primary key
+type Product @key(fields: "id") {
+  id: ID!
+  name: String!
+}
+
+# @external: Field defined in another subgraph
+extend type User @key(fields: "id") {
+  id: ID! @external
+  email: String! @external
+  isVerified: Boolean! @external
+}
+
+# @requires: Field needs external data
+extend type User @key(fields: "id") {
+  id: ID! @external
+  email: String! @external
+  isVerified: Boolean! @external
+  # Can only compute if we have email and isVerified
+  canPost: Boolean! @requires(fields: "email isVerified")
+}
+
+# @provides: Optimization hint
+type Post @key(fields: "id") {
+  id: ID!
+  author: User! @provides(fields: "username")
+}
+
+# @shareable: Field can be resolved by multiple subgraphs
+type Product @key(fields: "id") {
+  id: ID!
+  sku: String! @shareable
+  name: String!
+}
+
+# @override: Migration between subgraphs
+type Product @key(fields: "id") {
+  id: ID!
+  # Override from legacy-subgraph
+  price: Float! @override(from: "legacy-subgraph")
+}
+
+# @inaccessible: Hide from supergraph
+type User @key(fields: "id") {
+  id: ID!
+  email: String!
+  internalId: String! @inaccessible
+}
+
+# @tag: Organize schema
+type Query {
+  products: [Product!]! @tag(name: "public")
+  adminUsers: [User!]! @tag(name: "admin")
+}
+```
+
+## Gateway Configuration
+
+```typescript
+// gateway/server.ts
+import { ApolloGateway, IntrospectAndCompose } from '@apollo/gateway';
+import { ApolloServer } from '@apollo/server';
+
+const gateway = new ApolloGateway({
+  supergraphSdl: new IntrospectAndCompose({
+    subgraphs: [
+      { name: 'users', url: 'http://localhost:4001/graphql' },
+      { name: 'posts', url: 'http://localhost:4002/graphql' },
+      { name: 'products', url: 'http://localhost:4003/graphql' },
+    ],
+    // Poll for schema updates
+    pollIntervalInMs: 10000,
+  }),
+
+  // Error handling
+  serviceHealthCheck: true,
+
+  // Query planning debug
+  debug: process.env.NODE_ENV === 'development',
+});
+
+const server = new ApolloServer({
+  gateway,
+
+  // Context propagation to subgraphs
+  context: async ({ req }) => {
+    const token = req.headers.authorization || '';
+    return { token };
+  },
+});
+
+await server.listen(4000);
+console.log('Gateway ready at http://localhost:4000');
+```
+
+## Managed Federation (Apollo Studio)
+
+```typescript
+// gateway/server.ts with managed federation
+import { ApolloGateway } from '@apollo/gateway';
+import { ApolloServer } from '@apollo/server';
+
+const gateway = new ApolloGateway({
+  // No subgraph URLs needed - fetched from Apollo Studio
+  // Schema composition happens in Apollo Studio
+  async supergraphSdl({ update }) {
+    // Fetch from Apollo Uplink
+    const supergraphSdl = await fetchSupergraphSdl();
+    return {
+      supergraphSdl,
+      cleanup: async () => {},
+    };
+  },
+});
+
+// Subgraph reporting to Apollo Studio
+import { ApolloServerPluginInlineTrace } from '@apollo/server/plugin/inlineTrace';
+
+const subgraphServer = new ApolloServer({
+  schema: buildSubgraphSchema([{ typeDefs, resolvers }]),
+  plugins: [
+    ApolloServerPluginInlineTrace(),
+  ],
+});
+```
+
+## Value Types vs Entities
+
+```graphql
+# Value type: no @key, resolved entirely by one subgraph
+type Address {
+  street: String!
+  city: String!
+  country: String!
+  postalCode: String!
+}
+
+# Entity: has @key, can be extended by other subgraphs
+type User @key(fields: "id") {
+  id: ID!
+  email: String!
+  # Value type embedded in entity
+  address: Address
+}
+
+# Another subgraph can extend User but not Address
+extend type User @key(fields: "id") {
+  id: ID! @external
+  orders: [Order!]!
+}
+```
+
+## Interface Objects
+
+```graphql
+# accounts-subgraph
+type User implements Account @key(fields: "id") {
+  id: ID!
+  email: String!
+  role: String!
+}
+
+type AdminUser implements Account @key(fields: "id") {
+  id: ID!
+  email: String!
+  role: String!
+  permissions: [String!]!
+}
+
+interface Account {
+  id: ID!
+  email: String!
+  role: String!
+}
+
+# orders-subgraph (doesn't know about User/AdminUser)
+extend schema @link(url: "https://specs.apollo.dev/federation/v2.5", import: ["@key", "@interfaceObject"])
+
+type Order @key(fields: "id") {
+  id: ID!
+  account: Account!
+}
+
+# Use @interfaceObject to reference Account without knowing implementations
+type Account @key(fields: "id") @interfaceObject {
+  id: ID!
+}
+```
+
+## Query Planning Optimization
+
+```graphql
+# Inefficient: requires multiple roundtrips
+type Query {
+  user(id: ID!): User
+}
+
+type User @key(fields: "id") {
+  id: ID!
+  posts: [Post!]!
+}
+
+extend type Post @key(fields: "id") {
+  id: ID! @external
+  author: User!
+}
+
+# Better: provide data to avoid extra fetch
+type Post @key(fields: "id") {
+  id: ID!
+  authorId: ID!
+  # Optimization: provide username directly
+  author: User! @provides(fields: "username")
+}
+
+# Gateway can fulfill some User fields from Post subgraph
+# without fetching from User subgraph
+```
+
+## Error Handling in Federation
+
+```typescript
+const resolvers = {
+  User: {
+    __resolveReference: async (
+      reference: { id: string },
+      context: Context
+    ) => {
+      try {
+        const user = await context.dataSources.users.findById(reference.id);
+        if (!user) {
+          // Return null for missing entity (soft error)
+          return null;
+        }
+        return user;
+      } catch (error) {
+        // Hard error propagates to client
+        throw new GraphQLError('Failed to resolve user', {
+          extensions: {
+            code: 'USER_RESOLUTION_FAILED',
+            userId: reference.id,
+          },
+        });
+      }
+    },
+  },
+};
+```
+
+## Federation Best Practices
+
+1. **Entity Design**: Use @key for types that need to be extended
+2. **Subgraph Boundaries**: Align with team/service boundaries
+3. **Shared Types**: Use @shareable for truly shared fields
+4. **Migration**: Use @override for gradual subgraph migration
+5. **Performance**: Use @provides to optimize query planning
+6. **Value Types**: Use plain types for embedded data
+7. **Composition**: Test schema composition in CI/CD
+8. **Versioning**: Use managed federation for safe deployments
+9. **Monitoring**: Track query planning and resolver performance
+10. **Documentation**: Document entity ownership and extension patterns