opensoma 0.1.0

package/skills/opensoma/SKILL.md

@@ -0,0 +1,345 @@
+---
+name: opensoma
+description: Interact with SWMaestro MyPage - manage mentoring sessions, reserve meeting rooms, view dashboard, team info, notices, and member profiles
+version: 0.1.0
+allowed-tools: Bash(opensoma:*)
+metadata:
+  openclaw:
+    requires:
+      bins:
+        - opensoma
+    install:
+      - kind: node
+        package: opensoma
+        bins: [opensoma]
+---
+
+opensoma is a comprehensive command-line interface and software development kit designed to bridge the gap between AI agents and the SWMaestro MyPage platform (swmaestro.ai). By wrapping the platform's complex, server-rendered interface, opensoma provides a clean, programmatic way to manage mentoring sessions, reserve meeting rooms at the SWMaestro center, monitor dashboard metrics, access official notices, and retrieve team or member profiles. It is built to handle the intricacies of the SWMaestro ecosystem, allowing for seamless automation of common administrative and educational tasks within the program. Whether you are a mentor organizing a lecture or a mentee looking for the next learning opportunity, opensoma streamlines your interaction with the SWMaestro platform by providing a structured, JSON-based interface to a traditionally unstructured web environment.
+
+### Important: CLI Only
+
+It is critical that you never attempt to scrape swmaestro.ai directly or initiate raw HTTP requests to the platform's endpoints. The SWMaestro MyPage is built on a traditional server-rendered Java/Spring architecture that does not expose a public REST API. The platform relies heavily on stateful session management, utilizing JSESSIONID cookies and CSRF (Cross-Site Request Fingerprinting) tokens for security. Every interaction requires these tokens to be correctly extracted from the HTML and passed back in subsequent requests. The opensoma CLI is specifically engineered to manage this entire lifecycle internally. It handles HTML parsing, session persistence, and token synchronization without requiring external intervention. Any attempt to bypass the CLI and make direct network calls will result in immediate failure due to missing session state, incorrect headers, or the inability to parse the complex, non-standard HTML structures that the platform returns. The CLI acts as a protective layer, ensuring that your interactions are both valid and secure according to the platform's requirements. Direct HTTP calls will fail because they require session cookies, CSRF tokens, and HTML parsing that the CLI manages.
+
+### Key Concepts
+
+To effectively use opensoma, you must understand the following core concepts that govern its operation:
+
+- **Session-based Authentication**: Unlike modern APIs that use persistent tokens like JWTs or API keys, SWMaestro uses a stateful session model. When you log in, the server issues a JSESSIONID cookie that must be sent with every subsequent request. These sessions are temporary and will expire after a period of inactivity or when the server-side session is cleared. If a command fails with an authentication error, it is a signal that the session has likely expired and you must re-authenticate using the `auth login` or `auth extract` commands.
+- **HTML Scraping and Transformation**: Because there is no underlying JSON API, the CLI acts as a transformation layer. It fetches the server-rendered HTML pages, parses the DOM structure, and extracts the relevant data points to construct a clean JSON response. This process is sensitive to changes in the platform's UI, and the CLI is updated to maintain compatibility with the latest HTML structures. The CLI handles the heavy lifting of converting unstructured HTML into structured data.
+- **Room Reservation Slot System**: Meeting room reservations at the SWMaestro center are managed in 30-minute increments. The available window for reservations typically spans from 09:00 in the morning to 23:30 at night. When making a reservation for a block of time, you must specify each 30-minute slot individually (e.g., "14:00,14:30,15:00"). These slots must be consecutive to form a valid booking. Furthermore, the system enforces a maximum limit of 8 slots (equivalent to 4 hours) per single reservation to ensure fair access for all participants.
+- **Room ID Mapping**: Meeting rooms can be referenced by short name (e.g., A1) or numeric ID. The CLI resolves short names to numeric IDs automatically via `resolveRoomId`. Known room mappings:
+  - **스페이스 A1**: 17 (Capacity: 4)
+  - **스페이스 A2**: 18 (Capacity: 4)
+  - **스페이스 A3**: 19 (Capacity: 4)
+  - **스페이스 A4**: 20 (Capacity: 4)
+  - **스페이스 A5**: 21 (Capacity: 4)
+  - **스페이스 A6**: 22 (Capacity: 4)
+  - **스페이스 A7**: 23 (Capacity: 4)
+  - **스페이스 A8**: 24 (Capacity: 4)
+- **Mentoring Session Types**:
+  - **자유 멘토링 (Public Mentoring)**: These are typically smaller, more intimate sessions focused on specific technical hurdles, project feedback, or career advice. They often have a limited number of attendees and are highly interactive. Any mentee can apply.
+  - **멘토 특강 (Mentor Lecture)**: These are larger-scale educational events or seminars led by mentors. They are designed for a broader audience and may be held in larger seminar rooms or conducted online.
+
+### Quick Start
+
+Get started with the most common workflows immediately:
+
+```bash
+# 1. Authenticate your session
+# Use your SWMaestro email and password
+opensoma auth login --username user@example.com --password mypassword
+
+# 2. View your current status and upcoming events
+# The --pretty flag makes the JSON output readable for humans
+opensoma dashboard show --pretty
+
+# 3. Browse available mentoring sessions
+# This lists sessions currently open for registration
+opensoma mentoring list --status open --pretty
+
+# 4. Reserve a meeting room for a team session
+# First, check what's available on a specific date
+opensoma room list --date 2026-04-10 --pretty
+# Check specific slots for a room (e.g., Room 17)
+opensoma room available 17 --date 2026-04-10 --pretty
+# Make the reservation
+opensoma room reserve --room 17 --date 2026-04-10 --slots "14:00,14:30,15:00,15:30" --title "팀 주간 회의"
+```
+
+### Authentication
+
+The `auth` command group is the gateway to all other operations. It manages the lifecycle of your SWMaestro session.
+
+- `auth login`: This is the primary method for establishing a session. You must provide your SWMaestro email via `--username` and your password via `--password`. For security, you can also set these as environment variables (`OPENSOMA_USERNAME` and `OPENSOMA_PASSWORD`) to avoid leaving them in your shell history. The command will attempt to log in, retrieve the necessary cookies, and store them locally.
+- `auth extract`: A powerful alternative for users who are already logged into SWMaestro in their web browser. This command scans the cookie stores of supported Chromium-based browsers (including Google Chrome, Microsoft Edge, Brave, Arc, Vivaldi, and standard Chromium) to find an active `JSESSIONID`. If found, it imports the session into the CLI, allowing you to bypass the login step. This is particularly useful for avoiding repeated password entry.
+- `auth status`: Use this command to verify your current connection state. It returns a JSON object indicating whether credentials exist on your machine and, more importantly, whether the current session is still recognized as valid by the SWMaestro server. It also provides the timestamp of your last successful login and the username associated with the session.
+- `auth logout`: When you are finished with your session, use this command to securely remove all stored credentials, cookies, and session data from your local configuration directory. This ensures that no sensitive session information remains on the disk.
+
+All authentication data is stored in a JSON file located at `~/.config/opensoma/credentials.json`. This file is created with 0600 permissions, ensuring that only your user account can read or write to it.
+
+### Memory
+
+To operate efficiently and provide a personalized experience, you should maintain a persistent memory of the information you discover. This allows you to avoid redundant network calls and provide more contextually aware assistance.
+
+**Reading Memory**: Every time you begin a new task involving opensoma, your first action should be to use the Read tool to check for the existence of `~/.config/opensoma/MEMORY.md`. This file serves as your long-term context for the user's SWMaestro environment. If the file is missing, you should proceed as if this is a first-time interaction, but be prepared to create it as you gather information.
+
+**Writing Memory**: You are responsible for keeping the memory file up-to-date. Whenever you encounter new, relevant information that isn't strictly transient (like a session cookie), you should update `MEMORY.md`. Key triggers for updating memory include:
+- Successfully running `dashboard show` for the first time (capture the user's name, their role—Mentor or Mentee—and their organization).
+- Discovering team details, such as the team name or the list of fellow members.
+- Identifying the numeric IDs for rooms that aren't part of the standard set, or rooms the user frequently mentions.
+- Learning user-specific preferences, such as a "usual" meeting room or a preferred time for mentoring.
+- Recording the IDs of notices or events that have already been summarized or acted upon.
+
+**What to Store**:
+- **User Profile**: Full name, role (멘토/연수생), organization, and position.
+- **Team Information**: Team name, member names, and mentor assignments.
+- **Room Registry**: A mapping of room names to their numeric IDs, along with notes on capacity or typical availability.
+- **Preferences**: Preferred output formats (e.g., always use --pretty), common reservation titles, or favorite mentoring topics.
+- **Processed Data**: IDs of notices or events that have already been summarized or acted upon.
+- **Aliases**: Any nicknames or shorthand the user uses for rooms, people, or sessions.
+
+**What NOT to Store**:
+- **Sensitive Credentials**: Never store passwords, JSESSIONID cookies, or CSRF tokens in the memory file. These are handled exclusively by the CLI's credential store.
+- **Transient State**: Do not store information that is likely to change within minutes, such as the current availability of a specific room slot.
+- **Large HTML Blobs**: Only store the extracted, relevant data, not the raw HTML content.
+
+**Handling Stale Data**: The SWMaestro environment is dynamic. If a piece of information in your memory (like a room ID or a mentoring session ID) results in a "Not Found" or "Invalid" error from the CLI, you must immediately remove or update that entry in `MEMORY.md` to prevent future errors.
+
+**Format/Example**:
+```markdown
+# OpenSoma Memory
+
+## User Profile
+- Name: 전수열
+- Role: 멘토
+- Organization: Indent
+- Position: CTO
+
+## Team Details
+- Team Name: 김앤강
+- Members: 김철수, 강영희
+
+## Room Registry
+- A1 (17): 4인실, 전수열 멘토가 선호하는 회의실
+- A5 (21): 4인실
+
+## Preferences
+- Always use --pretty for output
+- Default reservation title: "멘토링 세션"
+- Preferred mentoring type: public (자유 멘토링)
+```
+
+### Commands
+
+#### Auth Commands
+
+Commands for managing your SWMaestro session and credentials.
+
+```bash
+# Authenticate with email and password
+# Flags: --username, --password, --pretty
+opensoma auth login --username <username> --password <password> [--pretty]
+
+# Import an active session from your browser
+# Supports: Chrome, Edge, Brave, Arc, Vivaldi, Chromium
+opensoma auth extract [--pretty]
+
+# Check if you are currently authenticated and if the session is valid
+opensoma auth status [--pretty]
+
+# Clear all stored session data and log out
+opensoma auth logout [--pretty]
+```
+
+#### Mentoring Commands
+
+Comprehensive management of mentoring sessions, from discovery to application.
+
+```bash
+# List mentoring sessions with optional filters
+# --status: open (접수중), closed (마감)
+# --type: public (자유 멘토링), lecture (멘토 특강)
+# --search: Search by title (default), author, or content
+#   "keyword"         → title search
+#   "title:keyword"   → title search (explicit)
+#   "author:이름"     → author search
+#   "author:@me"      → my sessions only
+#   "content:keyword" → content search
+# --page: Navigate through results (default: 1)
+opensoma mentoring list [--status <open|closed>] [--type <public|lecture>] [--search <query>] [--page <n>] [--pretty]
+
+# Retrieve full details for a specific mentoring session
+# Includes content (HTML), venue, and attendee counts
+opensoma mentoring get <id> [--pretty]
+
+# Create a new mentoring session (Available for Mentors only)
+# --title: The name of the session
+# --type: public or lecture
+# --date: YYYY-MM-DD
+# --start: HH:MM (24-hour format)
+# --end: HH:MM (24-hour format)
+# --venue: Location name (e.g., "스페이스 A1")
+# --max-attendees: Maximum number of participants
+# --reg-start: Registration start date (YYYY-MM-DD)
+# --reg-end: Registration end date (YYYY-MM-DD)
+# --content: Detailed description in HTML format
+opensoma mentoring create --title <title> --type <public|lecture> --date <YYYY-MM-DD> --start <HH:MM> --end <HH:MM> --venue <venue> [--max-attendees <n>] [--reg-start <YYYY-MM-DD>] [--reg-end <YYYY-MM-DD>] [--content <html>] [--pretty]
+
+# Delete a mentoring session you created
+opensoma mentoring delete <id> [--pretty]
+
+# Apply for a mentoring session (Available for Mentees only)
+opensoma mentoring apply <id> [--pretty]
+
+# Cancel an existing mentoring application
+# Requires applySn and qustnrSn, which can be found in mentoring history
+opensoma mentoring cancel --apply-sn <id> --qustnr-sn <id> [--pretty]
+
+# View your complete mentoring application history
+opensoma mentoring history [--page <n>] [--pretty]
+```
+
+#### Room Commands
+
+Manage meeting room reservations at the SWMaestro center.
+
+```bash
+# List all rooms and their availability for a specific date
+# --date: Target date (YYYY-MM-DD), defaults to today
+# --room: Filter by a specific room name (e.g., "A1")
+opensoma room list [--date <YYYY-MM-DD>] [--room <name>] [--pretty]
+
+# Check the availability of 30-minute slots for a specific room
+# Accepts short name (e.g., A1) or numeric ID (e.g., 17)
+opensoma room available <room> --date <YYYY-MM-DD> [--pretty]
+
+# Reserve a room for a specific set of time slots
+# --room: Room short name (e.g., A1) or numeric ID (e.g., 17)
+# --date: YYYY-MM-DD
+# --slots: Comma-separated list of 30-minute slots (e.g., "14:00,14:30,15:00")
+# --title: The purpose of the reservation
+# --attendees: Number of people expected
+# --notes: Additional information for the reservation
+opensoma room reserve --room <room> --date <YYYY-MM-DD> --slots <HH:MM,...> --title <title> [--attendees <n>] [--notes <text>] [--pretty]
+```
+
+#### Dashboard Commands
+
+Get a high-level overview of your SWMaestro activity.
+
+```bash
+# Show a summary of your profile, upcoming mentoring, and room reservations
+opensoma dashboard show [--pretty]
+```
+
+#### Notice Commands
+
+Stay informed with official announcements from the SWMaestro center.
+
+```bash
+# List all notices with pagination support
+opensoma notice list [--page <n>] [--pretty]
+
+# Read the full content of a specific notice
+opensoma notice get <id> [--pretty]
+```
+
+#### Team Commands
+
+Access information about your team and its members.
+
+```bash
+# Show your team name, member list, and current status
+opensoma team show [--pretty]
+```
+
+#### Member Commands
+
+View and verify your personal profile data.
+
+```bash
+# Show your email, phone number, organization, and other profile details
+opensoma member show [--pretty]
+```
+
+#### Event Commands
+
+Manage your participation in SWMaestro-wide events.
+
+```bash
+# List all upcoming events
+opensoma event list [--page <n>] [--pretty]
+
+# Get detailed information about a specific event
+opensoma event get <id> [--pretty]
+
+# Submit an application for an event
+opensoma event apply <id> [--pretty]
+```
+
+### Global Options
+
+Every command in the opensoma CLI supports the following global option:
+
+- `--pretty`: When this flag is present, the CLI will output the JSON response in a formatted, indented style. This is highly recommended for human users and for agents during the debugging phase. When the flag is omitted, the CLI outputs compact, single-line JSON. This compact format is the default and is optimized for AI agents to minimize token consumption and maximize context window efficiency. It allows for more data to be processed within a single turn.
+
+### Output Format
+
+The CLI is designed to be "JSON-first." All successful operations return a JSON object or array. Errors are also returned as JSON but are directed to the standard error (stderr) stream. This consistent format makes it easy to parse and handle responses programmatically.
+
+Example of a successful compact response:
+`{"items":[{"id":123,"title":"Notice"}],"pagination":{"total":1}}`
+
+Example of an error response:
+`{"error":"Session expired. Please log in again."}`
+
+For a complete reference of the JSON schemas for every command, please consult the [references/output-format.md](references/output-format.md) document.
+
+### Pagination
+
+To handle large datasets, commands that return lists (such as `mentoring list`, `notice list`, and `event list`) implement a standard pagination model. The response will include a `pagination` object with the following fields:
+
+- `total`: The total number of items available across all pages.
+- `currentPage`: The index of the page currently being returned.
+- `totalPages`: The total number of pages available.
+
+You can navigate through these pages by using the `--page <n>` option, where `<n>` is the desired page number starting from 1. This allows you to efficiently browse through hundreds of entries without overwhelming the system.
+
+### Common Patterns
+
+For detailed workflow examples and best practices, refer to the [references/common-patterns.md](references/common-patterns.md) document. This includes patterns for daily schedule checks, creating mentoring sessions with room reservations, and handling common error scenarios.
+
+### Troubleshooting
+
+1. **Authentication Loop**: If you find yourself repeatedly getting "Session expired" errors even after logging in, check if your system clock is synchronized. Significant clock drift can cause session cookies to be treated as expired immediately.
+2. **Browser Extraction Issues**: If `auth extract` fails, ensure that your browser is completely closed or that you have granted the necessary permissions for the CLI to access the browser's profile directory. On some systems, browser security features may block external access to cookie databases.
+3. **Missing Data in Responses**: If a JSON response is missing fields you expect, it may be because that data isn't available for your specific user role (e.g., a Mentee cannot see certain Mentor-only fields).
+4. **Command Not Found**: If the shell cannot find the `opensoma` command, ensure it is installed globally via `bun install -g opensoma` or `npm install -g opensoma`. Alternatively, use `npx opensoma` to run it without a global installation.
+5. **Network Timeouts**: SWMaestro's servers can occasionally be slow or unresponsive. If a command hangs, try again after a few moments. The CLI does not currently implement aggressive retry logic.
+6. **Empty Results**: If a list is empty, verify your authentication status with `auth status`. If valid, the list may simply have no items matching your criteria.
+7. **HTML Parsing Errors**: If the platform's HTML structure changes, the CLI may fail to parse data correctly. In such cases, check for CLI updates or report the issue to the maintainers.
+8. **CSRF Token Mismatch**: If you encounter errors related to CSRF tokens, try logging out and logging back in to refresh your session and tokens.
+9. **Permission Denied**: Ensure that the user running the CLI has the necessary permissions to read and write to the `~/.config/opensoma` directory.
+10. **Invalid Room IDs**: If a room reservation fails with an "Invalid Room ID" error, use `room list` to verify the correct numeric ID for the target room.
+
+### Limitations
+
+- **HTML Parsing Fragility**: Because the CLI relies on parsing server-rendered HTML, any change to the SWMaestro website's layout or structure can potentially break specific commands. Always ensure you are using the latest version of the CLI.
+- **No Real-time Notifications**: The CLI is a request-response tool. It cannot "listen" for new notices or mentoring sessions in real-time. You must poll the relevant list commands to find updates.
+- **Attachment Handling**: The current version of the CLI does not support uploading or downloading file attachments (such as mentoring materials or notice downloads).
+- **Role Restrictions**: Many operations are strictly bound to your SWMaestro role. Mentors cannot apply for sessions, and Mentees cannot create them. The CLI will return an error if you attempt an unauthorized action.
+- **Reservation Race Conditions**: The SWMaestro room reservation system is highly competitive. A room slot that appears available when you run `room list` may be booked by another user by the time you run `room reserve`. Always attempt reservations as quickly as possible after checking availability.
+- **Undo Operations**: Write operations like `create`, `delete`, `reserve`, and `apply` are executed immediately and cannot be undone through the CLI. Double-check your parameters before executing these commands.
+- **Rate Limiting**: While the CLI doesn't enforce rate limits, the SWMaestro server might if it detects an unusual volume of requests. Use the CLI responsibly and avoid excessive polling.
+- **Platform Availability**: The CLI depends on the swmaestro.ai platform being online. If the platform is down for maintenance, the CLI will also be unavailable.
+- **Browser Compatibility**: The `auth extract` command is limited to Chromium-based browsers. Users of Firefox or Safari must use the `auth login` command.
+- **Data Precision**: Some data points extracted from HTML may be slightly less precise than those from a native API (e.g., relative timestamps like "2 hours ago" instead of exact ISO strings).
+- **Concurrent Sessions**: Logging in via the CLI may invalidate an existing session in your web browser, and vice versa, depending on the platform's session management policies.
+- **Environment Variables**: When using environment variables for authentication, ensure they are set correctly in your shell environment to avoid "Missing credentials" errors.
+- **JSON Schema Changes**: While the CLI aims for stability, the JSON response schemas may evolve over time to accommodate new features or changes in the underlying platform data.
+- **Error Message Clarity**: Some error messages from the server are passed through directly. If an error message is unclear, it may be a direct response from the SWMaestro platform's internal logic.
+- **Pagination Limits**: The server may impose limits on the maximum number of pages or items that can be retrieved in a single session.
+- **Venue Availability**: The list of venues for mentoring sessions is determined by the platform and may change based on the center's scheduling.
+- **Attendee Limits**: Mentoring sessions have strict attendee limits enforced by the platform. The CLI will return an error if you attempt to apply for a full session.
+- **Registration Windows**: Mentoring sessions and events have specific registration start and end dates. The CLI will not allow applications outside of these windows.
+- **Content Formatting**: Content retrieved from notices or mentoring sessions is in HTML format. Agents should be prepared to handle or strip HTML tags as needed.

package/skills/opensoma/references/common-patterns.md

@@ -0,0 +1,182 @@
+# Common Patterns
+
+## Daily Schedule Check
+
+To get a comprehensive view of your daily activities, combine dashboard, mentoring, and room availability checks. This pattern is essential for staying on top of your SWMaestro commitments.
+
+```bash
+# 1. Check dashboard for current status
+# This provides a summary of your profile, upcoming mentoring, and room reservations
+opensoma dashboard show --pretty
+
+# 2. List open mentoring sessions
+# This lists sessions currently open for registration, allowing you to find new opportunities
+opensoma mentoring list --status open --pretty
+
+# 3. Check room availability for today
+# This shows which meeting rooms are available for the current date
+opensoma room list --date $(date +%Y-%m-%d) --pretty
+```
+
+## Creating a Mentoring Session with Room
+
+When creating a mentoring session that requires a physical space, follow this workflow to ensure the room is secured first. This prevents the situation where a session is created but no room is available.
+
+```bash
+# 1. Check room availability for the target date
+# This lists all rooms and their availability for the specified date
+opensoma room list --date 2026-04-15 --pretty
+
+# 2. Reserve the room (e.g., Room A1, ID 17)
+# This reserves the specified 30-minute slots for the room
+opensoma room reserve --room 17 --date 2026-04-15 --slots "14:00,14:30,15:00,15:30" --title "TypeScript 기초"
+
+# 3. Create the mentoring session using the reserved venue
+# This creates the mentoring session with the specified details and venue
+opensoma mentoring create \
+  --title "TypeScript 기초 특강" \
+  --type lecture \
+  --date 2026-04-15 \
+  --start 14:00 \
+  --end 16:00 \
+  --venue "스페이스 A1" \
+  --max-attendees 8 \
+  --reg-start 2026-04-10 \
+  --reg-end 2026-04-14
+```
+
+## Listing My Mentoring Sessions
+
+When the user asks "show my lectures", "list my mentoring", "내 멘토링", or any variation of viewing sessions they created, use `--search "author:@me"`. This filters to only the sessions authored by the current user.
+
+```bash
+# List mentoring sessions I created
+opensoma mentoring list --search "author:@me" --pretty
+
+# Combine with status and type filters
+opensoma mentoring list --search "author:@me" --status open --pretty
+opensoma mentoring list --search "author:@me" --type lecture --pretty
+```
+
+## Searching Mentoring Sessions
+
+Use `--search` to find mentoring sessions by title, author, or content. Title search is the default when no field prefix is given.
+
+```bash
+# Search by title (default)
+opensoma mentoring list --search "OpenCode" --pretty
+
+# Search by author name
+opensoma mentoring list --search "author:전수열" --pretty
+
+# Search by content
+opensoma mentoring list --search "content:하네스" --pretty
+
+# Compose search with other filters
+opensoma mentoring list --search "OpenCode" --status open --type lecture --pretty
+```
+
+## Checking a Specific Mentoring Session
+
+To find and inspect a specific mentoring session, first list the sessions to find the ID, then retrieve the details. This is the standard way to get full information about a session.
+
+```bash
+# 1. List sessions to find the target ID
+# This lists sessions with optional filters to narrow down the search
+opensoma mentoring list --pretty
+
+# 2. Get full details for the specific session ID
+# This retrieves the full content, venue, and attendee counts for the session
+opensoma mentoring get 9572 --pretty
+```
+
+## Finding Available Rooms
+
+For a specific date, you can find rooms with open morning or afternoon slots by listing all rooms and filtering the output. This is useful for planning team meetings or study sessions.
+
+```bash
+# List all rooms for a specific date
+# This provides a comprehensive view of room availability for the entire day
+opensoma room list --date 2026-04-10 --pretty
+```
+
+## Viewing Team and Member Info
+
+Access your team and personal profile information. This is useful for verifying your status and seeing who else is on your team.
+
+```bash
+# Show team members and status
+# This lists the members of your assigned team and their current status
+opensoma team show --pretty
+
+# Show your profile details
+# This displays your email, phone number, organization, and other profile details
+opensoma member show --pretty
+```
+
+## Checking Notices
+
+Stay updated with the latest official announcements from the SWMaestro center. This is important for keeping track of program updates and requirements.
+
+```bash
+# List recent notices
+# This lists all notices with pagination support
+opensoma notice list --pretty
+
+# Read a specific notice by ID
+# This retrieves the full content of the specified notice
+opensoma notice get 36387 --pretty
+```
+
+## Error Handling Patterns
+
+When a command fails, follow these patterns to resolve the issue. These steps will help you quickly recover from common operational problems.
+
+- **Authentication Failure**: If you receive a "Not logged in" or "Session expired" error, re-authenticate immediately. This is the most common cause of command failure.
+  ```bash
+  opensoma auth login --username <email> --password <password>
+  # OR
+  opensoma auth extract
+  ```
+- **Empty Results**: If a list is empty, verify your authentication status with `auth status`. If valid, the list may simply have no items matching your criteria. This is common for mentoring sessions or events that haven't started yet.
+- **Session Expired Mid-Workflow**: If a multi-step workflow fails halfway, re-authenticate and restart the process. Check the status of any write operations (like room reservations) before retrying to avoid duplicate actions.
+- **CSRF Token Issues**: If you encounter CSRF token errors, it often means your session is invalid. Re-authenticating will usually resolve this.
+- **Network Timeouts**: If a command hangs or times out, wait a few moments and try again. The SWMaestro servers can occasionally be slow.
+
+## Best Practices
+
+- **Verify Auth**: Always check `auth status` before starting a multi-step workflow to ensure your session is valid. This saves time and prevents partial failures.
+- **Output Mode**: Use `--pretty` for human inspection and debugging. Omit the flag for programmatic use to save context space and improve processing speed.
+- **Memory Usage**: Store discovered IDs (rooms, mentoring sessions, notices) in `MEMORY.md` to avoid redundant lookups. This makes your interactions more efficient.
+- **Immediate Reservation**: For room reservations, check availability immediately before reserving. Slots can be taken quickly by other users, especially during peak times.
+- **Start with Dashboard**: Use `dashboard show` as the starting point for any task to get an overview of your current state and any pending actions.
+- **Check Role Restrictions**: Be aware of your role (Mentor or Mentee) and the operations available to you. The CLI will return an error if you attempt an unauthorized action.
+- **Use Environment Variables**: For security, use `OPENSOMA_USERNAME` and `OPENSOMA_PASSWORD` environment variables for authentication instead of passing them as flags.
+
+## Anti-Patterns
+
+- **Caching Room Availability**: Do not cache room availability for long periods. It changes constantly as other users make reservations. Always get fresh data before making a booking.
+- **Assuming Persistent Sessions**: Do not assume sessions will last forever. They expire based on server-side policies. Be prepared to re-authenticate at any time.
+- **Hardcoding Room IDs**: Avoid hardcoding room IDs in your logic. Use `room list` to discover them dynamically, as IDs can occasionally change or new rooms may be added.
+- **Direct Scraping**: Never attempt to scrape swmaestro.ai directly. Always use the opensoma CLI to interact with the platform. The CLI handles the complex session and parsing logic for you.
+- **Ignoring Errors**: Do not ignore error responses from the CLI. They provide valuable information about why a command failed and how to fix it.
+- **Excessive Polling**: Avoid excessive polling of the SWMaestro servers. This can lead to rate limiting or temporary bans. Use the CLI responsibly.
+- **Storing Sensitive Data**: Never store passwords or session cookies in your memory file or other insecure locations. Use the CLI's built-in credential management.
+- **Skipping Auth Status**: Do not skip checking your authentication status before starting a complex task. It's better to find out early if you need to log in.
+- **Mixing Roles**: Do not attempt to perform actions that are not allowed for your role. Mentors should not try to apply for sessions, and Mentees should not try to create them.
+- **Ignoring Pagination**: When listing items, do not assume all results are on the first page. Check the pagination object and use the `--page` flag if necessary.
+- **Manual HTML Parsing**: Do not try to parse the HTML output of the CLI yourself. The CLI already provides structured JSON for this purpose.
+- **Hardcoding Dates**: Avoid hardcoding dates in your scripts. Use dynamic date generation (e.g., `$(date +%Y-%m-%d)`) to ensure your commands are always relevant.
+- **Neglecting Memory**: Do not ignore the `MEMORY.md` file. It is a valuable tool for maintaining context across different sessions and tasks.
+- **Overwriting Memory**: Be careful not to overwrite important information in `MEMORY.md`. Always read the file first and append or update as needed.
+- **Sharing Credentials**: Never share your `credentials.json` file or its contents with anyone. It contains sensitive session information that could be used to access your account.
+- **Committing Secrets**: Do not commit your `credentials.json` or any other files containing secrets to a public repository. Use `.gitignore` to prevent this.
+- **Using Outdated CLI**: Do not use an outdated version of the opensoma CLI. The SWMaestro platform changes frequently, and the CLI is updated to keep pace.
+- **Ignoring Troubleshooting**: If you encounter a problem, refer to the troubleshooting section in `SKILL.md` before seeking external help.
+- **Assuming Success**: Do not assume a command succeeded without checking the output and exit code. The CLI provides clear error messages when something goes wrong.
+- **Neglecting Pretty Print**: While compact JSON is better for agents, don't forget to use `--pretty` when you need to inspect the output yourself.
+- **Ignoring Venue Names**: When creating a mentoring session, ensure the venue name matches one of the recognized rooms to avoid confusion.
+- **Skipping Registration Windows**: Be mindful of registration start and end dates. Applying outside of these windows will result in an error.
+- **Ignoring Attendee Limits**: Do not try to apply for a session that is already full. Check the attendee counts in the session details first.
+- **Manual CSRF Handling**: Do not attempt to handle CSRF tokens manually. The CLI manages them automatically for every request.
+- **Direct HTTP Calls**: As a final reminder, never make direct HTTP calls to swmaestro.ai. Always use the opensoma CLI.

package/skills/opensoma/references/output-format.md

@@ -0,0 +1,130 @@
+# Output Format
+
+## JSON (Default)
+All commands output compact JSON by default. Use the `--pretty` flag for indented, human-readable output. This compact format is optimized for AI agents to minimize token consumption and maximize context window efficiency.
+
+## Response Schemas
+
+### notice list
+```json
+{"items":[{"id":36387,"title":"[센터] 연수센터 이용 규칙","author":"AI·SW마에스트로","createdAt":"2026.04.07 15:14:20"}],"pagination":{"total":11,"currentPage":1,"totalPages":2}}
+```
+
+### notice get
+```json
+{"id":36387,"title":"[센터] 연수센터 이용 규칙","author":"AI·SW마에스트로","createdAt":"2026.04.07","content":"<p>HTML content...</p>"}
+```
+
+### mentoring list
+```json
+{"items":[{"id":9482,"title":"초기 제품 개발 준비","type":"자유 멘토링","registrationPeriod":{"start":"2026-04-08","end":"2026-04-23"},"sessionDate":"2026-04-30","sessionTime":{"start":"19:00","end":"22:00"},"attendees":{"current":3,"max":4},"approved":true,"status":"접수중","author":"김태성","createdAt":"2026-04-08"}],"pagination":{"total":586,"currentPage":1,"totalPages":50}}
+```
+
+### mentoring get
+```json
+{"id":9482,"title":"초기 제품 개발 준비","type":"자유 멘토링","registrationPeriod":{"start":"2026-04-08","end":"2026-04-23"},"sessionDate":"2026-04-30","sessionTime":{"start":"19:00","end":"22:00"},"attendees":{"current":0,"max":4},"approved":true,"status":"접수중","author":"김태성","createdAt":"2026-04-08","content":"<p>HTML content...</p>","venue":"스페이스 A5"}
+```
+
+### room list
+```json
+[{"itemId":17,"name":"스페이스 A1","capacity":4,"availablePeriod":{"start":"2026-04-06","end":"2026-04-30"},"description":"스페이스 A1 회의실 : 4인","timeSlots":[{"time":"09:00","available":true},{"time":"09:30","available":true},{"time":"10:00","available":false}]}]
+```
+
+### room available
+```json
+[{"time":"09:00","available":true},{"time":"09:30","available":true},{"time":"12:00","available":false}]
+```
+
+### dashboard show
+`team` is optional — omitted when user has no team assigned.
+```json
+{"name":"전수열","role":"멘토","organization":"Indent","position":"","team":{"name":"김앤강","members":"김철수, 강영희","mentor":"전수열"},"mentoringSessions":[{"title":"게임 개발 AI 활용법","url":"/sw/mypage/mentoLec/view.do?qustnrSn=9582&menuNo=200046","status":"접수중"}],"roomReservations":[{"title":"OpenCode 하네스 만들어보기 (전수열)","url":"/sw/mypage/itemRent/view.do?rentId=17905&menuNo=200059","status":"예약완료"}]}
+```
+
+### member show
+```json
+{"email":"devxoul@gmail.com","name":"전수열","gender":"남자","birthDate":"1995-01-14","phone":"01020609858","organization":"Indent","position":""}
+```
+
+### team show
+```json
+{"teams":[{"name":"김앤강","memberCount":0,"joinStatus":"참여"}],"currentTeams":0,"maxTeams":100}
+```
+
+### auth status
+```json
+{"authenticated":true,"valid":true,"username":null,"loggedInAt":"2026-04-09T16:07:56.247Z"}
+```
+
+### auth extract
+```json
+{"ok":true,"extracted":true,"valid":true}
+```
+
+### event list
+```json
+{"items":[],"pagination":{"total":0,"currentPage":1,"totalPages":1}}
+```
+
+### mentoring history
+```json
+{"items":[],"pagination":{"total":0,"currentPage":1,"totalPages":1}}
+```
+
+### Error Responses
+All errors are written to stderr as JSON objects. This allows agents to distinguish between successful data retrieval and operational failures.
+
+Example of an authentication error:
+```json
+{"error":"Not logged in. Run: opensoma auth login"}
+```
+
+Example of a session expiration error:
+```json
+{"error":"Session expired. Please log in again."}
+```
+
+Example of a missing parameter error:
+```json
+{"error":"Provide --username and --password or set OPENSOMA_USERNAME and OPENSOMA_PASSWORD"}
+```
+
+Example of a CSRF token error:
+```json
+{"error":"CSRF token not found. This may indicate a session issue or a change in the platform's structure."}
+```
+
+Example of a browser extraction error:
+```json
+{"error":"No SWMaestro session found in any browser. Ensure you are logged in at swmaestro.ai."}
+```
+
+Example of a room reservation error:
+```json
+{"error":"The selected room slots are no longer available. Please check availability and try again."}
+```
+
+Example of a mentoring application error:
+```json
+{"error":"You have already applied for this mentoring session or the session is full."}
+```
+
+Example of a notice retrieval error:
+```json
+{"error":"Notice not found. The ID may be invalid or the notice may have been removed."}
+```
+
+Example of a team information error:
+```json
+{"error":"Team information not found. Ensure you are assigned to a team."}
+```
+
+Example of a member profile error:
+```json
+{"error":"Member profile not found. Ensure your session is valid."}
+```
+
+Example of an event retrieval error:
+```json
+{"error":"Event not found. The ID may be invalid or the event may have ended."}
+```