This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

This is Webtool 4.2 - the new release of the linguistic annotation and FrameNet management system.

This project uses Laravel Sail for containerized development. All PHP/Laravel commands run inside Docker containers.

Starting the Development Environment:

./vendor/bin/sail up -d        # Start all services in background
./vendor/bin/sail down          # Stop all services
./vendor/bin/sail restart       # Restart services

Recommended: Add Shell Alias

alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'

Vite runs outside Docker on your local machine for optimal performance:

• yarn dev - Start Vite development server with hot reload
• npm run dev - Alternative to yarn dev
• yarn install - Install Node.js dependencies
• npm run build - Build production assets

• sail artisan migrate - Run database migrations
• sail artisan tinker - Open interactive shell
• sail composer install - Install PHP dependencies
• sail test - Run tests
• sail shell - Access container bash shell
• sail redis - Access Redis CLI

• Laravel App: http://localhost:80 (APP_PORT=80)
• Redis: localhost:6379 (FORWARD_REDIS_PORT=6379)
• Reverb WebSocket: http://localhost:8080 (REVERB_PORT=8080)
• Vite Dev: http://localhost:5173 (VITE_PORT=5173)

External Services (not in Docker):

• MariaDB: Your existing database server (DB_HOST=host.docker.internal)
• Neo4J: Graph database if enabled (NEO4J_HOST=localhost)

See SAIL_SETUP.md for complete setup details.

This is a Laravel 12 application with a custom Query Builder that extends Laravel's capabilities for linguistic data management.

• app/ - Laravel application code
  • Http/Controllers/ - Route controllers using PHP attributes for routing
  • Services/ - Business logic layer for annotation, reports, and data processing
  • Data/ - Data transfer objects and form validation
  • Repositories/ - Data access layer abstractions
  • UI/ - User interface with Visual components and Blade template views
• resources/ - Frontend assets and Javascript app
• public/scripts/ - Third-party JavaScript libraries (jQuery EasyUI, JointJS, etc.)
• config/webtool.php - Application-specific configuration and menu structure

Uses a Laravel Authentication and Authorization classes. Can integrate with Auth0 for external authentication.

• Uses Laravel Blade templates with custom UI components
• Vite for asset compilation with LESS preprocessing
• Uses Fomantic-UI CSS components and AlpineJS libraries
• JointJS for graph visualizations (frame relations, semantic networks)
• HTMX for dynamic content updates

Database Schema (file database/webtool42_script.sql): The schema is designed around linguistic annotation and FrameNet concepts:

Core Linguistic Entities:

• frame - Semantic frames with multilingual descriptions
• frameelement - Frame elements (FEs) with coreness types and color coding
• construction - Grammatical constructions with abstract patterns
• constructionelement - Construction elements with constraints
• lu (Lexical Units) - Words that evoke frames
• lexicon - Lexical entries with morphological information

Annotation System:

• annotationset - Groups annotations for sentences/documents
• annotation - Individual annotations linking text spans to semantic elements
• staticobject - Static multimodal annotations (images)
• dynamicobject - Dynamic multimodal annotations (video)

Content Management:

• corpus - Text corpora organization
• document - Individual documents within corpora
• sentence - Sentence-level segmentation
• image/video - Multimodal content for annotation

User & Task Management:

• user - User accounts with authentication
• usertask - Task assignments for annotation projects
• user_group - Role-based access control

Semantic Relations:

• entityrelation - Generic relation framework
• relationtype - Types of semantic relations (inheritance, subframe, etc.)
• Views like view_frame_relation provide structured access to semantic networks

Key Views:

• view_* tables provide optimized queries for complex linguistic data relationships
• Include multilingual support and efficient access patterns for annotation interfaces

• Annotation Tools: Multiple annotation modes (static/dynamic, full-text, deixis, bounding boxes)
• Linguistic Data Management: Frames, constructions, lexical units, semantic types
• Visualization: Interactive graphs for semantic networks and frame relations
• Multimodal Support: Video and image annotation capabilities
• Export Systems: XML export with XSD validation for linguistic data interchange

Uses PHPUnit for testing. Run tests with vendor/bin/phpunit.

• Main app configuration in config/webtool.php
• Environment variables in .env file
• Database configuration supports multiple connections defined in config/database.php

• Framework Foundation: Uses Fomantic-UI (Semantic UI) as the primary CSS framework - maintain framework defaults for consistency, accessibility, and maintainability
• LESS-Based Styling: All customizations use LESS variables, not CSS custom properties
  • Primary theme customization: resources/css/fomantic-ui/site/globals/site.variables
  • Entity-specific colors: resources/css/colors/entities.less (frames, lexical units, frame elements, etc.)
  • Component styling: Organized in resources/css/components/ and resources/css/layout/
• Specialized Academic Context: Design should reflect the specialized nature of linguistic annotation tools while maintaining usability

