Giya — How to use the app

Giya is Livro Systems’ assistant for tasks, QA/bugs, and school setup. In Cebuano/Binisaya, giya means to guide, steer, conduct, or give direction. It answers from your account, role, and connected tools—not from access you don’t have.

Open Docs anytime from the home page.

---

Get started

1. Open Giya and choose Sign in.
2. Sign in with Livro (or your school ERP, if you opened Giya from a school site).
3. Agree to the Terms of Use.
4. Finish onboarding (name, role, focus) if this is your first time.
5. You land in the workspace. Connect School or Livro in tools before you ask Giya to use them. Gmail, Calendar, Meet, and GitHub live in Welay on Discord — not in Giya.

There is no public sign-up. Your Livro or school ERP login creates the Giya account.

---

Sign in

Livro (usual path)

1. Go to Sign in.
2. Enter your Livro email and password.
3. Check the Terms box, then Sign in with Livro.

School ERP (when Giya is opened from a school site)

1. Confirm the ERP site shown on the form.
2. Enter email and password, then Sign in.
3. If the school asks for OTP, enter the Verification code and Verify & continue.

Opened from an ERP desk with a live session: Giya signs you in automatically—no password.

If Terms change later, a bar appears: Agree and continue.

---

Onboarding

Skipped if you already have a role.

1. What’s your name? — enter your display name, then Continue.
2. What is your role? — pick from the cards (for example Tech, Sales, Dev, QA, PO, PM, Finance). Owner, Admin, and Team leader are not listed here.
3. What should I help with most?
   • Tasks & priorities — overdue work and what to tackle next
   • Bug analysis — errors, logs, and likely causes
   • School setup — academic year, enrollment, roles
   • General help — anything your permissions allow
4. Finish, then Open Giya workspace.

You can Redo onboarding from the done screen if you need to change this.

---

First-run tutorial

New users (no chats yet) see a First steps card on the workspace: XP, level, and missions.

Later hides the card until the next visit. Skip tutorial dismisses it for good. Completing every mission awards a Guide badge. People who already have chats never see it unless a catalog update adds missions — then First steps can reopen with a New update banner, and XP / completed missions stay saved (nothing is wiped).

---

Workspace

This is the main screen.

Left sidebar (use Show sidebar if it is collapsed)

• New chat — start a blank conversation.
• Chats — reopen past conversations.
• Canvas — Web Pages, Web Forms, and Print Formats Giya generated (one canvas per chat).
• Trash icon on a chat → Archive chat.
• Your name and email open Profile.
• Log out ends the session.
• Admins see Control center (users, teams, schools, roles).

Chat

Greeting is Hi, {your first name}. Ask about tasks, bugs, or school setup.

---

Server-side OAuth (GPT Actions)

Giya can act as a confidential OAuth authorization server (Authorization Code Grant).

