Skip to content

Job application tracker and AI-powered job search assistant. Helps job seekers manage their search journey with AI resume review, job matching, task logging, and application analytics, all while keeping your data private.

docs(wiki): add Activities and Tasks documentation

Khuram Niaz74778ef986de
diff --git a/src/lib/wiki/schema.ts b/src/lib/wiki/schema.ts
index f567769..48f79d8 100644
--- a/src/lib/wiki/schema.ts
+++ b/src/lib/wiki/schema.ts
@@ -19,6 +19,7 @@ export const WIKI_FEATURES = [
"profile",
"ai",
"tasks",
+ "activities",
"questions",
"mcp",
] as const;
diff --git a/wiki/activities.md b/wiki/activities.md
new file mode 100644
index 0000000..7cad39f
--- /dev/null
+++ b/wiki/activities.md
@@ -0,0 +1,71 @@
+---
+type: how-to
+title: Activities
+description: Timing the work you put into your job hunt — starting and stopping an activity, taking breaks, logging time after the fact, and where the hours show up.
+feature: activities
+tags: [activities, activity, time tracking, timer, start activity, stop activity, break, pause, log time, duration, activity type, activity calendar, weekly activities, hours, delete activity]
+aliases: [time log, timesheet, timer, time spent, tracking time]
+status: stable
+stale_after: 2027-09-14
+---
+
+# Activities
+
+## What are activities for?
+
+An activity is one stretch of time spent on your job hunt — an hour of applications, a mock interview, an evening on a portfolio. Each activity has a name, an activity type, a start and end time, a duration and an optional description.
+
+Finished activities are listed under **Activities** in the sidebar, newest first. Activity types are the categories your hours add up under on the Dashboard, and they are the same list as **Library → Activity Types** and the Activity Type field on a [task](./tasks.md).
+
+## How do I time an activity?
+
+Start one and stop it when you are done. There are three places to start:
+
+- **From a task** — **Start Activity** in the task's **⋮** menu, or **Save & Start** when adding it. The activity is named after the task and linked to it. See [Tasks](./tasks.md#how-do-i-start-an-activity-from-a-task).
+- **From a past activity** — **Start Activity** in its **⋮** menu on the Activities page, or the green play button on hover. This starts a new activity with the same name, type and description; the old one is left as it was, and the new one is not linked to any task.
+- **From the Dashboard** — the play button beside an entry in **Recent Activities**.
+
+A green banner then appears at the top of every dashboard page with the activity's name and running time. Click **Stop Activity** on it to finish; the activity is saved and appears in the list.
+
+Only one activity runs at a time, across all your tabs and devices. Starting another while one is running asks whether to stop the current one — **Stop & Start** does both.
+
+## How do I take a break?
+
+Click **Break** on the activity banner. Pick a length — 5, 10, 15 or 30 minutes, or step it with **−** and **+** anywhere from 5 to 60 — then click **Start Break**. A countdown ring covers the app until you come back, and you can still change the length while it runs.
+
+When the time is up you get a *Break time is up* notice and the clock counts on past zero; the break does not end by itself. Click **Resume Activity** to carry on, or **Stop Activity** to end the whole activity from there. Stopping during a break asks you to confirm, because a stopped activity cannot be resumed.
+
+Break time is never counted as work: it is taken off the activity's duration when you stop, including a break you never resumed from.
+
+## Why wasn't my activity saved?
+
+Because it was shorter than 2 minutes of work. Stopping an activity under that discards it with *Activity not saved because duration was less than 2 minutes* — break time does not count toward the 2 minutes, so a long activity that was almost all break is discarded too.
+
+The other limit is 8 hours. An activity still running 8 hours after it started, breaks included, stops itself with a notice saying so, and no saved activity's duration is ever more than 8 hours. If you left one running overnight, delete it and log the real time with **New Activity**.
+
+A running activity does not appear in the Activities list at all; it shows up there once you stop it.
+
+## How do I log time I already spent?
+
+Click **New Activity** in the Activities card header. Fill in **Activity Name** (at least two characters) and **Activity Type** — both are required, and the type combo box creates a new type if you type a name that does not exist. Set **Start Date**, **Start Time**, **End Date** and **End Time**; the End Time label shows the duration as you change them.
+
+The start cannot be in the future, the end must be after the start, and the duration must be between 2 minutes and 8 hours. **Description** holds up to 1000 characters. An activity added this way is not linked to a task.
+
+The list is ordered by when each entry was saved, not when it happened, so an activity you backfill for last week appears at the top.
+
+## Where do I see how much time I've spent?
+
+On the Activities page, the **Duration** column shows each activity's worked time, and the search box matches name, description and activity type. The Dashboard adds up the totals:
+
+- **Jobs & Activity** — hours by activity type over the last 7 or 30 days.
+- **Weekly Activities** — pick **Activities** on the weekly chart for hours per day over the last seven days, stacked by type.
+- **Recent Activities** — pick **Activities** on the recent card for your last ten, grouped by the day they ended.
+- **Activity Calendar** — hover a day for its hours of activity. The colour of each day reflects jobs applied, not hours.
+
+The charts put an activity on the day it started, so one that runs past midnight counts toward the earlier day.
+
+## How do I change or delete an activity?
+
+Activities cannot be edited. To correct one, delete it from its **⋮** menu and add the right one with **New Activity**. Deleting asks you to confirm and cannot be undone.
+
+Deleting an activity started from a task is also how you unblock deleting that task, which is refused while any activity is linked to it. An activity type cannot be deleted from **Library → Activity Types** while any activity uses it, and the message says how many are in the way.
diff --git a/wiki/getting-started.md b/wiki/getting-started.md
index 305cddf..95b3f16 100644
--- a/wiki/getting-started.md
+++ b/wiki/getting-started.md
@@ -32,8 +32,8 @@ There is a faster route once an AI provider is set: click **Chat AI** in the hea
- **Dashboard** — summary cards: application counts, recent jobs and activities, and weekly charts.
- **Jobs** — every job you are tracking, plus jobs discovered by automations.
- **Automations** — scheduled searches that pull new postings in and score them against your resume.
-- **Tasks** — to-dos with a due date, priority and percent complete, optionally linked to a job.
-- **Activities** — time logged against jobs and tasks, with a calendar view.
+- **Tasks** — to-dos with a due date, priority and percent complete, and a timed activity you can start from each one.
+- **Activities** — time you spend on your job hunt, timed with a start/stop timer or logged afterwards, optionally started from a task.
- **Questions** — a question bank for interview preparation.
- **Profile** — your resumes, contact information and the profile the AI features read from.
- **Library** — the shared reference lists behind the dropdowns: Companies, Job Titles, Locations, Sources, Skills and Activity Types.
diff --git a/wiki/index.md b/wiki/index.md
index 0327903..91e12b3 100644
--- a/wiki/index.md
+++ b/wiki/index.md
@@ -11,6 +11,8 @@ JobSync tracks job applications, resumes and the work you do around them. These
- [Contacts](./contacts.md) — track recruiters, interviewers and references, link them to the jobs they touched, and record how you know them.
- [Companies](./companies.md) — a company's details page with its jobs and contacts, watching a company, and why a company can't be deleted.
- [Automations](./automations.md) — set up a scheduled search over Greenhouse, Lever and Ashby company boards, fill in the filters that make it work, and handle the jobs it discovers.
+- [Tasks](./tasks.md) — add to-dos with a priority and due date, find them with the status filter and activity-type panel, mark them done, and start a timed activity from one.
+- [Activities](./activities.md) — time the work you do with a start/stop timer and breaks, log time after the fact, and see your hours on the Dashboard.
- [MCP Access](./mcp.md) — connect an external AI agent such as Claude Desktop, generate and revoke access tokens, and what the agent can do once connected.
Installation, Docker and environment variables are in the [project README](https://github.com/Gsync/jobsync#readme).
diff --git a/wiki/tasks.md b/wiki/tasks.md
new file mode 100644
index 0000000..65cd988
--- /dev/null
+++ b/wiki/tasks.md
@@ -0,0 +1,64 @@
+---
+type: how-to
+title: Tasks
+description: Keeping a to-do list for your job hunt — adding tasks, finding them again with the status filter and activity-type sidebar, marking them done, and starting a timed activity from one.
+feature: tasks
+tags: [tasks, task, to-do, todo, priority, due date, percent complete, status, activity type, start activity, save and start, group by, overdue, complete, cancelled, delete task]
+aliases: [to-do list, todos, my tasks, task list, reminders]
+status: stable
+stale_after: 2027-09-14
+---
+
+# Tasks
+
+## What are tasks for?
+
+A task is one piece of work you want to get done — tailor a resume, follow up with a recruiter, prepare for Thursday's interview. Each task holds a title, an activity type, a status, a priority from 0 to 10, a percent complete, an optional due date and a rich-text description.
+
+Tasks live under **Tasks** in the sidebar. Their activity type is what connects them to time tracking: starting an activity from a task logs the time you spend on it under **Activities**. Tasks are not linked to jobs; mention the job in the title or description if it matters.
+
+## How do I add a task?
+
+Click **New Task** in the Tasks card header, or **Task** at the bottom of the Dashboard card on the Dashboard. Only **Title** is required, and it needs at least two characters. The form arrives with Status set to **In Progress**, Priority at **5** and % Complete at **0%**.
+
+**Activity Type** is a combo box: pick an existing type or type a new name to create one, the same list as **Library → Activity Types**. **Due Date** can be today or later but not in the past, and **Description** holds up to 2000 characters of formatted text.
+
+**Save** adds the task. **Save & Start** adds it and immediately starts an activity from it, which is the quick way to begin working on something the moment you write it down — it needs an activity type, the same as starting from the list.
+
+## Why don't I see all my tasks?
+
+Because the list starts filtered to **In Progress** and **Needs Attention**, so completed and cancelled tasks are hidden. Click **Status** in the card header and tick **Complete** or **Cancelled** to bring them back. The filter goes back to its default when you reload the page.
+
+Two other things narrow the list. The search box matches a task's title, description and activity type. The **Activity Types** panel on the left limits the list to one type, and that choice is kept in the address bar; pick **All** to clear it. The panel's counts include only tasks that are not complete or cancelled, whatever the Status filter says, and it lists only types that have such tasks. On a narrow screen the panel is hidden, and the arrow on its edge collapses it on a wide one.
+
+## How are tasks sorted and grouped?
+
+Highest priority first, then newest. The priority badge colours the number: 0–3 is Low, 4–6 Medium, 7–8 High and 9–10 Critical.
+
+**Group by** in the card header splits the list into headed sections, each with a count:
+
+- **Due Date** — Overdue, Today, Tomorrow, This Week, Later and No Due Date, in that order.
+- **Created Date** and **Updated Date** — one section per day, newest first.
+- **Activity Type** — one section per type, with No Activity Type for tasks without one.
+
+Grouping, like the Status filter, resets when you reload the page.
+
+## How do I mark a task done or change its status?
+
+Tick the checkbox at the start of the row. The task becomes **Complete**, its row dims and its title is struck through; untick it to put it back to **In Progress**. Ticking the box does not change % Complete — edit the task if you want that at 100%.
+
+For **Needs Attention** or **Cancelled**, open the row's **⋮** menu and choose **Change Status**. A task that leaves the Status filter's selection drops out of the list straight away. To change anything else, click the task's title or choose **Edit Task** from the same menu; the edit dialog also shows when the task was created and last updated. An icon beside a title means the task has a description, and hovering it shows the first lines.
+
+## How do I start an activity from a task?
+
+Choose **Start Activity** from the row's **⋮** menu, or hover the row and click the green play button at its end. An activity named after the task starts running under its activity type, and a banner with its running time appears at the top of every dashboard page until you stop it.
+
+The task needs an activity type, and it cannot be complete or cancelled. If another activity is already running, you are asked whether to stop it first — **Stop & Start** does both. You can start from the same task as many times as you like; each start logs a new activity linked to that task, so the time you spend on it adds up over several sittings.
+
+## Why can't I delete a task?
+
+Because an activity is linked to it. Once you have started an activity from a task, the task is kept so that logged time still has its task, and **Delete** fails with *Cannot delete task with linked activity*. Delete those activities under **Activities** first, then delete the task — or set the task to **Cancelled** to keep the history and hide it from the list.
+
+A task that never had an activity started from it deletes straight away after you confirm. There is no undo.
+
+The same link works the other way: an activity type cannot be deleted from **Library → Activity Types** while any task uses it, and the message says how many tasks are in the way.