• Respect Framework Patterns: Enhance Fomantic-UI components rather than replacing them
• Strategic Customization: Focus enhancements on domain-specific needs (linguistic notation, annotation workflows)
• Consistency First: Use established LESS variables and color schemes before creating new ones
• Accessibility: Maintain framework's built-in accessibility features when customizing

IMMEDIATELY after implementing any front-end change:

1. Identify what changed - Review the modified app/UI and resources folders
2. Navigate to affected pages - Use mcp__playwright__browser_navigate to visit each changed view
3. Verify framework consistency - Ensure changes work with Fomantic-UI patterns
4. Validate feature implementation - Ensure the change fulfills the user's specific request
5. Check LESS compilation - Verify custom variables compile correctly with framework
6. Capture evidence - Take full page screenshot at desktop viewport (1440px) of each changed view
7. Check for errors - Run mcp__playwright__browser_console_messages

This verification ensures changes meet design standards and maintain framework integrity.

Invoke the @agent-design-review subagent for thorough design validation when:

• Completing significant UI/UX features
• Before finalizing PRs with visual changes
• Needing comprehensive accessibility and responsiveness testing
• Evaluating framework customization approaches

===

The Laravel Boost guidelines are specifically curated by Laravel maintainers for this application. These guidelines should be followed closely to ensure the best experience when building Laravel applications.

This application is a Laravel application and its main Laravel ecosystems package & versions are below. You are an expert with them all. Ensure you abide by these specific packages & versions.

• php - 8.3.6
• laravel/framework (LARAVEL) - v12
• laravel/octane (OCTANE) - v2
• laravel/prompts (PROMPTS) - v0
• laravel/reverb (REVERB) - v1
• pestphp/pest (PEST) - v4
• phpunit/phpunit (PHPUNIT) - v12
• laravel/mcp (MCP) - v0
• laravel/pint (PINT) - v1
• laravel/sail (SAIL) - v1
• tailwindcss (TAILWINDCSS) - v3
• alpinejs (ALPINEJS) - v3
• laravel-echo (ECHO) - v1

This project has domain-specific skills available. You MUST activate the relevant skill whenever you work in that domain—don't wait until you're stuck.

• pest-testing — Tests applications using the Pest 4 PHP framework. Activates when writing tests, creating unit or feature tests, adding assertions, testing Livewire components, browser testing, debugging test failures, working with datasets or mocking; or when the user mentions test, spec, TDD, expects, assertion, coverage, or needs to verify functionality works.
• tailwindcss-development — Styles applications using Tailwind CSS v3 utilities. Activates when adding styles, restyling components, working with gradients, spacing, layout, flex, grid, responsive design, dark mode, colors, typography, or borders; or when the user mentions CSS, styling, classes, Tailwind, restyle, hero section, cards, buttons, or any visual/UI changes.

• You must follow all existing code conventions used in this application. When creating or editing a file, check sibling files for the correct structure, approach, and naming.
• Use descriptive names for variables and methods. For example, isRegisteredForDiscounts, not discount().
• Check for existing components to reuse before writing a new one.

• Do not create verification scripts or tinker when tests cover that functionality and prove they work. Unit and feature tests are more important.

• Stick to existing directory structure; don't create new base folders without approval.
• Do not change the application's dependencies without approval.

• If the user doesn't see a frontend change reflected in the UI, it could mean they need to run npm run build, npm run dev, or composer run dev. Ask them.

• You must only create documentation files if explicitly requested by the user.

• Be concise in your explanations - focus on what's important rather than explaining obvious details.

=== boost rules ===

• Laravel Boost is an MCP server that comes with powerful tools designed specifically for this application. Use them.

• Use the list-artisan-commands tool when you need to call an Artisan command to double-check the available parameters.

• Whenever you share a project URL with the user, you should use the get-absolute-url tool to ensure you're using the correct scheme, domain/IP, and port.

• You should use the tinker tool when you need to execute PHP to debug code or query Eloquent models directly.
• Use the database-query tool when you only need to read from the database.

• You can read browser logs, errors, and exceptions using the browser-logs tool from Boost.
• Only recent browser logs will be useful - ignore old logs.

• Boost comes with a powerful search-docs tool you should use before trying other approaches when working with Laravel or Laravel ecosystem packages. This tool automatically passes a list of installed packages and their versions to the remote Boost API, so it returns only version-specific documentation for the user's circumstance. You should pass an array of packages to filter on if you know you need docs for particular packages.
• Search the documentation before making code changes to ensure we are taking the correct approach.
• Use multiple, broad, simple, topic-based queries at once. For example: ['rate limiting', 'routing rate limiting', 'routing']. The most relevant results will be returned first.
• Do not add package names to queries; package information is already shared. For example, use test resource table, not filament 4 test resource table.

1. Simple Word Searches with auto-stemming - query=authentication - finds 'authenticate' and 'auth'.
2. Multiple Words (AND Logic) - query=rate limit - finds knowledge containing both "rate" AND "limit".
3. Quoted Phrases (Exact Position) - query="infinite scroll" - words must be adjacent and in that order.
4. Mixed Queries - query=middleware "rate limit" - "middleware" AND exact phrase "rate limit".
5. Multiple Queries - queries=["authentication", "middleware"] - ANY of these terms.