1. Run npm run db:migrate (adds oauth_auth_code / oauth_token).
2. Set env:
   • GIYA_OAUTH_CLIENT_ID
   • GIYA_OAUTH_CLIENT_SECRET
   • GIYA_OAUTH_REDIRECT_URIS — comma-separated callbacks ChatGPT shows after you save the Action (e.g. https://chat.openai.com/aip/g-…/oauth/callback,https://chatgpt.com/aip/g-…/oauth/callback)
3. In the GPT Action Authentication form:
   • Authorization URL: https://<your-giya-host>/api/oauth/authorize
   • Token URL: https://<your-giya-host>/api/oauth/token
   • Client ID / Secret: same as env
4. User signs in to Giya → code → ChatGPT POSTs grant_type=authorization_code to the token URL.

Generate a client id/secret with issueOAuthClient("web-server") when you need new values; paste them into env and the GPT editor.

---

Chat

1. Type in Ask Giya (example: What tasks are overdue?).
2. Enter sends. Shift+Enter adds a new line.
3. Paperclip Upload pictures — images, video, or PDF. Remove a file from the thumbs above the box.
4. Ctrl+V pastes images.
5. While Giya is answering, use Stop generating.

Canvas — if Giya builds a Web Page, Web Form, Print Format, Script Report, or document, use Show canvas / Hide canvas. Saved canvases also appear under the sidebar Canvas tab.

Chat uses Cursor by default when your role allows it. That is the route that can use School ERP and Livro ERP tools in the same turn. There is no model picker in the composer. Team leaders set Allowed AI models on the team profile.

Which API key is used (personal, team, or system) is set in Profile → Account → Default prompt API key, not in the chat box.

Ask in plain language. Giya matches skills from what you type (for example “file leave” or “morning briefing”). You do not need a / menu.

---

Connect tools

Bottom-right Open tools (layers button). Tabs depend on your role:

Teachers in a school embed may not see this FAB (School/Livro are for internal roles). Close the panel with Dismiss tools.

Gmail, Calendar, Meet, and GitHub are not in Giya. Use Welay on Discord for those.

Theme, Skills, and knowledge settings are in Profile, not this dock.

---

Welay (Gmail, Calendar, Meet, GitHub)

Giya no longer connects Google Workspace or GitHub. For mail, calendar, meetings, or repos/PRs/issues, chat with Welay on Discord:

1. Go to general chat.
2. Look for Welay in the Members List.
3. Right-click and click Message.
4. Welay should appear in your Direct Message column.
5. Ask Welay from there.

---

School ERP

1. Open tools → School.
2. Enter the School ERP URL (or pick a recent/preset).
3. Username / email and password → Connect school.
4. Complete OTP if asked.

You should see students, teachers, classes, and Refresh / Logout. Opened from a school desk, the password form may be skipped.

Then ask Giya for enrollment walkthroughs, Print Formats, report cards, grade slips, progress reports, Form 10 / TOR, SF4–SF6, rankings, and related grading reports. Ask Giya to analyze any DocType on the connected school (duplicates, empty fields, counts, group-by) — it scans the table in tools, not a short list. Use Cursor (the default) so School ERP tools run. Giya can create and update School ERP documents (Script Reports, Print Formats, Web Pages, drafts) on the connected school site via the school SID — not Welay.

---

Livro ERP

Livro is the same session as Sign in with Livro. There is no second password in the tools panel. Giya reads Livro via MCP and can update / submit existing Desk documents with `livro_erp_*`. It cannot create or delete Livro documents.

Open tools → Livro to browse eLibrary DocTypes (tech reference from Livro eLibrary guides). Expand a DocType to open the guide in Desk. If it says Livro session missing, Log out and sign in with Livro again.

Ask Giya for customer lookup, invoices, stock, leave, overtime, sprint backlogs, or Livro Desk edits. Gmail, Calendar, Meet, and GitHub still live in Welay on Discord — not School ERP work.

---

Profile

Click your name or email in the left sidebar.

Account

• View full profile, usage & prompt archives opens your user profile page.
• Edit name, then Save.
• Team — join with a 6-digit code, Leave team (leaders cannot leave), or Manage team if you lead.
• Default prompt API key — Personal key, Team key, or System key, then Save default.
• API keys — add or clear personal Gemini and Cursor keys. Team keys are set by the leader on the team profile.

Theme — presets such as Artisan Teal, or Add a custom theme. Custom themes stay in this browser.

Tools

• MCPs — install or configure extra MCP servers.
• Installed — skills currently active.
• Knowledge — files Giya indexed from attachments and output.

Deeper MCP catalogue: /mcp.

---

Skills

Skills are repeatable workflows. Giya picks them up from normal chat (and from installed marketplace skills).

Create a skill

• Profile → Skills → Add Your Own Skill — name, category, short description, instructions, Private or Published → Save Skill. New skills are private unless you publish them.

Marketplace — search, filter, Install / Uninstall. Delete only skills you authored.

Giya matches installed skills from plain language in chat (the / command menu is not used).

---

Teams and keys

1. Get a 6-digit join code from your team leader.
2. Profile → Account → enter the code → Join team.
3. Prefer Team key in Default prompt API key when the leader has shared Cursor/Gemini credentials.

Team leaders (from Manage team or Control center):

• Share Cursor and Gemini team keys (Edit keys).
• Set Allowed AI models (Edit models). Cursor should stay allowed if people need School / Livro ERP in one turn.
• See members, join code, and team usage.

Personal keys override team keys when the default is Personal key.

---

Admin

If you have team-management permission, open Control center in the sidebar.

Signed-in users can submit the survey from the sidebar Feedback survey (/feedback). Email is stored from the account. You can update your response later.

Back to chat returns to the workspace. Owner and Admin roles are system-protected.

Server Gemini env vars are documented in GOOGLE_CREDENTIALS.md for DevOps. Workspace OAuth is unused in Giya.

---

Install as an app

On / (or /landing):

• Chrome / Edge — Install app when the browser offers it.
• Android — Chrome ⋮ → Install app or Add to Home screen.
• iPhone — Safari Share → Add to Home Screen.

Standalone windows show Installed. Optional Notifications can be enabled later.

When Giya is embedded in ERP, use Fullscreen / Exit fullscreen.

---

Tips

• Connect the right ERP tool (School / Livro) before asking for school reports or Livro Desk work.
• Use Welay on Discord for Gmail, Calendar, Meet, or GitHub.
• Stay on Cursor (the default) when you need School or Livro tools in the same request.
• After you Add Your Own Skill, it is available in chat without a reload.
• Use Team keys when your leader has shared credentials.
• If Livro tools fail, sign out and Sign in with Livro again.

---

Product name: Giya · Maker: Livro Systems Inc.