# Codecks Manual
Fundamentals
===================
Welcome to Codecks! This guide introduces the core concepts and shows you how to get started with a production tool built specifically for game development. Whether you're a solo developer or part of a large studio, you'll learn how Codecks helps you organize assets, track work across disciplines, and ship your game.
## Cards: Your Atomic Work Units
Codecks uses a trading card game metaphor where every task, [document](/doc-cards/), or bug is represented as a card. Unlike traditional Kanban where cards only exist in columns, each Codecks card is self-contained with its own [workflow](/workflow/) state, properties, and [conversation](/conversations/) threads. The card is the source of truth, not its position in a column.
Cards move through a built-in lifecycle: Unassigned → Assigned → Started → Review → Done. You can organize them by any dimension you need: [owner](/owner/) (who's working on it), [milestone](/milestones/) (when it ships), [priority](/priority/) (how important), [effort](/effort/) (how big), or custom [tags](/tags/).
> **The Big Advantage:** View the same cards multiple ways without duplication. A Task Deck shows coding work, while [Hero Cards](/hero-cards/) organize those same tasks by asset. Switch views freely; the card's state stays intact.
## Decks: Your Organized Backlog
Cards are organized into [decks](/decks/), with each card belonging to exactly one deck. The Decks tab serves as your backlog, containing all the tasks, ideas, and bugs you might tackle in the future. Codecks offers four [deck types](/decks/#deck-types) optimized for different kinds of content:
- **Asset Decks** - Game content like enemies and weapons (cards become [Hero Cards](/hero-cards/))
- **Task Decks** - Discipline-specific work queues
- **Knowledge Decks** - Documentation and meeting notes
- **Mixed Decks** - For when you need flexibility
You can group related decks into [Spaces](/projects/) to keep your project organized. A typical game project setup includes a GDD space containing your Asset Decks, a Tasks space with decks organized by discipline (Art, Code, Animation, Audio, Design, QA), and a Knowledge space for documentation. This structure gives you both an asset-oriented view for producers and a discipline-oriented view for individual contributors.
## Milestones and Runs: Time-Based Planning
Codecks helps you break work into manageable chunks through two complementary systems.
- **[Milestones](/milestones/)** are collections of cards tied to specific delivery dates like "Alpha Build - Dec 2025," "Vertical Slice Demo," or "Early Access Launch." They answer the question "what are we shipping by when?"
- **[Runs](/runs/)** are recurring work cycles (weekly, biweekly, or monthly sprints) that help you commit to specific work in the near term. They answer "what are we doing this week or this sprint?"
## Hand: Your Personal Queue
Your [hand](/hand/) is a personal queue of cards you plan to tackle next, like a hand of cards in a card game. The Hand tab serves as your home base in Codecks, showing your cards, conversations, runs, due dates, and team activity all in one place. The hand creates healthy WIP (work in progress) limits - when your hand feels cluttered with too many cards, it signals that it's time to finish something before starting more.
You can think of a card's lifecycle as a commitment funnel with increasing levels of urgency:
1. Cards start in a Deck ("we should probably do this"),
2. get assigned to a Milestone ("we're shipping this by December"),
3. pulled into a Run ("we're doing this in the next sprint"),
4. added to your Hand ("I'm tackling this today or tomorrow"),
5. and finally marked as Started ("I'm working on this right now").
This funnel works for larger studios with formal planning, but smaller teams or solo devs might skip straight from Deck to Hand. Codecks adapts to your scale.
## Community Features
Codecks includes unique integrations built specifically for game studios who want to engage with their community. The [Discord integration](/discord/) lets you collect bug reports directly from your Discord community, while [Open Decks](/open-decks/) allow you to publish and maintain a public roadmap that updates automatically from your internal Codecks project. You can also use [User Reporting](/user-reports/) to collect bugs and feedback directly from your game through Unity, Unreal, or the API, making it easy for players to report issues without leaving your game.
## Setting Up Your Project
When you create a new project in Codecks, you'll be asked "What stage are you in?" and offered a set of templates keyed to the phase of your game: **Conception**, **Pre-Production**, **Production**, and **Post-Production**. Each provides an initial scaffolding with sensible decks, spaces, and sample cards appropriate for that stage. There is also a **Software Project** template for studios using Codecks beyond game development, plus a blank option if you'd rather start from scratch. The templates are designed as inspiration — customize them to match your specific game and team structure.
When you create your very first project, Codecks also sets up an **Inbox** Deck and assigns it as the [Default Inbox Deck](/decks/#default-inbox-deck) for everyone on your team. This means any Card you create without picking a Deck lands in the Inbox automatically, giving you a frictionless place to dump ideas while you figure out your project structure.
The [Project Setup guide](/project-setup/) walks you through a battle-tested structure: a GDD space for assets, a Tasks space for discipline-specific work, and a Knowledge space for documentation. Using [Journeys](/hero-cards/#journeys), you can define repeatable asset pipelines that automatically generate the right tasks for each new asset. This structure gives you dual perspectives that stay in sync - producers can track asset completion status while individual contributors see their discipline-specific work queues.
## Onboarding Quests
As you start using Codecks, you'll find a list of **Quests** in the navigation — small guided tasks that walk new teams through key features (creating a Card, setting up a Run, inviting a teammate). Each completed Quest unlocks the next one.
Quests are tracked at the **organization level**: when one team member finishes the "Create your first Run" Quest, that step is marked done for everyone. This avoids the situation where every new hire is asked to re-do the same setup steps on a project that's already up and running.
If you've invited people who shouldn't be poked to change project structure (e.g. external collaborators or seat-courtesy staff users), you can switch the **Quests for staff users** setting under Organization Settings > General to **Simplified**. The Simplified mode hides any Quests that would modify org-wide data and keeps only the read-only "get oriented" ones.
## What's Next?
Now that you understand the basics, explore the rest of the manual to deepen your knowledge. The [Scope-Driven Production](/scope-driven-production/) page explains the methodology behind Codecks and why it's designed the way it is. The [Project Setup](/project-setup/) guide provides a detailed walkthrough for structuring your project with GDD and Task spaces. Learn how to create repeatable asset pipelines in [Hero Cards & Journeys](/hero-cards/), understand day-to-day card mechanics in [Workflow](/workflow/), [Conversations](/conversations/), and [Hand](/hand/), or discover power user features like [Shortcuts](/shortcuts/), [Bulk Actions](/bulk-actions/), and [Tags](/tags/).
The system adapts to what you need. Small teams can skip structure and work from the hand. Large studios can build complex pipelines with dependencies and forecasting. **Welcome home.** You've found a project management tool built by game developers, for game developers.
# Scope-Driven Production
Game development has adopted production methodologies from other industries. Scrum emerged from manufacturing. Kanban from automotive. Agile from enterprise software. These frameworks have brought valuable discipline to creative work, and we respect the problems they solved.
But game development is distinct. We ship interconnected assets and features, not isolated tickets. Our teams are highly specialized, not interchangeable. Our work flows through parallel pipelines, not linear boards. The estimation challenges we face are structural, not procedural.
We believe game production is ready for its own methodology that reflects how successful studios actually work. Not a rejection of what came before, but an evolution built on our industry's specific needs. We have observed these patterns across studios that ship well, and we are giving them a name and a structure so they can be taught, refined, and supported by better tooling. **We call this approach Scope-Driven Production.**
## Tenet 1: Assets Over Tickets
**The principle:** The primary unit of game production is the asset, not the task.
**Why this matters:** Games are made of concrete things like weapons, characters, levels, dialogue trees, and sound effects. These assets have identity, state, and dependencies that persist throughout production. When we organize work around assets rather than abstract tasks, we gain clarity about what we are building and where it stands.
**How it works:** Tasks don't disappear. They live in service of assets. The asset is the anchor. The tasks are the work required to complete it.
> **The test question:** Can you answer "What is the current state of the broadsword needed for Level 3?" If your system lets you trace an asset from concept through completion, seeing all related work and dependencies in one place, you are practicing this tenet.
## Tenet 2: Estimation by Discipline
**The principle:** Art, engineering, design, and audio have different effort costs. Measure them separately.
**Why this matters:** Game teams are specialized. A character artist cannot complete a networking task, and a sound designer cannot unblock a shader bug. Different people have different capacities and velocities, which means you need to track effort separately by discipline to understand your real constraints.
**How it works:** One asset might require 3 days of art, 1 day of engineering, and half a day of audio. These aren't interchangeable - you need to track them separately to see where your bottlenecks are.
> **The test question:** Can you see, at a glance, how much art effort versus engineering effort remains in your milestone? If your system tracks effort by discipline and lets you assess workload per team, you are practicing this tenet.
## Tenet 3: Estimation by Asset Type
**The principle:** A shotgun is two pistols. Compare within asset types, not across them.
**Why this matters:** Traditional story points ask you to compare incomparable things. How do you calibrate a story point for implementing a credits screen against creating a new enemy type? They're fundamentally different kinds of work and frames of context. A "5-point story" is unintuitive when you're mixing asset types.
**How it works:** Estimate within asset categories instead. Compare enemies to other enemies. Compare weapons to other weapons. Ship a few assets in a category and use that completed work as your baseline. A standard pistol took 28 effort points across all disciplines. A shotgun needs more animations, more VFX, more balance tuning - probably 1.5x or 2x the pistol. You're not guessing hours, you're saying "this is like that, but bigger."
**The benefit:** Comparisons within asset types are intuitive because the work is structurally similar. Your estimates improve with every asset you complete in that category. After shipping 5 enemies, your enemy estimates become reliable. After shipping 5 weapons, your weapon estimates become reliable. The data compounds over time.
> **The test question:** Do you estimate new assets by comparing them to completed assets of the same type? If you can say "this enemy is 3.0x a standard enemy" based on shipped work, you are practicing this tenet.
## Tenet 4: Parallel Pipeline Architecture
**The principle:** Assets flow through multiple disciplines simultaneously, not sequentially through a single board.
**Why this matters:** A character requires concept art, modeling, rigging, animation, and implementation. Some work is sequential (you can't animate without a rig), while other work runs in parallel (VFX and implementation can happen simultaneously). Linear Kanban columns (To Do → In Progress → Done) can't capture this complexity.
**How it works:** During pre-production, you design pipeline templates for each asset type. During production, you apply these templates to new assets. Over time, you refine them based on what you learn. The pipeline becomes institutional knowledge, encoded in structure, not dependent on tribal memory.
> **The test question:** Can you see all disciplines working on an asset in a single view, with clear stages and handoffs? If your system supports configurable, parallel pipelines with predefined stages, you are practicing this tenet.
## Tenet 5: Scope Control
**The principle:** You control scope through data. Adjust what you're building based on what you can actually ship.
**Why this matters:** Asset count × effort × complexity ÷ velocity = ship date. When you know your team's velocity (how much work you complete per sprint) and the total effort required for your remaining assets, you can project a completion date. More importantly, you can manipulate the variables to control your timeline.
**How it works:** Cut 10 assets and your ship date moves up 2 weeks. Reduce complexity and gain another week. Add capacity and gain 3 more weeks. Increase quality (higher effort per asset) and your date pushes out. These aren't guesses - they're calculations based on your team's actual performance.
**The benefit:** This approach is not perfect, but it is improvable. Each completed asset refines your understanding. Each sprint updates your velocity. Your projections get better because they're built on structure and real data.
> **The test question:** Can you look at your remaining scope and current velocity and project a realistic completion date? More importantly, can you adjust scope variables and understand the timeline impact? If you can control your scope through informed trade-offs rather than wishful thinking, you are practicing this tenet.
## Why This Matters for Game Development
Traditional project management treats all work as interchangeable units flowing through sequential stages. This works for assembly lines and software features, but breaks down for games.
**Game development is different:**
| Characteristic | What it means | Why traditional PM fails |
|----------------|---------------|--------------------------|
| **Asset-heavy** | Building concrete things with persistent identity | Can't track "where is the Broadsword?" |
| **Multi-disciplinary** | Each asset needs specialized work from different people | Can't measure art effort vs code effort |
| **Parallel** | Work happens simultaneously across pipelines | Linear columns don't capture parallel work |
| **Iterative** | Scope refines based on learnings | Bottom-up estimates drift out of sync |
**What Scope-Driven Production gives you:**
- **Clarity:** See what you're building (assets) and what it takes (effort by discipline)
- **Flexibility:** Organize by asset or discipline without duplication
- **Predictability:** Calculate scope from data, not hope
- **Scalability:** Templates that work for 10 assets or 1,000
## Closing Words
Scope-Driven Production is not a rejection of existing methodologies. Iteration matters. Adaptation matters. Responding to change matters. These principles remain valuable.
What we are proposing is a layer of structure designed specifically for how games are made. We did not invent these ideas. We observed them in studios that consistently deliver. We are offering language and framework so these practices can be shared, taught, and improved upon.
If your production process already embodies these tenets, you are practicing Scope-Driven Production—whether you have called it that or not. If some of these ideas are new to you, we invite you to experiment with them.
This manifesto is a starting point, not a final word. We welcome conversation, critique, and collaboration from producers, leads, and directors who care about how games get made.
**Game development deserves production methodology built for game development.**
---
*The Scope-Driven Production methodology is developed and maintained by Codecks. For tooling, resources, and discussion, visit [codecks.io](https://codecks.io)*
# Project Setup
This guide shows you how to structure a game project in Codecks following [Scope-Driven Production](/scope-driven-production/) principles.
## Starting Point: Templates vs Blank
When you create a new project, Codecks offers genre-based templates (RPG, Puzzle, Action, Strategy, and more) that provide initial scaffolding. Each template includes:
- Pre-configured spaces and decks organized by genre conventions
- Sample asset cards demonstrating the structure
- Suggested tags relevant to that game genre
- Journey templates for common asset types
**Templates are inspiration, not prescription.** Every game is unique, so treat templates as a starting point that you'll customize heavily. The structure below represents best practices, but your specific game and team may require different organization. If you're experienced with Codecks or have a clear vision for your project structure, feel free to skip the templates and start with a blank project.
## Step 1: Create Your Spaces
Under your [project](/projects/), create three spaces to organize your decks into logical groups. Each space serves a distinct purpose and uses a different deck type to optimize how you work with its contents.
- **GDD Space (Game Design Documents)** - Set the default deck type to Asset Decks, then create decks for your asset categories like Enemies, Weapons, Levels, Characters, Systems, NPCs, and Items. Each card in these decks represents one complete asset or feature that will flow through your production pipeline.
- **Tasks Space** - Set the default deck type to Task Decks and create decks organized by discipline: Code, Art, Animation, Audio, Design, and QA. These hold the actual work items that individual contributors will tackle, separated by their area of expertise.
- **Knowledge Space (optional)** - Set the default deck type to Knowledge Decks and create decks for Meeting Notes, Technical Docs, Design Decisions, and Postmortems. This keeps your documentation organized and accessible without cluttering your production decks.
## Step 2: Define Asset Pipelines with Journeys
This is where Codecks becomes powerful. [Journeys](/hero-cards/#journeys) are reusable templates that define the standard pipeline for each asset type.
### Example: Enemy Pipeline
Open your "Enemies" deck → click the Journey button → create these steps:
| Step | Deck | Tags | Effort |
|------|------|------|--------|
| Concept | Art | concept-art | 2 |
| Model | Art | 3d-modeling | 5 |
| Rig | Art | rigging | 3 |
| Animate | Animation | - | 8 |
| Implement | Code | - | 5 |
| VFX | Art | vfx | 3 |
| Tune & Polish | Design | - | 2 |
| QA Pass | QA | - | 2 |
**What happens:** When you create a new enemy and click "Start Journey," all sub-cards are created automatically in the right decks with the right effort values.
### Add Dependencies
Define workflow order with [Journey Dependencies](/dependencies/#journey-dependencies) to make it clear which work can happen in parallel and which steps must wait. Team members instantly see what's blocking them and what they can start.
- **Sequential work** - Animation requires Rig to be complete first (can't animate without a rig)
- **Parallel work** - Implementation and VFX both require Animation, but can happen simultaneously
- **Final gate** - QA Pass requires everything else to be complete before it can begin
## Step 3: Get Dual Perspectives
This structure gives you two simultaneous views of the same work.
### Asset View (for producers, directors)
Open the **Enemies deck** and you'll see all your enemies as [Hero Cards](/hero-cards/). Each card shows completion at a glance - Orc Warrior is 60% done, Fire Elemental is stuck on rigging, Ice Giant hasn't started. You can quickly track which assets are on schedule, which are blocked, and where effort is concentrated.
### Task View (for individual contributors)
Open the **Art deck** and you'll see all art tasks across all assets. Artists can find their next modeling task without hunting through individual asset cards. They can [sort](/sorting/) by priority or view their personal queues while the context about which asset each task belongs to stays visible.
**Both views stay in sync automatically.** Same cards, different angles.
## Step 4: Set Up Milestones and Runs
Break your work into manageable chunks.
### Milestones (the "when")
Create [milestones](/milestones/) for major releases like "Alpha Build - Dec 2025," "Vertical Slice Demo," or "Early Access Launch." When you assign Hero Cards (assets) to milestones, the sub-cards automatically inherit that milestone, letting you see total effort by discipline. This gives you a clear view of how much art, code, and design work remains for each release.
### Runs (the "what's next")
Create recurring [runs](/runs/) for work cycles, choosing a cadence that matches your team's pace. Weekly runs work well for fast-paced teams doing early prototyping, biweekly runs are most common and balance planning with execution, while monthly runs suit teams working on large features with slower-paced production. Assign specific sub-cards to the current run, then review completed effort after each run to track your team's velocity over time.
## Step 5: Refine Over Time
As you ship assets and learn what works, continuously refine your setup to better serve your team. The structure should adapt to your needs, not the other way around. Here are common refinements teams make:
- **Update Journeys** - Found a missing step in your pipeline? Add "Tech Art Pass" to the Journey template and all future assets will include it automatically.
- **Adjust Effort** - After shipping 10+ of an asset type, update the effort estimates in your Journey templates based on actual data to improve future predictions.
- **Split Decks** - When a deck grows to hundreds of cards, consider splitting it. "Art" might become "Character Art" and "Environment Art," or "Code" splits into "Gameplay" and "Engine."
- **Merge Decks** - If two decks each have fewer than 10 cards, merge them together. "Props" plus "Pickups" can become a single "Items" deck.
## Common Variations
The structure adapts to different team sizes and project types. Here are the most common ways teams modify the setup to fit their needs:
- **Small Teams / Solo Devs** - Simplify by combining Art, Animation, and Audio into one "Creative" deck, using fewer Journey steps, or skipping runs entirely and working directly from your [hand](/hand/). The core principles still apply even with a minimal setup.
- **Large Studios** - Add more granular organization with multiple GDD spaces for different areas (Core Gameplay, Meta Systems, UI/UX), split task decks into specific disciplines (Gameplay Code, Engine Code, Tools), or add spaces for Marketing, Localization, and Publishing. Scale the structure to match your team size and production complexity.
- **Live Games / Ongoing Content** - Set up repeating Journeys that define your seasonal pipeline. Create a "Season Content" deck with templates for new characters and items, an "Events" deck for limited-time content, and track velocity per season to project future schedules. This creates predictable production cycles for ongoing development.
## Video Walkthrough
See this video for our best practice tips for how to build your projects around Journeys:
## Next Steps
Once your project structure is in place, deepen your understanding by reading about [Hero Cards & Journeys](/hero-cards/) to master asset pipelines and learning [sorting and filtering](/sorting/) to view your work in different ways. Set up [effort tracking](/effort/) and establish baseline complexity values for your asset types, then create your first [milestone](/milestones/) to define scope and start using [runs](/runs/) to measure your team's velocity. The structure gives you the foundation, but consistent practice with these features gives you the benefits.
# Hero Cards and Journeys
Hero Cards and Journeys are the core implementation of [Scope-Driven Production](/scope-driven-production/) in Codecks.
## Hero Cards
Hero Cards bundle related cards together into a single unit that represents a complete asset or feature. Think of them as **Epics** if you use agile terminology, but with more power. Combined with Journeys, they create repeatable asset pipelines that automatically generate all the tasks needed to complete an asset.
### Creating Hero Cards
There are several ways to create Hero Cards depending on your workflow. You can drag and drop a card onto an opened card to make it a sub-card, use the hero sidebar to attach existing cards or create new ones, select multiple cards and use the [bulk action bar](/bulk-actions/) to group them, or [sort](/sorting/) your view by Hero Card and drag cards into the appropriate lanes.
When you use the parent-card picker (via `Shift+S` while hovering a card, the bulk action bar, or the sub-cards panel of an opened card), the search results are grouped into **Hero Cards** (cards that are already Hero Cards — pick one to attach to an existing pipeline) and **Non-Hero Cards** (regular cards that will be promoted to Hero Cards if you pick them). The same overlay also offers a **Create New** tab if you'd rather spawn a fresh Hero Card on the spot.
Keep in mind two important rules: each sub-card can only be part of one Hero Card, and Hero Cards cannot be nested (no Hero Cards inside Hero Cards).
### Working with Hero Cards
Hero Cards are recognizable by their golden color. Their own workflow states are disabled, and their effort is calculated by adding up the efforts of all contained sub-cards. They can have a priority or be assigned to a [Run](/runs/) or [Milestone](/milestones/). To get a quick overview of the contained sub-cards, hover over the progress bar which fills up as more cards are set to done, with different colors showing cards that are in progress, in review, or blocked. [Beast Mode](/runs/#beast-mode) does not track Hero Cards themselves — only the sub-cards inside them can become beasts.
You can see the full list of contained sub-cards and jump between them by opening the hero sidebar (click on the header bar of Hero Cards, click on the hero icon next to opened cards, or use the `s` shortcut). The sub-list shows all contained cards including their title, owner, priority, effort, run, and milestone. You can remove any sub-card by clicking the small `X` on the entry or use drag and drop to change their order.
For Hero Cards with many sub-cards, there's a search field to filter the list instantly, along with "Expand All" and "Collapse All" buttons to manage grouped views. Use the filter and order buttons to handle larger lists more easily, or `ctrl/cmd + click` on a group header to open that group while closing all others. When you create a new sub-card from the sidebar, it opens and highlights automatically so you can start editing right away.
For more interaction options, click the magnifying glass on top of the list to view all sub-cards in their regular card size. From this view you can use the bulk action bar to perform operations on multiple sub-cards at once, like assigning an owner to several cards in one step. Remember that sub-cards are fully functioning Codecks cards with access to all workflow and conversation features, which allows you to separate the sub-tasks of a bigger feature into different runs and assign them to different owners.
### Filtering Sub Cards
Whenever you're viewing a deck, run, or milestone that contains Hero Cards and sub-cards, you'll find an additional hero filter button on the header bar. This filter lets you show or hide sub-cards that are contained in Hero Cards currently part of the same view, helping you focus on either the high-level assets or the detailed tasks depending on what you need to see.
## Journeys
Journeys are an awesome way for working with Hero Cards. They allow you to template full sequences of Sub Cards and to activate them with one mouse click.
### Preparing Journeys
Journeys are always associated with Decks. To prepare a Journey, open a Deck and click on the Journey button on the Deck header bar. This opens the Journey setup page where you manage the **Journey Steps**: whenever somebody clicks on the Journey icon on a Card within this Deck, the Card becomes a Hero Card containing a list of Sub Cards that mirrors the step Cards that have been set up for this Deck.
All these features combined work towards allowing for a unique asset pipeline system.
Once you're ready to start a Journey, open the card you want to attach the pipeline to and click the "Journey" button towards the bottom to open the "Start Journey" view. This allows you to view and alter the cards that will be created before committing. Clicking the Journey button a second time will show you which cards have been applied, allowing you to add any missing steps.
After creating a Hero Card from a Journey, you have complete flexibility to edit, add, or remove sub-cards as needed for that particular asset. Changes to Journey steps don't affect Hero Cards that were already created using that Journey, so you can refine your templates without breaking existing work.
### The Template Library
You don't have to build every Journey from scratch. Right from the Journey view you can open the **browse panel** to discover Journey templates shared by the community — a library of proven pipelines covering typical game-dev workflows. Find one that fits, import it, and adapt it to your project.
#### Deck Mapping
Importing a template means making it fit your own project. A template's "Code Tasks" Deck probably needs to map to your own "Programming" Deck, for example. When you apply a template, a **mapping step** lets you control exactly which of your Decks each part of the template lands in, so imported Journeys slot cleanly into your existing project structure.
#### Sharing Your Own Journeys
Built a workflow you're proud of? You can save any Journey you've set up as a template. Templates you submit to the community library go through a quick review by the Codecks team before they show up publicly, so the library stays useful for everyone.
### Cloning Journeys
If you've set up a Journey in one Deck and want to reuse it elsewhere, you can clone it to another Deck using the clone button in the Journey setup. This is faster than recreating the same steps manually. You can also clone Journeys via bulk actions when selecting multiple Cards.
### Zones for Journey Steps
For more complex setups Codecks offers to organize your Steps into Zones. They work just like Card Zones when using the [manual order](/sorting/#manual-order-and-zones). This could be used to separate e.g. mandatory from optional tasks or to allow model separate Journeys within the same Deck. When starting a Journey, you can then select or de-select the relevant Steps to just create the Sub Cards you need.
Check the [Dependencies Chapter](/dependencies/#journey-dependencies) to learn how to use dependencies within Journeys.
## Project Structure
See this video for our best practice tips for how to build your projects around Journeys.
Card Basics
===================
# Workflow and Card States
At the heart of Codecks is a unique workflow and conversation model. If you want to make sure to understand how magical Codecks can feel, then this is the part to pay attention to. It can turn your team work into a finely tuned steampunk machinery of joyful efficiency (_you can probably tell, we're really excited about this part_).
By default all cards are in Unassigned state. All other states are optional and may or may not be used depending on your own preference. We recommend using all of them to appreciate the full power of Codecks.
The only cards not using this workflow are [Hero Cards](/hero-cards/) and [Doc Cards](/doc-cards/).
## Unassigned and Assigned card
These are the defaults states for cards with (assigned) and without (unassigned) owners.
Cards can represent whatever you put on them. Not all cards will contain actionable tasks and it is completely fine for cards to always stay in this state if applying a work state to them makes no sense.
Examples for cards where it might make no sense to assign work states are technical or organizational look-up documents, overarching game design documents and similar cards.
## Started cards
Cards that represent tasks and that you are working on should be put into the _started_ state by pressing the play button on top of the opened card. The `spacebar` also starts the card whether you're hovering over a mini card or have the card opened. If the card has no owner yet, starting it will assign it to you first.
Without real-time tracking, clicking the play button on a started card toggles it back to _not started_. With [real-time tracking](/time-tracking/) enabled, the play button acts as a combined start-and-track control on your own task cards: a single click sets the card to _started_ and begins the timer. A second click then only stops the timer, leaving the card in the _started_ state. To mark a started card as no longer in progress in this mode, open the **…** (More Options) menu in the top-right of the opened card and pick _Unstart this Card_.
The play button has additional time-tracking duties when real-time tracking is on. It appears on Hero Cards and Doc Cards (which never enter the _started_ state) purely as a tracker, and it lets you track time on a card that is blocked, in review or owned by someone else without changing the card's workflow state. See [Time Tracking](/time-tracking/) for the full picture.
Started cards are shown in blue color and signal your teammates that you're actively pursuing the work that this card represents.
## Blocked Cards
Alas, as in life not everything in game dev or project management always runs smoothly. While you are working on the card, you may run into a roadblock in the form of missing information, missing assets or technical issues. In this case you may set the card to _blocked_ by clicking the exclamation point icon on top of the opened card.
This opens a special conversation thread. Use it to draw team mates into a conversation and to describe the issue that you're currently facing. Use the portrait icons or typing `@` to add as many team members as you need to resolve the situation. Whereas cards can only be assigned to one person at most, there is no limit to how many of your team mates can be involved in discussions.
If you're working solo or you are blocked by outside influences you can still set the card to blocked even without drawing in additional team members. This will help signal to yourself or to other team members why you currently can't proceed on a certain task.
Send the message by pressing `ctrl/cmd + enter` or click the send button and your mentioned team mates will receive a notification alert informing them that you are stuck and need help. Blocked cards are shown in red color.
As your team members reply to the block conversation and give you valuable information, you get notifications for each reply. Depending on the information you may want to draw in additional people by mentioning them in your comment. Team members that can't help may opt out of the conversation (see the [conversations document](/conversations/) for more info).
Once the underlying issue is resolved, you can unblock the card by clicking on the _unblock this card_ button below the block conversation. This will put the card back into its previous state. The special block conversation will be closed doing this.
If you are running on [real-time tracking](/time-tracking/) the time that the card spends in blocked state is not counted towards the work time of the card.
## In-Review Cards
Let's assume everything now goes swimmingly and you're able to finish the work on the card. If you are looking for the opinion or approval of other team members, you can put the card into _review_ state by clicking the _question mark_ icon above the opened card.
Doing this opens a special review conversation. As with block conversations or regular conversations you may select as many team mates as you want or need. All mentioned team members get a notification and can support you with the required feedback.
As with block conversation it is not required to draw in any person at all and you can set the review state even if you're the only participant. In-review cards are shown in turquoise color.
Once you've gained enough feedback you may end the review state by clicking the 'close this review' button. After doing that the card will ask you if you want to set the card to done as well.
## Done Cards and Archived Cards
Done cards are shown in green color and represent cards that don't have any actionable tasks left to do. You may reach this card state after going through the whole _started_-_blocked_-_review_ workflow or by simply setting a card directly to done. How many or few of the workflow steps you use is up to you and your team. We recommend using the full workflow for maximum magic of course.🧙♂️
Cards which are done feel great but might clutter up your Decks, Runs and Milestones as time passes. Codecks auto archives done cards after a set amount of time. You can customize that time limit in the organization settings (reachable via the joystick button in the top left).
Archived cards look like regular cards with an additional icon on the card. By default they are hidden from the deck view or search results but can be retrieved by using the _include archived_ button in the top-right area of any search popup box. As a shortcut, Decks, Runs and Milestone views also feature a _include archive_ button directly next to the search input field.
You can also skip the auto-archival step and manually archive cards by clicking the _archive_ button in the bottom right area of opened cards. Cards that were archived but not done yet, are shown in a dark gray color to signal that they have become obsolete.
Once a card has been archived you may choose to delete it by using the _remove_ button again in the bottom right area of the opened archived card. It is a good idea to keep around most archived cards to look up information at a later point. Deleted cards can't be searched or found again after deletion.
You can use the [bulk action bar](/bulk-actions/) to archive multiple cards.
## Snoozing Cards
Once a card was started and hasn't been touched in a long time, it will enter a snoozing state. This is basically the app asking: _"Hey haven't heard from you in a long time, is everything okay?"_. You can hit the snoozing icon at the top of the opened card to continue. Changing a property or the card text will unsnooze the card as well.
This state should help you and your team identifying stale tasks. You can configure the time it takes for an untouched started card to snooze via the organization settings.
# Managing conversations
At the core of each team is strong communication. Conversations and [workflow](/workflow/) are two key components of Codecks.
## Creating a new conversation
All conversations live inside of Cards. Click on the conversations button on any opened Card to see all conversations tied to that Card. Hit "New Thread" and your cursor will be placed directly in the comment field, ready to type. Click 'send' or `ctrl/cmd + enter` to open a new thread or to reply to an existing thread.
The conversation sidebar is resizable - drag its edge to make it wider or narrower depending on how much space you need.
Mention [team members](/users/) to draw them into the conversation. You can do this by typing `@` and selecting their name from the popup list or by clicking on their portrait image. Adding teammates to the conversation will notify them that you're looking for their input. You can see who is part of a conversation by looking at the user icons on top of each conversation.
All conversations in Codecks are open. You can read all ongoing or past conversations on any Card that you have access to. If you comment on a conversation that you were not yet part of, you will automatically be added to the participants list and be notified on further replies.
## No-loose ends
Ever had to deal with tasks that were not done because they were forgotten? Tasks that got lost in the gaps of the proverbial project management cushions, to be found again too late and close to a deadline? Codecks features a no-loose ends paradigm 🚀 , which guides many of our design decisions, but here are a couple of key rules:
- **Closable Conversations** Conversations in Codecks have a clear start and end point. As long as a conversation is not closed by a team member, the topic will be regarded as unresolved and all the active participants will receive reminders to push them towards coming to a conclusion.
- **Threaded Conversations** You may have multiple conversations running at the same time on a Card. This allows addressing different topics with different participants on the same Card. Less participants often also helps with coming to a conclusion quicker.
- **Snoozing & Awakening** If you can't act on a conversation right now, snooze it to keep your inbox focused (see below). Snoozed conversations automatically reappear when somebody else comments — so a reply you're waiting on can't slip past you.
- **Smart Notifications** Notifications are automatically dismissed when you inspect them - no need to manually click dismiss buttons. Think of them as an impromptu todo list that stays relevant to what needs your attention right now.
- **Browser Notifications** You can enable real-time operating system notifications to stay on top of conversations even when the Codecks tab is in the background or closed. Enable this per device in your [profile](/profile/#browser-notifications).
## Snoozing conversations
Sometimes you're part of a conversation but can't take action right now - maybe you're waiting on someone else's reply or some other information. To keep your conversation list focused on what actually needs your attention, you can snooze conversations to temporarily move them out of your inbox.
Snoozing a conversation is a manual reminder for yourself: you pick a return time, and the conversation drops out of your hand until then. The available durations are "Until tomorrow" (or "Until next work day"), "For 3 work days", "Until next week", "For 1 week", and "For 2 weeks". You can also un-snooze a conversation again at any time.
Don't worry about missing important updates while a conversation is snoozed: as soon as somebody else leaves a comment on it, Codecks automatically wakes it back up. Snoozing is a reminder, not a mute — it pauses your attention, not the thread.
To snooze a conversation look for the button with the snoozing icon below the comment field. It'll show you a couple of options. You can also trigger the button by hovering over the conversation and hitting `v`. The button needs to be in view for this to work as there might be multiple ongoing conversations on a single Card.
This helps keep your conversation tab focused on discussions that require your immediate attention, rather than being cluttered with conversations you're waiting on others to advance.
## Reactions
Sometimes a full comment isn't necessary, but you want to quickly acknowledge a message, show appreciation, or give simple feedback. Emoji reactions let you do just that directly on individual comments.
**To add a reaction:**
1. **Hover your mouse** over the comment you want to react to.
2. An emoji selection bar will appear.
3. Click on one of your **recently used emojis** for a quick reaction, or click the **add reaction button** to open the full emoji picker and find the perfect one.
A key benefit is that **you don't need to be part of the conversation thread to add a reaction**. This avoids the awkwardness of joining a thread just to drop a quick "👍" or "✅" and then immediately leaving. Whether you opted out previously or are just browsing a conversation you weren't part of, you can add a reaction without affecting your participation status.
Reactions provide a lightweight way to enhance communication, making interactions more seamless and adding a touch of personality to your team's discussions on Codecks.
## Opting-out
Unless you're the owner of a Card, you can remove yourself from a conversation, if you don't have anything to add and don't want to receive further notification. To remove yourself from a conversation click on your own portrait icon on top of the thread. Your portrait icon will become grayed out to signal that you were part of the conversation but opted out from further updates. Codecks will also add a note to let the other participants know.
You may return to the conversation by clicking on your portrait icon again. Other team members might also add you back into the conversation by mentioning you again.
## Conversation View
If you want to get an overview of all conversations that you're part of or that are currently happening in your project(s), open the 'conversations tab' in your [hand](/hand/) dashboard. This will show you all Cards conversations that you're involved in:
- Blocked Cards
- Cards in review
- Cards with open comment threads
The conversation tab focuses on discussions that need your attention. Snoozed conversations are hidden from this view unless they're awakened by new activity — a "X snoozing" button on the right reveals them on demand. You can also inspect any conversation that is going on without your involvement by clicking the 'Show all' toggle next to it. Conversation updates also show up in the activity stream.
The Hand tab is your central dashboard showing your personal work queue, ongoing conversations that require your attention and your bookmarks.
# Card Hand
In Codecks Hands are personal todo lists. They can contain any Card you want to work on, independent of project, milestone, priority — or whether you own the Card at all. That important review waiting on your feedback or a Document Card owned by a teammate can sit right next to your own tasks. You can freely drag and drop Cards to sort them in any order that you want. Like in a Card game you can think of them as your short list of Cards that are relevant right now and will be played next.
A Card can live in several people's Hands at the same time, so the same review or shared Document Card can be on everyone's todo list who wants to tackle it. Importantly, adding a Card to your Hand does **not** make you its owner unless it was unassigned — your Hand simply reflects what you intend to work on, regardless of who the Card belongs to. Starting progress on a Card automatically moves it to the front of your Hand.
In front of your Hand, you'll find the **done pile** which contains all your recently done Cards. As you set Cards to done, they'll be automatically moved out of your Hand into the done pile. The top of the done pile will feature the most recently done Card, but clicking on it allows you to inspect all the Cards of the pile. Below the pile you'll see a small badge showing the **number of Cards** and the **total effort** you've completed since the start of the current week — hover it for the equivalent numbers from the previous week. You may clear your done pile as you like (we recommend daily or weekly).
Your Hand has a limit of how many Cards it can contain. The minimum number is seven Cards, which represent your **top Cards**. Beyond those seven top Cards, your Hand may also contain up to 21 additional Cards (the exact setting can be customized in your organization settings). The default setting is set to 14 (7 top Cards and 7 additional slots).
The Hand icon on a Card's header reflects its Hand status at a glance:
- **Highlighted:** the Card is in **your** Hand.
- **Solid:** the Card is in somebody else's Hand, but not yours.
- **Dashed:** the Card is not in any Hand.
If a Card is in one of your seven top slots, the highlighted icon will also feature a small number specifying the exact spot.
## Hand Management
On any opened Card you can click the Hand icon at the top to open the **Quick Hand** view. This allows you to quickly inspect the relevant Hand — the Card owner's, or your own if the Card has no owner — and drop the Card into any of the slots. You may even re-arrange the order of other Cards in the Hand. You can discard Cards from the Hand by clicking the disCard action that appears when hovering over a Card or by dragging the Card into the lower "Cards not in Hand" section.
When exiting the quick view by clicking outside the panel or pressing `ESC` you will be put back right at your previous location so that you never lose context.
Selecting multiple Cards and clicking the _Hand_ bulk action will open the _quick Hand view_ with all the selected Cards being added to the view. This allows you slot in multiple Cards at once. You can even select Cards that are owned by multiple people and the quick Hand view will feature a user tab for quickly switching between the different relevant Hands. If you hold down the `CTRL/CMD` key before clicking the [Hand bulk action](/bulk-actions/) the quick view will be skipped and all Cards will instead be directly appended to their owner's Hand. If all the selected Cards are already in a Hand, the action will instead discard them from all their Hands without opening the quick view.
When creating a new Card you can choose to add it to the owner's Hand right away by toggling the Hand icon on top the Card-creation dialogue. The Card will be appended to the owner's Hand. This action won't be available if they don't have any open Hand slots available anymore.
## Your Conversations
This section gives you quick access to all the ongoing conversations (reviews, blocks and comments) that you're involved in. Your ongoing conversations will appear in this section until the conversation has been closed or you opted out of the conversation.
By toggling the **Show all** button on the right side you can see all the ongoing conversations in the project, including those that you're not currently part of. Next to it, a **Show Snoozing** button appears whenever any of your conversations is currently snoozed (see [Conversations](/conversations/#snoozing-conversations)). Click it to switch the list to just those snoozing conversations so you can review or wake them up.
## Your Runs
This section will show all Cards owned by you in all your current [Runs](/run/). It will show all Runs that you have access to. This depends on whether there's an overlap with the projects you have access to and the projects that are used in the Run Configuration.
The Runs are ordered as follows:
- If you own no cards, in a Run, the Run will be shown in the bottom group
- Both groups are ordered by the end date of a Run, the closer the end, the higher up it will be
For each Run, Cards will be grouped by Zone as defined by the Run's [manual order](/sorting/#manual-order-and-zones).
You can use drag and drop to move Cards within the section or to your Hand above.
Clicking on the Run's name will open the full Run view in the Timeline.
## Pinned Milestone
You can pin any [Milestone](/milestones/) by opening it and looking for the pin icon 📌. Once pinned, this Milestone will show up in your Hand under the `Pinned Milestone` section. This section will show all your owned Cards of this Milestone. The Cards will be grouped according to the Milestone's [zones](/sorting/#manual-order-and-zones). You can use drag and drop to move Cards within the section or to your Hand above.
Use the `See full Milestone` button at the top right to manage both Zones and see all the Cards of the Milestone.
## Team Hands
Beyond the quick Hand view you can also inspect the Hands of other team members directly from the Hand tab in the **Team Hands** section. Click _manage_ to set which team member's Hand you want to see and the order in which they should appear. This gives you a quick overview of what other team members are working on right now and planning to do next. You may even change the Card order of Cards inside of your team member's Hand by simply drag and dropping Cards. Make sure to establish with your team how and when this is appropriate to do.
If a Card inside a Hand is not accessible to you (e.g. it is a ghost Card - see below - or is inside a project to which you have no access), it will be shown as _inaccessible_ Card featuring the icon of our rogue figure. Accordingly your own private Cards are never shared with your team members and shown as inaccessible to your team members, even if you add it your own Hand. They will see that the Hand slot is occupied by a Card but not be able to get further information. This still relays information the information to them that you're busy with something, but not what exactly.
In addition, both your Hand as well as each Team Hand offer to pick a [Default Inbox Deck](/decks/#default-inbox-deck) via the button at the top right. You can always set your own Inbox Deck from your personal Hand. To set the Inbox Deck for a teammate from their Team Hand you need to be a Producer somewhere in the organization — handy for setting people up so their newly created Cards land in the right place from day one.
## Bookmarks
Bookmarks allow you to keep a shortlist of any set of Cards, even those that are not owned by you. You may use these to quickly access document Cards that you need to look up often. You can bookmark an unlimited amount of Cards and rearrange them freely by drag'n'dropping Cards into place.
A Card can be added to the bookmark list by clicking the bookmark button on the bottom right side of each opened Card. You can also bookmark new Cards right away by toggling the bookmark icon when creating a new Card.
**Ghost Cards** (see below) will always be bookmarked automatically so you won't lose them. Archiving a Card will also remove them from the bookmark tab. To retrieve archived bookmarks you can hit the "Open bookmarks in search view" at the right of the panel and include archived Cards in the search panel.
## Activity
The activity button in the left action bar allows you to inspect all your recent activity. Use the button on top of the activity list to enable/disable activity types. By default all activity types are shown. Enabling a filter will only show activities of that type. You can switch to the activity list of other team members by using the user selection box in the top right of the screen.
You can also access the activity list of an individual team member by clicking the activity icon that appears on hover in the top right corner of each Hand inside the Team Hands section.
## Your Cards
Beyond the Cards inside your Hand, you may see all Cards assigned to you throughout all visible projects and decks by clicking the button featuring your portrait on the left hand side of the Hand tab. As anywhere you can also use the shortcut `q` to access this view quickly.
## Ghost Cards
If you don't specify a deck during the Card creation process, the Card becomes a private ghost Card. That means that the content of the Card is hidden from all other team members. You can't share it via comments or by passing the URL around. You can use these Cards to keep personal notes (_e.g. if you want to edit your radical design proposal before shocking the rest of the team_).
To convert a ghost Card into a regular Card, just put it into a deck. This makes the Card findable by your teammates and lets them appreciate your creation. Note that this isn't reversible: i.e once a Card is in a deck you can't turn it into a private Card anymore.
You can recognize ghost Cards by the cute ghost icon at the bottom of the Card. If you're wondering why a Card is not showing up for somebody else, making sure that you didn't create a ghost Card is a good thing to check first.
# Text Editor
Cards can be as simple as containing brief task descriptions or as extensive as complex design documents.
## Formatting
The card text editor supports the [markdown syntax](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet). Once you save the card, it will be rendered in a way that turns your text, lists and headers into nice looking documents.
To help you with the syntax we've added some helpers.
### Slash Command
You can type `/` anywhere in the editor to open this overlay. It'll allow you to explore both markdown features as well as codecks-sepecific features such as mentioning co-workers or referencing other cards.
### Floating Action Bar
If you start selecting text, an action bar will show up allowing you to format the selected text. Available formatting options are: bold, italic, strike through, code and links.
You can also format without reaching for the action bar: select some text and hit `cmd/ctrl + b` for **bold** or `cmd/ctrl + i` for _italic_. To rearrange your text, `alt + up/down` moves the current line (or selected lines) up and down.
### Preview
If you are unsure how something will look on the final card, you can use the preview mode to see how your formatting will look without having to save the card the first.
### Markdown Mini Cheat Sheet
````
# heading level 1
## heading level 2
### heading level 3
etc
- list element 1
- list element 2
- can be nested too
1. numbered list
2. second entry
a [link](https://example.com)
inline formatting: _italics_, __bold__, ~~strike through~~, `code`
> quote
```
code block
```
---
horizontal rule
````
Check out this [cheat sheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) for more examples like embedding tables or images. Note that Codecks does not support using HTML within markdown.
## Focus Mode
At the top right of an opened card you are able to find the Focus Mode button. Focus Mode allows you to view and edit on a full screen view without any distractions. For even more focus you can enter the `Full Screen` mode at the top right corner of a card in focus mode.
## Checklists
If you want to split up a task into sub steps you may use checklists. The syntax for checklists looks like:
```
- [ ] a task for me
- [ ] another task
- [x] one more task which is already done
- [] works without space as well
```
Saving this card text will show a list of checklist items. You can use the mouse to check off the items directly on the card. You can manually create a checked-off checklist item by putting an 'x' between the square brackets as shown above. Whenever you mark a checklist item as done using the mouse, the text is automatically updated to stay in sync.
Similar to any other activity, changes to checklists are also visible in the history panel of each card.
Checklists are great for items that are managed on a single card. When a checklist item grows into something that deserves its own card, you can promote it: use the **Convert List Items to Sub Cards** action in the card's [More Options menu](/quick-settings/#the-more-options-menu). You pick which list items to convert (incomplete, completed, or all), choose a target Deck, and Codecks creates a [Sub Card](/hero-cards/) for each one — replacing the original list items with `$`-references to the new cards so nothing gets lost. This action is available on regular cards (not private Ghost Cards, and not on cards that are already Sub Cards) that contain list items.
## Referencing other cards
Entering `$` will pop open a list of other recently touched cards. You may modify the content of the list by entering a couple more letters to narrow down the search card list. You can also search for multiple words by separating them with `_`. Select the card you want to reference by using the mouse or by using the arrow keys and confirming with tab or enter. A color-coded link will be entered in the card text.
This is a great way to build multi-card documents in a wiki-style, allowing you to build your full [GDD](https://www.codecks.io/blog/2020/writing-modern-game-design-documents/) in Codecks. The link shows the title and workflow state of the linked card. Hovering over the link will open a mini preview of the referenced card. If you change the title or workflow state of referenced cards, the link will update its appearance automatically as well. Clicking the link opens the referenced card.
You may also reference another card by copy'n'pasting the URL of another card. It will automatically convert the link into a short-hand reference link. To get the URL of a card you can also just click on the dollar sign label shown on top of each opened card.
URLs of cards contain the title so that other people can already infer what the card is about when you paste it into an email or chat. It is good to know that those links remain valid even if the card content changes, so you don't have to worry about breaking links by changing the card text.
These references also work inside of comments.
## Referencing decks
Similar to cards, you can use `$$` to add a deck reference. These deck references will result in clickable elements linking straight to the deck view.
## Referencing team members
Entering `@` will open a list of your team members. You can narrow down the content list by entering some letters of the user name that you want to reference. Selecting an entry via mouse or keyboard will add a link to that user and notify them of the fact that they were mentioned on this card.
Mentioning a user within a card automatically leads to that user watching that card. This means they will receive notifications for important updates to the card.
Mentioning a user within a comment adds them to the conversation if they're not already present.
## Wide Mode
If you want to focus on writing or reading a longer document, you can extend the width of the card container by dragging it with your mouse. This setting will be remembered on your browser.
## Emojis
Entering `:` and a letter will open the emoji selector allowing you to choose an emoji from the list. As you enter more letters the list will be filtered by emojis fitting to your search word.
You don't have to remember the precise emoji name as we have categorized our emojis via keywords. For example entering `:hand` will also offer you the `:pinchedfingers:` emoji although technically the emoji name does not contain the word **hand**. 🦸
## Images & Videos
There are two ways to add an image or video to your card or comment:
1. If you've got an image or video in your clipboard you can simply paste it into the opened editor. It'll upload the file and add it at your cursor's location. The file will also be added as an [attachment](/attachments/).
2. If you already added an image or video as attachment, you can enter `!`. This will open a searchable picker of the card's images and videos. Use your mouse or keyboard to select one, and it'll be inserted at the cursor's position.
Inserted images can be viewed with our image viewer. Note that video playback depends on browser support for the provided video file.
## Tags
Entering `#` will open a list of available tags. Typing more characters will filter the list. You can always "invent" new tags by continuing to type without confirming any suggested tags. For more information on how to work with tags and the difference between project tags and personal tags, refer to the [Tags](/tags/) section.
# Owner
You can assign an owner to each card. The owner usually refers to the person that has actionable work to do on this card or that is responsible for reaching the goal of the card.
## Assigning owner
Open the properties sidebar by clicking on the top button to the right of an opened card. You can also click on the user portrait icon of a card and it will open the sidebar and highlight the owner input area.
You can use the user input field to type the name of an user and to select them from the list or click on one of the proposed username buttons. To remove any owner use the 'None' button.
The list of potential owners is restricted to the people that have access to the card based on the deck it is in. If you don't see a person make sure to put the card into a deck that you share with that person.
You can also use this **shortcut** to assign a card to yourself: hover your mouse cursor over a card and press the `spacebar` to assign it to yourself. If the card was already assigned to yourself, pressing the space button will set the card to in-progress.
You can also use the [bulk action bar](/bulk-actions/) to set the owner of multiple cards at once. By default new cards don't have any owner set.
You're also able to drag and drop cards into the corresponding owner swim lane if your current view is sorted by owner.
Finally there's the [Quick Settings](/quick-settings/) to modify the owner as well as other properties.
# Priority
You can use priority to signal how important a card is. The priority is shown in the bottom right corner of a card.
A card can have one of three priority levels:
- High
- Medium
- Low
You can also use 'none' priority to mark cards that yet have to receive a priority or for cards where a priority makes no sense. By default new cards are created with no priority.
## Assigning priority
Open the properties sidebar by clicking on the top button to the right of an opened card. You may also click on the priority icon and it will open the sidebar and highlight the priority input field. Click on one of the priority icons to set the new priority value.
**Cool shortcut**: hover your mouse cursor over the priority icon of a card and press the keyboard keys 1, 2 or 3 to set the card priority to low, medium or high priority.
You may also use the [bulk action button](/bulk-actions/) to set priority of multiple cards.
Another option is to drag and drop cards if your current view is sorted by priority.
Finally there's the [Quick Settings](/quick-settings/) to modify the priority amongst other properties.## Customizing priority
You can customize the priority labels from your organization settings (reachable via the joystick button). This allows you to use custom labels for each of the priority levels.
A popular alternative to the standard labels are:
- Must Have
- Medium
- Bonus
## Sorting and searching
You can see all cards sorted by priority in ascending or descending order by using the corresponding order-by priority button. You can also search for all cards up to a certain priority level, at least at a certain priority level or exactly at a certain priority level. Just start typing into the search bar and make sure to use the priority labels that you set up.
# What is effort?
Effort is a value that expresses the estimated quantity of work described on this card. What the value specifically means is up to you and your team. You can use it to represent time units like hours or days or you use it to represent more relative units like story points. Together with [priority](/priority/) it is the backbone of your scope management.
## Assigning effort
Open the properties sidebar by clicking on the top button to the right of an opened card. You may also click on the effort number and it will open the sidebar and highlight the effort input field.
You can click on the numbers to set the effort to the corresponding number. You can also use the input field to enter any number manually.
Cool **shortcut**: Hovering your mouse pointer over the effort area of any card and pressing a number keyboard button will set the effort to that. This works on both - the mini cards and also opened cards.
As with most other properties you can also update cards by dragging and dropping them into the corresponding swim lane if your current view is sorted by effort.
Finally there's the [Quick Settings](/quick-settings/) to modify the effort amongst other card properties.
## Effort Scales
You can customize the default effort numbers by going into your organization settings and choosing from..
- Linear (0,1,2,3,4,5,6,7,8,9,10)
- Fibonacci (0,1,2,3,5,8)
- Exponential (0,1,2,4,8,16)
This comes down to a matter of taste. You may also use the input field to enter any number (including those outside of the scale) manually.
You can use the [bulk action bar](/bulk-actions/) to set the effort on multiple cards at once. By default new cards don't have any effort assigned yet.
## Using effort
Make sure you populate this field to enjoy all the project metrics we offer.
We also show effort on top of a lot of the swim lanes that split cards between sorting dimensions. For example: if you choose to sort your cards by [owner](/owner/), you'll see an effort tracking label next to each user name. The label has the format N (M).
N means the sum of all card efforts in this section. M is the number of all cards in this section which don't have any effort associated. We generally advise to use efforts everywhere, including setting cards to zero effort if they are negligible.
Another way to quickly add up effort points is to use the selection feature. The effort icon in the bulk selection header will also show the summed up effort of selected cards. (Did you know you can quickly select lots of cards using shift once you've selected the first card?)
Clicking on the effort icon will open the [quick settings](/quick-settings/), which allow you to quickly set [priority](/priority/), effort, deck and [owner](/owner/) of a card.
## Hero Cards
[Hero cards](/hero-cards/) automatically add up the effort of all their contained sub cards. You may add a custom effort for the hero card itself.
# Attachments
Beyond texts, cards can contain various attachments. You can inspect the attachments of a card by clicking on the paper-clip button to the right side of an opened card.
You can recognize cards containing attachments by the small paper-clip icon on them. Here's a nice **shortcut**: clicking on the icon will open the card with the attachment sidebar already expanded.
## Adding attachments
When dropping any file onto Codecks, the cards will update their look to highlight that you may drop the attachment onto any card on the screen. You may also browse for a file to upload clicking the _browse_ button in the attachments sidebar.
Our favorite way of adding attachments is by pasting via the keyboard (CTRL+V on Windows and CMD+V on Mac). This is the fastest way of getting an image or video from your image editing software, screenshot tool, or file manager into Codecks. You may also use this to add an image or video directly into the [card text](/text-editor/).
## Attachments Sidebar
The attachments sidebar contains all the attached files. Using the buttons on the top you may filter the attachments by type or change their sorting order.
Below you'll see all the attached files with information who added them and when. Individual attachments may also be downloaded onto your machine or deleted.
Clicking on images opens them in the Codecks image viewer. The viewer allows you to zoom and pan the image without leaving Codecks. In the image viewer you may use the arrow buttons to jump between other images attached to the same card.
If a video was uploaded you may watch it inline if your Browser supports playback of the file.
If your attachment order is set to _newest first_ pressing the left arrow will jump to newer images, the right arrow will jump to older images. If you are sorting by _oldest first_ this order is reversed. You sort preference is persisted across all cards.
## Image Cover
You may also use images as card cover images by clicking on the eye icon next to the image. This will open the Image Cover Editor allowing you to fine tune the position of the image. You may also chose whether to render a light or dark title on top of it. Blurring the bottom may be helpful for noisy backgrounds which might make it hard to identify the icons.
## Managing File Storage
The file storage limit for your account is based on the [pricing plan](/plans/) of your organization:
- Free: 1 GB total
- Plus: 1 GB per user
- Pro: 10 GB per user
Individual files (including videos) are capped per upload: **10 MB per file on Free**, and **250 MB per file on Plus and Pro**. The same limits apply whether you drop, browse, or paste the file.
To see how much file storage you are currently using, enter Mission Control (joystick icon in the top left) and click on the _Files_ button. This opens up your files library showing you the total amount of attachments and file size in use. From there you can delete large files that you don't need anymore. This view can also be useful as an alternative way for finding a specific attachment.
# Tags
In Codecks each card lives in only one deck at a time. This makes the project more manageable and nudges you towards creating a reasonable project structure.
Tags allow to extend that basic structure by assigning searchable labels to cards which extend over Decks, Runs or Milestones. You can use these to find all cards relating to a certain theme independent of which Deck, Run or Milestone they're currently in. Cards can have as many tags as you like.
## Assigning tags
You can assign a card tag by writing `#` followed by the tag name in the text of the card. Entering the hashtag character pops open a list of tag proposals which you can select or narrow down by inserting more characters.
Alternatively you may assign and unassign a project tag by using the tag shortcuts in the properties sidebar of any card. Tags that are assigned this way are not added as part of the card text, but kept in a special tag area at the bottom of the card. For searchability or sorting there is no difference between these two tagging styles.
You may also assign tags by using the [bulk action bar](/bulk-actions/) to add and remove tags to multiple cards.
## Project tags and user tags
In Codecks we separate between user tags and project tags. Project tags are officially sanctioned tags which are part of the agreed-upon custom tag taxonomy of your project.
Project tags can only be configured by the project admin and only project tags are shown in the sidebar when creating or editing cards. In case you want to break out of the confined and regulated world of project tags, you can do that too though! These unofficial tags are called user tags and created or assigned with the `#` character in card text.
You can recognize if you're using a project tag or a user tag by looking at the visual representation of the tag. Project tags are highlighted using a black background and the text being shown in white color. User tags are shown as plain colored hashtags.
## Administering tags
To edit project tags click on the _manage_ button in the project tags area of the properties sidebar of any card. You can also go to the **Project tags** section of your project settings.
There you will find a full list of all created tags. From here you can add new tags and rename or remove existing tags. Renaming tags will also update all cards having the old tag to use the new tag instead. This includes updating the card text where the tag name is mentioned by text.
Note that removing a project tag from the settings will _not_ remove all tag instances on cards. Instead they'll show up as 'Deprecated tags' within a card's properties panel.
You may update your personal user tags in the same style through [your profile](/profile/#personal-tags) (accessible by clicking on your profile portrait in Mission Control, reachable via the joystick button in the top left). Note that updating your personal tags won't trigger any card changes.
## Visual Tag Markers
From the project tags admin interface (see above) you can assign a custom color or emoji to each project tag.
### Tag Emoji
You can assign a emoji to a project tag. This will make any card with that tag show the emoji in front of its card title. If the card has multiple emoji tags they will all be shown. Emojis are a great way for highlighting the card tags.
### Tag Colors
Pick one of our pre-defined colors or enter your own hex-based color value.
Setting up a color will add a colored dot onto your cards so that you can visually quickly recognize them. Should the card reference multiple colored tags, the dot will be rendered as a pie chart style dot reflecting all the colors of the associated tags. You can hover the dot(s) to get a textual representation of the tags.
## Auto Tagging
For each Deck, you may automatically assign one project tag. Any card that is created in that deck or moved into that deck will have the chosen tag automatically applied to it. Removing the card from the deck or disabling the auto-tag feature on the deck will also automatically remove the tag again. You can access this feature by clicking the 🤖 button on any deck header bar.
See this video for a walk-through and examples:
## Searching and Sorting
You may use tags as search filter by clicking on a tag link inside a card or by typing the tag name into the search bar. The search bar will automatically recognize tag names and offer the fitting search completion even if you don't lead your input with `#`.
Using the _order-by_ option with tags you can sort cards by project tags, user tags or both.
There is also a tag based selection button (designated with the `#` icon) which allows you to select all cards that share a certain tag. If you select multiple tags, the _and_ and _or_ buttons on top of the order area become enabled. They allow you to switch between searching for cards that share **all** the selected tags or cards that contain **any** of the selected tags.
# Doc Cards
In addition to tracking tasks, Codecks can also be used to manage game design documents and other reference material: Doc Cards are made specificaly for this.
### Creating Doc Cards
You can turn any Task Card into a Doc Cards by selecting the Doc icon on the bottom right side of an opened card (or use the [bulk action bar](/bulk-actions/) to convert multiple cards in one step). Doc Cards can be converted back into a Task Card at any point by selecting the same icon.
### Doc Cards features
This is what sets Doc Cards apart from regular Task Cards:
- No [workflow states](/workflow/): this prevents from accidentally setting document content to Done and having the card archived
- No [priority](/priority/) or [effort](/effort/)
- Word count always visible in the bottom right corner, both in mini and expanded card view
- Dedicated swimlane when ordering by Priority, Effort or Status
### Making the most out of Doc Cards
In order to build wiki-like structures we recommend referencing other cards using $-links, which can be inserted by typing `$` or by copy’n’pasting the URL of another card (more about this in the [Text Editor](/text-editor/) entry on our Manual). This will add a backlink at the bottom of the card for faster navigation.
It's also possible to bundle up multiple Doc Cards under a [Hero Card](/hero-cards/). Hero Cards consisting only of Doc Cards get a dedicated Doc Hero Card look.
Organizing Cards
===================
# Decks
Each Card in Codecks can belong to exactly one Deck. Your collection of Decks can be found in the **Decks tab**. This tab essentially serves as your project's backlog – a collection of all your tasks, ideas, and bugs that you might address at various points in the future, or perhaps not at all. It's the central repository for everything, from broad, ambitious concepts to concrete, actionable tasks.
## Organizing Your Decks
### Deck Types
Each Deck has a type that determines what kind of Cards it holds. You can set the Deck type using the dedicated button in the Deck header. There are four types to choose from:
- **Asset Decks**: For your player-facing assets and gameplay systems. If you drop a Card here without sub-cards, it automatically becomes an empty Hero Card.
- **Task Decks**: Your standard work items containing task Cards and sub Cards. Defaults to Table View.
- **Knowledge Decks**: For documentation and meeting notes. Only allows [Doc Cards](/doc-cards/).
- **Mixed Decks**: The "anything goes" option when you need flexibility.
The Deck picker is smart about types - it won't let you accidentally drop a Card into a Deck type that doesn't fit.
There is a default Deck type for each new Deck that depends on the Space it is in (see below).
- **GDD** Spaces create Asset Decks by default
- **Tasks** Spaces create Task Decks by default
- **Knowledge** Spaces create Knowledge Decks by default
### Using Spaces for Navigation
[Spaces](/projects/) within Projects can be used to further categorize and separate different Deck types, which greatly helps with navigation and organization within your project.
### Deck Descriptions
You can add descriptions to each Deck. This makes it easier for your team to quickly identify where specific Cards belong and how those Cards should be structured, ensuring consistency and clarity.
### Default Inbox Deck
To simplify Card creation, Codecks allows you to set a default inbox Deck per user. This means Cards created by a specific user can be automatically placed in their designated Deck (e.g., new art tasks go directly to the "Art Tasks" Deck). New organizations come with a default Inbox Deck already set up, so you can start capturing ideas immediately.
To configure a default inbox deck for your team members you can use the button on the top right of the [Team Hands](/hand/#team-hands). As a producer, setting this up for each team member ensures their Cards land in the right spot automatically.
### Automation
Each Deck has an automation section, reachable via the 🤖 button on the Deck header bar. Here you can set up rules that apply automatically to Cards in that Deck:
- **Template Card:** define default content and properties that get applied whenever a Card is created in this Deck. Use it for a Card text with bug-reporting guidelines, a checklist for onboarding new team members, or to set a default tag or default owner for every Card in the Deck. It works independently of whether the Deck has a [Journey](/hero-cards/#journeys).
- **Auto-tagging:** [automatically assign](/tags/#auto-tagging) one project tag to every Card created in this Deck.
## Decks in the Codecks Workflow
Decks are a fundamental part of how work is managed and progressed in Codecks.
### Relationship with Cards
- Every Card can be assigned to at most one Deck.
- If you don't specify a Deck when creating a Card, it becomes a private Ghost Card, hidden from other team members. To make it visible and shareable, you must place it into a Deck.
- Once a Card is in a Deck, it can't be made private again.
### Interaction with Other Features
- **Milestones and Runs**: You can assign any Card from your Decks to a [milestone](/milestones/) or a [Run](/runs/) to schedule your work.
- **Hand**: For your next immediate tasks, you might move Cards straight from the Decks tab into your [hand](/hand/).
- **Project Structure**: [Projects](/projects/) are containers for Decks. When setting up a new project, you might create spaces like `Tasks` with Decks for work areas (coding, animation) or `GDD` with Decks for game assets (enemies, levels).
- **Sorting and Filtering**: You can [sort and filter](/sorting/) the Cards within any Deck to view them in different ways, such as by priority or owner. Decks also support a `Manual` order where you can define a custom order via drag and drop, which is shared with the team.
- **Default Order**: You can define a [**Default Order**](/sorting/#default-view) for how Cards are displayed in a Deck. This shared preference will be the initial view for team members or public visitors (if part of Open Decks, see below).
- **Automation**: Each Deck can [apply a default Template Card and auto-assign a tag](#automation) to new Cards via the 🤖 button on the Deck header bar.
- **Journeys**: [Journeys](/hero-cards/#journeys) (template-based Sub Card creation) are always associated with Decks. To prepare a Journey, you open a Deck and click on the Journey button on the Deck header bar.
- **Guardians**: The [Guardians](/guardians/) feature, which helps manage Card completion workflows, can be enabled in the header area of any opened Deck by looking for the shield icon. Only appointed Guardians (and Producers/Admins) can then mark Cards in that Deck as done directly.
- **Open Decks**: When you make a project public using [Open Decks](/open-decks/), visitors will see all the Decks contained in that public project. You can set a default Card order for these public Decks. Quick links (🌍 icon) to the public page of a Deck appear on the Deck header.
# Projects
A project is a container for decks as well as an instrument for limiting access within your organization. Each deck belongs to exactly one project. An organization may create multiple projects. On the [Free plan](/plans/) you can create up to 3 projects. On paid plans there's no limit to the number of projects you can create.
## Creating a project
By default your account will already contain one project. To create a new project, open the mission control side panel (click on the joystick icon in the top left) and use the _add_ button next to the project's label. You can use drag and drop to change the sorting position in which your new project is shown. This sorting position is user-specific and won't affect the order for anyone else in the team.
## Setting a project image
You can already assign an image during the creation step. If you want to set the background image of an existing project, drag and drop an image file onto the project tile in the sidebar or use the Project Settings.
## Managing visibility
You can use mission control (click on joystick at top) to show and hide projects quickly. Use this depending on whether you want to focus on a single project or prefer to have an overview of everything that is happening.
Click on the checkbox or anywhere on the project tile to show or hide the project. You can also click on the bullseye button to hide all other projects and only show the selected project.
If you hide a project you will not see any cards belonging to decks within that project. You will still see notifications for all projects though, so you won't miss anything important going on in other projects.
## Archiving Projects
If you don't need active access to a project anymore, you can archive it using its project settings screen. You can access the project settings by clicking the gear icon on the project tile (once you hover your mouse there).
Archived projects are removed from the mission control list and all its cards won't be visible to you anymore. You may restore archived projects at any time by selecting "Show archived projects" in the Mission Control.
## Deleting Projects
In case you feel strongly about not just archiving a project, but completely eradicating any memory of it (_we've all been there_), you can delete it from the project settings screen.
Be aware that there is now way of restoring that data easily. If you regret your choice for any reason, reach out to us and let us know. We might be able to restore your project from backup.
## Spaces: Organizing Decks Within Projects
Projects can be subdivided into **Spaces** to group related [decks](/decks/) together. Each project starts with a default space, and you can add more using the **Add Space** button.
### Space Types
When creating a space, you can choose from predefined templates or create a custom one:
**GDD** (Game Design Documents)
- Icon: 📋 GDD
- Default deck type: **Asset Decks**
- Purpose: For decks containing your game's assets ([Hero Cards](/hero-cards/) like enemies, weapons, levels, characters)
**Tasks**
- Icon: ✓ Tasks
- Default deck type: **Task Decks**
- Purpose: For work area decks (Code, Art, Animation, Audio, Design, QA)
**Knowledge**
- Icon: 📖 Book
- Default deck type: **Knowledge Decks**
- Purpose: For documentation decks containing [Doc Cards](/doc-cards/) (meeting notes, technical docs, postmortems)
**QA**
- Icon: 🐛 Bug
- Default deck type: **Task Decks**
- Purpose: For decks focused on bugs and issues
**Custom**
- You can create your own space with a custom icon and name
- Default deck type: **Mixed Decks** (accepts any card type)
The space type determines which [deck type](/decks/#deck-types) is used by default when you create a new deck within that space. For example, creating a deck in your GDD space automatically makes it an Asset Deck, while creating a deck in your Tasks space makes it a Task Deck. You can always change the deck type later if needed.
This space type system is designed to support the recommended structure: GDD space for asset tracking, Tasks space for work organization, and Knowledge space for documentation. But you're free to organize spaces however makes sense for your team.
### Managing Spaces
Once created, spaces can be:
- **Edited**: Change the name, icon, or default deck type
- **Reordered**: Drag and drop to change the order (affects the whole team)
- **Collapsed**: Click the space header to collapse/expand it
- **Deleted**: Only empty spaces can be deleted (you must always have at least one space)
[Decks](/decks/) can be freely moved within and across spaces via drag and drop. Changing the order affects the whole team. Be aware that moving a deck from one project to another might change user access. If this impacts ongoing [conversations](/conversations/), you'll get a warning about how the move will affect discussions. The system will also warn you if card [owners](/owner/) don't have access to the target deck.
To change the order in which projects are shown in the decks view, open Mission Control and drag the project tiles to reorder them.
# Sorting & Grouping
Codecks comes with a powerful grouping mechanism. Learn how to slice and dice your cards to surface the important stuff.
#### Basic principles
The order button shows up in three contexts:
1. Search results
2. Decks
3. Milestones
You can find it in the action bar to the left.
By default, cards will be grouped by `Manual` in milestones and by `Priority` everywhere else. By using the order panel (shortcut `shift+o`) you can pick any of the other available orders:
- [Priority](/priority/)\*
- [Effort](/effort/)\*
- [Workflow state](/workflow/)\*
- [Tags](/tags/)\*
- [Owner](/owner/)\*
- [Run](/runs/)\*
- [Milestone](/milestones/)\*
- Last updated
- Creation date
- Creator
- Deck\*
- [Project](/projects/)
- Title
- [Upvotes](/discord/)
- [Time tracked](/time-tracking/)
- [Due date](/due-dates/)
- [Hero Card](/hero-cards/)\*
- [Beast Level](/runs/#beast-mode)
- Manual (see below)
To get a more compact view, you can activate the `Compact` toggle at the bottom. This will group all cards into a single swim lane. Tags do not support a compact view as a card can show up multiple times if it has more than one tag.
#### Manual Order and Zones
Decks and Milestones have special order: `Manual`. This allows to define a custom order via drag and drop which is shared amongst the team.
Note that within Manual order, relative positioning of cards is preserved when moving them from one milestone or deck to the next.
Rather than working with predefined swimlanes, Manual order allows you to define `Zones`. Cards can be freely moved across and within Zones.
If you have the [permission](/users/) to modify the respective Deck or Milestone, you can create Zones via the `Add Zone` Button at the bottom. If you hover over the Zone name, you can modify its name or change the order. Empty zones can be deleted via the edit dialog.
You can use the `+` icon at the end of each zone to directly add a new card to it. When cards are added another way (either via moving them into the deck or milestone, or via creating them with the red plus button) they are always added at the end of the top-most Zone.
#### Table View
Table View is especially helpful for browsing large deck contents. You can find the option at the bottom of the sort panel.
It supports all sorting options as well as the drag and drop operations of both the manual mode and the other supported sorting options.
#### The swim lane header
The swim lane header consists of up to three parts:
1. **Swim lane label:** Most sorting order allow you to click on the label to add the underlying property as a search entry. This allows you to quickly drill down on interesting properties by continuously iterating search terms and order.
2. **Select all button:** This button only shows when hovering the area with the mouse. It allows you to quickly select all cards of the swim lane. **Pro tip:** if you selected a single card of a swim lane and hitting `ctrl/cmd + a` will select all cards of the current swim lane. Hitting `ctrl/cmd + a` once again will select all visible cards.
3. **Effort summary**: if at least one card in a swim lane has an effort set, this section will be present. It shows the effort of all cards. The number in brackets indicate the number of cards without an effort set. I.e. cards with an effort of "None".
4. **Time tracking summary**: If at least one card has time tracking information associated with it, this section will be shown. Hovering it will show a pop which breaks down the tracked time by user.#### Secondary search order
For cards that share the same attribute of the primary sort order there's an implicit secondary sort order. It's based on priority, then effort and lastly creation date. So if you order by e.g. "Owner", then high priority cards will be shown first for each owner.
You can overwrite this behavior by `ctrl/cmd + click` on an order button. This will effectively push the selected sort order in front of the implicit order defined above. So if you picked "Milestone" as a secondary order while keeping "Owner" as primary order it'll show cards in the nearest milestone first for cards with the same owner. Cards with the same owner and milestone will again use priority then effort and creation date to sort those further.
You can also define more than one secondary search order by `ctrl/cmd + click`ing on additional buttons. The number next to the button indicates the rank of the selected search order. To reset you can do a normal click on the primary order.
#### Default View
Whenever you apply an order in a Deck, Run or Milestone, this choice will be remembered for your browser.
To share your preferences with your team (or in case of a public deck with your audience), you can define a **Default Order**. Do this by looking for the corresponding area at the bottom. When team members or visitors see the Deck, Run or Milestone for the first time they will see cards in the preferred order. They can still pick their own order but will see a small hint at the sort icon as a reminder that they might want to go back to the default view.
# Runs
Sprints are a common tool in the development process. Runs allow you to model your sprints by allowing to set up recurring milestones of a certain length in weeks.
## Set up Runs
First ensure Runs are enabled via the Organization Settings > Features section. (They are enabled by default though.)
Open the **Timeline** tab in the header or press `Shift + 3` on your keyboard. The Timeline tab remembers the last Run or Milestone you opened — clicking it again brings you straight back to that view rather than to a generic timeline overview.
Look for the ➕ icon at the top right. A Calendar opens which includes a `Set up Runs` button in the header.
### Set up a Run Configuration
- **Short Name**: Up to 5 letters. Helpful to differentiate Runs in case there exist parallel Run Configurations.
- **Color**: The color in which the Runs are shown throughout the app.
- **Project-specific**: If left unchecked the generated Runs will be _global_ ones, that can contain Cards from any project. If you make it project-specific, it will only be shown on the timeline if the associated project is currently visible as well. This mechanism can also be used to hide certain Runs from team members that don't have access to the respective project.
- **Run duration**: How many weeks a Run is active
- **Run start day**: This option differs depending on whether you are creating or updating a Run Configuration. When creating a Run Config, you can pick a start date from a calendar. When editing, you can change the weekday the Run starts.
- **Number of upcoming Runs to create**: This number also includes the currently active Run. Once a Run has been finished, a new one is automatically created.
- **Finish Sprint At**: Define the time and time zone at which the Run shall end. Note that 0:00 refers to the beginning of the specified end day, while 24:00 refers to the end of that day.
- **Finish Behaviour**: Here you can configure which Cards should be automatically moved to the next Run once a Run is finished.
All settings can be changed later on. Updating the Run duration will only impact the currently running or future Runs. Updating the start day will only impact future Runs and prolong (or shorten the current one).
### Run Automations
Look for the 🤖 icon in the Run Inspector to set up a couple of useful automations:
1. **Auto Milestone**
Codecks automatically applies the selected milestone to any card added to this Run.
2. **Auto Assign Started Card**
This Option automatically adds started Cards to the Run, unless they're already in another Run.
3. **Auto Assign New Card**
New Cards from the Run's projects will be automatically suggested for the Run. You can adjust this before saving the Card.
Note that option 2. and 3. might result in a situation where a Card could be applied to multiple Run Configurations if their projects overlap. In that case the Run Config is chosen whose current Run's end date is closest.
### Run Description, Statistics & User Capacity
Once a Run is opened, you can click on the `i` button below the **Add Card** button on the left. This will show you the description box as well as statistics about the Run including a burndown chart. The description area allows you to update the description and upload a cover image. This image will also be used for the Run's tooltip.
The shown velocity is accumulating done Cards from the full Run Configuration.
This view also includes Capacity Tracking. It shows how work is distributed across your team mates. You can set the individual capacity of each team member to see who might be overbooked or out of work. Look for the ⚙️ icon at the top right to set and modify the capacity for each user.
If a user is overbooked, the line chart will show striped overlay. If a member still has capacity left, it will be represented with dots.
Users are sorted by the percentage of work done (based on work assigned, not capacity). Note that when editing Capacities, the tooltip shows the Historical Workload for a user helping to identify a good value for future workloads.
The Run header also shows your personal capacity vs work load at a quick glance.
### Deleting Runs
You cannot directly delete a Run Configuration, but you can delete active or future Runs. Deleting a Run sets an implicit stop date for that Run Configuration beyond which no new Run is started even if you change e.g. the Run duration.
You can remove the Stop date to resume the Run by opening the Run Configuration via the cog icon ⚙️ on an opened Run.
## Adding Cards to a Run
There are various ways to do so:
- Open the Card properties by clicking the properties button on the top right side of an opened Card, you can find the Run picker below the priority and effort properties. Click the "Pick" button to select either upcoming or past Runs.
- Select multiple Cards and use the [bulk action](/bulk-actions/) milestone button to add multiple Cards to the same Run.
- Order your Cards by Run to drag Cards between different Run lanes.
- Click on the Run icon on any Card to open the [Quick Settings](/quick-settings/).
There can only be one Run assigned to a Card. To distribute a task over multiple Runs you can consider using [Hero Cards](/hero-cards/).
## Beast Mode
Beast Mode tracks Cards that get pushed from one Run to the next, keeping you aware of what’s slipping through the cracks. The more a Card moves, the stronger its Beast level grows.
A Card within a Run with active Beast mode may be in two states:
1. **Pending:** Cards entering the Run will start out in the `Pending` state. Cards can be moved to different Runs without increasing their Beast level. Cards in the `Pending` state have a `NEW` label at the bottom.
2. **Locked in:** After the grace period has passed, Cards will be locked in. Once locked in, Cards won't be able to move out of this Run without increasing their Beast level.
When opening a Run, you will find the Beast icon in the Run'sheader bar. Codecks offers multiple options to configure Beast Mode.
- **Manually start Beast mode:** hitting this button will lock all Cards within the Run that have been in the Run for longer than the grace period. This button is available even if you've set up the "Auto Activate" option below. Once Beast Mode is active, the Beast icon will turn red.
- **Auto-activate Beast Mode:** Allows you to set up the number of days after which Beast Mode is activated. This setting affects all Runs within this Run Configuration. Once scheduled, the Beast icon will turn yellow.
- **Beast Grace Period:** The grace period determines how long a Card might be in a Run with activated Beast Mode before being locked in. If a Card has been added to a Run before the Run has started, the Run's start time will be considered for the grace period.
Beast Mode is a feature available in the `Pro` plan.
## Working with Runs
### Run Icons
Cards with a Run will show a small circular-ish arrow icon. Hover over the icon to see more information about the current state of the Run.
Cards with a past Run will show an empty Icon. The current one will be filled whereas future ones are also filled but show a dashed outline.
### Run Tab in the Hand
This section displays all Cards you own across your current [Runs](/run/). If multiple Run Configurations are active at the same time (for instance if their schedules overlap), each Run is shown as its own section so you can see them side by side. The tab label switches between "Run" and "Runs" depending on how many are currently active.
You'll see all Runs you have access to, ordered as follows:
- Runs where you own no Cards appear in the bottom group
- Within each group, Runs are ordered by end date, with those ending soonest at the top
For each Run, Cards are grouped by Zone as defined by the Run's [manual order](/sorting/#manual-order-and-zones). You can drag and drop Cards within this section or move them to your Hand above. Click on a Run's name to open the full Run view in the Timeline.
# Milestones
Milestones are important due dates for your projects. These may be public release dates or publisher deliverable deadlines. If you're looking for sprints, have a look at the [Runs](/runs/) feature.
The Timeline tab is one of the three main views in Codecks and home to everything that relates to attaching associating tasks with dates. Each card can be assigned to one Milestone. The Milestone view allows you to see all cards belonging to that Milestone independent of which project, deck or workflow state they are currently in.
## Timeline View
To open the Timeline view clicking on the "Timeline' tab in the header or press `Shift + 3` on your keyboard. To create a Milestone, open the Calendar via the button at the top right of the screen. On the calendar, select the preferred date and enter the new Milestone data.
The Timeline view provides an overview of projects' progress via showing Milestones, [Runs](/runs/) and [due dates](/due-dates/). You can use either mouse wheel or drag and drop to move the timeline.
### Features of a Milestone
- Title: The name of the new Milestone. We recommend keeping it short. On some UI elements only the first four letters of the Milestone name are displayed.
- Date: For when this Milestone is due
- Color: The color in which this Milestone is shown throughout the app.
- Project-specific Milestone: If left unchecked the Milestone will be a _global Milestone_ that is always shown. If you make it project-specific, it will only be shown on the timeline if the associated project is currently visible as well. This mechanism can also be used to hide certain Milestones from team members that don't have access to the respective project.
To delete a Milestone, you can click on the bin icon in the Milestone header bar. Doing this won't delete the cards, but unassign all the cards from the deleted Milestone. If the Milestone still contains undone cards, you will get a warning informing you about the number of cards this deletion will affect.
### Milestone Description, Statistics & User Capacity
Once a Milestone is opened, you can click on the `i` button below the **Add Card** button on the left. This will show you the description box as well as statistics about the Milestone including a burndown chart. The description area allows you to update the description and upload a cover image. This image will also be used for the Milestone tooltip.
This view also includes Capacity Tracking. It shows how work is distributed across your team mates. You can set the individual capacity of each team member to see who might be overbooked or out of work. Look for the ⚙️ icon at the top right to set and modify the capacity for each user.
If a user is overbooked, the line chart will show striped overlay. If a member still has capacity left, it will be represented with dots.
Users are sorted by the percentage of work done (based on work assigned, not capacity).
The Milestone header also shows your personal capacity vs work load at a quick glance.
### Calendar View and Milestone Overview
The Calendar button at the very top right of the screen allows you to open the Calendar.
The Calendar View allows you to get a high level overview of your Milestones. You can click on any date to create a new Milestone and use drag and drop to move them around. `Ctrl/Cmd+click` will open the Milestone in inspector view behind.
Next to the Calendar Butto you can find "Show Overview" button allowing you to view metrics for each of the Milestones.
The data includes the amount of [time tracked](/time-tracking/), the [workflow state](/workflow/) of the cards as well as an overview over the [priority](/priority/) and [owner](/owner/) distribution including their completion rate. The length of these bars use are based on the same unit to allow comparisions accross Milestones.
## Assigning Milestones to Cards
You can assign a Milestone to a card in various ways:
- Open the card properties by clicking the properties button on the top right side of an opened card, you can find the Milestone picker below the priority and effort properties. Click the Pick button to allow chosing upcoming and past Milestones.
- Select multiple cards and use the [bulk action](/bulk-actions/) Milestone button to assign multiple cards to the same Milestone.
- Order your cards by Milestones to easily drag cards between different Milestone lanes.
- Use the [Quick Settings](/quick-settings/).
There can only be one Milestone assigned to a card. To distribute a task over multiple Milestones you can consider using [hero cards](/hero-cards/).
## Working with Milestones
### Milestone Icons
Cards with Milestones will show a small Milestone diamond icon. Hover over the icon to see more information about the current completion progress and the due date.
Future Milestones will be filled, whereas past Milestones will only have an outline.
### Pinned Milestone
The top bar of the Milestone inspector includes a pin icon 📌. Pinning a Milestone allows you to quickly move cards between it and your hand without having to leave the hand view.
# Vision Board
While other tabs help you manage short-term tasks ([Hand](/hand/)), your complete backlog ([Decks](/decks/)), and mid-term planning ([Timeline](/milestones/)), the Vision Board gives you the ultimate high-level, "bird's-eye view" of your entire project.
Vision Boards are Codecks' interpretation of whiteboards, designed to bridge the gap between freeform ideation and structured project management. You can use them for quick brainstorming, creating mood boards, or crafting detailed documentation. But their real power lies in their ability to connect with your live project data, allowing you to build powerful dashboards.
You can create a Vision Board on any opened Card using the telescope button. Changes to Vision Boards are tracked in your project's [activity log](/activity/).
## Scope
Vision Boards are attached to individual [Cards](/doc-Cards/). This means access rules for a Vision Board are inherited from its underlying card. For instance, a Vision Board on a private [Ghost Card](/hand/#ghost-Cards) can only be seen by you, and project access restrictions apply as well.
For more organization-wide Vision Boards, you can use the [bookmark](/hand/#bookmarks) feature on the underlying card or create a dedicated [Deck](/decks/) for Cards that hold important Vision Boards.
You can navigate all available Vision Boards via the Vision Board picker at the top left of the screen. The picker shows the last board you opened and provides a list of all others you have access to, named after the titles of their underlying Cards. The card button next to the picker opens the underlying card in a sidebar so you can inspect or edit it without leaving the board. The Vision Board tab in the main header will always take you to the last board you had open.
## Whiteboard Functionality
At its core, the Vision Board is an infinite canvas for your ideas. You and your team can collaborate in real-time to work with the following nodes:
### Node Types
#### Text Node
You can use this for anything from small labels to rich, detailed documents. Text nodes have a solid background for readability and support full [Markdown formatting](/text-editor/), including Codecks-specific extensions like referencing [Cards](/doc-Cards/) with `$`, [decks](/decks/) with `$$`, and [users](/users/) with `@`. You can paste images directly into text nodes, and checklists work just like they do in card descriptions.
#### Image Node
This node allows you to upload an image directly to the Vision Board. For a faster workflow, you may also paste an image from your clipboard or drop a file straight onto the canvas to add it. Image nodes can also have a text label.
#### Video Node
You can embed YouTube videos directly on the board. This is useful for reference footage, trailers, or tutorial videos that your team needs quick access to. Pasting a YouTube URL onto the canvas creates a video node automatically.
#### Card Node
You can either search for any existing Card and add it to the Vision Board, or create a new one. Card nodes have three display modes:
- **Card Lane** – a compact, single-line view.
- **Mini Card** – the standard mini-card view.
- **Full Card** – the full card with description, comments, and properties inline on the board.
Clicking on a Card node opens it in a sidebar so you can inspect and modify it directly from the board.
#### Smart Node
This is a **[Pro](/plans/)** feature that lets you create dynamic, data-driven widgets. You define which Cards a Smart Node represents in one of two ways:
- Write a query to find Cards based on specific criteria, such as "all Cards with high priority in Deck X," "all Cards assigned to User Y," or "all Sub Cards of Hero Card Z."
- Manually add specific Cards to the node by using the plus button on the search results.
Once the Cards are defined, you can visualize them in several ways:
- **Progress Bar** breaks down the Cards by their [workflow state](/workflow/) (Not Started, Started, Snoozing, Blocked, Review, Done). A simple variant shows only the Done portion.
- **Horizontal Bar** and **Vertical Bar** charts visualize the same workflow breakdown stretched along an axis. Useful as labelled status bars inside a larger composition.
- **Donut Chart** (also called Pie Chart) shows the same breakdown radially. You can drop a cover image into the centre and choose between a simple "done vs. open" arc or a segmented one.
- **Number Widget** displays a single big number: either the remaining card count or the remaining effort.
- **Table View** shows all matching Cards as rows. You can customize the columns ([priority](/priority/), [effort](/effort/), [owner](/owner/), [Run](/runs/), [milestone](/milestones/), [checklist progress](/text-editor/#checklists), [deck](/decks/), [upvotes](/discord/)), pick a sort order and direction, and choose whether to hide archived Cards. Inside the table you can select multiple Cards with the checkbox in each row to reveal the standard [bulk action](/bulk-actions/) toolbar, and use `j` / `k` to step through cards once one is opened in the sidebar.
Effort-based charts (Bar, Donut, Number) use [effort](/effort/) values; a configurable fallback effort is used for Cards without one. Smart Nodes automatically generate a label from the filter, which you can override.
Configuring a Smart Node opens a dedicated panel in the left sidebar where you can edit the query, switch the visualization, and tweak its options without leaving the board.
#### Container Node
Containers allow you to visually and logically group other nodes. They can be nested, with sub-containers inside parent containers. Any node that is fully enclosed within a container's boundaries will automatically belong to it, so resizing or moving a container will "capture" other nodes. The easiest way to add nodes to a container is to drag them directly into it. You can also select multiple nodes at once and use the context menu to create a new container around them. Containers can be given a custom label.
### Shared Functionality
- **Colors:** All nodes can be set to a neutral default or one of six accent colors (green, blue, pink, red, brown, yellow).
- **Arrows:** You can draw arrows between any nodes or containers to show relationships. Arrows can also have a color and a label.
- **Clipboard:** Standard cut, copy and paste are supported, including pasting nodes between different Vision Boards.
- **Duplicate:** Quickly duplicate any selected node(s) with `ctrl/cmd + d`.
- **Delete:** Remove selected node(s) using `backspace`.
- **Undo/Redo:** Correct mistakes easily using the buttons on the left or with the standard `ctrl/cmd + z` (undo) and `ctrl/cmd + shift + z` or `ctrl/cmd + y` (redo) shortcuts.
### Adding Nodes
You can add new nodes to the canvas in several ways:
- Click a node-type button on the toolbar to arm the cursor with that node, then click anywhere on the canvas to place it. A dashed placeholder follows the cursor while you aim. Press `Esc` to cancel.
- Drag a node-type button directly onto the canvas and drop it where you want the node placed.
- Double-click anywhere on an empty part of the canvas to open the node picker at that spot. Use arrow keys to navigate the picker.
- Draw an arrow from an existing node into an empty section of the canvas to create a node anchored to that arrow.
- Paste text from your clipboard onto the canvas to create a text node. If the pasted text is a YouTube URL, a video node is created instead.
- Drop image files onto the canvas to create image nodes, or paste images from the clipboard.
### Navigating on the Canvas
- **Touchpad:** Use a two-finger scroll to pan the canvas. Pinch to zoom.
- **Mouse:** Use the mouse wheel to zoom in and out. Right-click or middle-click and drag to pan the canvas.
- **Keyboard + Mouse:** Hold `space` and left-click and drag to pan.
- **Zoom Controls:** Manage and reset the zoom level using the controls at the bottom right of the screen.
- **Zoom Lock:** When using a mouse, you can press `z` to toggle Zoom Lock. With Zoom Lock active, the wheel scrolls the canvas content instead of zooming, and you need to hold `ctrl/cmd` to zoom.
## Multiplayer and Sync
Vision Boards are fully collaborative. You can see your teammates' cursors moving on the canvas in real-time, and any elements they have selected are highlighted with their color. Note that changes inside a text node are not shown in real-time and only become visible once the editing user saves them.
A small status indicator in the top right of the canvas shows whether you're currently connected to the server. If you lose connection, you can keep editing — your changes are stored locally and synced automatically the next time you reconnect. If the automatic sync runs into trouble, an "Attempt Sync" button appears so you can retry on demand.
## Access and Lock States
Whether you can edit a board is determined first by your permissions on the underlying Card, and then by the board's own lock state. The creator of a board and any [admin](/users/) can change its state from the "…" menu next to the Vision Board picker:
- **Editable** — Anyone with access may edit. This is the default.
- **Read Only** — Only the creator may edit; everyone else sees a read-only view.
- **Locked** — No one may edit, including the creator. Switch back to Editable to make changes again.
Deleting a board is also done from the "…" menu and requires creator or admin rights.
## Vision Boards on Open Decks
If you publish a project via [Open Decks](/open-decks/), you can pick a Vision Board to be shown as the project's landing page instead of the deck overview. Configure this under **Project Settings → Open Decks → Vision Board**. Only Vision Boards whose underlying Card lives in the published project are eligible. Visitors see a read-only version of the board and can drill into any Cards that are part of the project.
# Dependencies
Dependencies allow you to track important relations between cards.
To enable the Dependencies feature, access the Mission Control by clicking on the joystick icon 🕹️ in the top left corner of the Codecks website, select _Organization Settings_ button. You will find the Dependencies setting under the _Features_ tab.
## Accessing Dependencies
Once the feature is enabled, any open non-private card will show the gate icon at the bottom right area.
Next to the gate icon which designates dependencies you will find two card numbers, the left showing the number of incoming dependencies (locked-by cards) and the right showing the number of outgoing dependencies (locking card). The strip under each of these numbers is colored by the card workflow states of the representative cards (e.g. green if already done).
Hovering over the dependencies area will show the dependency inspector which lists more details about the individual cards. You can toggle the inspector by clicking on the dependency area on the opened card. Toggling the inspector will make it remain open so you can click on any of the dependency cards to open it.
If a card is locked by dependencies, the mini card will also have a dependency icon. Hovering over the icon will also open the inspector, allowing you to see the dependent cards at a glance.
The dependency icons are color-coded so you can read a card's situation at a glance. When a card still has undone incoming dependencies — meaning it can't be worked on yet — the gate icon is shown with a red highlight on the mini card, the opened card, and in [Table View](/sorting/#table-view). The coloring also makes it immediately visible when a card is _locking_ others, so you can spot the cards that are holding up the rest of the team.
## Adding Dependencies
To add a dependency toggle the dependency inspector on an open card and choose one of the two buttons in the top right of the inspector. You can..
- Add a locked-by card (a card which should be done before this card should be started)
- Add a locking card (a card that will be unlocked by setting this card to done)
A card may have multiple incoming or outgoing dependencies.
## Working on Dependency Cards
If a card has undone incoming dependencies, clicking to [start](/workflow/) work on the card will cause a warning box to appear that will let you know that the card still has unfilled requirements. You may choose to ignore the warning (_if you are a rebel game dev that takes commands from now one, not even Codecks_) or abort the action and let the card remain in the unstarted state. The same confirmation dialog appears when you mark a locked card as **done**, so you don't accidentally bypass its dependencies.
If a card becomes available for work because all its incoming dependencies (locked-by cards) are set to done, the owner of the now available card gets a notification letting them know that their card is ready for action. This is especially useful when the person working on the follow-up card is a different person than the one that worked on the prerequisite cards.
## Journey Dependencies
You may also add dependencies to cards in [journeys](/hero-cards/). Open the journey setup screen and add dependencies like you would for any other card. These dependencies will be applied to the newly created sub cards once the journey is triggered.
To quickly setup complex dependency chains inside of journeys, select multiple cards and use the _Dependency Chain_ [bulk action](/bulk-actions/#hero-cards--dependencies) (it has a gate icon) to add a full chain of dependencies with one click. The dependency chain will be applied to the selected cards and in the order in which they are appearing inside of the journey screen.
For example if you have a journey with cards A-B-C-D-E-F and you select the cards B-C-E and trigger the chain bulk action it will add..
- The dependency B->C
- The dependency C->E
# Due Dates
Due dates allow you to associate a card with a specific date. Non-done cards with pending due dates will be highlighted and create a notification for the card owner on the due date itself (based on their time zone).
### Assign a Due date to a card
Due dates can be assigned both when creating a new card and when editing an existing card. The field can be found in the property panel below the Milestone section. Use the **Pick** button open the date picker to add a due date for this card.
Note that a card can have both a milestone and a due date associated with it. To remove a due date, use the **None** button at the top right.
You can also assign a a due date to multiple cards at once. Select the cards and look for the bell icon with the selection actions.
### Overview of your and your team's Due dates
The [Hand tab](/hand/) contains a section called `Your due cards`. The color indicates the state of the most due cards whereas the number indicates how many cards are in that state:
- **Red:** This card is due today or already overdue
- **Yellow:** This card is due within the next 5 workdays
Note that this color pattern is also applied for the bell icon at the bottom left of the mini card.
Opening that tab shows up to three groups: `Due now`, `Due soon` (again, due within 5 workdays) and `Due later`.
Clicking the `Show all` button at the very right of the panel allows you to inspect all due dates of the team no matter who this card is assigned to.
### Due dates in the Timeline
You can find the Timeline by opening the "Timeline" tab at the very top. Every due card that is assigned to you will create an entry in the timeline via the bell icon. You can click the bell icon to open an inspector showing all your due cards for that day.
### Notifications
If these conditions are met for a card, a notification is created for you at the beginning of the day (based on the timezone of your browser):
- Card is due for today
- Card is assigned to you
- Card is not done
- Card is not archived
To remove the notification you need to change one of these properties above as you cannot directly dismiss the notification.
Advanced
===================
# Search & Navigation
Finding cards quickly becomes essential as your project grows. Codecks search does double duty: it filters the cards you're viewing _and_ lets you jump directly to any card or deck in your workspace. You can open it by pressing `/` anywhere in the app or by clicking the search field in the top navigation bar.
## How Search Works
When you type in the search field, Codecks suggests matching filters based on what you're typing. Select a suggestion and it becomes an active filter, appearing as a pill below the search bar. These filters narrow down which cards are displayed in your current view.
You can stack multiple filters to create precise queries. For example, you might filter for cards assigned to you, with high priority, in the current run - all at once.
### Negating Filters
Sometimes it's easier to describe what you _don't_ want. Start a search with `!` to reveal all the filter options that can be negated — for example "not owned by Sarah" or "not done". Negated options also work for Smart Nodes on the [Vision Board](/vision-board/), so you can build boards that exclude certain cards just as easily as including them.
## Filter Categories
### Filtering by Users
Type `@` followed by a name to see user-related filters:
- **Owner** - Find cards assigned to a specific person. You can also select _"no owner"_ to find unassigned cards.
- **Creator** - Find cards created by a specific person.
- **Mentioned** - Find cards where someone is mentioned in conversations.
- **Bookmarked by** - Find cards that a specific user has bookmarked.
### Filtering by Tags
Type `#` followed by the tag name to filter by tags. Codecks recognizes three types of tags:
- **Project Tags** - Tags managed by admins, often with colors or emojis for visual distinction.
- **Personal Tags** - Your own private tags that only you can see.
- **Inline Tags** - Tags written directly in card text using `#tagname`.
When you filter by multiple tags, you can choose how they combine. By default, cards must match _all_ selected tags (AND logic). But when multiple tag filters are active, an _"or"_ pill appears - click it to switch to OR logic, showing cards that have _any_ of the selected tags.
### Filtering by Status
You can filter cards by their [workflow state](/workflow/):
- `unassigned` - Cards without an owner
- `assigned` - Cards with an owner but not yet started
- `started` - Cards currently being worked on
- `snoozing` - Cards that went quiet for too long
- `blocked` - Cards waiting on something
- `review` - Cards ready for feedback
- `done` - Completed cards
- `archived` - Archived cards (also enables the archive toggle automatically)
- `undone` - A handy filter for all cards _not_ marked as done
### Filtering by Card Type
Quickly narrow down to specific kinds of cards:
- `hero` - [Hero Cards](/hero-cards/) only
- `subcard` - Sub Cards (cards that belong to a Hero Card)
- `doc` - [Doc Cards](/doc-cards/)
- `private` - Private [Ghost Cards](/hand/#ghost-cards)
- `locked` - Cards that are dependency-[locked](/dependencies/), i.e. they still have undone incoming dependencies and can't be worked on yet
- `locking` - Cards that are dependency-locking others, i.e. they're holding up other cards until they're done
- `coverImage` - Cards that have a cover image set
- `beast` - Beast Cards (cards that have overstayed their welcome in a [Run](/runs/#beast-mode))
### Filtering by Priority and Effort
When filtering by [priority](/priority/) or [effort](/effort/), you can use comparison operators for more flexibility:
- Select a single value for an exact match
- `A+` means priority A or higher (i.e., A and above)
- `C-` means priority C or lower
This is particularly useful when you want to find _"all high priority cards"_ rather than just cards at one specific level.
### Filtering by Location
#### Deck, Project, and Space
You can filter to show only cards from a specific [deck](/decks/), [project](/projects/), or Space. Selecting _"no decks"_ shows Ghost Cards that haven't been placed in any deck yet.
#### Zone
If you're using [Manual order with Zones](/sorting/#manual-order-and-zones), you can filter by specific zones.
### Filtering by Run
[Runs](/runs/) have several specialized filters that help with sprint planning:
- **Specific Run** - Cards assigned to a particular Run
- **Current Run** - Cards in whatever Run is currently active
- **Future Run** - Cards scheduled for upcoming Runs
- **Past Run** - Cards from Runs that have already ended
- **Not in Run** - Cards that haven't been scheduled for any Run
### Filtering by Milestone
Filter by a specific [Milestone](/milestones/) or select _"no milestone"_ to find cards that haven't been assigned to any milestone.
### Filtering by Hand Status
- `hand` - Cards currently in your [Hand](/hand/)
- `notHand` - Cards not in your Hand
### Filtering by Due Date
- `dueNow` - Cards due today
- `soon` - Cards due within the next 7 days
- `due` - Any card that has a [due date](/due-dates/) set
### Filtering by Upvotes
For cards created through community feedback (like [Discord](/discord/) integration), you can filter by upvote thresholds: `5+`, `10+`, `25+`, or `50+` upvotes.
### Searching Card Content
#### Title Search
Type `t:` followed by your search term to search specifically in card titles:
```
t:player movement
```
#### Full Text Search
Simply type any text without a special trigger to search across card content. This performs a full-text search through card descriptions.
### Finding Sub Cards
Type `sub:` followed by a card reference or title to find all sub cards of a specific [Hero Card](/hero-cards/).
## Navigation Commands
Beyond filtering, search provides powerful navigation commands that take you directly to cards and decks. These are especially useful once you get comfortable with them - they're faster than clicking through the UI.
### Jump to Card by ID
Every card in Codecks has a unique ID displayed as a short code like `$ABCD` (you'll see it on mini cards and in the card header). Type `$` followed by the code to jump directly to that card:
```
$CODE
```
This is the fastest way to open a specific card when someone shares a card ID with you or when you've noted one down.
### Jump to Deck
Type `gd:` (short for _"go to deck"_) followed by a deck name to navigate directly to that deck:
```
gd:backlog
```
This searches decks within your currently visible projects. If you need to find a deck in a hidden project, use `gad:` (_"go to any deck"_) instead:
```
gad:archive
```
### Jump to Card by Title
Type `gc:` (_"go to card"_) to search for cards by title and jump directly to one:
```
gc:main menu redesign
```
For searching across all projects including hidden ones, use `gac:` (_"go to any card"_).
## Combining Multiple Filters
Filters from different categories combine with AND logic by default. For example, if you select an owner _and_ a priority _and_ a status, you'll see cards matching all three criteria.
For certain categories - tags, titles, and content searches - adding multiple filters from the same category shows an _"or"_ pill. Click it to toggle between AND and OR logic for those specific filters.
## Including Archived Cards
By default, archived cards are hidden from search results to reduce clutter. To include them, look for the _"Archive"_ toggle in the search area and enable it.
When you filter specifically for `archived` status, this toggle is enabled automatically.
## Contextual Search
Search behaves slightly differently depending on where you are in the app:
- **In a Deck** - Filters apply only to cards in that deck
- **In a Milestone** - Filters apply to cards in that milestone
- **In a Run** - Filters apply to cards in that run
- **In the Hand tab** - Filters apply across all your visible projects
You don't need to manually add a deck filter when you're already viewing a specific deck - the context is implicit.
## Quick Reference
| Trigger | What it does | Example |
| ------- | ------------------ | -------------- |
| `@` | Filter by user | `@sarah` |
| `#` | Filter by tag | `#bug` |
| `$` | Jump to card by ID | `$ABCD` |
| `t:` | Search card titles | `t:login` |
| `sub:` | Find sub cards | `sub:player` |
| `gd:` | Go to deck | `gd:backlog` |
| `gad:` | Go to any deck | `gad:archive` |
| `gc:` | Go to card | `gc:main menu` |
| `gac:` | Go to any card | `gac:settings` |
## Keyboard Shortcuts
| Shortcut | Action |
| ----------- | ------------------------------------------- |
| `/` | Open search |
| `Esc` | Close search or clear filters |
| `q` | Toggle _"my cards"_ filter |
| `shift+o` | Open order/sort options |
| `shift+t` | Open tags filter sidebar |
| `Backspace` | Remove last filter (when search is focused) |
import {Aside} from "../../components/MarkdownComponents";
# Bulk Actions
The bulk action bar is one of Codecks' most powerful productivity features, allowing you to select multiple cards and perform operations on all of them at once. This is essential for efficiently managing large numbers of cards.
## Selecting Multiple Cards
There are several ways to select multiple cards:
### Using the Mouse
- **Click to select** - Click the selection icon (checkbox) that appears in the top-left corner when hovering over a card
- **Click and drag** - Click and drag across multiple cards to select them all at once
- **Ctrl/Cmd + Click** - Hold Ctrl (Windows/Linux) or Cmd (Mac) and click individual cards to add them to your selection
### Using Keyboard Shortcuts
| Shortcut | Action |
|----------|--------|
| **`x`** | Select or deselect the card you're hovering over |
| **`ctrl/cmd+a`** | Select all visible cards in the current view |
| **`i`** | Invert the selection (toggle all) |
| **`Esc`** | Clear the selection |
### Tag-Based Selection
In views with [tag filters](/tags/), you can use the tag selection button (designated with the `#` icon) to select all cards that share certain tags. When multiple tags are selected, use the "and" and "or" buttons to switch between finding cards that have all the selected tags or any of the selected tags.
## The Bulk Action Bar
Once you've selected one or more cards, the bulk action bar appears at the top of your screen, replacing the normal header. It shows how many cards are selected and provides quick access to all bulk operations.
## Available Bulk Actions
The bulk action bar groups operations into several categories. Not all actions are available in every context - some depend on your permissions, the organization's enabled features, or whether you're in a specific view (like milestones or runs).
### Moving & Organizing
| Action | Shortcut | Description |
|--------|----------|-------------|
| **Change [Deck](/decks/)** | `d` | Move selected cards to a different deck |
| **Add/Remove from [Hand](/hand/)** | `h` | Add cards to your hand or remove them if already there. Hold `ctrl/cmd` while clicking to skip the quick hand view |
| **Change Bookmark** | - | Add or remove cards from your bookmarks |
| **Assign to [Run](/runs/)** | `,` | Add selected cards to a specific run (if runs are enabled) |
| **Assign to [Milestone](/milestones/)** | `m` | Assign selected cards to a milestone (if milestones are enabled) |
| **Set [Due Date](/due-dates/)** | - | Set or change due dates for selected cards ([Pro](/plans/) feature) |
| **Change Zone** | - | Move selected cards to a different zone (only in manual order views with zones) |
### Card Properties
| Action | Shortcut | Description |
|--------|----------|-------------|
| **Set [Effort](/effort/)** | `e` | Assign or change effort values for multiple cards at once |
| **Set [Priority](/priority/)** | `p` | Change priority (A, B, or C) for selected cards |
| **Change [Owner](/owner/)** | `o` or `space` | Assign cards to a team member or unassign them. Use `space` to quickly assign to yourself |
| **Modify [Tags](/tags/)** | `t` | Add or remove project tags from multiple cards |
| **Convert to/from [Doc Card](/doc-cards/)** | - | Convert task cards to doc cards or vice versa |
### Hero Cards & Dependencies
- **Add to [Hero Card](/hero-cards/)** (`s`) - Add selected cards as sub cards to an existing hero card, or create a new hero card containing the selected cards
- **Create [Dependency](/dependencies/) Chain** (only in [journey](/hero-cards/#journeys) views) - Automatically create a chain of dependencies between selected cards in the order they appear. Example: Selecting cards B, C, and E creates dependencies B→C→E
### Card Management
- **Copy Cards** - Duplicate selected cards to the same or a different deck. Choose which properties to copy: [effort](/effort/), [priority](/priority/), [owner](/owner/), [tags](/tags/), [attachments](/attachments/), [runs](/runs/), [milestones](/milestones/). [Hero cards](/hero-cards/) are copied without their sub cards.
- **Export as CSV** - Export selected cards to a CSV file with customizable fields.
- **Mark as Done** - Quickly mark multiple cards as done (updates [workflow](/workflow/) state)
- **Archive Cards** (`r`) - Archive selected cards that are not already archived
- **Delete Cards** (`backspace`) - Permanently delete selected cards
- **Snooze Conversations** (only visible when in [conversation](/conversations/) threads) - Move unactionable conversations out of your conversation overview for a set time period
## Bulk Actions for Observers
## Common Workflows
### Bulk triage after planning session
1. [Filter cards](/search/) by a specific [tag](/tags/) (e.g., "needs-estimation")
2. Select all with `ctrl/cmd+a`
3. Set [effort](/effort/), [priority](/priority/), and [owner](/owner/) via bulk actions
4. Assign to current [run](/runs/)
### Clean up completed work
1. Filter by [workflow](/workflow/) status "done" and old [milestone](/milestones/)
2. Select all
3. Archive with `r`
### Export for reporting
1. Filter cards by [run](/runs/)/[milestone](/milestones/)
2. Select all
3. Export with custom fields (owner, effort, [tracked time](/time-tracking/), workflow state)
4. Analyze in spreadsheet
### Reorganize after deck split
1. Filter cards by a specific [tag](/tags/)
2. Select all
3. Move to new [deck](/decks/) with `d`
4. Remove the tag with `t`
# Quick Settings & More Actions
The Quick Settings Panel allows to change a card's main properties from various places. It can be controlled exclusively by the keyboard, allowing mouse-free interactions.
## How to open the Quick Settings
The Quick Settings Panel can be summoned in various ways:
1. Via clicking the Effort Icon on the Mini Card or an opened Card
2. Via a slash command while editing a card's content. It's the first slash command, so activating can be done by hitting `/` followed by `Enter`.
3. On an opened Card you can use any of the property shortcuts (`p`, `e`, `o`, `m`, `,`) to invoke the Quick Settings panel already opened with the respective sections.
## How to operate the Quick Settings
The following properties can be changed:
- Deck
- [Owner](/owner/)
- [Runs](/runs/)
- [Milestones](/milestones/)
- [Priority](/priority/)
- [Effort](/effort/)
Note that a decks's project has an impact on which owners, Runs or Milestones are available.
While mouse operations work as expected, the overlay is meant to be operated by the keyboard. You can use the up and down arrow keys to select amongst the options for the current property. Use the left and right arrow keys for switching between properties. You can filter the shown options if you start typing.
When navigating by Keyboard changes are not stored immediately but only once the overlay is closed by hitting `Enter`. Pending property changes are marked with a dot next their icon. To abort, you can hit `Esc`, or click outside of the overlay.
## The More Options Menu
Where the Quick Settings panel changes a card's _properties_, the **`…` (More Options)** button on every opened card collects the card-level _actions_ that don't have their own dedicated button. Which entries you see depends on the card and your permissions, but the menu can include:
- **Copy Card Content** — copies the card's content as Markdown to your clipboard, ready to paste elsewhere.
- **Convert List Items to Sub Cards** — turn the items of a checklist into proper [Sub Cards](/hero-cards/) (see [Text Editor → Checklists](/text-editor/#checklists)).
- **Bookmark / Unbookmark Card** (shortcut `.`) — add or remove the card from your [bookmarks](/hand/#bookmarks).
- **Watch / Unwatch Card** — start or stop receiving notifications for updates to the card.
- **Turn into Doc Card / Turn into Task Card** — switch the card's type (see [Doc Cards](/doc-cards/)).
- **Unstart this Card** — return a started card to the unstarted state (available with real-time [time tracking](/time-tracking/)).
- **Archive / Unarchive Card** (shortcut `R`), **Delete Card** (shortcut `Backspace`), and **Restore Card** for deleted cards.
# Activity
### Where to find it?
There are four contexts in which an activity feed can be found:
1. **[The Hand](/hand/):** this allows to show a feed on a user basis. By default it shows your updates, but the select box at the top allows to change to different users
2. **The Deck Library:** This feed is a global one across all projects
3. **Deck:** Opens an activity feed for changes wihtin this deck
4. **[Runs](/runs/):** Opens an activity feed for changes for a given Run
5. **[Milestones](/milestones/):** Opens an activity feed for changes for a given milestone
Click the activity button to inspect all recent actions for any card within a deck or milestone or hand. Clicking on the card opens it. You can then check the specific card history for more details about that card.
Load more activity by scrolling down and clicking on 'load more'.
### Filters
The filter section at the top of the activity screen allows you to filter the activity feed according to these criteria:
- Created cards
- [Workflow state changes](/workflow/) (e.g. card started, done or archived)
- Show only done cards
- [Adding or removing attachments](/attachments/)
- Property changes (i.e. [priority](/priority/), [effort](/effort/), [owner](/owner/), [run](/runs/), [milestone](/milestones/), [due date](/due-dates/) )
- Content changes
- Created comments
# Time Tracking
Time Tracking can be enabled via `Organization Settings > Features`. You can pick between two modes:
- Manual
- Real-time and Manual
If time tracking is disabled, no exisiting time tracking information will be lost.
## Manual Time Tracking
In this mode the History side panel of an open Card contains an _Add Time_ button which allows to enter and edit time tracking information. Using the button, you may enter time spent and choose the date and time on which this work happened. The entered time tracking data is always associated with your user account.
The history panel also shows previously tracked time. You can correct the tracked time by using the plus/minus buttons next to the time entry to add or remove time in 5 minutes steps (\*spent too long at the coffee machine?).
You can also click on the time entry itself for an input field offering more extensive editing. You can delete the full time tracking entry by clicking the trash icon next to it.
At the top of the Card history panel you'll find a _Total tracked time_ entry summing up all time entries on this Card sorted by owner. There is also a small clock icon at the bottom of each Card containing time information. Hovering over it will allow you to check the total amount of time spent at a glance.
The clock icon contains a colored fill that grows as more time is tracked. The filled area increases exponentially with the total time spent on the card, meaning it provides a quick visual intuition for comparing relative time spent between cards, but the relationship isn't linear (e.g., a half-filled icon doesn't necessarily mean twice the time of a quarter-filled icon). The area approaches being full asymptotically, meaning it would only theoretically reach 100% fill with infinite time spent.
You can also use time tracking information to sort cards. This is a good way for quickly identifying expensive tasks in your Run, Milestone or Deck view.
## Real-time tracking
Enabling real-time tracking, includes all features described above for manual time tracking. In addition, the play button in the top bar of every Card doubles as your timer control — it's used to start, stop and inspect the timer.
The play button is the single combined entry point for both starting work and tracking time:
- On your own task cards that are not yet started, clicking it sets the Card to _started_ ([blue](/workflow/#started-cards)) **and** starts your timer in one go. Clicking it a second time only stops the timer; the Card stays in the _started_ state. Use the **…** (More Options) menu on the opened card to _unstart_ it again.
- On Hero Cards and Doc Cards (which don't have a _started_ state), the same button only controls the timer.
- On Cards that are blocked, in review, or owned by someone else, you can still start the timer through this button without changing the Card's workflow state — handy for tracking time you spend reviewing or helping out.
- If a Card gets marked as done or gets archived, all running timers on it will be stopped automatically.
Cards that are actively being time-tracked show a small **blue timer widget**, no matter whose timer is running. This makes it easy to tell apart cards that have merely been _started_ ([blue](/workflow/#started-cards)) from cards that someone is actively working on _right now_. It works across the whole team — not just for your own cards — and shows up both on mini cards and in [Table View](/sorting/#table-view).
Here's some rules around time tracking:
- A single user can only have a single timer running.
- The timer can started on any type of card by any amount of people. This could be useful for e.g. meetings that can be represensented via meeting cards.
Enabling real-time tracking also gives you a handy widget in the bottom left, which highlights your current task and the time spent so far. You can quickly adjust the time spent by using the plus/minus buttons. You can also stop the timer by pressing the stop button on the widget.
In addition the web site title will change so that you can scan the time spent on your browser tab. In case you forget to stop the Card timer you can always manually edit the Card history to fix up the time. In your organization settings you will also find a field to edit the amount of time after which a Card time tracker will stop automatically due to suspiciously effective work segments. If the tracker was automatically stopped, you'll receive a notication and the widget of the bottom will have turned into a snoozing purple color.
A Card's history panel also highlights these entries with a snoozing icons until the time entries have been adapted.
## Time Tracking Report
You can access the time tracking report via the mission control (open by clicking on the joystick in the top left). The report contains a detailed list of all time tracked by all team members.
You can sort by:
- Start Date / Time
- Duration
- User
- Card
- Project
To filter the table use the filter icons next to the individual table columns to show/hide individual entries. You can filter by date, user and project.
At the bottom left you can see the total time tracked in Codecks.
You can export all information for your current filter in CSV format by clicking the export button in the bottom right.
# Shortcuts
Here's a complete overview for all available shortcuts:
### General Shortcuts
- **`Esc`**
Closes active panel
- **`?`**
Open shortcut overview
- **`shift+1`**
Go to your hand
- **`shift+2`**
Go to decks
- **`shift+3`**
Go to Timeline
- **`shift+4`**
Open Mission Control
- **`/`**
Open search
### Card detail view
- **`Space`**
Assign card to self if it's not yours yet. If you already own it, it triggers the play button (starting the card and — with real-time tracking — its timer, stopping the timer, or stopping the card)
- **`o`**
Focus owner field and open input field for typing owner
- **`t`**
Focus tags. Use the `tab` key to navigate across tabs and hit `space` to confirm them.
- **`h`**
Add/dismiss card to hand
- **`d`**
Opens change deck dialog
- **`e`**
Focus effort field (after that hit a number between 0 and 9 to set the effort)
- **`p`**
Focus priority field (after that hit either 1, 2 or 3 to set the priority)
- **`,`**
Focus Run field and open dialog.
- **`m`**
Focus Milestone field and open dialog.
- **`s`**
Open sub cards panel
- **`r`**
Archive/unarchive card
- **`backspace`**
Delete card
- **`n`**
Opens conversation panel
- **`a`**
Opens attachments panel. Hitting `a` again will open the first image.
- **`z`**
Open property panel
- **`shift-x`**
Dismiss all non-conversation notifications associated with this card
- **`alt+x`**
Dismiss all notifications on this card (including conversations).
- **`i`**
Open history panel
- **`shift+t`**
Open the history panel with the manual time entry form ready to be filled in (only available if [Time Tracking](/time-tracking/) is enabled)
- **`return`**
Open Text Editor
### Card Overview (e.g. Hand/Decks/Runs/Milestones)
- **`shift+m`**
Open metrics
- **`shift+i`**
Recent Activity
- **`shift+t`**
Open tags filter side bar
- **`shift+o`**
Opens 'order by' search box
- **`j`**
Open previous card
- **`k`**
Open next card
- **`arrow keys`**
Open card to left/right/up/down of current card
- **`q`**
Add/dismiss "my cards" filter
- **`c`**
Open card creation
- **`shift+c`**
Create sub card
- **`ctrl/cmd+a`**
Select all cards in current context### Mini card
These only work if no card is opened, and affects the card under your mouse cursor.
- **`Space`**
Assign card to self if hovered. If card is assigned already, start card. Or mark as non-started if it's started.
- **`o`**
Opens quick owner assignment picker
- **`t`**
Opens quick tag assignment picker
- **`h`**
Add or dismiss to hand
- **`d`**
Change deck
- **`e`**
Open effort picker
- **`p`**
Open priority picker
- **`,`**
Open Run picker
- **`m`**
Open Milestone picker
- **`s`**
Open hero card picker
- **`r`**
Archive/unarchive card
- **`0-9`**
Assign effort to card if mouse is over the effort icon.
- **`0-3`**
Assign priority to card if mouse is over the priority icon.
- **`backspace`**
Delete card
- **`n`**
Open card with the conversation panel focused
- **`v`**
Snooze conversation (when hovering over a card with an open conversation)
- **`u`**
Upvote / remove upvote (only on cards in projects that allow upvotes)
- **`w`**
Toggle the card's _done_ state
- **`.`**
Bookmark / unbookmark card
- **`shift+d`**
Change the card's zone (when the current view is in [manual order](/sorting/#manual-order-and-zones))
- **`x`**
Select card
#### Bulk Selection Actions
- **`i`**
Inverts currently selected cards
- **`space`**
Assign all selected cards to myself
- **`o`**
Select new owner for selected cards
- **`t`**
Change tags for selected cards
- **`h`**
Add selected cards to hand, or removes from hand if all cards were already in the hand
- **`d`**
Move selected cards to deck
- **`e`**
Set effort for selected cards
- **`p`**
Set priority for selected cards
- **`,`**
Add selected cards to a Run
- **`m`**
Assign Milestone for selected cards
- **`s`**
Open hero card dialog
- **`r`**
Archive selected cards
- **`backspace`**
Delete selected cards
- **`Esc`**
Deselects all cards
For more tips on how to use Codecks effectively check this video (tip 7 is specifically about shortcuts):
# User Management & Permissions
## Roles
Codecks differentiates between **org-wide roles** and **project-specific** roles.
Here's a high-level overview of org-wide roles:
- #### `Owner`
Assigned to the creator of an organization. There may only be one owner.
- #### `Admin`
Have access to all projects and can manage billing and integrations.
- #### `Staff`
May access assigned projects only. Can be assigned the project-specific `Producer` role.
- #### `Observer`
May access assigned projects only. They can't change any data but may add comments to cards.
Users with the `Staff` role may be given the project-specific `Producer` role. A producer can manage Decks, Runs, Milestones and integrations for the project. The producer role is available to organizations with the [Pro plan](/plans/).
## Project Visibility
`Admins` and `Owners` have access to all projects. Projects have a visibility setting which determines if all `Staff` members can access a project or whether they need to be explicitely added. `Observers` always have to be explicitely added, no matter the project visibility setting.
`Limited` Project Visibilty is available in the [Pro plan](/plans/).
## Permissions
### `Limited` vs `Full` Staff Permissions
`Admins` and `Owners` can set Staff Permissions with the **User Management** screen. `Full` Staff Permissions allows all Staff members to
- Create and manage Decks
- Create and manage project-specific Runs and Milestones
- Manage global Runs and Milestones
- Manage Journeys
- Manage Project Tags
in the projects they have access to.
### Permission Matrix
The list below shows the minimum role that has permission to perform or access the corresponding actions.
Here's the full hierarchy to know what a minum role implies:
`Owner > Admin > Producer > Staff > Observer`
This means that if a `Producer` is allowed to perform a certain action, then the `Owner` and `Admins` are also allowed to do it.
Entries marked with `Staff*` imply that `Staff Permissions` are set to `Full`. Otherwise these actions are only available to `Producers`.
#### Organization-based Permissions
| Action | Minimum Role |
| ------------------------------------------ | ------------ |
| Can view user overview | `Observer` |
| Can manage integrations 1 | `Producer` |
| Can manage billing | `Admin` |
| Can invite users | `Admin` |
| Can assign org-wide roles (except `Owner`) | `Admin` |
| Can manage organization settings | `Admin` |
| Can delete attachment files | `Admin` |
| Can disable organization | `Owner` |
| Can assign different Owner | `Owner` |
1 `Producers` will be able to access all integrations. But project or deck names they don't
have access to won't be shown. They may only pick target decks from projects they are producer of.
#### Project-based Permissions
| Action | Minimum Role |
| ---------------------------------------------------------- | --------------------- |
| Can modify and archive project | `Producer` |
| Can manage user project access for `Staff` and `Observers` | `Producer` |
| Can assign project-specific user role | `Producer` |
| Can make project public | `Producer` |
| Can create and manage project tags | `Producer` / `Staff*` |
| Can create project | `Admin` |
| Can delete project | `Admin` |
| Can change default access for `Staff` and `Observers` | `Admin` |
#### Run-based Permissions
| Action | Minimum Role |
| ------------------------------------------- | --------------------- |
| Can assign cards to Runs | `Staff` |
| Can create and manage project-specific Runs | `Producer` / `Staff*` |
| Can manage global Runs | `Producer` / `Staff*` |
| Can create global Runs | `Admin` |
#### Milestone-based Permissions
| Action | Minimum Role |
| ------------------------------------------------- | --------------------- |
| Can pin milestone | `Observer` |
| Can assign cards to milestones | `Staff` |
| Can create and manage project-specific milestones | `Producer` / `Staff*` |
| Can manage global milestones | `Producer` / `Staff*` |
| Can create global milestones | `Admin` |
#### Deck-based Permissions
| Action | Minimum Role |
| ----------------------------------------- | --------------------- |
| Can assign cards to decks | `Staff` |
| Can create and manage decks | `Producer` / `Staff*` |
| Can create and manage journeys | `Producer` / `Staff*` |
| Can set preferred card sort order in deck | `Producer` |
| Can modify public deck's deck order | `Producer` |
#### Card-based Permissions
| Action | Minimum Role |
| ------------------------ | ------------ |
| Can bookmark card | `Observer` |
| Can create & modify card | `Staff` |
| Can create card preset | `Staff` |
| Can manage card preset | `Admin` |
## Invite Users
If you open the Mission Control via the Joystick icon at the top left, you'll find the `User Management` section. This contains an overview of the current users as well as two options for inviting new members to your organization if you are an admin or owner.
### Invite via E-Mail
This option allows to invite users on a one-by-one basis by entering their email. This will sent a message to the entered email containing a link that allows to join your invitations. This option allows to define the user's role as well as which project access this user should get.
### Invite via Link
If you want to invite multiple team members in one go, you can generate an invite link. This will allow anyone who has access to it to join your organization. The person creating the link will receive a confirmation email for each person joining. The invited people will join as staff members with the default project accessiblity rights.
You can disable this link anytime by pressing the "Disable Link" button.
# History
The card history side panel is the central hub for seeing all card changes that ever happened to a card. It also contains additional tools to manage card notifications. Access it by clicking the history button to the right side of an opened card.
## Timeline
The history panel contains a timeline listing in detail all the changes to a card, including changes to:
- Text
- Priority
- Effort
- Text
- Checklists
- Sub Cards
- Attachments
- Runs
- Milestones
- Tags
- Workflow state
- Conversations
If you are using time tracking, it also contains time tracking related entries as well as a time tracking summary at the top.
You can use the filters at the top to focus on specific kind of entries.## Created by
You can scroll down the history timeline to find the initial card creation properties including who assigned them. For a quick glance for who created the card at what date, you may also check the dedicated _created_ table at the top.
## Watching a card
Here you can see who currently is watching the card and add or remove yourself as watcher of the card. Anyone mentioned within the card content will be watching it automatically. Watching a card means you will get notified when the workflow state changes or a conversation is started.
When creating a card, the card creator is added as a watcher of this card by default. You can disable this behavior by clicking the eye icon next to the card creation dialogue. This especially makes sense if you're creating many cards for other team members for which you don't want to receive detailed updates.
# Guardians
As your team grows it can be hard to ensure that no cards fall through the cracks within your workflow. Hunting down invalid review processes can cost time and cause confusion.
This is why Codecks allows to appoint Guardians for a deck. Any member of your team can become a Guardian by selecting them from the corresponding Section.
Once Guardians have been chosen, only them (and Producers and Admins) are able to directly mark a card of this deck as done.
Anyone else has to go through the review process. All guardians will automatically be added to a review. The review flow will be slightly altered for cards within Guardian decks.
Instead of opting out, review participants are shown the option **Approve and leave conversation**. Once all participants have approved, the card owner will be able to close the review and mark the card as done.
In addtion to the altered review flow, non-Guardians may not archive cards or move cards into a different deck.
import { Aside } from "../../components/MarkdownComponents";
# Plans & Pricing
Codecks offers three plan tiers to fit teams of all sizes, from small indie studios to large game development organizations. All plans include core project management features with paid plans unlocking advanced collaboration and productivity tools.
## Plan Comparison
### Free Plan
Perfect for small teams getting started with Codecks.
| | |
| ------------- | --------------------- |
| **Pricing** | €0 per user per month |
| **Users** | Up to 5 users |
| **Projects** | Up to 3 projects |
| **Storage** | 1 GB total (shared) |
| **File size** | 10 MB max per file |
**Premium features not included:** [Observers](/users/#roles), [limited project access](/projects/#project-access), [time tracking](/time-tracking/), [due dates](/due-dates/), [dependencies](/dependencies/), [guardians](/guardians/), capacity tracking, beast mode, pro Decky features, [vision board smart nodes](/vision-board/).
---
### Plus Plan
For growing teams that need unlimited users and projects.
| | |
| ------------- | --------------------------------------------------------------- |
| **Pricing** | €7 per user per month, or €6 per user per month billed annually |
| **Users** | Unlimited |
| **Projects** | Unlimited |
| **Storage** | 1 GB per user |
| **File size** | 250 MB max per file |
**Everything in Free, plus:**
- **[Observers](/users/#roles)** - Add read-only users at no charge. Observers can view cards and comment but cannot modify data. Observers don't count toward your purchased seats — they're free on Plus and Pro.
---
### Pro Plan
Full-featured plan for professional game development teams.
| | |
| ------------- | ---------------------------------------------------------------- |
| **Pricing** | €11 per user per month, or €9 per user per month billed annually |
| **Users** | Unlimited |
| **Projects** | Unlimited |
| **Storage** | 10 GB per user |
| **File size** | 250 MB max per file |
Observers don't count toward your purchased seats — they're free on Plus and Pro.
**Everything in Plus, plus:**
- **[Time Tracking](/time-tracking/)** - Manual and real-time time tracking with automatic timer start/stop, comprehensive reports, and CSV export
- **[Due Dates](/due-dates/)** - Set date-based deadlines on individual cards with automatic reminders
- **[Dependencies](/dependencies/)** - Link cards to track task relationships and prerequisites
- **[Guardians](/guardians/)** - Designate required reviewers for [deck](/decks/) approval [workflows](/workflow/)
- **[Producers](/users/#roles)** - Enhanced project-level permissions for managing [decks](/decks/), [milestones](/milestones/), and integrations
- **Capacity Tracking** - Monitor team workload and bandwidth across [runs](/runs/)
- **Beast Mode** - Advanced [milestone](/milestones/) management features with enhanced forecasting
- **Pro Decky Features** - Additional Decky card statuses and customization
- **[Vision Board Smart Nodes](/vision-board/)** - Dynamic, filter-based vision board widgets
## Billing & Subscription Management
### Billing Dashboard
The billing page provides an overview of your subscription:
| Item | Description |
| ----------------- | ---------------------------------------- |
| **Current plan** | Your active plan tier and pricing |
| **Amount due** | Charges per billing cycle |
| **Billing cycle** | Your current cycle end date |
| **Trial status** | Active trial information (if applicable) |
### Managing Your Subscription
#### Upgrading Your Plan
To upgrade from Free to Plus or Pro, or from Plus to Pro:
1. Navigate to **Billing > Plans**
2. Click the **Upgrade** button on your desired plan
3. Confirm the plan change
#### Starting a Free Trial
Free and Plus plan users can try Pro features with a **14-day free trial**. The trial is activated from **Billing > Plans** and can only be started by an Owner or Admin.
**During your trial:**
- Full access to all Pro features
- Email reminder 7 days before trial ends
- Cancel anytime without being charged
- Upgrade to a paid plan anytime during the trial
#### Switching Billing Interval
To switch between monthly and yearly billing, go to **Billing > Plans** and toggle the interval on your current plan. Interval changes are **scheduled for the start of your next billing cycle** — you can revoke a scheduled change any time before then.
#### Downgrading Your Plan
To downgrade from Pro to Plus, or from paid to Free:
1. Navigate to **Billing > Plans**
2. Click **Downgrade** on your target plan
3. Confirm the downgrade
### Managing Seats
On Plus and Pro you purchase a specific number of seats. Every Staff, Admin, Owner, or Guest in your organization consumes one seat. [Observers](/users/#roles) are always free and don't count toward the total.
**To adjust your seats:**
1. Open **Mission Control** and go to **Billing > Plans**
2. Click **Manage seats** next to your current seat usage
3. Enter the new seat count and review the invoice preview
4. Confirm
#### Adding seats
Seat upgrades take effect **immediately**. On monthly plans you're billed a prorated amount for the rest of the current cycle; on yearly plans an invoice for the new seats is created and paid right away.
#### Reducing seats
Seat downgrades are **scheduled for the start of your next billing cycle** — you keep access to all your current seats until then. The confirmation screen shows the exact date the change takes effect. You can revoke a scheduled downgrade any time before the cycle ends.
#### Inviting someone with no free seats
If every purchased seat is filled, the invite form shows a **Purchase more seats** callout that opens the seat-management modal directly. You can also invite the person as a free Observer instead, and upgrade their role later once you've added seats.
### Billing Cycle
Codecks uses monthly billing cycles:
- **Charged users**: Staff, Admins, and Owners count toward billing
- **Free users**: Observers and limited role users don't incur charges
- **Billing timing**: Charges occur at the start of each monthly cycle (or once per year on yearly plans). Your cycle is tied to the day you subscribed — e.g. starting a subscription on the 12th means you're charged on the 12th of every subsequent month.
- **Payment**: Charged to your saved payment method at the start of each cycle
### Payment Methods
**Accepted payment methods:**
- **Credit and debit cards** (via Stripe)
- **SEPA direct debit** (European accounts)
**To update your payment method:**
1. Go to **Billing > Payment method**
2. Enter your new payment details
3. Save changes
### Invoices
**To view and download past invoices:**
1. Go to **Billing > Invoices**
2. Browse your invoice history
3. Click any invoice to download the PDF
### Billing Address & VAT
**To update your billing address or VAT ID:**
1. Go to **Billing > Address & VAT ID**
2. Enter your billing details
3. For EU businesses: Add your VAT ID to avoid VAT charges (reverse charge applies)
4. Save changes
## Understanding Plan Limits
### User Limits
| Plan | Paid Users | Observers |
| -------- | ---------------------------------------------------------------- | ---------------- |
| **Free** | Maximum 5 (Staff, Admins, Owners) | Not available |
| **Plus** | Purchase seats as needed (see [Managing Seats](#managing-seats)) | Unlimited (free) |
| **Pro** | Purchase seats as needed (see [Managing Seats](#managing-seats)) | Unlimited (free) |
### Project Limits
| Plan | Active Projects | Archived Projects |
| -------------- | ----------------- | ------------------ |
| **Free** | Maximum 3 (total) | Count toward limit |
| **Plus & Pro** | Unlimited | Unlimited |
### Storage Limits
Storage limits apply to [file attachments](/attachments/):
| Plan | Total Storage | Per User |
| -------- | -------------- | -------------------------- |
| **Free** | 1 GB | Shared across organization |
| **Plus** | 1 GB per user | Scales with team size |
| **Pro** | 10 GB per user | Scales with team size |
### File Size Limits
Maximum individual [file attachment](/attachments/) upload size:
| Plan | Max File Size |
| -------------- | --------------- |
| **Free** | 10 MB per file |
| **Plus & Pro** | 250 MB per file |
## Frequently Asked Questions
---
## Need Help?
If you have questions about billing, plans, or need assistance with your subscription, contact us at [team@codecks.io](mailto:team@codecks.io).
For detailed pricing and plan comparison, visit [codecks.io/pricing](https://www.codecks.io/pricing/).
Integrations
===================
# User Reports
User Reports allow your users to send feedback directly from within your application. Each feedback will result in a new Codecks card in the deck(s) of your choice. You can either directly talk to our API endpoint or use our ready-made Unity integration to connect to our Codecks server.
## Setup your first application
As a first step you need to open up your Organization Settings and look for the **User Reports** section. You'll get to chose between the Unity integration and creating reports via the API. Changes in either section will be reflected in the other (i.e. settings made in the **via API** section will be used in the Unity integration and vice versa).
Whichever option you've picked, you will be asked to add your first application. You need to enter the name and the target deck in which cards shall be added by default. Both options can be changed later on. Once submitted, you'll receive two keys: a **Report Token** and an **Access Key**. Let's have a look at those two.
### Report Token
Report Tokens are meant to be embedded within your application. They allow you to create a card according to the options passed to the endpoint and according to the rules you've set up in the settings. Report Tokens can be disabled to prevent more reports from coming in. This can be helpful if one token has gone "rogue". You can re-enable a disabled token anytime.
An application can have multiple Report Tokens, each with a unique label. This is meant to differentiate feedback coming from different builds.
By default, Codecks creates a Report Token with a **Default** label for you. To create new Report Tokens you need to use another API endpoint along with an `Access Key`.
### Access Key
Access Keys are more security sensitive and should not end up in your builds. They are meant to be used within your build process though. Whenever you are about to release a new version, you can use the Access Key to create a new Report Token with a version-specific label. The label will be used as a tag in generated cards and thus allows you to quickly filter and sort your reports.
An Access Key is automatically generated when adding a new application in the settings. You won't be able to see that key again within Codecks. In case you have lost it, you are able to regenerate a new one. This will invalidate the old Access Key however.
## Codecks Settings
Here's a tour of all options available in the settings screen:
- **Report Tokens**
This tab presents you an overview of all created Report Tokens for your application. It allows you to disable or re-enable specific tokens. Disabling a Report Token will prevent any feedback using this token from creating a card. This list also shows the token itself, label, creation date and the number of created cards.
- **Update Settings**
This screens allows you to change these settings:
- **Name of Application:** The name is used in the select box on the top right as well as in emails sent to feedback reporters (see below)
- **Maximum Upload Size:** As Report Tokens are part of your builds they can theoretically be extracted and used for malicious activites. To prevent user reports from quickly filling up your storage quota, you can configure a limit here.
- **Map Severity to Deck:** feedback reports can set a **severity** value. Each severity can be mapped to a different deck allowing e.g more severe issues to be put into a dedicated deck.
- **Map Severity to Priority:** You can also use priority as a signal for severity.
- **New Access Key**
In case you either lost your current Access Key or you want to invalidate it, this section allows you to create a new Access Key. Make sure to copy it somewhere safe as it won't be shown again after it has been generated.
- **Delete Application**
This tab allows to remove the application from the User Report integration. Any Access Key or Report Token will be deleted and no more emails will be sent out to feedback reporters. Applications calling the endpoint with a deleted token will receive a `401 unauthorized` response.
### Multi-Application support
In case you're working on multiple games or apps, you can add another application to this integration. Look for the `+` icon next to the application selector in the top right of the settings screen.
## Automatic email updates to feedback reporters
When submitting feedback to Codecks, you can provide an optional `userEmail` field. This field will be used to send an email to the provided address once the associated card is set to done. Theses types of email will be sent once a day and batch all done cards for any given email address. The email will contain the name of the application as well as the current card title and a link to it. The link of the card is a smart link and has three modes:
- if the current user is a member of the organization, the smart link will open the card within the organization
- if the card is within a public open deck, the card will be opened in this context
- if neither is true, the link will render a card which only displays the title of the card.## API
In case you want to setup your own engine integration or want to understand how the Unity plugin works exactly, we will describe how the API endpoints work exactly:
### Create a report
To create a card issue a `POST` message in the following form:
`POST https://api.codecks.io/user-report/v1/create-report?token=[REPORT_TOKEN]`
#### Body
The body of the message has to be a JSON object of this form:
```json
{
"content": "text content of your report\n\nthe first line will be treated as the title.",
"severity": "high",
"fileNames": ["logs.txt", "screenshot-1.png"],
"userEmail": "user@example.com"
}
```
Note that `severity`, `fileNames`, `userEmail` are optional. `severity` can be either `"critical"`, `"high"`, `"low"` or `null`. If a `userEmail` is provided, that user will receive an email once their report is marked as done.
#### Curl example
Here is an example of how to issue the message via `curl`:
```bash
curl 'https://api.codecks.io/user-report/v1/create-report?token=[REPORT_TOKEN]' \
-H 'Content-Type: application/json' \
--data-binary '{"content":"report content", "fileNames": ["logs.txt"]}'
```
#### Response
The response object for this endpoint has this form:
```json
{
"ok": true,
"cardId": "[CARD_ID]",
"uploadUrls": [
{
"fileName": "logs.txt",
"url": "https://[UPLOAD_URL]",
"fields": {
"key1": "[VALUE1]",
"key2": "[VALUE2]"
}
},
{
"fileName": "screenshot-1.png",
"url": "https://[UPLOAD_URL]",
"fields": {
"key1": "[VALUE1]",
"key2": "[VALUE2]"
}
}
]
}
```
#### Uploading files
You'll receive an entry in the `uploadUrls` list for each file name you specified in `fileNames`. This contains a signed URL that allows you to directly upload the files to the respective Codecks S3 bucket.
This means we're relying on [AWS Api](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-HTTPPOSTConstructPolicy.html) here which unfortunately is a bit more involved.
For each file you need to create a `POST` request to the specified `url`. The payload is _not_ JSON-based but is `multipart/form-data` encoded. We strongly encourage you to use a http library of your choice to construct the request. The `FormData` contains all the listed `fields` as well as an additional field called `file` containing the binary contents of your file and another field `Content-Type` containing the mime-type of the file (e.g. `text/plain` or `image/png`).
In case you want to go the route of constructing the multipart/form-data request yourself, here's what the body typically looks like assuming that your request defines a content-type header like this: `Content-Type: multipart/form-data; boundary=gfLcwHS2rnS8ATXB10lG`
```
--gfLcwHS2rnS8ATXB10lG
Content-Disposition: form-data; name="key"
["key" value from uploadUrls]
--gfLcwHS2rnS8ATXB10lG
Content-Disposition: form-data; name="Cache-Control"
["Cache-Control" value from uploadUrls]
--gfLcwHS2rnS8ATXB10lG
Content-Disposition: form-data; name="acl"
["acl" value from uploadUrls]
--gfLcwHS2rnS8ATXB10lG
Content-Disposition: form-data; name="bucket"
["bucket" value from uploadUrls]
--gfLcwHS2rnS8ATXB10lG
Content-Disposition: form-data; name="X-Amz-Algorithm"
["X-Amz-Algorithm" value from uploadUrls]
--gfLcwHS2rnS8ATXB10lG
Content-Disposition: form-data; name="X-Amz-Credential"
["X-Amz-Credential" value from uploadUrls]
--gfLcwHS2rnS8ATXB10lG
Content-Disposition: form-data; name="X-Amz-Date"
["X-Amz-Date" value from uploadUrls]
--gfLcwHS2rnS8ATXB10lG
Content-Disposition: form-data; name="Policy"
["Policy" value from uploadUrls]
--gfLcwHS2rnS8ATXB10lG
Content-Disposition: form-data; name="X-Amz-Signature"
["X-Amz-Signature" value from uploadUrls]
--gfLcwHS2rnS8ATXB10lG
Content-Disposition: form-data; name="Content-Type"
[YOUR CONTENT TYPE]
--gfLcwHS2rnS8ATXB10lG
Content-Type: [YOUR CONTENT TYPE]
Content-Disposition: form-data; name="file"; filename="[YOUR FILE NAME]"
[CONTENTS OF THE FILE]
--gfLcwHS2rnS8ATXB10lG--
```
The last section would look like this for a binary file:
```
--gfLcwHS2rnS8ATXB10lG
Content-Type: [YOUR CONTENT TYPE]
Content-Disposition: form-data; name="file"; filename="[YOUR FILE NAME]"
Content-Transfer-Encoding: binary
[CONTENTS OF THE FILE]
--gfLcwHS2rnS8ATXB10lG--
```
### Create a new Report Token
To create a new report token issue a `POST` of this form:
`POST https://api.codecks.io/user-report/v1/create-report-token?accessKey=[ACCESS_KEY]`
#### Body
The body of the message has to be a JSON object of this shape:
```json
{
"label": "string describing your version"
}
```
#### Curl example
Here is a `curl` example using this endpoint:
```bash
curl 'https://api.codecks.io/user-report/v1/create-report-token?accessKey=[ACCESS_KEY]' \
-H 'Content-Type: application/json' \
--data-binary '{"label":"v0.2.1"}'
```
#### Response
The response is expected to be of this form:
```json
{
"ok": true,
"token": "[TOKEN]"
}
```
# Open Decks
Codecks allows you to share the contents of any of your projects publicly on the web. Visitors are be able to navigate to your public URL and see all the project cards and their contents. You can even choose to allow your visitors to upvote their favorite cards. Don't worry: your visitors won't be able to change the card content or card properties themselves.
If you want to share only some cards, but not all the cards in your project, we recommend creating two separate projects inside your organization. One for the cards that you want to share and one for the cards that you want to keep private.
## Sharing your project
To share your project go into the project settings of the project that you want to share. To access the project settings open the mission control by clicking on the joystick icon 🕹️ in the top left corner. In the sidebar hover over the project that you want to share and click on the cogwheel icon ⚙.
You will see a settings section called _Make Project Public_. Enable the toggle switch to enable sharing. Make sure to choose an URL name for your project in the text field. You can see a preview of the full URL underneath the text field.
You may even share multiple projects to different URLs.
## Open Deck Communities
Visitors to your Open Decks can join your community by clicking the button in the top right. To do so they can either use their existing Codecks user account or quickly sign up using their email or Discord login to create a visitor profile.
Joining your community will allow them to upvote individual cards (if you enabled upvoting). Community members may also choose to receive email updates about your project by clicking _Get notified of updates_ in the right top corner. In that case they will be able to choose between daily or weekly updates.
## Upvote Stats
This view can be reached from the hand dashboard and shows your latest upvotes, including those from your Open Decks, your Discord community and also your own team. It also shows you how many guests are visiting your public Open Decks web site. You may also receive this information as a weekly email report by enabling the _Receive weekly report per mail_ toggle.
## Open Decks Gallery
The website **[open.codecks.io](https://open.codecks.io)** features an overview of some of the shared projects. It is a great way for discovering cool projects that are already using the Open Decks feature and to get inspired by how other devs are using Codecks. If you like to be listed on that page and receive potential social media shout-outs by us, enable the toggle for allowing us to feature you.
To make your project stand out on the Open Decks gallery, make sure to upload a custom promo image. This image will only be used on the gallery page. If you provide no image, we’ll try to be smart and select the image of your first cover image.
## Information for your audience
Make sure to provide some initial information about your project to your guests. The chosen display name of your project will be shown in the top left corner of your public page. The banner image will be shown in the center. You may also provide a message to your audience that will be shown front and center of your public page.
You may also choose to allow your users to see the comments on each shared card. Enabling this still won’t allow them to write comments themselves.
## Customizing the Card Order
When users visit your page, they’ll see all the decks contained in the public project. If they open a deck they’ll see all the contained cards. We recommend setting a default card order for your public shared decks.
To set the default card order visit the deck in the Codecks app and open the ordering options in the left sidebar. Select the order option that you want to use and click on the star icon ⭐ at the top _“Ordering”_ sidebar. Doing so will make this the sort order which guests will see when they visit your public deck.
They may still choose to change this default order to something else. To return to the default presentation order they just have to click on the _reset to default order_ icon that appears on the deck header.
For cards that require a specific order, you can also choose the _manual_ sort option and manually arrange the order by drag’n’dropping cards into the right positions.
## Quick URLs
If you have enabled sharing your project, you’ll notice globe icons 🌍 appear in various places around your shared deck. These are quick links for jumping to the public page of that specific content. You’ll notice these..
- next to your project in the mission control sidebar
- on the deck header of each public deck
- on the top of each card that is inside a public deck
Clicking on the project or deck quick links will open the public URL for that context. Clicking on the globe icon on a card will copy the URL to your clipboard. These are great for sharing links to specific content with your audience.
# Quick Guide to Codecks API
_Version: Aug 2023 (beta)_
The Codecks API is the source for powering the web app, so expect it to be fairly stable and expansive. We can't yet make any guarantees regarding the stability of all schema definitions and endpoints at this point. So tread with care!
To get started you need to extract your access token. **This token will allow anyone who holds it to impersonate you**. This also means they have access to all the same Organizations and contents as you do via the web app. So be careful who you share it with. You might want to create an observer user and use their token if this helps your use case (and the observer limitations suit your use case) you might also create a new non-observer user but this will count towards your user quota.
To extract the token, check requests going to the codecks api (https://api.codecks.io). There you'll find a cookie called `at` containing your token.
> Note: we've changed the token handling in January 2021, if your login session is older than that you need to logout and login again to find this cookie.
## Reading Data
This token and the subdomain of your organization should be all you need to do our first request:
```bash
curl 'https://api.codecks.io/' \
-H 'X-Account: [SUBDOMAIN]' \
-H 'Content-Type: application/json' \
-H 'X-Auth-Token: [TOKEN]' \
--data-binary '{"query":{"_root":[{"account":["name"]}]}}'
```
(if your organization is on `team123.codecks.io` the `[SUBDOMAIN]` value should be `team123`)
This should return the name of your organization (= `account`). Note that there is only this single endpoint for getting information. Use the `"query"` portion to create a nested graphql-like request to get whatever data however deeply nested is required.
I won't go into all details but here's some helpful queries to give you an idea of whats possible:
**return all cards with their titles within your account (aka organization)**
```json
{ "_root": [{ "account": [{ "cards": ["title"] }] }] }
```
**return all cards with their title whose title contains `[SEARCHTERM]`**
```json
{
"_root": [
{
"account": [
{
"cards({\"title\":{\"op\":\"contains\",\"value\":\"[SEARCHTERM]\"}})": [
"title"
]
}
]
}
]
}
```
**return 10 cards from deck `123` ordered by creation date**
```json
{"_root":[
{"account":[{"cards({"deckId": 123, "$order": "createdAt", "$limit": 10})":["title"]}]}
]}
```
**equivalent to:**
```json
{"deck(123)":{
"cards({"$order": "createdAt", "$limit": 10})":["title"]
}}
```
**return all cards with an effort > 5 or effort <= 1**
```json
{"_root":[
{"account":[{"cards(
{\"$or\": [
{\"effort\": {\"op\": \"gt\", \"value\": 5}},
{\"effort\": {\"op\": \"lte\", \"value\": 1}}
]}
)":["title"]}]
}
```
to get more ideas of what's doable, check the "network" tab in your browser dev tools and see which queries are triggered when opening a specific part of the app.
## Writing data
Again, I won't provide a full reference of available actions. The most helpful thing would be to perform the desired action in the web app and use the network tab in your dev tools to check which `/dispatch/` endpoint was triggered.
Here's an example for creating a card:
```bash
curl 'https://api.codecks.io/dispatch/cards/create' \
-H 'X-Auth-Token: [TOKEN]' \
-H 'X-Account: [SUBDOMAIN]' \
-H 'Content-Type: application/json' \
--data-binary '{"assigneeId":null,"content":"My card content","deckId":null,"milestoneId":null,"masterTags":[],"attachments":[],"effort":12,"priority":"b"}'
```
This would create a card on your hand and return the id.
## Restrictions
A single IP may perform 40 requests every 5 seconds before being rate-limted.
## Example Snippets
Do you have a script or snippet you'd like to share? Feel free to get [in touch with us](mailto:hello@codecks.io)!
#### Add file to card (python)
```py
import os
import requests
import mimetypes
def add_file_to_card(filepath, card_id, user_id, subdomain, token):
content_type = mimetypes.guess_type(filepath)[0]
file_size = os.path.getsize(filepath)
filename = os.path.basename(filepath)
headers = {
'X-Account': subdomain,
'X-Auth-Token': token,
}
# request s3 upload details
response = requests.get("https://api.codecks.io/s3/sign?objectName=%s" % filename, headers=headers)
response.raise_for_status()
u = response.json()
# upload file
files = [('file', (filename, open(filepath, 'rb'), content_type))]
payload = u['fields']
payload["Content-Type"] = content_type
requests.request("POST", u['signedUrl'], headers=headers, data=payload, files=files)
# update card
requests.request("POST", "https://api.codecks.io/dispatch/cards/addFile", headers=headers, json={
"cardId": card_id,
"userId": user_id,
"fileData": {
"fileName": filename,
"url": u['publicUrl'],
"size": file_size,
"type": content_type,
}
})
```
# Importers
Codecks offers two types of Importers. A generic CSV importer as well as importers for specific services (Trello and HacknPlan at the moment).
## CSV Importer
The CSV Importer is the most flexible solution and comes with smart heuristics to make the experience as smooth as possible.
You can find it towards the bottom of the Organzation Settings. You start the flow by picking or dragging a csv file into file picker.
Once imported you can go through each of the card properties above and decide which column in your CSV should be considered. Based on some heuristics based on column name and content type some columns will already be selected.
Here's what these heuristics look like:
- **Title:**
The column title contains `summary`, `title`, `description` or `content` and every row has a value.
- **Content:**
There's at least one row that contains a new line
- **Owner:**
The column title contains `creator`, `assignee` or `owner`.
- **Effort:**
The content consists of numbers and the column title contains `estimate`, `effort`.
- **Priority:**
The content consists of numbers or values that are reused at least once. And the column title contains `priority`.
- **Status:**
The column title contains `status` or `state`.
Once you've mapped the columns to the card properties you may have one of two choices, depending on what type of csv you're using:
### Importing new Cards
This option is availabl for any csv. You can define an output deck and export all your cards there.
There currently is no support to use a single csv to import into multiple decks.
### Re-Importing existing Cards
If you exported a csv from Codecks (By selecting cards and looking for the `Export cards` option), you notice that the csv also includes a `Card id` column. If this column is present and all rows contain a valid id, another option is shown: `Update cards`.
This allows to update the cards in place. One use case could be to change the effort of all cards by a factor of 2.
You'll export these cards and load them into a spreadsheet tool. There you can bulk update the contents to your liking.
You can then export the results as csv and re-import them using the CSV Importer.
## Trello Importer
This tool can be found towards the bottom of the Organzation Settings as well. The importer allows you to map most Trello properties to their Codecks counterparts:
Most notably comments, any power-up content or the activity history won't be imported.
Once you start the flow, you'll be asked to give read-only access to your organizations. You may then pick the Board to be imported.
You get a high-level overview of the project to be imported and can decide whether new decks will be created in an existing project or whether a new project should be created.
The next screen allows you to decide whether or not to import attachments and how the existing trello users should be mapped. If the users are not on Codecks yet, you might want to invite them first before starting the importer. Otherwise you'd have to manually assign the tasks once they are on Codecks.
## HacknPlan Importer
Just like the Trello Importer, this tool can be found towards the bottom of the Organzation Settings as well. The importer allows you to map most HacknPlan properties to their Codecks counterparts:
Most notably comments, the start date and the work logs won't be imported.
To start the flow you first need to generate a read-only API key within the HacknPlan [Api Settings](https://app.hacknplan.com/settings?section=api).
To create an Api Key within the settings screen:
1. Click the "Create" Button.
2. Create an Api Key with a name like `Codecks`. It needs `Projects Read` and `Work Items Read` access.
3. Copy the Api key and paste it into the Codecks importer. The key won't be stored, so if you plan to import multiple times, make sure to store the Api key somewhere safe.
The next step allows to pick the HacknPlan project of your choice.
You may then decide whether to import the tasks into an existing project or a new one.
You'll then see an overview of the project to be imported and can make a few decsions:
- **Deck Strategy:** as you can see in the box above, there's two options for how to import decks. They can either based on boards or on categories.
- **Import closed Tasks:** allows you to import closed tasks as archived Codecks cards.
- **Import closed Boards:** will consider closed boards when importing. The resulting decks or milestones (depending on the Deck Strategy) won't look different than non-closed boards.
- **Import attachments**
- **Effort scaling:** the effort is based on the `Estimated cost` within HacknPlan. This field allows to convert hours into an effort value. The value you enter corresponds to "effort points per hour".
- **Importance Level Mapping:** Pick how to map to the 4 Codecks priority options
- **User Mapping:** Pick which HacknPlan user corresponds to which Codecks user. If the users are not on Codecks yet, you might want to invite them first before starting the importer. Otherwise you'd have to manually assign the tasks once they are on Codecks.
# Discord
Codecks features the built-in Discord bot **Decky**. Beyond notifications and card manipulation commands Decky helps you with community management by allowing your users to vote on ideas and feedback. These ideas become cards that live inside Codecks and that can be scheduled and managed like any other card. As you work on these cards, you can let Decky automatically update your community on the state of their feedback.
Decky will keep your community engaged and save you a ton of time by letting your community help in prioritizing and managing the feedback that you receive.
## Enabling Discord Integration
To add Decky to your server, go to the Discord section in your Organization Settings. To see the Organization Settings, open the Mission Control sidebar by clicking the joystick icon 🕹️ in the top left.
Click on _“Add Discord Server”_ to be redirected to your Discord account page. After logging in you can select any of your Discord servers and authorize our bot.
If you authorize multiple servers you’ll be able to switch between the server that you’re currently managing by using the selection box in the top right of the Discord integration settings screen. If you have already added a server, you may add additional servers by clicking the "+" sign next to the selection box.
## Slash Commands
Slash commands are used by your Discord community to send feedback (e.g. features requests or bug reports) to you. They allow your community to create cards inside your project management tool, so you can convert feedback directly into actionable task cards that live in your project management along with your other tasks. Decky will update the user on the state of their card and will manage any follow-up questions that you might have for them.
### Keywords
Any chat message in the chosen channel that starts with a "/" followed by the command keyword will be recognized as a command for the bot. Messages which don’t start with a keyword are ignored by Decky, allowing community members to also have regular conversations in that channel.
The card content will consist of the chat message (excluding the initial command keyword), any files attached to it and any messages included in the discussion thread.
### Channels
Slash commands can be set to listen in all channels (meaning community members will be able to use them across the entire Discord server), or only in one specific channel. You can also choose a private channel, but you need to make sure that you set up the bot with the appropriate Discord permissions to be able to receive and send messages on that channel.
### Upvoting & Threshold
If you set the threshold to zero, any time the command is triggered a card will be immediately created in your Codecks project. If you want messages to have to be vetted by your Discord community first, you can set a minimum number of required upvotes by your community. Only once enough Discord users have approved the message, it will create a card in your Codecks project.
Each feedback messages contains an upvote button with your reaction emoji below. You can customize this reaction emoji within the settings. The person who created the message will automatically upvote their entry. This is why the minimum threshold needs to be 2 if you set one up.
### Workflow State Updates
Decky allows your community to stay up to date with workflow changes of their feedback entries. There are two types of feedback: Annotations and Status Messages.
**Annotations** are embedded directly into the users feedback entry and also visible in leaderboards.
**Status Messages** are additional messages that can be send either within a feedback entry's thread or a channel of your choice.
Here's an overview over all available workflow state updates. You may enable Annotations and Status Messages in any combination you want within the settings.
- **Threshold reached**: When a card has been created due to reaching the threshold
- **Card seen (Pro)**: Triggered when a card has been opened the first time
- **Card assigned (Pro)**: Triggered when a card has been assigned the first time
- **Run (Pro)**: Triggered when a card has been put into a Run the first time
- **Milestone (Pro)**: Triggered when a card has been put into a milestone the first time
- **Hand (Pro)**: Triggered when a card has been put into someone's hand the first time
- **Card started**: Triggered when a card has been started the first time
- **Card done**: Triggered when a card has been marked as done the first time
Note that the order of these entries is meaningful. At most one Annotation is shown on a feedback entry, and it's always the one that is last in the order above. I.e. adding a card to the milestone and assigning in it to a user afterwards will still result in the milestone Annotation being shown as it has a higher priority.
Workflow state updates labeled with **Pro** are available only to organizations on the **Pro** plan.### Community Cards in Codecks
Once a slash command has received enough upvotes a card with its content will be created in Codecks. These cards behave like regular cards in Codecks and have access to the full suite of workflows. For example you can assign them to a team member, assign priority or add them to a Run.
You can recognize the cards that were added by Decky through a potion icon. The icon will appear in the bottom row of the mini card or in the top right of any opened card. Hovering over the icon will show you the number of upvotes the card has received across all channels: Discord, Codecks (internal team upvotes) and on your public [Open Decks](/open-decks/) page. You may also use _‘upvoted’_ as criteria for sorting cards and to quickly identify the top reported community messages.
### Commenting on Cards
You can send the feedback author a message without leaving Codecks. Opening a comment on a Discord-reported card, you’ll see the username and portrait of the user that reported the card, as if they were part of your team 🤯. Their portrait is also designated by a small Discord icon. You can also add them to the conversation by using the user handle `@discord`.
Once you submit the comment, the user will receive a direct message from Decky with the content of your comment. The user can respond to the message like any other DM. Their responses will directly show up inside the comment thread and you’ll receive a notification for the new comment thread content. This even works with Attachments.
You'll receive a warning message should the user not allow DMs by Decky.
Users may also directly contact you. They can hit the ⚙️ button below a feedback entry. Given that the entry has a card associated with it and that the user has the configured role (by default everyone may use it), a "Add private Feedback" button shows up. This allows a user to enter a message which will create a new conversation on your card. Replying to this conversation in the card will send the user a DM just like above.
### Images
Decky can also handle images, either as part of the original report message, in the thread or via direct message, so your community can send you screenshots of bugs or helpful drawings. Their images will be attached to the card.
### Leaderboards
Leaderboards are periodic overviews of the most popular requests received by Decky and posted to a channel of your choice. It lists the most upvoted entries for the specified period, with links to the original chat message.
You can customize the number of entries the leaderboard should contain and the text message that will appear on top. You can also specify on which days and at what time the leaderboard should be posted.
The leaderboard includes entries whether they have already reached the threshold or not, so they may also contain those that still need a couple more upvotes to make it into your Codecks project.
### Karma
Submitting good or useful feedback will award users with Karma points and additional roles. Users gain 1 point for each upvote reaction to their feedback, and a configurable amount of points for each feedback that gets marked as "done" by the developer.
A user's karma is displayed next to the submitted feedback and can also be shown with `/karma` slash command. As a reward, server admins may auto-assign custom roles to contributors that reach a certain Karma threshold. Each slash command can define their own Karma value within the "Basic settings" when a report gets marked as done. By default this is set to 10.
This feature can be found in the Slash Commands section of the Discord Integration settings.
### Deactivating Feedback Entries
Once a card has passed the upvote threshold and has been created in Codecks, you can also use the regular archive and remove actions on it. Doing so will also prevent the card from showing up in future leaderboards.
Sometimes you might want to get rid of a feedback entry that hasn’t made it through the Decky threshold yet but is still appearing in the leaderboards or you might want to delete a card that made it through the threshold without leaving Discord.
For this you can use the ⚙️ button attached to the message. If you have the configured role (by default it's a role containing "Adminstrator" rights), you'll receive a reply containing a "Deactivate" button. Clicking it allows you to specify a reason and deactivates the message. The reason is shown below the original entry and upvotes are prevented.
### Conversation Threads
Every time feedback is submitted via a Slash Command, Decky creates a conversation thread on Discord. The contents of this thread can also be found in the Card on Codecks. You can click on the Discord logo there to jump into the thread.
Here's who gets automatically added to these threads:
- The community member who submitted the feedback.
- Any members reacting to the feedback via emoji.
- Optional: members with a specific server role. This is particularly useful for server moderators, so that they can be notified of any new message being posted. The setting for this can be found in the "Workflow state updates" section of a command.
## User Mapping
If your team uses Discord for internal communication, you can map Codecks users to Discord members in the Decky settings. Once mapped, team members will get an `@` mention on Discord whenever they participate in a [comment thread](/conversations/) on a card — so you don't have to hop into Codecks to know that you've been pulled into a discussion.
You'll find this under "User Mapping" on the Discord integration page of your Organization Settings, next to your other Decky configuration.
## Project Notifications
Codecks features a powerful built-in notification system. You can also share some or all of these notifications in a Discord channel of your choice.
You can select one channel in which these notifications should appear. Make sure that you have given Decky a role that allows it to access the channel and to write to it. Select a project and the type of notifications that you want to have reported. You can select:
- New card created
- Card started
- Card marked as done
- Block or review started
- Comment thread started
- New comment in existing thread
- New milestone created
- Milestone updated
You can set up multiple project notifications at the same time and also choose to use the same channel for notifications from multiple projects.
## Removing the bot
To remove Decky from your server, go to Organization Settings in Codecks and select _“Remove Server”_ at the bottom of the Discord Integration window. If you have Decky running on multiple servers, make sure to first choose the correct server in the top right selection box. You might also want to remove Decky from the Discord Server Settings (under "Integrations"), but you should know this will make Decky very sad 😢!