=== php rules ===

• Always use curly braces for control structures, even for single-line bodies.

• Use PHP 8 constructor property promotion in __construct().
  • public function __construct(public GitHub $github) { }
• Do not allow empty __construct() methods with zero parameters unless the constructor is private.

• Always use explicit return type declarations for methods and functions.
• Use appropriate PHP type hints for method parameters.

• Typically, keys in an Enum should be TitleCase. For example: FavoritePerson, BestLake, Monthly.

• Prefer PHPDoc blocks over inline comments. Never use comments within the code itself unless the logic is exceptionally complex.

• Add useful array shape type definitions when appropriate.

=== tests rules ===

• Every change must be programmatically tested. Write a new test or update an existing test, then run the affected tests to make sure they pass.
• Run the minimum number of tests needed to ensure code quality and speed. Use php artisan test --compact with a specific filename or filter.

=== laravel/core rules ===

• Use php artisan make: commands to create new files (i.e. migrations, controllers, models, etc.). You can list available Artisan commands using the list-artisan-commands tool.
• If you're creating a generic PHP class, use php artisan make:class.
• Pass --no-interaction to all Artisan commands to ensure they work without user input. You should also pass the correct --options to ensure correct behavior.

• Always use proper Eloquent relationship methods with return type hints. Prefer relationship methods over raw queries or manual joins.
• Use Eloquent models and relationships before suggesting raw database queries.
• Avoid DB::; prefer Model::query(). Generate code that leverages Laravel's ORM capabilities rather than bypassing them.
• Generate code that prevents N+1 query problems by using eager loading.
• Use Laravel's query builder for very complex database operations.

• When creating new models, create useful factories and seeders for them too. Ask the user if they need any other things, using list-artisan-commands to check the available options to php artisan make:model.

• For APIs, default to using Eloquent API Resources and API versioning unless existing API routes do not, then you should follow existing application convention.

• Always create Form Request classes for validation rather than inline validation in controllers. Include both validation rules and custom error messages.
• Check sibling Form Requests to see if the application uses array or string based validation rules.

• Use Laravel's built-in authentication and authorization features (gates, policies, Sanctum, etc.).

• When generating links to other pages, prefer named routes and the route() function.

• Use queued jobs for time-consuming operations with the ShouldQueue interface.

• Use environment variables only in configuration files - never use the env() function directly outside of config files. Always use config('app.name'), not env('APP_NAME').

• When creating models for tests, use the factories for the models. Check if the factory has custom states that can be used before manually setting up the model.
• Faker: Use methods such as $this->faker->word() or fake()->randomDigit(). Follow existing conventions whether to use $this->faker or fake().
• When creating tests, make use of php artisan make:test [options] {name} to create a feature test, and pass --unit to create a unit test. Most tests should be feature tests.

• If you receive an "Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest" error, you can run npm run build or ask the user to run npm run dev or composer run dev.

=== laravel/v12 rules ===

• CRITICAL: ALWAYS use search-docs tool for version-specific Laravel documentation and updated code examples.
• Since Laravel 11, Laravel has a new streamlined file structure which this project uses.

• In Laravel 12, middleware are no longer registered in app/Http/Kernel.php.
• Middleware are configured declaratively in bootstrap/app.php using Application::configure()->withMiddleware().
• bootstrap/app.php is the file to register middleware, exceptions, and routing files.
• bootstrap/providers.php contains application specific service providers.
• The app\Console\Kernel.php file no longer exists; use bootstrap/app.php or routes/console.php for console configuration.
• Console commands in app/Console/Commands/ are automatically available and do not require manual registration.

• When modifying a column, the migration must include all of the attributes that were previously defined on the column. Otherwise, they will be dropped and lost.
• Laravel 12 allows limiting eagerly loaded records natively, without external packages: $query->latest()->limit(10);.

• Casts can and likely should be set in a casts() method on a model rather than the $casts property. Follow existing conventions from other models.

=== pest/core rules ===

• This project uses Pest for testing. Create tests: php artisan make:test --pest {name}.
• Run tests: php artisan test --compact or filter: php artisan test --compact --filter=testName.
• Do NOT delete tests without approval.
• CRITICAL: ALWAYS use search-docs tool for version-specific Pest documentation and updated code examples.
• IMPORTANT: Activate pest-testing every time you're working with a Pest or testing-related task.

=== pint/core rules ===

• You must run vendor/bin/pint --dirty before finalizing changes to ensure your code matches the project's expected style.
• Do not run vendor/bin/pint --test, simply run vendor/bin/pint to fix any formatting issues.

=== tailwindcss/core rules ===

• Always use existing Tailwind conventions; check project patterns before adding new ones.
• IMPORTANT: Always use search-docs tool for version-specific Tailwind CSS documentation and updated code examples. Never rely on training data.
• IMPORTANT: Activate tailwindcss-development every time you're working with a Tailwind CSS or styling-related task.